@fragments-sdk/mcp

Source-available. This package is distributed publicly on npm under FSL-1.1-MIT; source stays private. Contribute by filing an issue at https://github.com/fragments-sdk/fragments/issues.

Standalone MCP server for Fragments. It helps AI coding assistants validate generated UI against your design system: check candidate specs, repair safe governance failures, suggest design tokens before hardcoded CSS is written, and triage real Fragments Cloud findings.

The public MCP surface is intentionally small: govern, validate_and_fix, tokens.suggest, findings_list, findings_summary, findings_for_file, and swap_to_canonical.

Setup

The recommended setup writes both MCP config and IDE rules that teach agents the validator loop:

npx @fragments-sdk/mcp@latest init

You can also add a project-level MCP config to your workspace root manually. 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).

Validator Loop

Ask your AI assistant to follow this loop whenever it generates or edits JSX, class names, style props, or CSS:

1. Draft the UI spec or code change.
2. Call govern({ spec }).
3. If the result asks for revision, call validate_and_fix({ spec, applyFixes: true }).
4. Apply deterministic repairs and run govern again.
5. Before writing hardcoded CSS values, call tokens.suggest({ property, value }) and use the returned cssValue when present.

Tools

| Tool | Description | |------|-------------| | govern | Validate an AI-generated UI spec and return violations/fix guidance | | validate_and_fix | Deterministically repair safe governance failures and return a fixed spec | | tokens.suggest | Suggest the right design token for a CSS property and optional raw value | | findings_list | List Cloud governance findings for agent planning | | findings_summary | Summarize Cloud findings by severity, category, rule, and file | | findings_for_file | Retrieve open Cloud findings for the file an agent is editing | | swap_to_canonical | Suggest swaps from raw HTML (<button>, <input>, <dialog>, …) to the project's canonical components when a mapping is at confidence auto or overridden |

How Token Suggestions Work

Validator tools run locally against your fragments.json or against a Cloud catalog when configured. Token suggestions use property-family-aware matching so color properties receive color tokens, spacing properties receive spacing tokens, and unsupported properties return an honest noSuggestion result.

Options

-p, --project-root <path>  Project root (default: cwd)
--cloud-api-key <key>      Cloud API key for org-scoped catalog and findings
--generate-rules           Generate IDE rules files and exit