chadtmiller.com/hud
A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts
place.hud.hudkit 0.3.1 Latest 5 packages
0
0
# HUD
HUD is a remote MCP server that shows atproto records as interactive UI inside Claude, ChatGPT and
any other host of MCP Apps. Give it a handle and it finds the account's PDS and reads the public
records there. Name a service's XRPC query (an AppView's feeds, say) and it calls it.
Views draw records and answers. A view is either a bundled one (Bluesky posts and feeds, plyr.fm's
playlists and likes, standard.site's blog posts and blogs), an operator's (`HUD_APPS`, as Grain's
galleries are) or one the host's model writes and passes in. With none, HUD builds a card from the
collection's lexicon, or a JSON tree. Hosts without MCP Apps get the same data as text.
Everything public works without signing in. Sign in once with an atproto account and Claude can
write records for you (a like, a repost, a gallery), click a view's buttons (Like) and read your
personal feeds (your timeline) through your own PDS. Signed in, you also get a workspace at
`/workspace`. It's canvases of tiles that you, the people you share them with, and any AI you
connect to HUD fill, live.
## Running it
```sh
cd web && npm ci && cd ..
just serve # http://localhost:8787, MCP at /mcp
```
Add `http://localhost:8787/mcp` to a host that reaches it, or a public deployment's
`https://<host>/mcp` as a custom connector in Claude. [Running it](docs/running.md) has the rest,
and every environment variable.
## Docs
| Page | What's there |
| --- | --- |
| [Overview](docs/overview.md) | What HUD is, and what isn't built |
| [Tools](docs/tools.md) | The MCP tools, their inputs and results, `query` and the writes |
| [Views](docs/views.md) | How a view draws records: joins, summaries, layouts, query joins, the bundled views, the operator's views and trust |
| [App pages](docs/app-pages.md) | An app's page, and where an account opens |
| [knotless](docs/knotless.md) | knotless's views and how its queries are made |
| [Sign-in](docs/sign-in.md) | OAuth, feed interactions, saved feeds, chats and procedures |
| [Workspace](docs/workspace.md) | Canvases, tiles, agents, music, themes and where canvases live |
| [Playground](docs/playground.md) | Writing a view at `/playground`, beside what it draws |
| [Building an app on HUD](docs/sdk.md) | HUD's packages for the web, iOS and Android, their registries, versions and releases |
| [Running it](docs/running.md) | Commands, environment variables and the image |
| [Memory](docs/memory.md) | What HUD holds in memory and how to measure it |
| [Observability](docs/observability.md) | What HUD logs, its traces and metrics, and the lines it keeps for its operators |
| [Workspace API](docs/workspace-api.md) | The workspace's XRPC methods, its event stream and `/icon` |
| [How it works](docs/internals.md) | Identity, lexicons, blobs, joins, counts, queries, storage and checks |
[`docs/_style.md`](docs/_style.md) says how the docs are written. `node harness/docs.mjs` (in
`just lint`) checks them.