Log inSubmit server
Primitiv logo

Primitiv

by AI-by-design

Builds a local design contract from code, Figma, Storybook, and tokens, then exposes it through read-only MCP tools.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Primitiv

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "ai-by-design-primitiv": {
      "command": "npx",
      "args": [
        "-y",
        "@ai-by-design/primitiv"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

AI-by-design/primitiv MCP server builds a machine-readable design contract from project code, Figma, Storybook, and token files. It reconciles source differences, extracts rules, identifies violations, and exposes the saved contract through read-only MCP tools. Use it when coding agents need consistent access to approved tokens, components, provenance, and design decisions before changing a codebase.

Use cases

  • Give coding agents a shared design contract
  • Look up approved tokens before editing UI
  • Reuse existing components and inspect their prop domains
  • Find conflicts between code, Figma, and Storybook
  • Check hardcoded values and component drift in CI

Key features

  • Local design contract generation
  • Read-only MCP access
  • Token and component lookup
  • Source conflict and drift detection
  • Inferred design rules
  • Hardcoded token misuse reports

Tools6

What Primitiv lets your agent do. Expand a tool for its parameters.

Self-reported~227 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 3d ago

Recent health check succeeded.

18/18 checks healthy over the last 79d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 10d ago via OSV.dev · @ai-by-design/primitiv (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars21Stargazers on the source repository.
npm downloads881Package downloads in the last 30 days.
Last commit7d agoMost recent push to the default branch.
Tools exposed6Callable tools this server registers over MCP.
Directory activity4 viewsConfig copies, upvotes, and views on AllMCPs.

How Primitiv works

What AI-by-design/primitiv does

AI-by-design/primitiv creates a local design contract for a project and serves it through MCP. The contract brings together evidence from source code, Figma, Storybook, and token files, then makes the resulting design context available to compatible agents and editors.

The contract can include design tokens, components, inferred rules, conflicts between sources, diagnostics, and token-misuse violations. Components include their props, variants, provenance, and a classification such as component, screen, provider, icon, or other. This lets an agent distinguish reusable UI from structures it should not copy as a component.

As a tool in the Developer Tools category, AI-by-design/primitiv is suited to repositories where design-system decisions are distributed across several sources and agents need one current reference.

How it works

Run the project commands from the repository root. init prepares Primitiv for the current project, build generates or refreshes the design contract, and serve exposes the saved contract to MCP-compatible clients.

The MCP interface is read-only. Agents can retrieve an overall summary, inspect individual tokens and components, review conflicts, read inferred rules, and list violations. Token lookup supports categories such as colors, spacing, and border radius; aliases including radius and z-index are normalized.

Primitiv also checks JSX usage against finite component prop domains. Out-of-domain values become pending within-source conflicts. Verification can compare the saved contract with current source evidence, including Storybook defaults, story arguments, controls, and mapped values. A normal verification run scans current sources, while --fast uses saved findings and modification times.

Setup and configuration

From the project root, run:

Terminal
npx @ai-by-design/primitiv init
npx @ai-by-design/primitiv build
npx @ai-by-design/primitiv serve

Keep the MCP configuration at project level. A global configuration may serve the contract for a different repository after switching projects. The README directs users to the Primitiv documentation for installation, configuration, commands, and integration guides.

Use primitiv verify in CI to check the saved contract against current evidence. Add --strict to make stale evidence or pending conflicts fail more strictly, --json for structured output, and --verbose for comparison diagnostics. Run build after intended changes so the saved contract is refreshed; verification does not rewrite it.

Tools and capabilities

The available MCP tools are:

  • get_design_context: Returns a summary by default, or tokens, components, conflicts, inferred rules, violations, and diagnostics when a category is requested.
  • get_token: Finds a token by name, optionally restricted to a category.
  • get_component: Returns component props, variants, provenance, and kind.
  • get_conflicts: Reports disagreements between sources, with optional conflict-type filtering.
  • get_inferred_rules: Lists rules extracted from codebase patterns, optionally by category.
  • get_violations: Lists hardcoded literals that bypass the design contract and suggests a matching token when available.

The AI-by-design/primitiv MCP server can therefore give agents the same saved design context while exposing evidence about drift and contract violations.

Limitations and notes

Its MCP interface is read-only, so agents retrieve contract information rather than modify the project through these tools.

Dynamic JSX values and incomplete component domains remain unknown during domain checks. Failed, incomplete, or truncated sources may prevent Primitiv from proving that a fact disappeared or that a conflict was resolved. Diagnostics describe uncertainty and do not themselves count as conflicts, although new diagnostics can make the saved contract stale.

MCP continues serving the saved contract until it is rebuilt and reloaded. Normal verification uses current sources; --fast reports saved findings instead. Under the documented governance rules, stale evidence and strict verification can produce nonzero exit codes.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Primitiv

AI-by-design/primitiv is an MCP server that connects a project’s code, Figma, Storybook, and token files into a local design contract. Its main tools retrieve design context, tokens, components, conflicts, inferred rules, and token-misuse violations for MCP-compatible agents.

Run `npx @ai-by-design/primitiv init`, then `npx @ai-by-design/primitiv build` and `npx @ai-by-design/primitiv serve` from the project root. Keep its MCP configuration at project level so the served contract matches the repository you are working in.

The tools retrieve design summaries, tokens, components, source conflicts, inferred rules, diagnostics, and token-misuse violations. Token and conflict queries support category or type filters, while component results include props, variants, provenance, and component kind.

Yes, `primitiv verify` checks the saved contract against current source evidence, including component prop facts, finite variants, JSX usage, component relationships, and Storybook arguments and controls. Use `--json` for structured results and `--strict` for stricter failure behavior.

No. The MCP interface provides read-only access to the locally generated contract.

Related MCP servers

All in Architecture & Design All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewPrimitiv AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/ai-by-design-primitiv?style=directory)](https://allmcps.com/mcp/ai-by-design-primitiv)
HTML Embed
<a href="https://allmcps.com/mcp/ai-by-design-primitiv"><img src="https://allmcps.com/api/badge/ai-by-design-primitiv?style=directory" alt="Primitiv on AllMCPs" /></a>