@fragments-sdk/mcp 0.2.2 → 0.3.0

package/README.md

@@ -0,0 +1,53 @@
+# @fragments-sdk/mcp
+
+Standalone MCP server for the Fragments design system. Gives AI coding assistants (Claude Code, Cursor, etc.) semantic search over components, blocks, and tokens — no Playwright or build tools required.
+
+## Setup
+
+Add to your editor's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "fragments": {
+      "command": "npx",
+      "args": ["@fragments-sdk/mcp"]
+    }
+  }
+}
+```
+
+The server auto-discovers `fragments.json` by walking up from cwd and scanning `node_modules`.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `fragments_discover` | List, search, or get AI-powered component suggestions |
+| `fragments_inspect` | Full component details — props, examples, guidelines |
+| `fragments_blocks` | Composition patterns (e.g. "Login Form", "Settings Page") |
+| `fragments_tokens` | CSS custom properties by category |
+| `fragments_implement` | One-shot: components + blocks + tokens for a use case |
+| `fragments_render` | Render a component screenshot (requires dev server) |
+| `fragments_fix` | Generate token-compliance patches (requires dev server) |
+
+## How search works
+
+Queries run through **hybrid search** — Convex-hosted vector search (Voyage-Code-3 embeddings) fused with local keyword scoring via Reciprocal Rank Fusion. If Convex is unreachable, falls back silently to keyword-only.
+
+## Options
+
+```
+-p, --project-root <path>  Project root (default: cwd)
+-u, --viewer-url <url>     Dev server URL for render/fix tools
+```
+
+## Convex backend
+
+The `convex/` directory contains the hosted search backend:
+
+- **schema.ts** — `entries` table with vector index (components, blocks, tokens)
+- **search.ts** — HTTP action that embeds queries with Voyage-Code-3 and runs vector search
+- **ingest.ts** — Mutation to upsert entries at publish time
+
+Index entries: `pnpm --filter @fragments-sdk/mcp index` (requires `VOYAGE_API_KEY` and `CONVEX_URL`).

package/package.json

@@ -1,19 +1,20 @@
 {
   "name": "@fragments-sdk/mcp",
-  "version": "0.2.2",
-  "description": "MCP server for AI agent integration with Fragments",
+  "version": "0.3.0",
+  "description": "Standalone MCP server for Fragments design system — zero-config component discovery with semantic search",
   "type": "module",
   "bin": {
     "fragments-mcp": "./dist/bin.js"
   },
+  "main": "./dist/server.js",
+  "module": "./dist/server.js",
+  "types": "./dist/server.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
     }
   },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "publishConfig": {
     "access": "public"
   },
@@ -24,27 +25,17 @@
     "@modelcontextprotocol/sdk": "^1.0.0"
   },
   "devDependencies": {
-    "@types/node": "^20.10.0",
-    "tsup": "^8.0.1",
-    "typescript": "^5.7.2",
-    "vitest": "^2.1.9",
-    "@fragments/core": "0.2.0",
-    "@fragments/service": "0.1.1"
-  },
-  "peerDependencies": {
-    "typescript": "^5.0.0",
-    "playwright": "^1.40.0"
-  },
-  "peerDependenciesMeta": {
-    "playwright": {
-      "optional": true
-    }
+    "@types/node": "^22.0.0",
+    "convex": "^1.17.0",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.2"
   },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "test": "vitest run",
     "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "index": "tsx scripts/index-components.ts"
   }
 }

package/dist/bin.d.ts

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

package/dist/bin.js

@@ -1,37 +0,0 @@
-#!/usr/bin/env node
-import { createRequire } from 'module'; const require = createRequire(import.meta.url);
-import {
-  startMcpServer
-} from "./chunk-OQOBENAX.js";
-import "./chunk-7OMNY6JX.js";
-
-// src/bin.ts
-var args = process.argv.slice(2);
-var projectRoot = process.cwd();
-var viewerUrl;
-for (let i = 0; i < args.length; i++) {
-  const arg = args[i];
-  if (arg === "--project-root" || arg === "-p") {
-    projectRoot = args[++i] ?? projectRoot;
-  } else if (arg === "--viewer-url" || arg === "-u") {
-    viewerUrl = args[++i];
-  } else if (arg === "--help" || arg === "-h") {
-    console.log(`
-Usage: fragments-mcp [options]
-
-Options:
-  -p, --project-root <path>  Project root directory (default: cwd)
-  -u, --viewer-url <url>     Viewer URL (default: http://localhost:6006)
-  -h, --help                 Show this help message
-`);
-    process.exit(0);
-  }
-}
-startMcpServer({
-  projectRoot,
-  viewerUrl
-}).catch((error) => {
-  console.error("Failed to start MCP server:", error);
-  process.exit(1);
-});
-//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { startMcpServer } from './server.js';\n\n// Parse command line arguments\nconst args = process.argv.slice(2);\nlet projectRoot = process.cwd();\nlet viewerUrl: string | undefined;\n\nfor (let i = 0; i < args.length; i++) {\n  const arg = args[i];\n\n  if (arg === '--project-root' || arg === '-p') {\n    projectRoot = args[++i] ?? projectRoot;\n  } else if (arg === '--viewer-url' || arg === '-u') {\n    viewerUrl = args[++i];\n  } else if (arg === '--help' || arg === '-h') {\n    console.log(`\nUsage: fragments-mcp [options]\n\nOptions:\n  -p, --project-root <path>  Project root directory (default: cwd)\n  -u, --viewer-url <url>     Viewer URL (default: http://localhost:6006)\n  -h, --help                 Show this help message\n`);\n    process.exit(0);\n  }\n}\n\n// Start server\nstartMcpServer({\n  projectRoot,\n  viewerUrl,\n}).catch((error) => {\n  console.error('Failed to start MCP server:', error);\n  process.exit(1);\n});\n"],"mappings":";;;;;;;;AAIA,IAAM,OAAO,QAAQ,KAAK,MAAM,CAAC;AACjC,IAAI,cAAc,QAAQ,IAAI;AAC9B,IAAI;AAEJ,SAAS,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;AACpC,QAAM,MAAM,KAAK,CAAC;AAElB,MAAI,QAAQ,oBAAoB,QAAQ,MAAM;AAC5C,kBAAc,KAAK,EAAE,CAAC,KAAK;AAAA,EAC7B,WAAW,QAAQ,kBAAkB,QAAQ,MAAM;AACjD,gBAAY,KAAK,EAAE,CAAC;AAAA,EACtB,WAAW,QAAQ,YAAY,QAAQ,MAAM;AAC3C,YAAQ,IAAI;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,CAOf;AACG,YAAQ,KAAK,CAAC;AAAA,EAChB;AACF;AAGA,eAAe;AAAA,EACb;AAAA,EACA;AACF,CAAC,EAAE,MAAM,CAAC,UAAU;AAClB,UAAQ,MAAM,+BAA+B,KAAK;AAClD,UAAQ,KAAK,CAAC;AAChB,CAAC;","names":[]}