开源MCP工具：设计系统基础设施

Install

```bash npm install @ai-by-design/primitiv

Quick start

npx @ai-by-design/primitiv init     # detect your stack, write config + MCP registration
npx @ai-by-design/primitiv build    # scan sources, resolve conflicts, write the contract
npx @ai-by-design/primitiv serve    # start the MCP server

init writes a .mcp.json to your project root, so Cursor, Claude Code, Codex, Windsurf, and any other MCP-compatible tool pick up the server without manual config. primitiv init is safe to re-run — it keeps your primitiv.config.js and refreshes the other wiring (MCP config, agent instructions, skill files, CI workflow).

If your project is on GitHub, init also installs .github/workflows/primitiv-verify.yml — a workflow that runs primitiv verify --strict on every PR and push. Pair it with branch protection on your default branch and the merge is blocked when an agent ships UI that breaks the contract or sneaks a hardcoded value past it.

From here, every agent that builds UI calls get_design_context first, then get_violations before generating any literal value — and gets your resolved design contract back.

Windsurf — edit ~/.codeium/windsurf/mcp_config.json and remove "primitiv"

```

Stale or mismatched contract warnings

If get_design_context returns a warnings array, stop and resolve before proceeding:

• STALE CONTRACT — the contract is outdated. The warning includes the exact command to rebuild, e.g.: npx @ai-by-design/primitiv build /path/to/your/primitiv.config.js
• CONTRACT MISMATCH — the server is serving a contract from a different project. This usually means Primitiv is in your global editor MCP config. Remove it from there and re-run primitiv init in the correct project.

Configuration

// primitiv.config.js
module.exports = {
  sources: {
    codebase: {
      root: "./src",
      patterns: ["**/*.css", "**/*.ts", "**/*.tsx"],
      ignore: ["node_modules", "dist", ".next"]
    },
    // figma: {
    //   token: process.env.FIGMA_ACCESS_TOKEN,
    //   fileId: "your-figma-file-id"
    // },
    // storybook: {
    //   url: "http://localhost:6006"
    // }
  },
  governance: {
    sourceOfTruth: "codebase", // "codebase" | "figma" | "storybook" | "manual"
    onConflict: "warn"         // "error" | "warn" | "auto-resolve"
  },
  output: {
    path: "./primitiv.contract.json"
  }
}

---