@actioneer/ads-mcp 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# `@actioneer/ads-mcp` — the ADS MCP server
+
+Lets a coding agent in **Claude Code / Cursor** discover and import the Actioneer
+Design System through the same flow it already uses for shadcn — always pointing
+at the canonical `@actioneer/ads` package, **never a fork or a deep import**.
+
+It is a thin MCP layer over two pure, unit-tested cores, both declared as **real
+package dependencies** (`@actioneer/ads-manifest`, `@actioneer/ads-lint`) so the
+published package is **self-contained** — `npx -y @actioneer/ads-mcp` runs with no
+repo checkout and no relative import escaping the package boundary:
+
+- the **manifest-query core** (`@actioneer/ads-manifest`) — `(manifest, query) → results`
+- the **lint core** — wraps `@actioneer/ads-lint` to self-check generated code
+
+All five tools read the L1 catalog (`ads-manifest.json`).
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `search_components(query, kind?, limit?)` | Enumerate what exists by name or purpose → exact export names, families, kinds, descriptions. |
+| `get_component(name)` | Full record for one EXACT export: the exact `import { … } from "@actioneer/ads"`, props, variant/size vocabulary, showcase URL, and a copy-paste usage example. Returns an error (never invents) on an unknown name. |
+| `get_token(role)` | The semantic token(s) for a role/utility/purpose (`brand`, `bg-danger`, `muted text`) so the agent references a token, not a literal ads-lint would reject. |
+| `get_principles(id?, enforcedByLint?)` | The 9 ADS design principles (elevation = actionability, borderless surfaces, minimal-information-per-screen, square dots, stroke-only icons, container-fluid responsiveness, …). Each flags whether `ads-lint` auto-checks it — pair the `[lint]` ones with `lint_snippet`, self-apply the `[judgment]` ones. Teaches on-brand UX the catalog + linter can't. |
+| `lint_snippet(code)` | Runs a snippet through `@actioneer/ads-lint` (consumer mode) and returns the verdict — deep imports, aliasing, external-UI, literals, weak motion. |
+
+## Wiring it into Claude Code / Cursor (`.mcp.json`)
+
+**Installed as a package** (recommended for consumer repos):
+
+```json
+{
+  "mcpServers": {
+    "ads": {
+      "command": "npx",
+      "args": ["-y", "@actioneer/ads-mcp"]
+    }
+  }
+}
+```
+
+`ads-mcp` resolves the catalog from the installed `@actioneer/ads/manifest.json`
+automatically. Override with `ADS_MANIFEST`:
+
+```json
+{
+  "mcpServers": {
+    "ads": {
+      "command": "node",
+      "args": ["tools/ads-mcp/bin/ads-mcp.mjs"],
+      "env": { "ADS_MANIFEST": "./ads-manifest.json" }
+    }
+  }
+}
+```
+
+The second form is what the ADS repo itself uses for dogfooding (it points at the
+generated repo-root `ads-manifest.json`). A ready-to-copy example lives at
+[`mcp.example.json`](./mcp.example.json).
+
+- **Claude Code:** drop the JSON in a `.mcp.json` at your repo root (or run
+  `claude mcp add ads -- npx -y @actioneer/ads-mcp`).
+- **Cursor:** add the same `mcpServers` block to `.cursor/mcp.json`.
+
+## Manifest resolution order
+
+1. `$ADS_MANIFEST` (explicit path)
+2. `@actioneer/ads/manifest.json` (the installed package's catalog)
+3. `<repo>/ads-manifest.json` (local dev — generated by `npm run build:lib` / `prebuild`)
+
+## Development
+
+```bash
+npm run test:mcp   # from the ADS repo root — tool layer, lint_snippet, stdio round-trip
+```
+
+The transport is a dependency-free newline-delimited JSON-RPC 2.0 stdio loop
+(`src/server.mjs`); all behavior lives in `src/tools.mjs` + the pure cores, which
+are tested without ever starting the loop.

package/bin/ads-mcp.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// ADS MCP server entry — loads the ADS manifest and starts the stdio server.
+//
+// Manifest resolution order (first hit wins):
+//   1. $ADS_MANIFEST                              (explicit path override)
+//   2. @actioneer/ads/manifest.json              (the installed package's catalog)
+//   3. <repo>/ads-manifest.json                  (local dev, generated by build)
+//
+// Wire it into Claude Code / Cursor via .mcp.json (see tools/ads-mcp/README.md).
+
+import { readFileSync, existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { startServer } from "../src/server.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+function resolveManifestPath() {
+  if (process.env.ADS_MANIFEST && existsSync(process.env.ADS_MANIFEST)) return process.env.ADS_MANIFEST;
+  try {
+    return require.resolve("@actioneer/ads/manifest.json");
+  } catch {
+    /* not installed as a package — fall through to repo dev copy */
+  }
+  const repoCopy = resolve(__dirname, "../../../ads-manifest.json");
+  if (existsSync(repoCopy)) return repoCopy;
+  return null;
+}
+
+const manifestPath = resolveManifestPath();
+if (!manifestPath) {
+  console.error(
+    "ads-mcp: could not find ads-manifest.json. Set $ADS_MANIFEST, install @actioneer/ads, " +
+      "or run the build so ads-manifest.json exists at the repo root."
+  );
+  process.exit(1);
+}
+
+const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+const pkg = JSON.parse(readFileSync(resolve(__dirname, "../package.json"), "utf8"));
+
+startServer({ manifest, name: "ads-mcp", version: pkg.version });
+// stdio server runs until the client closes the pipe; keep the process alive.
+process.stdin.resume();

package/mcp.example.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "ads": {
+      "command": "npx",
+      "args": ["-y", "@actioneer/ads-mcp"]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@actioneer/ads-mcp",
+  "version": "0.1.0",
+  "description": "ADS MCP server — lets an agent in Claude Code / Cursor discover and import the Actioneer Design System through the same flow it uses for shadcn, always pointing at the canonical @actioneer/ads package (never a fork or deep import).",
+  "type": "module",
+  "bin": {
+    "ads-mcp": "bin/ads-mcp.mjs"
+  },
+  "exports": {
+    ".": "./src/server.mjs",
+    "./tools": "./src/tools.mjs",
+    "./lint": "./src/lint.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "mcp.example.json",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@actioneer/ads-lint": "^0.1.0",
+    "@actioneer/ads-manifest": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@actioneer/ads": "*",
+    "typescript": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "@actioneer/ads": { "optional": true },
+    "typescript": { "optional": true }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/lint.mjs

@@ -0,0 +1,42 @@
+// lint_snippet core — run a code string through @actioneer/ads-lint's rules in
+// CONSUMER mode and return a structured verdict. No file IO: the ads-lint rule
+// functions are (relPath, source, cfg) → findings, so a snippet lints directly.
+
+// `@actioneer/ads-lint` is a real dependency (declared in package.json), so it
+// resolves identically whether this package is installed standalone via npx or
+// run from the monorepo (where it is linked into node_modules as a `file:` dep).
+// No relative import escapes the package boundary.
+import { DEFAULT_CONFIG, lintImports, lintMotion, lintLiterals } from "@actioneer/ads-lint";
+
+const RULES = [lintImports, lintMotion, lintLiterals];
+
+/**
+ * Lint a snippet as if it were a consumer file.
+ * @param {string} code
+ * @param {{filename?:string, config?:object}} [opts]
+ * @returns {{ok:boolean, errorCount:number, warningCount:number, findings:Array}}
+ */
+export function lintSnippet(code, opts = {}) {
+  const filename = opts.filename ?? "snippet.tsx";
+  // Consumer mode by default: every file is a consumer, all import rules apply.
+  const cfg = opts.config ?? DEFAULT_CONFIG;
+
+  const findings = [];
+  for (const rule of RULES) {
+    for (const f of rule(filename, code, cfg)) findings.push({ file: filename, ...f });
+  }
+  findings.sort((a, b) => a.line - b.line || String(a.rule).localeCompare(String(b.rule)));
+
+  const errorCount = findings.filter((f) => f.severity === "error").length;
+  const warningCount = findings.filter((f) => f.severity === "warn").length;
+  return { ok: errorCount === 0, errorCount, warningCount, findings };
+}
+
+/** Human-readable one-liner per finding (mirrors the ads-lint CLI format). */
+export function formatVerdict(result) {
+  if (result.findings.length === 0) return "ads-lint: clean — 0 errors, 0 warnings.";
+  const lines = result.findings.map(
+    (f) => `  ${f.file}:${f.line} [${f.severity}] ${f.rule}: ${f.match} — ${f.guidance}`
+  );
+  return `ads-lint: ${result.errorCount} error(s) · ${result.warningCount} warning(s)\n${lines.join("\n")}`;
+}

package/src/server.mjs

@@ -0,0 +1,66 @@
+// Minimal MCP stdio server — newline-delimited JSON-RPC 2.0, no SDK dependency.
+// Wires the transport-independent tool layer (tools.mjs) to stdin/stdout. Kept
+// deliberately thin: all behavior lives in the pure cores, which are unit-tested
+// without ever starting this loop.
+
+import { createTools } from "./tools.mjs";
+
+const PROTOCOL_VERSION = "2024-11-05";
+
+export function startServer({ manifest, name = "ads-mcp", version = "0.1.0", input = process.stdin, output = process.stdout }) {
+  const tools = createTools({ manifest });
+
+  const send = (msg) => output.write(JSON.stringify(msg) + "\n");
+  const reply = (id, result) => send({ jsonrpc: "2.0", id, result });
+  const fail = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
+
+  function handle(msg) {
+    const { id, method, params } = msg;
+    // Notifications (no id) never get a response.
+    if (id === undefined || id === null) return;
+
+    switch (method) {
+      case "initialize":
+        return reply(id, {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities: { tools: {} },
+          serverInfo: { name, version },
+        });
+      case "tools/list":
+        return reply(id, { tools: tools.definitions });
+      case "tools/call": {
+        const result = tools.call(params?.name, params?.arguments ?? {});
+        return reply(id, result);
+      }
+      case "ping":
+        return reply(id, {});
+      default:
+        return fail(id, -32601, `Method not found: ${method}`);
+    }
+  }
+
+  let buffer = "";
+  input.setEncoding?.("utf8");
+  input.on("data", (chunk) => {
+    buffer += chunk;
+    let nl;
+    while ((nl = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (!line) continue;
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        continue; // ignore malformed lines
+      }
+      try {
+        handle(msg);
+      } catch (err) {
+        if (msg?.id != null) fail(msg.id, -32603, `Internal error: ${err?.message ?? err}`);
+      }
+    }
+  });
+
+  return { tools };
+}

package/src/tools.mjs

@@ -0,0 +1,168 @@
+// The ADS MCP tool layer — transport-independent. Each tool is a thin adapter
+// over the pure manifest-query core (tools/ads-manifest) + the lint_snippet
+// core. `createTools({ manifest })` returns the tool definitions and a
+// `call(name, args)` dispatcher, so the stdio server and node:test share one
+// code path (no MCP dependency needed to test the tools).
+
+import { searchComponents, getComponent, getToken, getPrinciples } from "@actioneer/ads-manifest/query";
+import { lintSnippet, formatVerdict } from "./lint.mjs";
+
+export function createTools({ manifest }) {
+  const definitions = [
+    {
+      name: "search_components",
+      description:
+        "Search the ADS catalog for components/utilities/hooks by name or purpose. " +
+        "Returns exact export names (import from '@actioneer/ads'), families, kinds, and descriptions. " +
+        "Use this first to discover what exists before importing.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Name or purpose, e.g. 'button', 'date picker', 'status'." },
+          kind: { type: "string", enum: ["component", "type", "hook", "util"], description: "Optional filter." },
+          limit: { type: "number", description: "Max results (default 25)." },
+        },
+        required: ["query"],
+      },
+    },
+    {
+      name: "get_component",
+      description:
+        "Get the full record for one ADS export by its EXACT name: the exact import statement, " +
+        "props, variant/size vocabulary, showcase URL, and a copy-paste usage example. " +
+        "Returns an error if the name is not an exact export (never invents one).",
+      inputSchema: {
+        type: "object",
+        properties: { name: { type: "string", description: "Exact export name, e.g. 'Button'." } },
+        required: ["name"],
+      },
+    },
+    {
+      name: "get_token",
+      description:
+        "Get the ADS semantic token(s) for a role or purpose (e.g. 'brand', 'muted-foreground', " +
+        "'bg-danger', 'primary text'). Reference the returned token/utilities instead of a raw " +
+        "color literal — ads-lint rejects literals.",
+      inputSchema: {
+        type: "object",
+        properties: { role: { type: "string", description: "A role, utility, or purpose." } },
+        required: ["role"],
+      },
+    },
+    {
+      name: "get_principles",
+      description:
+        "Get the ADS design principles — the house rules for every ADS UI (elevation = actionability, " +
+        "borderless surfaces, minimal-information-per-screen, square status dots, stroke-only icons, " +
+        "container-fluid responsiveness, …). Each flags whether @actioneer/ads-lint auto-checks it " +
+        "(pair those with lint_snippet) or whether it is a judgment call to self-apply. Pull these to " +
+        "produce on-brand UI, not just lint-clean UI.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "Optional: one principle by its id or number (e.g. 'ads-first' or '7')." },
+          enforcedByLint: {
+            type: "boolean",
+            description: "Optional: only lint-enforced (true) or only judgment-call (false) principles.",
+          },
+        },
+      },
+    },
+    {
+      name: "lint_snippet",
+      description:
+        "Run a code snippet through @actioneer/ads-lint (consumer mode) to self-check generated ADS " +
+        "code. Flags deep imports, aliased/default/namespace barrel imports, external-UI imports, " +
+        "hardcoded color/dimension literals, and banned/weak motion. Returns the verdict.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          code: { type: "string", description: "The TSX/TS code to lint." },
+          filename: { type: "string", description: "Optional filename for context (default snippet.tsx)." },
+        },
+        required: ["code"],
+      },
+    },
+  ];
+
+  const handlers = {
+    search_components: (args) => {
+      const results = searchComponents(manifest, args.query ?? "", {
+        kind: args.kind,
+        limit: args.limit ?? 25,
+      });
+      if (results.length === 0) {
+        return text(`No ADS export matches "${args.query}". Try a broader term or a different kind.`);
+      }
+      const lines = results.map(
+        (r) => `- ${r.name} (${r.kind}, ${r.family})${r.description ? ` — ${r.description}` : ""}`
+      );
+      return text(
+        `${results.length} match(es) — import from "${manifest.importPath}":\n${lines.join("\n")}`
+      );
+    },
+
+    get_component: (args) => {
+      const rec = getComponent(manifest, args.name);
+      if (!rec) {
+        const near = searchComponents(manifest, args.name ?? "", { limit: 5 }).map((r) => r.name);
+        return text(
+          `"${args.name}" is not an ADS export. ${near.length ? `Did you mean: ${near.join(", ")}?` : "Use search_components to discover names."}`,
+          true
+        );
+      }
+      return json(rec);
+    },
+
+    get_token: (args) => {
+      const tokens = getToken(manifest, args.role ?? "");
+      if (tokens.length === 0) {
+        return text(`No ADS token matches "${args.role}". Use a semantic role like 'brand' or 'muted-foreground'.`, true);
+      }
+      return json(tokens);
+    },
+
+    get_principles: (args) => {
+      const wantLint = typeof args.enforcedByLint === "boolean" ? args.enforcedByLint : undefined;
+      const principles = getPrinciples(manifest, { id: args.id, enforcedByLint: wantLint });
+      if (principles.length === 0) {
+        const total = manifest.principles?.length ?? 0;
+        if (total === 0) return text("No ADS principles are available in this manifest.", true);
+        if (args.id) return text(`No ADS principle matches "${args.id}". Omit filters to get all ${total}.`, true);
+        // A filter (enforcedByLint) matched nothing, though principles do exist.
+        const kind = wantLint ? "lint-enforced" : "judgment-call";
+        return text(`No ${kind} principles found. Omit filters to get all ${total}.`, true);
+      }
+      return json(principles);
+    },
+
+    lint_snippet: (args) => {
+      if (typeof args.code !== "string" || args.code.trim() === "") {
+        return text("lint_snippet requires a non-empty `code` string.", true);
+      }
+      const result = lintSnippet(args.code, { filename: args.filename });
+      return text(formatVerdict(result));
+    },
+  };
+
+  return {
+    definitions,
+    /** Dispatch a tool call. @returns {{content:Array, isError?:boolean}} */
+    call(name, args = {}) {
+      const handler = handlers[name];
+      if (!handler) return text(`Unknown tool "${name}".`, true);
+      try {
+        return handler(args);
+      } catch (err) {
+        return text(`Tool "${name}" failed: ${err?.message ?? err}`, true);
+      }
+    },
+  };
+}
+
+function text(t, isError = false) {
+  return { content: [{ type: "text", text: t }], ...(isError ? { isError: true } : {}) };
+}
+function json(obj) {
+  return { content: [{ type: "text", text: JSON.stringify(obj, null, 2) }] };
+}