# AI-by-design/primitiv [Health: Active] **Category:** 💰 Finance & Fintech **Repository:** https://github.com/AI-by-design/primitiv **GitHub Stars:** 19 **npm Downloads (last month):** 2309 **Views:** 2 **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 & README # Primitiv **The design system contract keeping teams and agents in sync.** Retrieval gives you data. Reconciliation gives you truth. ## The problem Design-system knowledge is spread across code, Figma, Storybook, and documentation. When those sources drift, people reconcile the differences through experience; AI coding agents often fall back to generic patterns that work but do not belong in the product. Primitiv gives every agent the same current design context through a machine-readable contract and a read-only MCP interface. It helps agents reuse what exists, follow established decisions, and surface inconsistencies before they ship. Primitiv runs locally. Your code never leaves your machine. ## Quick start Run these commands from your project root: ```bash npx @ai-by-design/primitiv init npx @ai-by-design/primitiv build npx @ai-by-design/primitiv serve ``` `init` sets up Primitiv for the current project, `build` creates its design contract, and `serve` makes that contract available to MCP-compatible agents. See the [Primitiv documentation](https://primitiv.design/docs) for installation, configuration, commands, and integration guides. > [!IMPORTANT] > Keep Primitiv configured at project level. A global MCP configuration can serve the wrong project's contract when you switch repositories. ## Capabilities - Bring design context from your codebase, Figma, and Storybook together - Make existing tokens, components, rules, and rationale available to agents - Surface conflicts, drift, and hardcoded token misuse - Provide read-only access from MCP-compatible agents and editors - Verify that the contract stays current in CI Primitiv also checks local JSX usage against each codebase component's complete finite prop domains. Known out-of-domain values produce a pending `within-source` conflict, even under `auto-resolve`. Align the JSX usage or widen the declared domain to resolve it. `warn` reports these conflicts without blocking; `error` and `verify --strict` exit with code 2. Dynamic values and incomplete domains remain unknown. When component evidence cannot be compared, `primitiv verify` reports a short diagnostic summary. Use `primitiv verify --verbose` for the reasons, or `--json` for a structured report. Diagnostics explain uncertainty and do not count as conflicts or directly fail verification; changes to them can still make the saved contract stale. `--fast` reports saved diagnostics instead of rebuilding them. Agents can read diagnostic counts in the MCP summary and paginated details through `get_design_context` with `category: "diagnostics"`. ## Component drift in CI Run `primitiv verify` against your saved contract to check declared prop facts, finite variant values, observed JSX values, and component relationships. Verification also compares Storybook default args, story args, and control choices, including mapped values. Story labels and other presentation metadata do not count as API drift. Observations and examples describe static source evidence, not runtime frequency or breaking-change severity. For example, changing a `Button` usage from `size="sm"` to `size="lg"` is detected even when the number of JSX sites stays the same. Drift messages identify the component ID and field path, such as `components/Button` and `usage.props.size`. Normal verification scans current sources in memory and uses their current conflicts for reporting and governance. Introducing or fixing an out-of-domain JSX value takes effect in verification immediately. The saved contract remains the drift baseline and is never rewritten by verification: run `primitiv build` to refresh it, then verify again. MCP continues serving the saved contract until it is rebuilt and reloaded. Failed sources and incomplete or truncated evidence cannot prove that an unavailable fact was removed or that a conflict was resolved. Verification reports available changes and comparison uncertainty. Older contracts remain readable; newly available evidence makes them stale until rebuilt. Stale evidence exits with code 1, or 2 under `--strict`. Pending conflicts exit with code 2 under `error` governance or `--strict`; warn-only conflicts do not independently fail verification. `--fast` uses saved findings and file modification times instead of scanning current API evidence, so use normal verification in CI. Use `--json` for the verification result and `--verbose` for comparison diagnostic details. ## Project links - [Documentation](https://primitiv.design/docs) - [Changelog](https://github.com/AI-by-design/primitiv/blob/HEAD/CHANGELOG.md) - [Contributing](https://github.com/AI-by-design/primitiv/blob/HEAD/CONTRIBUTING.md) - [Code of Conduct](https://github.com/AI-by-design/primitiv/blob/HEAD/CODE_OF_CONDUCT.md) - [Security](https://github.com/AI-by-design/primitiv/blob/HEAD/SECURITY.md) - [Issues](https://github.com/AI-by-design/primitiv/issues) - [Apache-2.0 license](https://github.com/AI-by-design/primitiv/blob/HEAD/LICENSE)