@linktr.ee/arbor-mcp 0.1.0

package/README.md

@@ -0,0 +1,163 @@
+# @linktr.ee/arbor-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that
+exposes Arbor design system tools to MCP-connected AI agents (Claude Code,
+Claude Desktop, Cursor, Zed, etc.).
+
+## What it does
+
+Currently registers a single tool:
+
+### `arbor.open_in_playroom`
+
+Resolves an Arbor PascalCase component name into a Playroom share URL with
+the canonical default snippet pre-loaded.
+
+**Input:**
+
+```json
+{ "componentName": "Button" }
+```
+
+**Output:** a `text` content item containing a JSON-stringified
+`CanonicalLookupResult`:
+
+```json
+{
+  "coverage": "mapped",
+  "arborComponentName": "Button",
+  "snippet": "<Button>Save changes</Button>",
+  "url": "https://arbor.linktr.ee/playroom/#?code=PEJ1dHRvbj5TYXZlIGNoYW5nZXM8L0J1dHRvbj4="
+}
+```
+
+`coverage` 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.
+
+## Install
+
+The package is published publicly to npm as `@linktr.ee/arbor-mcp`. The
+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
+```
+
+If you're working inside the Arbor monorepo, build the local source
+instead so you're testing your changes:
+
+```bash
+yarn install
+yarn workspace @linktr.ee/arbor-mcp build
+```
+
+That produces a single bundled ESM file at
+`packages/arbor-mcp/dist/index.js` (with shebang) ready to be spawned by
+any MCP client.
+
+## Wire it into an MCP client
+
+### Claude Code / Claude Desktop / Cursor (`.mcp.json` or equivalent)
+
+The recommended setup uses the public npm package — no clone required:
+
+```jsonc
+{
+  "mcpServers": {
+    "arbor": {
+      "command": "npx",
+      "args": ["-y", "@linktr.ee/arbor-mcp"]
+    }
+  }
+}
+```
+
+If you're hacking on the server inside the Arbor workspace, point at the
+local build instead so changes pick up without republishing:
+
+```jsonc
+{
+  "mcpServers": {
+    "arbor": {
+      "command": "node",
+      "args": ["./packages/arbor-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+For portability across clients that don't substitute path variables
+(Claude Desktop, most CLI MCP clients), prefer absolute paths over
+`${workspaceFolder}`.
+
+### Verify the connection
+
+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.
+
+The agent will call the tool and return the URL.
+
+## Develop
+
+```bash
+# Run the server against tsx directly (no build step) — useful for
+# 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).
+yarn workspace @linktr.ee/arbor-mcp test
+
+# Smoke-test the full JSON-RPC handshake end-to-end.
+printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"manual","version":"0.0.0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/list"}\n' | node dist/index.js
+```
+
+## Architecture
+
+```
+packages/arbor-mcp/
+├── src/
+│   ├── index.ts              # entrypoint: connects stdio transport
+│   ├── server.ts             # creates the Server + registers handlers
+│   └── tools/
+│       └── open-in-playroom.ts  # tool metadata + dispatch function
+├── tests/
+│   └── 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
+`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.
+
+## Why bundle vs. emit `tsc` files?
+
+`tsc` would emit one `.js` per `.ts` and preserve cross-package directory
+structure under `dist/`. Node's ESM resolver doesn't add `.js` extensions
+to extensionless imports (the workspace TS source uses extensionless
+imports because `moduleResolution: bundler`), so the multi-file output
+fails to resolve at runtime. Bundling with esbuild flattens the
+dependency graph into a single self-contained file. `tsc --noEmit` still
+runs in the build script for type checking.
+
+## Future tools
+
+When adding a second tool, follow the existing pattern:
+
+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/`.