# AI-by-design/primitiv [Health: Active]

**Category:** 📐 Architecture & Design  
**Repository:** https://github.com/AI-by-design/primitiv  
**GitHub Stars:** 21  
**npm Downloads (last month):** 881  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ai-by-design-primitiv

## Description
Design contract layer for your codebase. Scans Figma, code, Storybook, and token files, reconciles conflicts, and serves a single machine-readable source of truth over MCP so every agent gets the same authoritative design rules before it builds. Local-first — your code never leaves your machine.

## Tools
Capabilities this server exposes over MCP:

- **get_design_context** — Get tokens, components, conflicts, inferred rules, and violation count. Default (no category) returns a summary with counts. Pass `category: "all" \
- **get_token** — Look up a specific token by name. Pass `category` to narrow search (e.g. `"colors"`, `"spacing"`, `"borderRadius"`); aliases like `"radius"` / `"z-index"` are normalized.
- **get_component** — Look up a specific component by name. Returns props, variants, source provenance, and `kind` — `component`, `screen`, `provider`, `icon`, or `other`, so agents reuse real UI and skip screens/providers/icons.
- **get_conflicts** — Get conflicts between sources. Pass `type: "all" \
- **get_inferred_rules** — Get the design rules Primitiv has extracted from your codebase patterns. Pass `category` to filter.
- **get_violations** — List token-misuse violations — hardcoded literals in source that bypass the contract, with a suggested token when one fits. Pass `category: "all" \

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "primitiv": {
    "command": "npx",
    "args": ["-y","@ai-by-design/primitiv"]
  }
}
```

## Documentation

## 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:

```bash
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.

_Full upstream README: https://allmcps.com/mcp/ai-by-design-primitiv/readme_