@linktr.ee/arbor-mcp 0.1.2 → 0.3.0

package/README.md

@@ -6,41 +6,100 @@ Claude Desktop, Cursor, Zed, etc.).
 
 ## What it does
 
-Currently registers a single tool:
+Registers a set of read-only Arbor design system tools. The
+component-resolution tool is documented in detail below; the DS-as-data
+metadata tools (component inventory, single-component lookup, version
+history) are described under [DS-as-data tools](#ds-as-data-tools).
 
-### `arbor.open_in_playroom`
+### `arbor_open_in_playroom`
+
+> The legacy name `arbor.open_in_playroom` remains registered as a deprecated
+> alias (it routes to the same handler) and will be removed in the next major.
+> Prefer the snake_case name.
 
 Resolves an Arbor PascalCase component name into a Playroom share URL with
 the canonical default snippet pre-loaded.
 
-**Input:**
+**Input** (validated by a strict Zod schema — unknown keys are rejected):
 
 ```json
 { "componentName": "Button" }
 ```
 
-**Output:** a `text` content item containing a JSON-stringified
-`CanonicalLookupResult`:
+**Output:** `structuredContent` matching the tool's `outputSchema` (the machine
+payload), plus a concise one-line `text` summary (the human mirror — it does
+**not** duplicate the full JSON):
 
 ```json
 {
   "coverage": "mapped",
   "arborComponentName": "Button",
   "snippet": "<Button>Save changes</Button>",
-  "url": "https://arbor.linktr.ee/playroom/#?code=PEJ1dHRvbj5TYXZlIGNoYW5nZXM8L0J1dHRvbj4="
+  "url": "https://arbor.linktr.ee/playroom/?slug=flowering-sapling-glen-5",
+  "source": "minted",
+  "slug": "flowering-sapling-glen-5"
 }
 ```
 
-`coverage` is one of:
+A `mapped` result carries the pretty `?slug=` URL when slug minting succeeds
+(`source: "minted"` or `"cached"`). If minting is unavailable it degrades to a
+self-contained lz-string `#?code=…` URL with `degraded: true` and a `reason`,
+and no `slug`.
+
+`coverage` (for this by-name tool) is one of:
 
 - `mapped` — the component appears in `figma-mappings.ts` AND has a
   canonical entry in `compositions.ts`. High confidence.
-- `fallback` — best-effort name matching (e.g. "Header Bar" → `HeaderBar`).
-  Used by the Figma plugin's selection-driven path; the by-name MCP tool
-  almost always returns `mapped` or `not_found`.
 - `not_found` — the URL points at the Playroom homepage; agents should
   surface this to the human rather than silently following the link.
 
+> A third coverage, `fallback` (best-effort fuzzy name matching), exists only
+> on the Figma plugin's selection-driven node-ID path. This by-name MCP tool
+> never returns it — its `outputSchema` is `mapped | not_found`.
+
+## DS-as-data tools
+
+Three read-only metadata tools (shipping in a forthcoming release) expose the
+design system as queryable data. They answer "what components / versions exist"
+— **not** token values. (For token values, read the compiled CSS in
+`packages/design-tokens/dist/web/` or the shadcn `registry.json`, which are
+fresher.)
+
+- **`arbor_list_versions`** — design system version history: each entry is
+  `{ id, name, createdAt, readOnly }`.
+- **`arbor_list_components`** — component inventory: `name`, `id`, and a short
+  `description` per component. Returns top-level components only (Figma variant
+  instances are filtered out). Accepts an optional case-insensitive `query`
+  string that filters by name or description.
+- **`arbor_get_component`** — one component's metadata, looked up by `name`
+  (case-insensitive) or `id`. Returns `{ found, component }`.
+
+(A fourth tool, `arbor_get_docs`, is deliberately **not** built yet — deferred
+until a docs page-content route exists.)
+
+### Runtime config + graceful degradation
+
+These tools read the design system's metadata from an internal Lambda
+federation proxy. Two env vars configure the connection — distributed
+internally through the same channel as `FIGMA_ACCESS_TOKEN`:
+
+| Variable                          | Purpose                                                  |
+| --------------------------------- | -------------------------------------------------------- |
+| `ARBOR_MCP_SUPERNOVA_PROXY_URL`   | Full proxy URL, including the `/supernova/query` path     |
+| `ARBOR_MCP_SUPERNOVA_PROXY_TOKEN` | Shared inbound bearer token presented to the proxy        |
+
+When either var is unset — or the proxy is unreachable — the tools **degrade
+gracefully**: they return a successful result with `source: "unavailable"` and
+a `detail` string explaining why. They never throw and never crash the server.
+An agent should treat `"unavailable"` as "couldn't reach the data" rather than
+"the design system has no components/versions."
+
+> **Metadata, not token values.** These tools surface Supernova *metadata*
+> (component names, ids, descriptions, version history) only. They deliberately
+> do **not** return token values — those live in the compiled CSS
+> (`packages/design-tokens/dist/web/`) and the shadcn `registry.json`, which are
+> the fresher source of truth.
+
 ## Install
 
 The package is published publicly to npm as `@linktr.ee/arbor-mcp`. The
@@ -48,8 +107,13 @@ expected use is `npx`-style spawning by an MCP client — see the wiring
 section below. No global install required.
 
 ```bash
-# Smoke-check the latest release
-npx -y @linktr.ee/arbor-mcp --help 2>&1 | head -5
+# Smoke-check the latest release. The server speaks JSON-RPC over stdio (there
+# is no --help flag); pipe a handshake in so stdin closes and the process
+# exits. Expect a tools/list response naming arbor_open_in_playroom.
+printf '%s\n%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
+  | npx -y @linktr.ee/arbor-mcp
 ```
 
 If you're working inside the Arbor monorepo, build the local source
@@ -101,7 +165,7 @@ For portability across clients that don't substitute path variables
 
 ### Verify the connection
 
-After restarting your MCP client, the `arbor.open_in_playroom` tool should
+After restarting your MCP client, the `arbor_open_in_playroom` tool should
 appear in the available-tools list. Ask the agent something like:
 
 > Use the arbor MCP server to open Button in Playroom.
@@ -115,8 +179,9 @@ The agent will call the tool and return the URL.
 # iterating on tool handlers.
 yarn workspace @linktr.ee/arbor-mcp dev
 
-# Run the unit tests (covers tool metadata, input validation, lookup
-# happy/not-found paths, and the 9-of-9 figma-mappings coverage gate).
+# Run the tests: the in-memory Client handshake + protocol contract
+# (server.test.ts) plus tool metadata, input validation, lookup
+# happy/not-found paths, and the figma-mappings coverage gate.
 yarn workspace @linktr.ee/arbor-mcp test
 
 # Smoke-test the full JSON-RPC handshake end-to-end.
@@ -129,20 +194,29 @@ printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion
 packages/arbor-mcp/
 ├── src/
 │   ├── index.ts              # entrypoint: connects stdio transport
-│   ├── server.ts             # creates the Server + registers handlers
+│   ├── server.ts             # creates the McpServer + registers ARBOR_TOOLS
 │   └── tools/
-│       └── open-in-playroom.ts  # tool metadata + dispatch function
+│       ├── registry.ts          # ArborTool convention + registerArborTool
+│       └── open-in-playroom.ts  # tool: schemas, annotations, handler
 ├── tests/
+│   ├── server.test.ts           # in-memory Client handshake + contract
 │   └── open-in-playroom.test.ts # node --test, validation + coverage
 ├── build.mjs                 # esbuild bundle to dist/index.js
 └── tsconfig.json             # rootDir: ../.. for cross-package imports
 ```
 
-The `arbor.open_in_playroom` handler delegates to `lookupByArborName` in
+The `arbor_open_in_playroom` handler delegates to `lookupByArborName` in
 `apps/playroom/src/canonical-snippet-lookup.ts` — the same module the
 Figma plugin's "Open in Playroom" relaunch button uses. This keeps the
 agent-facing surface and the designer-facing surface in lockstep.
 
+The server is built on the SDK's high-level `McpServer` + `registerTool`
+(the modern, non-deprecated API). Every tool is an `ArborTool` registry
+object (`tools/registry.ts`): a `.strict()` Zod `inputSchema`, a Zod
+`outputSchema` (the handler returns matching `structuredContent`),
+annotation hints, and a total handler. Input-validation and handler errors
+surface as `isError: true` results, never protocol rejections.
+
 ## Why bundle vs. emit `tsc` files?
 
 `tsc` would emit one `.js` per `.ts` and preserve cross-package directory
@@ -155,9 +229,17 @@ runs in the build script for type checking.
 
 ## Future tools
 
-When adding a second tool, follow the existing pattern:
+When adding a second tool, follow the registry convention:
+
+1. New file under `src/tools/<name>.ts` exporting an `ArborTool` object
+   (see `tools/registry.ts`): `name`, optional deprecated `aliases`, a
+   `config` with `title` / `description` / `.strict()` Zod `inputSchema` /
+   Zod `outputSchema` / `annotations`, and a total `handler` returning
+   `{ content, structuredContent }`.
+2. Add it to the `ARBOR_TOOLS` array in `src/server.ts`.
+3. Mirror the test file shape under `tests/` (drive it through the in-memory
+   `Client` as in `server.test.ts`, plus pure-handler unit tests).
 
-1. New file under `src/tools/<name>.ts` exporting `TOOL_NAME`,
-   `TOOL_DESCRIPTION`, `TOOL_INPUT_SCHEMA`, and a `run<Name>` handler.
-2. Register it in `src/server.ts` alongside the existing entry.
-3. Mirror the test file shape under `tests/`.
+Pass `inputSchema` as a `z.object({...}).strict()` (a ZodObject, **not** a
+raw shape) — the SDK only preserves `.strict()` rejection of unknown keys
+for a ZodObject; a raw shape is rebuilt non-strict and silently strips them.