~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/hud

A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts

0
0
142 lines · 11.5 KB Raw History
---
title: Tools
section: HUD
order: 2
summary: The MCP tools HUD serves, what each takes and answers, and how queries and writes are made.
---

HUD serves its reads, writes and workspace as MCP tools. Seven of them read and need no sign-in. The rest only show up with sign-in on.

`describe_repo`, `describe_app`, `list_records`, `get_record` and `query` draw their results on the server. Views are covered in [views](views.md).

## The tools

| Tool | Input | View |
| --- | --- | --- |
| `describe_repo` | `actor` (handle, DID, or `me`) | yes |
| `describe_app` | `domain` (as `bsky.app`), `actor` (optional: handle, DID, or `me`), `cursor` (an app page's page more), `page` (optional: the path of one of an operator's app's own pages) | yes |
| `describe_collection` | `actor`, `collection` | no |
| `describe_method` | `method` (a query's NSID) | no |
| `list_records` | `actor`, `collection`, `limit` (25, ≤100 · a view's `pageSize`), `cursor`, `view` | yes |
| `get_record` | `uri` (at-uri), `view` | yes |
| `query` | `method`, `params`, `service` (`did:…#fragment` · a bundled view's by default), `cursor`, `view`, `at` (what a view showing one thing at a time shows first), `compose` (`true` or a `Compose`'s label: the form its screen opens at, [as an `open`'s](views.md#stories)) | yes |
| `create_record` | `collection`, `record`, `rkey` (signed in) | no |
| `apply_writes` | `writes` (a template, as a view's `Compose` gives), `values` (signed in) | no |
| `delete_record` | `uri` (signed in) | no |
| `canvas_list` | `canvas` (signed in) | no |
| `canvas_add` | `tool` (a read tool), `arguments`, `title`, `from` (a tile it is opened from), `after` (a tile it goes right of), `width`, `canvas` (signed in) | no |
| `canvas_place` | `id`, `before` or `after` (a tile), `width`, `canvas` (signed in) | no |
| `canvas_remove` | `id`, `canvas` (signed in) | no |
| `canvas_create` | `name` (signed in) | no |
| `send_interactions` | `feed` (a feed generator's at-uri), `interactions` (signed in · the view's alone) | no |
| `call_procedure` | `method`, `service`, `input` (signed in · the view's alone, a procedure a bundled view calls, or a query whose deletion plan a bundled view deletes) | no |
| `link_card` | `url` (signed in · the view's alone: a link's card, its picture uploaded) | no |
| `find_place` | `q`, or `lat` and `lon` (signed in · the view's alone: places named so, or the place at that point, a photo's, from OpenStreetMap's Nominatim) | no |
| `admin_logs` | `trace`, `message`, `level`, `minMs`, `limit` (signed in · HUD's operators alone) | no |

The first seven read and need no sign-in. HUD lists the rest only with sign-in on. Three of them write as the signed-in account, and five keep the canvases of that account's [workspace](workspace.md), which HUD lists only where it serves the workspace (`HUD_WORKSPACE`, [running HUD](running.md#environment-variables)). It lists `send_interactions` only where a served view reports interactions. A call of a tool HUD doesn't list is a call of no tool.

`send_interactions`, `call_procedure`, `link_card` and `find_place` are the view's, and HUD hides them from the model (`_meta.ui.visibility: ["app"]`). The view calls `send_interactions` to tell a feed what was read of it. It calls `call_procedure` for a procedure a bundled view calls, such as sending a chat message, and for what an Action's `deletes` deletes, as Delete account ([Action](views.md#action)). A composer calls `link_card` for a link's card and `find_place` for a place.

HUD lists `admin_logs` only to its operators, the accounts `HUD_OPERATOR_DIDS` names. It answers the lines the server kept as `place.hud.getLogs` does, and refuses anyone else with a tool error. Details: [observability](observability.md#reading-the-kept-lines).

### `me`

With sign-in on, an actor can be `me`, meaning the signed-in account. That holds for a query's `params.actor` and an at-uri's authority too. Signed out, `me` asks the host to sign in.

## Results

A result's data is its `structuredContent`, and its `content` is a short summary. What only the view needs goes in `_meta`.

For `describe_repo`, `describe_app`, `list_records`, `get_record` and `query`, `_meta` holds `ui`. That's the records or answer drawn as their view draws them. The server resolves it against the data into a tree of the catalog's components. While it does, it reads the view's bindings and holds its URLs to the view's origins. It also fetches a document's Bluesky posts and reads in the lexicon's fields and the verified handles of the DIDs named. The tree's `title` is the view's description. The clients (the view, the workspace and the iOS app) only draw that tree. With no view, they get the generic drawing.

These five tools name the one UI resource, `ui://records/view/<hash>`. Its URI changes with every build of the view, so a host never keeps an old view for a newer server's results.

Every result made signed in names the account in `_meta.viewer` (`{ did, handle }`).

## `describe_repo`

`describe_repo` is an account's universal profile, across the atmosphere's apps.

An app is the domain behind an NSID, with its first two segments reversed. So `app.bsky.*` is bsky.app, `dev.knotless.*` is knotless.dev and `fm.plyr.*` is plyr.fm. HUD names an app as a bundled view of it names it (`"app": "Bluesky"`), and otherwise by its domain. The app's icon is its favicon (`/icon/<domain>`).

### Its data

The data holds four things:

- the account's profile (its `app.bsky.actor.profile`, or null)
- every collection it holds
- the collections a bundled collection view draws (`views`)
- the apps it uses (`apps`), each with its domain, name, icon and how many of its collections it holds, most first

### Its tree

The server builds the tree in this order:

1. The profile, with banner, avatar, name, handle, bio and where its PDS is.
2. The apps the account uses, each with its icon and name. Each opens the app's page with the account's part in it ([`describe_app`](#describe_app)). Past eight, there's a plain "+N more".
3. Its recent activity.
4. A section from each bundled view that adds one to profiles ([`profile`](views.md)) and whose app the account uses, in the views' order. Each section shows its app's icon, a title and "See all" over a few recent things, drawn by that view's own layout.

HUD never shows collections directly. No chip, link or list opens an account's collections. An account with none reads "This repository has no records."

### Recent activity

Recent activity is the newest record of each collection a bundled view names an activity of. That's a collection view's `activity`, or the `activity` of a method view's `records` entry ([`activity` and `records`](views.md)). HUD takes at most 8 of these, in the apps' order. It reads them with `com.atproto.repo.listRecords` and no joins, and merges them newest first into at most 6 rows.

Each row shows three things and opens the record:

- the app's icon
- what the account did, on one short line: the verb and the record's label as its summary reads it ("Posted “main's where the posts go”", or "Posted a post" with no label)
- when, from its `createdAt` or else the TID of its record key (with neither, HUD leaves it out)

With no activity, there's no section.

### How sections are asked

HUD asks for the sections and the activity all at once, as the person asking (signed in or not, as `query` and `list_records` are). Each gets 3 seconds. HUD leaves out one that fails or hasn't answered.

The text names the person and what can be drawn of theirs. It never gives their bio or every collection.

## `describe_app`

`describe_app` is an app's page, by its domain. Its data is the domain, name and icon. With `actor`, it adds the account (`{ did, handle }`).

The tree shows the app's icon, name and domain, and a link to its site. Then comes "Go to", the app's entry points. These are the `launch` of its bundled method views ([`launch`](views.md)), and each opens its query.

With `actor`, the page adds "<name> here" ("Yours here" for the person asking). That's the account's profile sections of this app alone, asked as `describe_repo` asks them. HUD shows it only where the account has some.

Signed out, HUD leaves out an entry point that needs an account. An app with no entry points and no section to show says it has nothing to open. Every client opens an app's page by calling `describe_app`. A bundled view can draw the page instead, as [app pages](app-pages.md) describes.

With `page`, `describe_app` answers one of the app's own pages, as an operator's app file names it ([pages of the app's own](views.md#pages-of-the-apps-own)): its `path`, `title` and `markdown`, drawn as its title over its text. A path the app has no page at is the call's error.

## `describe_collection` and `describe_method`

A model reads `describe_collection` before it writes a view. It answers with four things:

- the collection's schema, with every lexicon description taken out
- three sample records
- the bundled view, if there is one
- the component catalog

`describe_method` does the same for a query. It gives the query's parameters and output with the defs they ref (three levels deep, at most 60), descriptions taken out.

## `query`

`query` calls an XRPC query, never a procedure. The method must resolve to a lexicon whose main def is a `query`.

The call goes to a service named by a DID and the fragment of a service in its document (`did:web:api.bsky.app#bsky_appview`). The document gives the endpoint. HUD checks the params against the lexicon first, and the answer after, with the lexicon validation of the `atproto` crate. The answer may hold fields the lexicon doesn't name. Otherwise HUD refuses an answer that isn't what its lexicon says.

Without sign-in, HUD makes the call as no one, so it only reads public data. A query that needs an account (`getTimeline`) asks the host to sign in. Signed in, the call goes through the account's own PDS, which calls the service for it (`atproto-proxy`, service auth). So personal queries answer. That holds for the services the bundled views name, which are the ones HUD's sign-in asks to call ([what HUD asks for](sign-in.md#what-hud-asks-for)). Any other service gets the call as no one, signed in or not.

A service's error comes back as one line naming the error alone (`AuthMissing`). An answer is kept a few seconds for whoever asked it, and forgotten as they write ([kept answers](internals.md#kept-answers)).

## Writes

`create_record` writes a record to the signed-in account's own repository. The record must validate against its collection's lexicon, and that lexicon must resolve. HUD sets its `$type` to the collection. It writes only the collections HUD's sign-in asks to write (those the bundled views write, and themes) and refuses any other before asking the PDS. The same goes for `apply_writes` and `delete_record`.

`apply_writes` writes the records a composer's template fills with its values, all at once, as Bluesky's and Grain's apps do ([`Compose`](views.md#compose)). Each record is checked as `create_record` checks one. A template that makes no records, as when no write's `when` holds, is refused before anything is sent. A write with `update` (a record key, such as a profile's `self`, or a value holding one, such as a gallery's) first reads that record from the account's PDS with `com.atproto.repo.getRecord`, as it is stored, so its blob refs are kept. A value that holds no record key is refused before anything is read. It's sent as an update over the record, or as a create where there's none yet.

`delete_record` deletes one of the account's own records. It can't delete anyone else's.

`create_record` answers `{ uri, cid }` and `delete_record` answers `{ uri }`.