~ 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.

The tools

ToolInputView
describe_repoactor (handle, DID, or me)yes
describe_appdomain (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_collectionactor, collectionno
describe_methodmethod (a query's NSID)no
list_recordsactor, collection, limit (25, ≤100 · a view's pageSize), cursor, viewyes
get_recorduri (at-uri), viewyes
querymethod, 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)yes
create_recordcollection, record, rkey (signed in)no
apply_writeswrites (a template, as a view's Compose gives), values (signed in)no
delete_recorduri (signed in)no
canvas_listcanvas (signed in)no
canvas_addtool (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_placeid, before or after (a tile), width, canvas (signed in)no
canvas_removeid, canvas (signed in)no
canvas_createname (signed in)no
send_interactionsfeed (a feed generator's at-uri), interactions (signed in · the view's alone)no
call_proceduremethod, 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_cardurl (signed in · the view's alone: a link's card, its picture uploaded)no
find_placeq, 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_logstrace, 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, which HUD lists only where it serves the workspace (HUD_WORKSPACE, running HUD). 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). 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.

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). 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) 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). 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), 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 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): 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). 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).

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). 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 }.