RELATED 01
style-system
Design-system lookup for coding agents: theme tokens, Tailwind classes, Storybook components and previews
14/wknpm downloads
9popularity score
Primitiv
Serves a project's reconciled design-system contract (tokens, components, conflicts) to coding agents
By AI by design TypeScript Local · stdio DesignDeveloper tools
28 popularity score ★ 21 ↓ 27/wk
Connect your client
Local (npm)
Add in one click
Opens the app, which asks before it adds the server.
Or add it by command or config
Claude CodeTerminal
claude mcp add primitiv -- npx -y @ai-by-design/primitiv serveClaude Desktopclaude_desktop_config.json
{
"mcpServers": {
"primitiv": {
"command": "npx",
"args": [
"-y",
"@ai-by-design/primitiv",
"serve"
]
}
}
}Cursor~/.cursor/mcp.json
{
"mcpServers": {
"primitiv": {
"command": "npx",
"args": [
"-y",
"@ai-by-design/primitiv",
"serve"
]
}
}
}VS Code.vscode/mcp.json
{
"servers": {
"primitiv": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@ai-by-design/primitiv",
"serve"
]
}
}
}Codex~/.codex/config.toml
[mcp_servers.primitiv]
command = "npx"
args = ["-y", "@ai-by-design/primitiv", "serve"]Gemini CLITerminal
gemini mcp add --scope user primitiv npx -- -y @ai-by-design/primitiv serveSettings 1
FIGMA_ACCESS_TOKEN |
Optional: Figma token read by the generated primitiv.config.js when the Figma source is enabled; used by build, not by serve. |
|---|
What it does
Primitiv is a command-line tool with a built-in stdio MCP server for front-end projects. Its build step scans a project's code (CSS variables, TypeScript tokens, React components) and, when configured, Figma variables and a Storybook manifest, compares what each source says, records disagreements as conflicts, flags hardcoded values that bypass the tokens, and writes the result to primitiv.contract.json. The serve command then exposes that file to an agent, so it can check which tokens and components already exist before writing new UI.
At version 2.21.1 the server registers seven read-only tools in src/mcp/server.ts: a design summary, token and component lookups, a component catalogue and filtered search, paged component context, and a paged conflict list (25 per page by default, up to 100). The docs' MCP Tools page also lists get_inferred_rules and get_violations, but neither is registered in that file at 2.21.1; violation counts appear in the get_design_context summary instead.
The server watches the contract file and reloads it when a new build replaces it. If the file is missing or invalid it logs a message telling you to run primitiv build. The makers advise keeping the MCP configuration per project rather than global, because a global entry can serve another repository's contract. The same package also provides init (writes primitiv.config.js, a project .mcp.json or .cursor/mcp.json, AGENTS.md and CLAUDE.md blocks, and a GitHub CI workflow) and verify, a CI check that exits 1 or 2 on stale contracts or pending conflicts.
What it needs
| Runtime | Node.js |
|---|
Node.js with npx. A JavaScript or TypeScript front-end project; init detects Next, Nuxt, Astro, SvelteKit, Remix, Expo, Qwik, Vite, Solid or React. Run `npx @ai-by-design/primitiv init` and `npx @ai-by-design/primitiv build` in the project root first, so primitiv.contract.json exists before serve starts. Figma as a source needs a Figma access token and file ID in primitiv.config.js; Storybook needs a reachable Storybook URL.
Limits
Read-only: no tool edits code, tokens or the contract. Agents see only the last built contract, so changes in code, Figma or Storybook are invisible until primitiv build runs again. Component evidence is static source analysis, not runtime usage, and dynamic prop values stay unknown. The docs list get_inferred_rules and get_violations as tools, but the 2.21.1 source does not register them. Figma and Storybook are optional by default: if one cannot be scanned, the build warns and carries on without it, unless it is the configured sourceOfTruth or is marked optional: false.
Who it suits
Teams with a React-family front end and an established design system who want coding agents to reuse existing tokens and components, especially when Figma, Storybook and code have drifted apart. Since it is local and read-only, it fits repositories where an agent must not change anything through MCP. It is less useful for projects without a token or component layer, and it will not edit Figma or fix code itself. If you only need Figma files themselves, a Figma-focused server is the better fit.
Tools 7
get_design_context- Summary of token, component, conflict and diagnostic counts, or full detail for one category, paged
get_token- Looks up one design token by name, optionally within a token category
get_component- Looks up one component by name or ID, with optional API, usage, relationship or conflict detail
get_component_catalog- Reports component counts, classification coverage, available filters and source health
find_components- Returns a filtered, paged shortlist of components by exact ID order
get_component_context- Returns API, guidance, relationships and source sections for one component ID, in pages
get_conflicts- Lists conflicts between design sources with filters; 25 per page by default, 100 at most