@fragments-sdk/cli

CLI, MCP server, and dev tools for the Fragments design system. This is the single tool package — it includes the CLI commands, the MCP server for AI agents, the dev viewer, screenshot capture, visual diffing, and migration tools.

Install

npm install @fragments-sdk/cli

CLI Usage

# Build fragments.json
fragments build

# Validate fragment files
fragments validate

# Generate AI-ready context
fragments context

# See all commands
fragments --help

MCP Server

The MCP server gives AI agents (Claude Code, Claude Desktop, etc.) access to your design system.

With Claude Code

Add to your Claude Code MCP settings (~/.claude/settings.json):

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

Or run the dedicated binary:

npx fragments-mcp

Options:

-p, --project-root <path>  Project root directory (default: cwd)
-u, --viewer-url <url>     Viewer URL (default: http://localhost:6006)

How It Works

1. Install a component library that ships fragments.json (e.g., npm install @fragments-sdk/ui)
2. Add the 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

Available MCP Tools

| Tool | Description | |------|-------------| | discover | List components, suggest by use case, find alternatives, or get a full context summary | | inspect | Get detailed component info: props, usage guidelines, code examples — all in one call | | blocks | Search composition blocks (e.g., "Login Form", "Settings Page") | | render | Render a component screenshot, verify against baseline, or compare to Figma | | fix | Generate patches to fix token compliance issues |

Visual tools

The render and fix tools require Playwright. Install it separately if you need visual tools:

npm install playwright

These tools are optional. All other tools work without Playwright.

Programmatic Usage

import { createMcpServer, startMcpServer } from '@fragments-sdk/cli/mcp';

// Start with stdio transport (default)
await startMcpServer({ projectRoot: process.cwd() });

// Or create the server instance for custom transports
const server = createMcpServer({ projectRoot: process.cwd() });

License

MIT