~ 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
100 lines · 9.1 KB Raw History

title: Workspace API section: Reference order: 300 summary: The workspace's XRPC methods, its event stream, /icon and the page's CSP.

HUD is an appview for its workspace, as knotless is for its repositories. Its methods are XRPC at /xrpc/<nsid>. Each has a lexicon in schemas/ (place.hud.*, with shared shapes in place.hud.defs), and HUD checks the input against it.

What the methods act on is described on the workspace page.

Queries

Queries go by GET.

MethodWhat it does
getWorkspaceWho's signed in, the open tabs, the current canvas, the theme chosen, HUD's themes, and whether to sign in again (signInAgain, sign-in). For the web session, accounts lists the other accounts the browser is signed in to (several accounts)
listCanvasesA page at a time. Owned canvases, then shared, then invitations
getCanvasA canvas and its tiles in strip order
listThemesPeople's themes, a page at a time. One account's, newest first, or everyone's, as the relay (HUD_RELAY) lists the repositories holding them. A theme with a text under 4.5:1 is left out
searchActorsAccounts whose handle or name starts with what's typed (q, limit 1 to 10, 6 by default), for the sign-in forms of the page and the iOS app. HUD asks the typeahead service at typeahead.waow.tech through its outbound client and keeps only well-formed accounts. Under two letters, or when that service fails, the answer is {actors: []}
getPlaygroundWhat the playground starts from: the bundled views by id, the component catalog (as describe_collection gives it) and HUD's themes. The same for everyone
getAccountDataWhat deleteAccountData would delete: the canvases the person owns (each with how many others are in it), how many canvases of others they're in, their invitations, their place.hud.theme records and whether they chose a theme (deleting your data)
getLogsThe lines the server kept (HUD_LOGS), for its operators alone (HUD_OPERATOR_DIDS): one request's by trace, or the last of a message, a level or a minMs, at most 500 (limit). Anyone else gets Forbidden, and a server keeping none answers NotFound (observability)

Procedures

Procedures go by POST.

MethodWhat it does
createCanvasMakes a canvas of the person's, opened as the last tab and made current
updateCanvasRenames a canvas. Only its owner can
deleteCanvasDeletes a canvas for every member, and it leaves their tabs. Only its owner can
openCanvasOpens a canvas as the last tab and makes it current (one open already just becomes current). It accepts an invitation
closeCanvasCloses a tab and keeps the canvas with its members and tiles. The last open tab isn't closed. Closing the current one makes its neighbour current
setTabOrderPuts the tabs named first, in that order, then the rest as they were
setThemeDraws the person's workspace in a theme: one of HUD's by key, or anyone's place.hud.theme by URI, its colours copied as they are now. With neither, the system's light or dark. Their other pages and apps are told
createThemeWrites a place.hud.theme record in the person's own repository, for anyone to choose. It doesn't choose it
deleteThemeDeletes one of the person's own themes. Those who chose it keep its colours
checkThemeSays which texts of a palette read at under 4.5:1 on what they're drawn on. It writes nothing
declineInviteTurns down an invitation, so the person is no longer a member
inviteMemberInvites an account by handle or DID as an editor or a viewer. Only the owner can
setMemberRoleMakes a member an editor or a viewer. Only the owner can, and never for their own role
removeMemberTakes a member or an invitation off a canvas, and it leaves their tabs. Only the owner can
leaveCanvasLeaves a canvas shared with the person. The owner can't leave, so they delete it
addTileAdds a tile, placed by the server, or answers the tile already there with the same call (placing tiles)
removeTileTakes a tile off. If it heads a column, the next in its stack heads it
placeTileMoves a tile right before or after another. Within one column it moves in its stack, else its column moves beside the other's and a stacked tile becomes a column of its own
setTileWidthChanges the width of a tile's column. A stacked tile's width is its head's, and the answer is the head
stackTileStacks a tile at the end of another's column (3 tiles at most). A column's head brings the tiles under it along
unstackTileTakes a stacked tile out as a column of its own, right after its old one
updateTileChanges a tile's title, or its call as a tab chosen in it. The tile stays in place and every page is told. A title made from the call follows the new call, and a given one stays
callToolCalls any of HUD's tools but the canvas ones, as the person. Its answer is the CallToolResult that /mcp gives. An app's call by Bearer gives kit ({ platform, version }), the renderer drawing it, and its tree is fitted to that kit, else to the oldest (old builds and new views). The page's is fitted to this HUD's version
previewViewDraws a view being written, for the playground. It takes tool (list_records, get_record or query) and arguments with the view in them. An invalid view answers {problems: [{at, message}]}, every problem, and nothing is read. Given answer (the structuredContent that call read before), it answers {ui}, the view drawn over it. Otherwise it makes the call and answers {result}. Its input can be up to 4 MiB
uploadBlobUploads an image (JPEG, PNG, WebP or HEIC, at most 2,000,000 bytes) to the person's PDS as their blob, for a record they write next, such as a post's images or a gallery's photos
deleteAccountDataDeletes everything HUD keeps of the person and ends every session of theirs (deleting your data). The input names their own DID, else 403. Only the page's cookie or HUD's own app's token may call it: another MCP client's token gets 403. With the cookie, the browser goes on as POST /workspace/signout leaves it

Views and errors

A canvas comes back as a canvasView. It holds the place.hud.canvas record, the members, the tile count, the storage and the viewer's role.

A tile comes back as a tileView. It holds the place.hud.tile record as kept, the author, the record's URI where the canvas is in a space, and icon.

A failure is {error, message}, with one of these errors: NotFound, Forbidden, InvalidRequest, LimitReached, AuthRequired, UpstreamFailure (uploadBlob's PDS failed, or deleteAccountData couldn't delete something), LogsUnreadable (getLogs couldn't read the kept lines).

Authentication

A method is called as the web session (with its cookie), or with a HUD access token as Bearer (the one an MCP client has). A procedure called with the cookie must carry X-HUD: 1 and the server's own Origin, else it gets 403. searchActors, getPlayground and previewView need no session. previewView calls as the account when a session is good, and as no one otherwise. These three answer with sign-in off too, and every other method then answers MethodNotImplemented.

With HUD_WORKSPACE=off (running HUD) there's no workspace, so only the methods an app's own pages call answer: searchActors, uploadBlob, getLogs, getAccountData and deleteAccountData. Every other method answers MethodNotImplemented (501).

Event stream

getWorkspaceEvents is one stream of server-sent events per person. It isn't an XRPC subscription, since it keeps no history to resume from. It covers every canvas the person has open and follows the tabs as they open and close.

Each data: is a JSON object typed by its $type:

$typeShape
defs#tileEvent{ canvas, op: add | update | remove, key, tile?, by: { did, handle?, kind: person | agent } }
defs#presenceEvent{ canvas, present: [{ did, handle }], by }
defs#canvasesEventThe workspace changed, so read it again

The server sends a ping every 25 s. The stream ends when the server stops, and the page connects again.

/icon

GET /icon/<domain> answers with an app's icon. HUD serves it with sign-in off too, since profiles draw apps' icons. The icon is the site's favicon as HUD_FAVICONS answers it, a PNG of at most 100 KB.

CaseAnswerKept
An iconthe PNGa week
A domain with none404a day
The service has no answer now502by no one

Page CSP

The page's CSP lets it reach only the server. It loads images and audio from the server and from the origins the bundled views trust, and images from the image CDN. It plays video from Bluesky's video service and CDN too.