@domphy/mcp 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Huu Khanh Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# @domphy/mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that gives MCP-capable AI agents (Claude Desktop, Cursor, …) first-class access to Domphy — so they can look up the real API and validate their own output instead of guessing.
+
+## Tools
+
+| Tool | Does |
+| --- | --- |
+| `domphy_list_patches` | every `@domphy/ui` patch with host tag + signature |
+| `domphy_get_patch` | one patch's full contract (host tag, signature, doc, source) |
+| `domphy_list_packages` | all `@domphy/*` packages with versions + descriptions |
+| `domphy_rules` | the Domphy code-generation rules (`llms.txt`) |
+| `domphy_diagnose` | run [`@domphy/doctor`](https://www.domphy.com/docs/doctor/) on a JSON element tree and return issues to fix |
+
+Patch/package data is fetched live from `domphy.com` (always current with the latest release); `domphy_diagnose` runs locally.
+
+## Use
+
+### Claude Desktop / Claude Code
+
+```json
+{
+  "mcpServers": {
+    "domphy": { "command": "npx", "args": ["-y", "@domphy/mcp"] }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{ "mcpServers": { "domphy": { "command": "npx", "args": ["-y", "@domphy/mcp"] } } }
+```
+
+Once connected, the agent can call `domphy_get_patch`/`domphy_rules` before writing code and `domphy_diagnose` after — the self-correction loop that lets it write correct Domphy despite thin training data.
+
+Set `DOMPHY_ORIGIN` to point at a different docs origin (e.g. a preview deploy).

package/dist/chunk-QJ7O62KB.js

@@ -0,0 +1,54 @@
+// src/tools.ts
+import { diagnose, format } from "@domphy/doctor";
+var ORIGIN = process.env.DOMPHY_ORIGIN ?? "https://www.domphy.com";
+var cache = null;
+async function loadManifest() {
+  if (cache) return cache;
+  const res = await fetch(`${ORIGIN}/manifest.json`);
+  if (!res.ok) throw new Error(`Failed to fetch manifest: ${res.status}`);
+  cache = await res.json();
+  return cache;
+}
+async function listPatches() {
+  const m = await loadManifest();
+  return m.patches.map(
+    (p) => `${p.name}${p.hostTag ? ` <${p.hostTag}>` : ""} \u2014 ${p.signature}`
+  ).join("\n");
+}
+async function getPatch(name) {
+  const m = await loadManifest();
+  const patch = m.patches.find((p) => p.name === name);
+  if (!patch) {
+    const near = m.patches.filter((p) => p.name.includes(name) || name.includes(p.name)).map((p) => p.name);
+    return `No patch named "${name}".${near.length ? ` Did you mean: ${near.join(", ")}?` : ""}`;
+  }
+  return JSON.stringify(patch, null, 2);
+}
+async function listPackages() {
+  const m = await loadManifest();
+  return m.packages.map((p) => `${p.name}@${p.version} \u2014 ${p.description}`).join("\n");
+}
+async function getRules() {
+  const res = await fetch(`${ORIGIN}/llms.txt`);
+  if (!res.ok) throw new Error(`Failed to fetch rules: ${res.status}`);
+  return res.text();
+}
+function diagnoseTree(elementJson) {
+  let tree;
+  try {
+    tree = JSON.parse(elementJson);
+  } catch (error) {
+    return `Invalid JSON: ${error.message}`;
+  }
+  return format(diagnose(tree));
+}
+
+export {
+  loadManifest,
+  listPatches,
+  getPatch,
+  listPackages,
+  getRules,
+  diagnoseTree
+};
+//# sourceMappingURL=chunk-QJ7O62KB.js.map

package/dist/chunk-QJ7O62KB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tools.ts"],"sourcesContent":["import { diagnose, format } from \"@domphy/doctor\";\n\n/**\n * Pure tool implementations for the Domphy MCP server. Kept transport-free so\n * they are unit-testable. The server (index.ts) wires these to MCP requests.\n */\n\nconst ORIGIN = process.env.DOMPHY_ORIGIN ?? \"https://www.domphy.com\";\n\ninterface Manifest {\n  version: string;\n  packages: Array<{\n    name: string;\n    version: string;\n    description: string;\n    subpaths: string[];\n    peerDependencies: string[];\n  }>;\n  patches: Array<{\n    name: string;\n    hostTag: string | null;\n    signature: string;\n    doc: string;\n    source: string;\n  }>;\n}\n\nlet cache: Manifest | null = null;\n\nexport async function loadManifest(): Promise<Manifest> {\n  if (cache) return cache;\n  const res = await fetch(`${ORIGIN}/manifest.json`);\n  if (!res.ok) throw new Error(`Failed to fetch manifest: ${res.status}`);\n  cache = (await res.json()) as Manifest;\n  return cache;\n}\n\nexport async function listPatches(): Promise<string> {\n  const m = await loadManifest();\n  return m.patches\n    .map(\n      (p) => `${p.name}${p.hostTag ? ` <${p.hostTag}>` : \"\"} — ${p.signature}`,\n    )\n    .join(\"\\n\");\n}\n\nexport async function getPatch(name: string): Promise<string> {\n  const m = await loadManifest();\n  const patch = m.patches.find((p) => p.name === name);\n  if (!patch) {\n    const near = m.patches\n      .filter((p) => p.name.includes(name) || name.includes(p.name))\n      .map((p) => p.name);\n    return `No patch named \"${name}\".${near.length ? ` Did you mean: ${near.join(\", \")}?` : \"\"}`;\n  }\n  return JSON.stringify(patch, null, 2);\n}\n\nexport async function listPackages(): Promise<string> {\n  const m = await loadManifest();\n  return m.packages\n    .map((p) => `${p.name}@${p.version} — ${p.description}`)\n    .join(\"\\n\");\n}\n\nexport async function getRules(): Promise<string> {\n  const res = await fetch(`${ORIGIN}/llms.txt`);\n  if (!res.ok) throw new Error(`Failed to fetch rules: ${res.status}`);\n  return res.text();\n}\n\n/** Runs @domphy/doctor on a JSON element tree (static parts only). */\nexport function diagnoseTree(elementJson: string): string {\n  let tree: unknown;\n  try {\n    tree = JSON.parse(elementJson);\n  } catch (error) {\n    return `Invalid JSON: ${(error as Error).message}`;\n  }\n  return format(diagnose(tree));\n}\n"],"mappings":";AAAA,SAAS,UAAU,cAAc;AAOjC,IAAM,SAAS,QAAQ,IAAI,iBAAiB;AAoB5C,IAAI,QAAyB;AAE7B,eAAsB,eAAkC;AACtD,MAAI,MAAO,QAAO;AAClB,QAAM,MAAM,MAAM,MAAM,GAAG,MAAM,gBAAgB;AACjD,MAAI,CAAC,IAAI,GAAI,OAAM,IAAI,MAAM,6BAA6B,IAAI,MAAM,EAAE;AACtE,UAAS,MAAM,IAAI,KAAK;AACxB,SAAO;AACT;AAEA,eAAsB,cAA+B;AACnD,QAAM,IAAI,MAAM,aAAa;AAC7B,SAAO,EAAE,QACN;AAAA,IACC,CAAC,MAAM,GAAG,EAAE,IAAI,GAAG,EAAE,UAAU,KAAK,EAAE,OAAO,MAAM,EAAE,WAAM,EAAE,SAAS;AAAA,EACxE,EACC,KAAK,IAAI;AACd;AAEA,eAAsB,SAAS,MAA+B;AAC5D,QAAM,IAAI,MAAM,aAAa;AAC7B,QAAM,QAAQ,EAAE,QAAQ,KAAK,CAAC,MAAM,EAAE,SAAS,IAAI;AACnD,MAAI,CAAC,OAAO;AACV,UAAM,OAAO,EAAE,QACZ,OAAO,CAAC,MAAM,EAAE,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,EAAE,IAAI,CAAC,EAC5D,IAAI,CAAC,MAAM,EAAE,IAAI;AACpB,WAAO,mBAAmB,IAAI,KAAK,KAAK,SAAS,kBAAkB,KAAK,KAAK,IAAI,CAAC,MAAM,EAAE;AAAA,EAC5F;AACA,SAAO,KAAK,UAAU,OAAO,MAAM,CAAC;AACtC;AAEA,eAAsB,eAAgC;AACpD,QAAM,IAAI,MAAM,aAAa;AAC7B,SAAO,EAAE,SACN,IAAI,CAAC,MAAM,GAAG,EAAE,IAAI,IAAI,EAAE,OAAO,WAAM,EAAE,WAAW,EAAE,EACtD,KAAK,IAAI;AACd;AAEA,eAAsB,WAA4B;AAChD,QAAM,MAAM,MAAM,MAAM,GAAG,MAAM,WAAW;AAC5C,MAAI,CAAC,IAAI,GAAI,OAAM,IAAI,MAAM,0BAA0B,IAAI,MAAM,EAAE;AACnE,SAAO,IAAI,KAAK;AAClB;AAGO,SAAS,aAAa,aAA6B;AACxD,MAAI;AACJ,MAAI;AACF,WAAO,KAAK,MAAM,WAAW;AAAA,EAC/B,SAAS,OAAO;AACd,WAAO,iBAAkB,MAAgB,OAAO;AAAA,EAClD;AACA,SAAO,OAAO,SAAS,IAAI,CAAC;AAC9B;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import {
+  diagnoseTree,
+  getPatch,
+  getRules,
+  listPackages,
+  listPatches
+} from "./chunk-QJ7O62KB.js";
+
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+var server = new Server(
+  { name: "domphy", version: "0.10.0" },
+  { capabilities: { tools: {} } }
+);
+var tools = [
+  {
+    name: "domphy_list_patches",
+    description: "List every @domphy/ui patch with its host tag and signature.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "domphy_get_patch",
+    description: "Get one patch's full contract (host tag, signature, doc, source).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "patch name, e.g. button" }
+      },
+      required: ["name"]
+    }
+  },
+  {
+    name: "domphy_list_packages",
+    description: "List all @domphy/* packages with versions and descriptions.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "domphy_rules",
+    description: "Get the Domphy code-generation rules (llms.txt) to follow.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "domphy_diagnose",
+    description: "Run @domphy/doctor on a JSON Domphy element tree and return issues to fix (inline-typography, void-content, unknown-tag, \u2026).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        element: {
+          type: "string",
+          description: "JSON of the Domphy element tree"
+        }
+      },
+      required: ["element"]
+    }
+  }
+];
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name } = request.params;
+  const args = request.params.arguments ?? {};
+  let text;
+  try {
+    switch (name) {
+      case "domphy_list_patches":
+        text = await listPatches();
+        break;
+      case "domphy_get_patch":
+        text = await getPatch(String(args.name));
+        break;
+      case "domphy_list_packages":
+        text = await listPackages();
+        break;
+      case "domphy_rules":
+        text = await getRules();
+        break;
+      case "domphy_diagnose":
+        text = diagnoseTree(String(args.element));
+        break;
+      default:
+        text = `Unknown tool: ${name}`;
+    }
+  } catch (error) {
+    text = `Error: ${error.message}`;
+  }
+  return { content: [{ type: "text", text }] };
+});
+await server.connect(new StdioServerTransport());
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport {\n  CallToolRequestSchema,\n  ListToolsRequestSchema,\n} from \"@modelcontextprotocol/sdk/types.js\";\nimport {\n  diagnoseTree,\n  getPatch,\n  getRules,\n  listPackages,\n  listPatches,\n} from \"./tools.js\";\n\nconst server = new Server(\n  { name: \"domphy\", version: \"0.10.0\" },\n  { capabilities: { tools: {} } },\n);\n\nconst tools = [\n  {\n    name: \"domphy_list_patches\",\n    description: \"List every @domphy/ui patch with its host tag and signature.\",\n    inputSchema: { type: \"object\", properties: {} },\n  },\n  {\n    name: \"domphy_get_patch\",\n    description:\n      \"Get one patch's full contract (host tag, signature, doc, source).\",\n    inputSchema: {\n      type: \"object\",\n      properties: {\n        name: { type: \"string\", description: \"patch name, e.g. button\" },\n      },\n      required: [\"name\"],\n    },\n  },\n  {\n    name: \"domphy_list_packages\",\n    description: \"List all @domphy/* packages with versions and descriptions.\",\n    inputSchema: { type: \"object\", properties: {} },\n  },\n  {\n    name: \"domphy_rules\",\n    description: \"Get the Domphy code-generation rules (llms.txt) to follow.\",\n    inputSchema: { type: \"object\", properties: {} },\n  },\n  {\n    name: \"domphy_diagnose\",\n    description:\n      \"Run @domphy/doctor on a JSON Domphy element tree and return issues to fix (inline-typography, void-content, unknown-tag, …).\",\n    inputSchema: {\n      type: \"object\",\n      properties: {\n        element: {\n          type: \"string\",\n          description: \"JSON of the Domphy element tree\",\n        },\n      },\n      required: [\"element\"],\n    },\n  },\n];\n\nserver.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));\n\nserver.setRequestHandler(CallToolRequestSchema, async (request) => {\n  const { name } = request.params;\n  const args = (request.params.arguments ?? {}) as Record<string, unknown>;\n  let text: string;\n  try {\n    switch (name) {\n      case \"domphy_list_patches\":\n        text = await listPatches();\n        break;\n      case \"domphy_get_patch\":\n        text = await getPatch(String(args.name));\n        break;\n      case \"domphy_list_packages\":\n        text = await listPackages();\n        break;\n      case \"domphy_rules\":\n        text = await getRules();\n        break;\n      case \"domphy_diagnose\":\n        text = diagnoseTree(String(args.element));\n        break;\n      default:\n        text = `Unknown tool: ${name}`;\n    }\n  } catch (error) {\n    text = `Error: ${(error as Error).message}`;\n  }\n  return { content: [{ type: \"text\", text }] };\n});\n\nawait server.connect(new StdioServerTransport());\n"],"mappings":";;;;;;;;;;AACA,SAAS,cAAc;AACvB,SAAS,4BAA4B;AACrC;AAAA,EACE;AAAA,EACA;AAAA,OACK;AASP,IAAM,SAAS,IAAI;AAAA,EACjB,EAAE,MAAM,UAAU,SAAS,SAAS;AAAA,EACpC,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,EAAE;AAChC;AAEA,IAAM,QAAQ;AAAA,EACZ;AAAA,IACE,MAAM;AAAA,IACN,aAAa;AAAA,IACb,aAAa,EAAE,MAAM,UAAU,YAAY,CAAC,EAAE;AAAA,EAChD;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,aACE;AAAA,IACF,aAAa;AAAA,MACX,MAAM;AAAA,MACN,YAAY;AAAA,QACV,MAAM,EAAE,MAAM,UAAU,aAAa,0BAA0B;AAAA,MACjE;AAAA,MACA,UAAU,CAAC,MAAM;AAAA,IACnB;AAAA,EACF;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,aAAa;AAAA,IACb,aAAa,EAAE,MAAM,UAAU,YAAY,CAAC,EAAE;AAAA,EAChD;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,aAAa;AAAA,IACb,aAAa,EAAE,MAAM,UAAU,YAAY,CAAC,EAAE;AAAA,EAChD;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,aACE;AAAA,IACF,aAAa;AAAA,MACX,MAAM;AAAA,MACN,YAAY;AAAA,QACV,SAAS;AAAA,UACP,MAAM;AAAA,UACN,aAAa;AAAA,QACf;AAAA,MACF;AAAA,MACA,UAAU,CAAC,SAAS;AAAA,IACtB;AAAA,EACF;AACF;AAEA,OAAO,kBAAkB,wBAAwB,aAAa,EAAE,MAAM,EAAE;AAExE,OAAO,kBAAkB,uBAAuB,OAAO,YAAY;AACjE,QAAM,EAAE,KAAK,IAAI,QAAQ;AACzB,QAAM,OAAQ,QAAQ,OAAO,aAAa,CAAC;AAC3C,MAAI;AACJ,MAAI;AACF,YAAQ,MAAM;AAAA,MACZ,KAAK;AACH,eAAO,MAAM,YAAY;AACzB;AAAA,MACF,KAAK;AACH,eAAO,MAAM,SAAS,OAAO,KAAK,IAAI,CAAC;AACvC;AAAA,MACF,KAAK;AACH,eAAO,MAAM,aAAa;AAC1B;AAAA,MACF,KAAK;AACH,eAAO,MAAM,SAAS;AACtB;AAAA,MACF,KAAK;AACH,eAAO,aAAa,OAAO,KAAK,OAAO,CAAC;AACxC;AAAA,MACF;AACE,eAAO,iBAAiB,IAAI;AAAA,IAChC;AAAA,EACF,SAAS,OAAO;AACd,WAAO,UAAW,MAAgB,OAAO;AAAA,EAC3C;AACA,SAAO,EAAE,SAAS,CAAC,EAAE,MAAM,QAAQ,KAAK,CAAC,EAAE;AAC7C,CAAC;AAED,MAAM,OAAO,QAAQ,IAAI,qBAAqB,CAAC;","names":[]}

package/dist/tools.d.ts

@@ -0,0 +1,26 @@
+interface Manifest {
+    version: string;
+    packages: Array<{
+        name: string;
+        version: string;
+        description: string;
+        subpaths: string[];
+        peerDependencies: string[];
+    }>;
+    patches: Array<{
+        name: string;
+        hostTag: string | null;
+        signature: string;
+        doc: string;
+        source: string;
+    }>;
+}
+declare function loadManifest(): Promise<Manifest>;
+declare function listPatches(): Promise<string>;
+declare function getPatch(name: string): Promise<string>;
+declare function listPackages(): Promise<string>;
+declare function getRules(): Promise<string>;
+/** Runs @domphy/doctor on a JSON element tree (static parts only). */
+declare function diagnoseTree(elementJson: string): string;
+
+export { diagnoseTree, getPatch, getRules, listPackages, listPatches, loadManifest };

package/dist/tools.js

@@ -0,0 +1,17 @@
+import {
+  diagnoseTree,
+  getPatch,
+  getRules,
+  listPackages,
+  listPatches,
+  loadManifest
+} from "./chunk-QJ7O62KB.js";
+export {
+  diagnoseTree,
+  getPatch,
+  getRules,
+  listPackages,
+  listPatches,
+  loadManifest
+};
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@domphy/mcp",
+  "version": "0.10.0",
+  "description": "Domphy MCP server - exposes patches, packages, rules, and the doctor to MCP-capable AI agents",
+  "type": "module",
+  "bin": {
+    "domphy-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./tools": {
+      "import": {
+        "types": "./dist/tools.d.ts",
+        "default": "./dist/tools.js"
+      }
+    }
+  },
+  "keywords": [
+    "domphy",
+    "mcp",
+    "ai",
+    "model-context-protocol"
+  ],
+  "author": "Huu Khanh Nguyen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/domphy/domphy.git",
+    "directory": "packages/mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@domphy/doctor": "^0.10.0"
+  },
+  "peerDependencies": {
+    "@domphy/core": "^0.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "vitest": "^4.0.18",
+    "@domphy/core": "0.10.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}