chadtmiller.com/hud
A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts
place.hud.hudkit 0.3.0 Latest 5 packages
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.
| Method | What it does |
|---|---|
getWorkspace | Who'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) |
listCanvases | A page at a time. Owned canvases, then shared, then invitations |
getCanvas | A canvas and its tiles in strip order |
listThemes | People'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 |
searchActors | Accounts 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: []} |
getPlayground | What 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 |
getAccountData | What 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) |
getLogs | The 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.
| Method | What it does |
|---|---|
createCanvas | Makes a canvas of the person's, opened as the last tab and made current |
updateCanvas | Renames a canvas. Only its owner can |
deleteCanvas | Deletes a canvas for every member, and it leaves their tabs. Only its owner can |
openCanvas | Opens a canvas as the last tab and makes it current (one open already just becomes current). It accepts an invitation |
closeCanvas | Closes 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 |
setTabOrder | Puts the tabs named first, in that order, then the rest as they were |
setTheme | Draws 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 |
createTheme | Writes a place.hud.theme record in the person's own repository, for anyone to choose. It doesn't choose it |
deleteTheme | Deletes one of the person's own themes. Those who chose it keep its colours |
checkTheme | Says which texts of a palette read at under 4.5:1 on what they're drawn on. It writes nothing |
declineInvite | Turns down an invitation, so the person is no longer a member |
inviteMember | Invites an account by handle or DID as an editor or a viewer. Only the owner can |
setMemberRole | Makes a member an editor or a viewer. Only the owner can, and never for their own role |
removeMember | Takes a member or an invitation off a canvas, and it leaves their tabs. Only the owner can |
leaveCanvas | Leaves a canvas shared with the person. The owner can't leave, so they delete it |
addTile | Adds a tile, placed by the server, or answers the tile already there with the same call (placing tiles) |
removeTile | Takes a tile off. If it heads a column, the next in its stack heads it |
placeTile | Moves 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 |
setTileWidth | Changes the width of a tile's column. A stacked tile's width is its head's, and the answer is the head |
stackTile | Stacks a tile at the end of another's column (3 tiles at most). A column's head brings the tiles under it along |
unstackTile | Takes a stacked tile out as a column of its own, right after its old one |
updateTile | Changes 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 |
callTool | Calls 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 |
previewView | Draws 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 |
uploadBlob | Uploads 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 |
deleteAccountData | Deletes 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:
$type | Shape |
|---|---|
defs#tileEvent | { canvas, op: add | update | remove, key, tile?, by: { did, handle?, kind: person | agent } } |
defs#presenceEvent | { canvas, present: [{ did, handle }], by } |
defs#canvasesEvent | The 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.
| Case | Answer | Kept |
|---|---|---|
| An icon | the PNG | a week |
| A domain with none | 404 | a day |
| The service has no answer now | 502 | by 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.