@kapowaz/design-mcp

A stdio Model Context Protocol server that exposes the @kapowaz design system — components, design tokens, and design guidance — to coding agents working in other repositories.

It lets an agent in any project ask "what components/tokens are available, and how should I use them?" without the design-system source being present.

What it surfaces

• Components — every component exported from @kapowaz/components: props, peer-provider requirements, and an example snippet.
• Tokens — every token from @kapowaz/design-tokens: CSS variable, getDesignTokens() accessor, and literal value.
• Guidance — the curated convention docs (docs/react/*) plus the package READMEs, with section-level access.

Tools

| Tool | Purpose | | ------------------ | ------------------------------------------------------------- | | list_components | Table of every component in @kapowaz/components. | | get_component | Props, peer requirements, and an example for one component. | | verify_component | Confirm a component is exported and (optionally) its props. | | list_tokens | Token groups (colors, spacing, typography, …) with counts. | | get_token | Resolve a dotted token path to CSS variable, accessor, value. | | list_guidance | Index of the bundled guidance docs. | | get_guidance | Read a doc (optionally a single section, fuzzy-matched). | | search | Fuzzy search across components, tokens, and guidance. |

Consumer setup

Once published, add it to the consuming project's .mcp.json (or your client's equivalent) and let your package manager fetch it:

{
  "mcpServers": {
    "kapowaz-design": {
      "command": "npx",
      "args": ["-y", "@kapowaz/design-mcp"]
    }
  }
}

To run it from a local checkout instead (e.g. before a release, or to test unpublished changes), build it and point at the entry directly:

pnpm --filter @kapowaz/design-mcp build   # builds @kapowaz/design-catalog first

{
  "mcpServers": {
    "kapowaz-design": {
      "command": "node",
      "args": [
        "/absolute/path/to/design-system/packages/design-mcp/dist/index.js"
      ]
    }
  }
}

The server reads only its bundled catalog — no network calls, and no file reads against the consuming workspace — so it is safe to run anywhere node is.

How the catalog is built

This package contains no catalog data. It imports the generated JSON from @kapowaz/design-catalog, a workspace dependency whose generators read the monorepo sources (packages/components/, packages/design-tokens/generated/tokens.css, the guidance docs) and emit JSON. Building this package via turbo rebuilds the catalog first.

Development

pnpm --filter @kapowaz/design-mcp build       # tsc; catalog rebuilt via the workspace dep
pnpm --filter @kapowaz/design-mcp typecheck
pnpm --filter @kapowaz/design-mcp test
pnpm --filter @kapowaz/design-mcp start       # run the built server on stdio

Publishing: the first version is bootstrapped by manually publishing a 0.0.0 placeholder (which registers the name on npm and lets npm OIDC trusted publishing be configured); every real release from 0.1.0 onward then ships automatically via Changesets + OIDC. See docs/PUBLISHING.md.