@fragments-sdk/mcp 0.2.3 → 0.3.0

package/README.md

@@ -1,12 +1,10 @@
 # @fragments-sdk/mcp
 
-MCP (Model Context Protocol) server that gives AI agents access to your design system. Agents can list components, get usage guidelines, view code examples, suggest components for use cases, and more.
+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.
 
-## Quick Start
+## Setup
 
-### With Claude Code
-
-Add to your Claude Code MCP settings (`~/.claude/settings.json`):
+Add to your editor's MCP config:
 
 ```json
 {
@@ -19,73 +17,37 @@ Add to your Claude Code MCP settings (`~/.claude/settings.json`):
 }
 ```
 
-The server automatically discovers `fragments.json` from any installed package that declares a `"fragments"` field in its `package.json` (e.g., `@fragments-sdk/ui`).
-
-### With other MCP clients
-
-Run the server directly:
-
-```bash
-npx @fragments-sdk/mcp
-```
-
-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
-```
-
-## How It Works
-
-1. Install a component library that ships `fragments.json` (e.g., `npm install @fragments-sdk/ui`)
-2. Add this MCP server to your AI tool
-3. The server reads `fragments.json` from the installed package and exposes component data to the AI agent
-
-The server searches for `fragments.json` in two places:
-- **Your project directory** (walks upward from cwd) — for library authors running `fragments build`
-- **Your package.json dependencies** — for consumers who installed a fragments-enabled package
+The server auto-discovers `fragments.json` by walking up from cwd and scanning `node_modules`.
 
-## Available Tools
+## Tools
 
 | Tool | Description |
 |------|-------------|
-| `fragments_context` | Get full design system context in one call. Use this first. |
-| `fragments_list` | List all components with names, categories, and variant counts |
-| `fragments_get` | Get detailed component info: props, usage, variants |
-| `fragments_suggest` | Suggest components for a use case (e.g., "form for email input") |
-| `fragments_guidelines` | Get when/when-not-to-use guidelines and accessibility rules |
-| `fragments_alternatives` | Find alternative or related components |
-| `fragments_example` | Get ready-to-use code examples for component variants |
-| `fragments_recipe` | Search composition recipes (e.g., "Login Form", "Settings Page") |
-| `fragments_render` | Render a component with specific props and return a screenshot |
-| `fragments_verify` | Verify a component render against the baseline screenshot |
-| `fragments_compare` | Compare a rendered component against its Figma design |
-| `fragments_fix` | Generate patches to fix token compliance issues |
+| `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) |
 
-### Visual tools
+## How search works
 
-The `render`, `verify`, `compare`, and `fix` tools require [Playwright](https://playwright.dev/). Install it separately if you need visual tools:
-
-```bash
-npm install playwright
-```
+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.
 
-These tools are optional. All other tools work without Playwright.
+## Options
 
-## Programmatic Usage
-
-```typescript
-import { createMcpServer, startMcpServer } from '@fragments-sdk/mcp';
+```
+-p, --project-root <path>  Project root (default: cwd)
+-u, --viewer-url <url>     Dev server URL for render/fix tools
+```
 
-// Start with stdio transport (default)
-await startMcpServer({ projectRoot: process.cwd() });
+## Convex backend
 
-// Or create the server instance for custom transports
-const server = createMcpServer({ projectRoot: process.cwd() });
-```
+The `convex/` directory contains the hosted search backend:
 
-## License
+- **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
 
-MIT
+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.3",
-  "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":[]}