@fragments-sdk/mcp

Standalone MCP server for the Fragments design system. Gives AI coding assistants (Claude Code, Cursor, etc.) intelligent component discovery over components, blocks, and tokens — no Playwright or build tools required.

Setup

Add a project-level MCP config to your workspace root. This ensures the server runs from your project directory and auto-discovers fragments.json via node_modules.

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "fragments": {
      "command": "npx",
      "args": ["-y", "@fragments-sdk/mcp"]
    }
  }
}

VS Code

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "fragments": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fragments-sdk/mcp"]
    }
  }
}

Claude Code

claude mcp add fragments -- npx -y @fragments-sdk/mcp

Windsurf

Create .windsurf/mcp.json in your project root:

{
  "mcpServers": {
    "fragments": {
      "command": "npx",
      "args": ["-y", "@fragments-sdk/mcp"]
    }
  }
}

How discovery works

The server auto-discovers fragments.json through two layers:

1. MCP roots — In IDEs that support the MCP roots/list capability (VS Code, Claude Code), the server automatically detects your workspace root. This means global MCP configs just work.
2. cwd fallback — For IDEs that don't yet support roots/list (Cursor), the server uses process.cwd(). Project-level configs ensure cwd = your workspace root.

Once the project root is known, the server walks up from it, scans package.json dependencies for packages with a "fragments" field, and resolves through node_modules (supporting pnpm, Yarn, and npm).

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) | | fragments_graph | Query the component relationship graph (dependencies, impact, composition, health) | | fragments_a11y | Run an accessibility audit on a component (requires dev server) |

How search works

Queries use keyword search with synonym expansion, weighted multi-field scoring (name, description, tags, usage, category, variants), and category-aware ranking — all running locally against your fragments.json. No external API calls are made.

Premium: Pass --api-key to enable semantic vector search (Voyage-Code-3 embeddings) fused with keyword results via Reciprocal Rank Fusion for deeper, meaning-based discovery.

Options

-p, --project-root <path>  Project root (default: cwd)
-u, --viewer-url <url>     Dev server URL for render/fix/a11y tools
-k, --api-key <key>        Premium API key for semantic vector search