designsource 0.2.1 → 0.3.0

package/README.md

@@ -4,10 +4,11 @@
 
 # designsource
 
-The command line for a [DS source](https://designsource.app) design system. Two things it does:
+The command line for a [DS source](https://designsource.app) design system. Three things it does:
 
 - **`integrate`** — add the design system to the app you already have: a `design-system/` folder with your tokens as CSS variables, a prompt that tells your coding agent how to wire them in, and the component kit as reference. Vue, Svelte, Angular or plain CSS.
 - **`create`** — start a new Next.js project from it: tokens, all 28 components and your mockup page, running after `pnpm install && pnpm dev`.
+- **`mcp`** — serve the design system to your coding agent over MCP: tokens, every component's source, your mockup page and a step-by-step integration guide, read on demand instead of pasted. Claude Code, Cursor, Codex — any client that speaks MCP over stdio.
 
 ```sh
 npx designsource integrate
@@ -62,22 +63,92 @@ Writes a runnable Next.js app into a new or empty folder (default `my-design-sys
   <img src="https://designsource.app/designsource/starter-light-components.png" alt="Component gallery, light" width="49%">
 </p>
 
+## `mcp` — serve it to a coding agent
+
+```sh
+npx designsource mcp [--token <project token>] [--api <origin>]
+```
+
+Not a command you run in a terminal: put it in your MCP client's config and the agent runs it. The server is plain stdio MCP, so every client takes the same command and env — only the config file's shape differs.
+
+| Client | Config | Shape |
+| --- | --- | --- |
+| Claude Code | `.mcp.json` in the repo, or `claude mcp add designsource -e DS_SYNC_TOKEN=<project token> -- npx -y designsource mcp` | `mcpServers` JSON |
+| Cursor | `.cursor/mcp.json` | `mcpServers` JSON |
+| Windsurf, Cline, Gemini CLI | their `mcp_config.json` / `settings.json` | `mcpServers` JSON |
+| Codex | `~/.codex/config.toml` | `mcp_servers` TOML |
+| VS Code (Copilot) | `.vscode/mcp.json` | `servers` JSON with `type: "stdio"` |
+| Anything else | its MCP config | command `npx -y designsource mcp`, env `DS_SYNC_TOKEN` |
+
+`mcpServers` JSON:
+
+```json
+{
+  "mcpServers": {
+    "designsource": {
+      "command": "npx",
+      "args": ["-y", "designsource", "mcp"],
+      "env": { "DS_SYNC_TOKEN": "<project token>" }
+    }
+  }
+}
+```
+
+Codex TOML:
+
+```toml
+[mcp_servers.designsource]
+command = "npx"
+args = ["-y", "designsource", "mcp"]
+env = { DS_SYNC_TOKEN = "<project token>" }
+```
+
+VS Code:
+
+```json
+{
+  "servers": {
+    "designsource": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "designsource", "mcp"],
+      "env": { "DS_SYNC_TOKEN": "<project token>" }
+    }
+  }
+}
+```
+
+The workbench's Copy dialog hands out all three. Then ask the agent to integrate the design system: in Claude Code, `/mcp__designsource__integrate-design-system` does it; elsewhere, "integrate the design system using the designsource MCP" — the `integrate-design-system` prompt is there for clients that expose MCP prompts, and `get_integration_guide` carries the same steps as a tool for those that don't. Running the agent headless (`claude -p`) needs its MCP tools allowed, e.g. `--allowedTools "mcp__designsource__*"`; interactive sessions prompt instead.
+
+| Tool | Returns |
+| --- | --- |
+| `get_project` | Name, token count, corner-radius strategy, font families, whether there is a mockup page. |
+| `get_tokens` | Tokens as `{path, $type, $value: {light, dark}, ref}`; filter by `tier`, `category`, `component`. |
+| `get_css_variables` | Every token as plain CSS custom properties, light and dark — for any stack. |
+| `get_shadcn_theme` | The shadcn/ui theme stylesheet for Tailwind v4. |
+| `list_components` | The 28 components and the CSS variables each reads. |
+| `get_component_source` | One component's React source (`utils` for the `cn` helper): verbatim in React + Tailwind, the spec to port from elsewhere. |
+| `get_mockup_page` | Your mockup page as a layout spec plus the renderer that paints it. |
+| `get_integration_guide` | The steps: wire the tokens, bring in the components, migrate existing styles, document. |
+
+Read-only: nothing an agent does here changes the design system. The project is fetched on the first tool call and refreshed every 60 seconds, so a Save in the workbench shows on the next call. Like every export, it needs the project's account on Pro; on the free plan every tool answers with one line saying so.
+
 ## Options
 
 | Flag | What it does |
 | --- | --- |
-| `folder` | Target folder. `integrate` defaults to `.`, `create` to `my-design-system`. |
+| `folder` | Target folder. `integrate` defaults to `.`, `create` to `my-design-system`; `mcp` takes none. |
 | `--framework` | `integrate` only. Skip the picker: `vue`, `svelte`, `angular` or `css`. |
 | `--token` | The project token, or set `DS_SYNC_TOKEN` for scripts. Asked hidden when neither is given. |
 | `--api` | API origin. Default `https://designsource.app`; point it at a self-hosted instance. |
-| `--force` | Overwrite files that already exist. Without it the command refuses rather than touching them. |
+| `--force` | `integrate` and `create` only. Overwrite files that already exist. Without it the command refuses rather than touching them. |
 
 Outside a terminal (CI, pipes) the pickers become numbered prompts, and `designsource` with no command prints usage instead of the menu. Ctrl+C or Esc in a picker exits 130 with nothing written.
 
 ## Safety
 
 - Every write is contained to the target folder. On any failure the command removes what it created, restores what it overwrote, and says so in one line.
-- The project token authorises read-only access to one project. Regenerate it in Project settings to revoke it; the command never stores it.
+- The project token authorises read-only access to one project. Regenerate it in Project settings to revoke it; the command never stores it; `mcp` reads it from the environment your MCP client passes and prints it nowhere.
 - Zero runtime dependencies. Node 20 or newer.
 
 ## Local development
@@ -88,8 +159,11 @@ From the [design-system](https://github.com/KaroMourad/design-system) repo, agai
 pnpm --filter designsource build
 pnpm --filter designsource start -- integrate --framework vue --api http://localhost:3001
 pnpm --filter designsource start -- create my-app --api http://localhost:3001
+DS_SYNC_TOKEN=<project token> pnpm --filter designsource start -- mcp --api http://localhost:3001
 ```
 
+For the MCP server, add it to Claude Code with `claude mcp add designsource -e DS_SYNC_TOKEN=… -- node apps/designsource/dist/index.js mcp --api http://localhost:3001` and run `/mcp__designsource__integrate-design-system` in a scratch app.
+
 `pnpm --filter designsource test` builds and runs the unit tests plus an end-to-end run of the binary against a throwaway local HTTP server, asserting the token never reaches stdout or stderr.
 
 ## Publishing

package/dist/index.js

@@ -11,6 +11,7 @@ var USAGE = `designsource <command> [options]        (also installed as: dss)
 Commands
   integrate [folder]   add the design system to an existing app \u2014 writes design-system/ (default folder: .)
   create [folder]      new Next.js project with the tokens, every component and your mockup page (default folder: ${CREATE_DEFAULT_FOLDER})
+  mcp                  serve the design system to a coding agent over MCP (stdio) \u2014 for .mcp.json, not for a terminal
 
 Run a command with --help for its options. In a terminal, no command shows a menu.
 `;
@@ -33,8 +34,18 @@ ${TOKEN_LINE}
 ${API_LINE}
   --force       overwrite files the bundle writes when design-system/ already exists
 `;
+var MCP_USAGE = `designsource mcp [--token <project token>] [--api <origin>]
+
+Serves the design system to a coding agent over MCP on stdin/stdout. Put it in your MCP
+client's config (Claude Code, Cursor, Codex\u2026); the token comes from --token or DS_SYNC_TOKEN.
+Read-only: tokens, component source, the mockup page and an integration guide.
+
+Options
+${TOKEN_LINE}
+${API_LINE}
+`;
 function usageFor(verb) {
-  return verb === "create" ? CREATE_USAGE : verb === "integrate" ? INTEGRATE_USAGE : USAGE;
+  return verb === "create" ? CREATE_USAGE : verb === "integrate" ? INTEGRATE_USAGE : verb === "mcp" ? MCP_USAGE : USAGE;
 }
 var ArgsError = class extends Error {
   constructor(message, usage) {
@@ -53,8 +64,36 @@ function parseArgs(argv, env) {
   if (first === void 0) return { kind: "menu" };
   if (HELP.has(first)) return { kind: "help", verb: void 0 };
   if (first === "create" || first === "integrate") return parseVerb(first, rest, env);
-  if (first.startsWith("-")) throw new ArgsError("Missing command. Use integrate or create.", USAGE);
-  throw new ArgsError(`Unknown command "${first}". Use integrate or create.`, USAGE);
+  if (first === "mcp") return parseMcp(rest, env);
+  if (first.startsWith("-")) throw new ArgsError("Missing command. Use integrate, create or mcp.", USAGE);
+  throw new ArgsError(`Unknown command "${first}". Use integrate, create or mcp.`, USAGE);
+}
+function parseApiOrigin(value, usage) {
+  const origin = value.replace(/\/+$/, "");
+  let parsed;
+  try {
+    parsed = new URL(origin);
+  } catch {
+  }
+  if (!parsed || !parsed.host) throw new ArgsError(`Option --api needs a full origin such as http://localhost:3001 (got "${value}")`, usage);
+  return origin;
+}
+function parseMcp(argv, env) {
+  const args = { api: DEFAULT_API_ORIGIN };
+  if (env.DS_SYNC_TOKEN) args.token = env.DS_SYNC_TOKEN;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") return { kind: "help", verb: "mcp" };
+    if (!arg.startsWith("--")) throw new ArgsError(arg.startsWith("-") ? `Unknown option ${arg}` : "mcp takes no folder", MCP_USAGE);
+    const eq = arg.indexOf("=");
+    const key = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
+    const value = eq === -1 ? argv[++i] : arg.slice(eq + 1);
+    if (key !== "token" && key !== "api") throw new ArgsError(`Unknown option --${key}`, MCP_USAGE);
+    if (value === void 0) throw new ArgsError(`Option --${key} needs a value`, MCP_USAGE);
+    if (key === "token") args.token = value;
+    else args.api = parseApiOrigin(value, MCP_USAGE);
+  }
+  return { kind: "mcp", args };
 }
 function parseVerb(verb, argv, env) {
   const usage = usageFor(verb);
@@ -84,16 +123,7 @@ function parseVerb(verb, argv, env) {
         args.token = value;
       } else if (key === "api") {
         needs();
-        const origin = value.replace(/\/+$/, "");
-        let parsed;
-        try {
-          parsed = new URL(origin);
-        } catch {
-        }
-        if (!parsed || !parsed.host) {
-          throw new ArgsError(`Option --api needs a full origin such as http://localhost:3001 (got "${value}")`, usage);
-        }
-        args.api = origin;
+        args.api = parseApiOrigin(value, usage);
       } else throw new ArgsError(`Unknown option --${key}`, usage);
       continue;
     }
@@ -119,8 +149,10 @@ var CANCELLED = "Cancelled.";
 var TOKEN_MESSAGE = "Project token not recognised. In the workbench open Project settings and copy the project token.";
 var UNREACHABLE = (api) => `Could not reach ${api}.`;
 var UPDATE_MESSAGE = "This design system needs a newer designsource CLI. Update it (for example `npx designsource@latest`) and run again.";
+var PLAN_MESSAGE = "This project's account is on the free plan. Exports need Pro: https://designsource.app/pricing";
 function messageForResponse(status, body, api) {
   if (status === 401) return TOKEN_MESSAGE;
+  if (status === 402) return PLAN_MESSAGE;
   const serverMessage = typeof body === "object" && body !== null && typeof body.error === "string" ? body.error : null;
   if (status === 400) return serverMessage ?? `${api} rejected the request (400).`;
   return `${api} answered ${status}.`;
@@ -468,6 +500,312 @@ async function runIntegrate(args, env, io) {
   await scaffold({ folder, framework, token, api: args.api, force: args.force }, env, io);
 }
 
+// src/mcp/server.ts
+import { createInterface as createInterface2 } from "node:readline";
+
+// src/version.ts
+var VERSION = true ? "0.3.0" : "0.0.0-dev";
+
+// src/mcp/jsonrpc.ts
+var PARSE_ERROR = -32700;
+var INVALID_REQUEST = -32600;
+var METHOD_NOT_FOUND = -32601;
+var INVALID_PARAMS = -32602;
+function respond(id, result) {
+  return { jsonrpc: "2.0", id, result };
+}
+function fail(id, code2, message) {
+  return { jsonrpc: "2.0", id, error: { code: code2, message } };
+}
+function encode(response) {
+  return `${JSON.stringify(response).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029")}
+`;
+}
+var isId = (v) => typeof v === "string" || typeof v === "number";
+function parseLine(line) {
+  let json;
+  try {
+    json = JSON.parse(line);
+  } catch {
+    return { kind: "error", response: fail(null, PARSE_ERROR, "Parse error") };
+  }
+  if (typeof json !== "object" || json === null || Array.isArray(json)) {
+    return { kind: "error", response: fail(null, INVALID_REQUEST, "Invalid Request") };
+  }
+  const m = json;
+  const hasId = "id" in m;
+  const id = hasId && isId(m.id) ? m.id : null;
+  if (m.jsonrpc !== "2.0" || typeof m.method !== "string" || hasId && !isId(m.id)) {
+    return { kind: "error", response: fail(id, INVALID_REQUEST, "Invalid Request") };
+  }
+  const params = "params" in m ? m.params : void 0;
+  if (hasId) {
+    const message2 = { jsonrpc: "2.0", id, method: m.method };
+    if (params !== void 0) message2.params = params;
+    return { kind: "request", message: message2 };
+  }
+  const message = { jsonrpc: "2.0", method: m.method };
+  if (params !== void 0) message.params = params;
+  return { kind: "notification", message };
+}
+
+// src/mcp/prompts.ts
+var INTEGRATE_PROMPT_NAME = "integrate-design-system";
+var INTEGRATE_TEXT = "Integrate the design system this MCP server serves into this repository. Call `get_integration_guide` first and follow it step by step. Detect the stack from the repository itself; do not ask which framework this is.";
+function promptList() {
+  return { prompts: [{ name: INTEGRATE_PROMPT_NAME, description: "Integrate the design system into the current repository, following the guide the server provides.", arguments: [] }] };
+}
+function getPrompt(name) {
+  if (name !== INTEGRATE_PROMPT_NAME) return null;
+  return { description: "Integrate the design system into the current repository.", messages: [{ role: "user", content: { type: "text", text: INTEGRATE_TEXT } }] };
+}
+
+// src/mcp/tools.ts
+var textResult = (text) => ({ content: [{ type: "text", text }] });
+var errorResult = (text) => ({ content: [{ type: "text", text }], isError: true });
+var TIERS = ["design", "semantic", "component"];
+var CATEGORIES = ["color", "spacing", "radius", "typography", "shadow", "zIndex", "border"];
+var NO_INPUT = { type: "object", properties: {}, additionalProperties: false };
+var pretty = (v) => JSON.stringify(v, null, 2);
+var SOURCE_HEADER = "// Reference implementation. Use verbatim in React + Tailwind; port to your stack otherwise, keeping every var() chain.";
+var UTILS_HEADER = "// The `cn` helper every component imports from `@/lib/utils`. Save as lib/utils.ts in React; port or drop elsewhere.";
+var componentsIn = (snapshot) => [...new Set(snapshot.canonical.tokens.map((t) => t.component).filter((c) => c !== null))].sort();
+function optionalEnum(args, key, allowed) {
+  const v = args[key];
+  if (v === void 0) return { ok: true, value: void 0 };
+  if (typeof v !== "string" || !allowed.includes(v)) {
+    return { ok: false, error: errorResult(`"${key}" must be one of: ${allowed.join(", ")}.`) };
+  }
+  return { ok: true, value: v };
+}
+var TOOLS = [
+  {
+    name: "get_project",
+    description: "The design system's name, token count, corner-radius strategy, font families and whether it has a mockup page. Call this first.",
+    inputSchema: NO_INPUT,
+    run: (snapshot, fetchedAt) => textResult(pretty({ ...snapshot.project, fetchedAt: new Date(fetchedAt).toISOString() }))
+  },
+  {
+    name: "get_tokens",
+    description: "Design tokens as {path, $type, $value: {light, dark}, ref}. Filter by tier (design | semantic | component), category and component; every filter is optional and they combine.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tier: { type: "string", enum: [...TIERS] },
+        category: { type: "string", enum: [...CATEGORIES] },
+        component: { type: "string", description: "A component name such as button or card (component tier only)." }
+      },
+      additionalProperties: false
+    },
+    run: (snapshot, _at, args) => {
+      const tier = optionalEnum(args, "tier", TIERS);
+      if (!tier.ok) return tier.error;
+      const category = optionalEnum(args, "category", CATEGORIES);
+      if (!category.ok) return category.error;
+      const components = componentsIn(snapshot);
+      if (args.component !== void 0 && components.length === 0) return errorResult("This project has no component tokens.");
+      const component = optionalEnum(args, "component", components);
+      if (!component.ok) return component.error;
+      const rows = snapshot.canonical.tokens.filter((t) => (tier.value === void 0 || t.tier === tier.value) && (category.value === void 0 || t.category === category.value) && (component.value === void 0 || t.component === component.value)).map(({ path, $type, $value, ref }) => ({ path, $type, $value, ref }));
+      return textResult(rows.length ? pretty(rows) : "No tokens match.");
+    }
+  },
+  {
+    name: "get_css_variables",
+    description: "The whole design system as plain CSS custom properties for any stack: design tokens in :root, semantic and component tokens as var() aliases per theme, light and dark via [data-theme] and prefers-color-scheme.",
+    inputSchema: NO_INPUT,
+    run: (snapshot) => textResult(snapshot.cssVars)
+  },
+  {
+    name: "get_shadcn_theme",
+    description: "The design system as a shadcn/ui theme stylesheet for Tailwind v4: :root and .dark blocks plus @theme inline. Use on the React + Tailwind path.",
+    inputSchema: NO_INPUT,
+    run: (snapshot) => textResult(snapshot.shadcnTheme)
+  },
+  {
+    name: "list_components",
+    description: "Every component in the kit with the CSS variables its source reads, plus the helper files. Follow with get_component_source.",
+    inputSchema: NO_INPUT,
+    run: (snapshot) => textResult(
+      pretty({
+        components: Object.entries(snapshot.kit.variables).sort(([a], [b]) => a.localeCompare(b)).map(([name, variables]) => ({ name, variables })),
+        helpers: Object.keys(snapshot.kit.sources).filter((n) => !(n in snapshot.kit.variables)).sort()
+      })
+    )
+  },
+  {
+    name: "get_component_source",
+    description: 'The React + Tailwind source of one component (see list_components), or "utils" for the cn helper. Use verbatim in React; port to any other stack keeping every var() chain.',
+    inputSchema: { type: "object", properties: { name: { type: "string", description: "A name from list_components, or utils." } }, required: ["name"], additionalProperties: false },
+    run: (snapshot, _at, args) => {
+      const names = Object.keys(snapshot.kit.sources).sort();
+      const name = args.name;
+      if (typeof name !== "string" || !names.includes(name)) return errorResult(`"name" must be one of: ${names.join(", ")}.`);
+      const header = name in snapshot.kit.variables ? SOURCE_HEADER : UTILS_HEADER;
+      return textResult(`${header}
+${snapshot.kit.sources[name]}`);
+    }
+  },
+  {
+    name: "get_mockup_page",
+    description: "The project's own mockup page as a layout spec, followed by the React renderer and schema that paint it. Render it as the first route.",
+    inputSchema: NO_INPUT,
+    run: (snapshot) => {
+      if (!snapshot.mockup) return textResult("This project has no mockup page.");
+      const files = Object.entries(snapshot.mockup.renderer).sort(([a], [b]) => a.localeCompare(b)).map(([file, source]) => `
+--- file: ${file}
+${source}`);
+      return textResult(`${pretty(snapshot.mockup.spec)}
+${files.join("\n")}`);
+    }
+  },
+  {
+    name: "get_integration_guide",
+    description: "Step-by-step instructions for integrating this design system into the current repository: wire the tokens, bring in the components, migrate existing styles, document. Read this before changing anything.",
+    inputSchema: NO_INPUT,
+    run: (snapshot) => textResult(snapshot.guide)
+  }
+];
+var TOOL_NAMES = TOOLS.map((t) => t.name);
+function toolList() {
+  return { tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) };
+}
+function findTool(name) {
+  return TOOLS.find((t) => t.name === name);
+}
+
+// src/mcp/protocol.ts
+var SUPPORTED_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+var asObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v) ? v : {};
+async function handle(parsed, deps) {
+  if (parsed.kind === "error") return parsed.response;
+  if (parsed.kind === "notification") return null;
+  return request(parsed.message, deps);
+}
+async function request(msg, deps) {
+  const { id } = msg;
+  const params = asObject(msg.params);
+  switch (msg.method) {
+    case "initialize": {
+      const asked = params.protocolVersion;
+      const protocolVersion = typeof asked === "string" && SUPPORTED_VERSIONS.includes(asked) ? asked : SUPPORTED_VERSIONS[0];
+      return respond(id, { protocolVersion, capabilities: { tools: {}, prompts: {} }, serverInfo: { name: "designsource", version: deps.version } });
+    }
+    case "ping":
+      return respond(id, {});
+    case "tools/list":
+      return respond(id, toolList());
+    case "tools/call": {
+      if (typeof params.name !== "string") return fail(id, INVALID_PARAMS, 'tools/call needs a string "name"');
+      const tool = findTool(params.name);
+      if (!tool) return fail(id, INVALID_PARAMS, `Unknown tool: ${params.name}`);
+      let cached;
+      try {
+        cached = await deps.snapshot();
+      } catch (e) {
+        if (e instanceof CliError) return respond(id, errorResult(e.message));
+        const message = e instanceof Error ? e.message : String(e);
+        deps.warn(`designsource mcp: loading the design system failed: ${message}`);
+        return respond(id, errorResult(`Could not load the design system: ${message}`));
+      }
+      try {
+        return respond(id, tool.run(cached.snapshot, cached.fetchedAt, asObject(params.arguments)));
+      } catch (e) {
+        if (e instanceof CliError) return respond(id, errorResult(e.message));
+        const message = e instanceof Error ? e.message : String(e);
+        deps.warn(`designsource mcp: tool ${params.name} failed: ${message}`);
+        return respond(id, errorResult(`Tool ${params.name} failed: ${message}`));
+      }
+    }
+    case "prompts/list":
+      return respond(id, promptList());
+    case "prompts/get": {
+      const prompt = typeof params.name === "string" ? getPrompt(params.name) : null;
+      if (!prompt) return fail(id, INVALID_PARAMS, `Unknown prompt: ${String(params.name)}`);
+      return respond(id, prompt);
+    }
+    default:
+      return fail(id, METHOD_NOT_FOUND, `Method not found: ${msg.method}`);
+  }
+}
+
+// src/mcp/snapshot-client.ts
+var malformed2 = () => new CliError("Unexpected response from the API \u2014 not a design system snapshot.");
+var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isStringRecord = (v) => isObject(v) && Object.values(v).every((x) => typeof x === "string");
+var isStringListRecord = (v) => isObject(v) && Object.values(v).every((x) => Array.isArray(x) && x.every((s) => typeof s === "string"));
+function validateSnapshot(json) {
+  if (!isObject(json)) throw malformed2();
+  if (typeof json.version !== "number") throw malformed2();
+  if (json.version !== 1) throw new CliError(UPDATE_MESSAGE);
+  const { project, canonical, cssVars, shadcnTheme, kit, mockup, guide } = json;
+  if (!isObject(project) || typeof project.name !== "string" || typeof project.radiusStrategy !== "string" || typeof project.tokenCount !== "number" || typeof project.hasMockup !== "boolean" || !isStringRecord(project.fonts)) throw malformed2();
+  if (!isObject(canonical) || !Array.isArray(canonical.tokens) || !canonical.tokens.every(isObject)) throw malformed2();
+  if (typeof cssVars !== "string" || typeof shadcnTheme !== "string" || typeof guide !== "string") throw malformed2();
+  if (!isObject(kit) || !isStringRecord(kit.sources) || !isStringListRecord(kit.variables)) throw malformed2();
+  if (mockup !== null && !(isObject(mockup) && isObject(mockup.spec) && isStringRecord(mockup.renderer))) throw malformed2();
+  return json;
+}
+var FETCH_TIMEOUT_MS = 3e4;
+async function fetchSnapshot(opts, fetchImpl = fetch) {
+  const url = new URL("/api/snapshot", `${opts.api}/`);
+  let res;
+  try {
+    res = await fetchImpl(url.toString(), {
+      headers: { Authorization: `Bearer ${opts.token}`, Accept: "application/json" },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+    });
+  } catch {
+    throw new CliError(UNREACHABLE(opts.api));
+  }
+  const body = await res.json().catch(() => null);
+  if (!res.ok) throw new CliError(messageForResponse(res.status, body, opts.api));
+  return validateSnapshot(body);
+}
+function createSnapshotCache(fetcher, opts = {}) {
+  const ttl = opts.ttlMs ?? 6e4;
+  const now = opts.now ?? Date.now;
+  let cached = null;
+  let inflight = null;
+  return {
+    get() {
+      if (cached && now() - cached.fetchedAt < ttl) return Promise.resolve(cached);
+      if (inflight) return inflight;
+      inflight = fetcher().then((snapshot) => {
+        cached = { snapshot, fetchedAt: now() };
+        return cached;
+      }).catch((e) => {
+        if (!cached) throw e;
+        opts.warn?.(`Could not refresh the design system; serving the snapshot from ${new Date(cached.fetchedAt).toISOString()}: ${e instanceof Error ? e.message : String(e)}`);
+        return cached;
+      }).finally(() => {
+        inflight = null;
+      });
+      return inflight;
+    }
+  };
+}
+
+// src/mcp/server.ts
+async function runMcp(args, io, streams = { input: process.stdin, output: process.stdout }) {
+  const token = args.token;
+  if (!token) throw new CliError("A project token is required: pass --token or set DS_SYNC_TOKEN (workbench \u2192 Project settings).");
+  const warn = (line) => io.stderr(`${line}
+`);
+  const cache = createSnapshotCache(() => fetchSnapshot({ api: args.api, token }, io.fetchImpl), { warn });
+  const deps = { version: VERSION, snapshot: () => cache.get(), warn };
+  const lines = createInterface2({ input: streams.input, crlfDelay: Infinity });
+  streams.output.on("error", () => {
+    lines.close();
+  });
+  for await (const raw of lines) {
+    const line = raw.trim();
+    if (!line) continue;
+    const response = await handle(parseLine(line), deps);
+    if (response) streams.output.write(encode(response));
+  }
+}
+
 // src/index.ts
 var MENU = [
   { value: "integrate", label: "Add to an existing project", hint: "writes design-system/ \u2014 tokens, prompt, reference kit" },
@@ -493,7 +831,7 @@ ${e.usage}`);
   try {
     if (command.kind === "menu") {
       if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
-        io.stderr(`Missing command. Use integrate or create.
+        io.stderr(`Missing command. Use integrate, create or mcp.
 
 ${USAGE}`);
         return 1;
@@ -501,6 +839,10 @@ ${USAGE}`);
       const verb = await pick("What do you want to do?", MENU, 0);
       command = verb === "create" ? { kind: "create", args: baseArgs(env) } : { kind: "integrate", args: baseArgs(env) };
     }
+    if (command.kind === "mcp") {
+      await runMcp(command.args, io);
+      return 0;
+    }
     if (command.kind === "create") await runCreate(command.args, env, io);
     else await runIntegrate(command.args, env, io);
     return 0;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "designsource",
-  "version": "0.2.1",
-  "description": "The DS source CLI: add a design system to an existing app (integrate) or start a new Next.js project from it (create) — tokens, every component and your mockup page.",
+  "version": "0.3.0",
+  "description": "The DS source CLI: add a design system to an existing app (integrate), start a new Next.js project from it (create), or serve it to a coding agent over MCP (mcp) — tokens, every component and your mockup page.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -19,7 +19,9 @@
     "shadcn",
     "vue",
     "svelte",
-    "angular"
+    "angular",
+    "mcp",
+    "model-context-protocol"
   ],
   "type": "module",
   "bin": {