@linktr.ee/arbor-mcp 0.1.2 → 0.2.0

package/README.md

@@ -8,39 +8,52 @@ Claude Desktop, Cursor, Zed, etc.).
 
 Currently registers a single tool:
 
-### `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`.
+
 ## Install
 
 The package is published publicly to npm as `@linktr.ee/arbor-mcp`. The
@@ -48,8 +61,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 +119,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 +133,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 +148,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 +183,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.