# MCP server

> Install the Kwark design MCP server in Claude Code, Cursor, Codex or Gemini so an agent can search the docs, read any page, look up components and tokens, and audit its own code against the system.

Source: https://kwark.space/designSystem/agents/mcp

## What it does

The Model Context Protocol lets an agent call tools while it works. The Kwark server gives it five, so it can look things up when it needs them instead of carrying the whole system in its context:

| Tool | What it returns |
|---|---|
| `search_docs` | Pages that match a query, with a snippet and the URL of each page's markdown twin. |
| `get_page` | Any page as markdown. `"agents.md"` returns the rules; `"llms"` returns the map. |
| `get_component` | A component's spec: status, React import and props when it is in the app, HTML, tokens and rules. `full: true` adds the whole page. |
| `get_tokens` | Tokens matching part of a name, with light and dark values, and a writing room's value when asked. |
| `audit_code` | Issues in a snippet of TSX, JSX, HTML or CSS: colour literals, px font sizes, font names, icon sizes off 14/16/20, icon-only buttons without an accessible name, buttons without `type`, clickable `div`s, glows, gradients and resting shadows. Each issue has its line and the fix. |

It is one file with no dependencies. It needs Node 18 or later.

## Install

Download the server:

```bash
mkdir -p ~/.kwark && curl -fsSL https://kwark.space/designSystem/mcp/kwark-design-mcp.mjs -o ~/.kwark/kwark-design-mcp.mjs
node ~/.kwark/kwark-design-mcp.mjs --self-test
```

The self-test checks the auditor and reads a page and the tokens, then prints where it read them from.

### Where it reads from

1. `KWARK_DS_DIR`, if set: a folder holding the built site, or a URL of one.
2. The built site beside the file. Inside the Kwark repository that is `public/designSystem/`, so the server always matches your local build.
3. Otherwise `https://kwark.space/designSystem`, fetched once per session and kept in memory.

### Claude Code

From the project folder:

```bash
claude mcp add kwark-design -- node ~/.kwark/kwark-design-mcp.mjs
```

Or commit it for the whole team in `.mcp.json` at the root of the repository:

```json
{
  "mcpServers": {
    "kwark-design": {
      "command": "node",
      "args": ["/Users/you/.kwark/kwark-design-mcp.mjs"]
    }
  }
}
```

Inside the Kwark repository itself, point at the copy that reads your local build:

```json
{
  "mcpServers": {
    "kwark-design": { "command": "node", "args": ["/path/to/kwark/design-system/mcp/kwark-design-mcp.mjs"] }
  }
}
```

Run `/mcp` in Claude Code to check that `kwark-design` is connected and lists five tools.

### Cursor

In `.cursor/mcp.json` (this project) or `~/.cursor/mcp.json` (every project):

```json
{
  "mcpServers": {
    "kwark-design": {
      "command": "node",
      "args": ["/Users/you/.kwark/kwark-design-mcp.mjs"]
    }
  }
}
```

### Codex

In `~/.codex/config.toml`:

```toml
[mcp_servers.kwark-design]
command = "node"
args = ["/Users/you/.kwark/kwark-design-mcp.mjs"]
```

### Gemini CLI

In `~/.gemini/settings.json`, or `.gemini/settings.json` in the project:

```json
{
  "mcpServers": {
    "kwark-design": {
      "command": "node",
      "args": ["/Users/you/.kwark/kwark-design-mcp.mjs"]
    }
  }
}
```

> Use an absolute path. Most clients do not expand `~` inside a JSON or TOML file. To read from your own build of the site instead, add `"env": { "KWARK_DS_DIR": "/path/to/public/designSystem" }` to the server's entry.

## Using it

You rarely need to name the tools. Ask for the work and say the server is there: "Build the Scene notes panel with the Kwark system. Use the kwark-design tools to look up components and audit what you write." Agents follow the server's own instructions: read the rules, look up parts, check tokens, audit before finishing.

Examples of what the agent sends, and what comes back:

```json
{ "name": "search_docs", "arguments": { "query": "sync error copy", "limit": 3 } }
```

Returns the best matches, such as Saving and sync and Errors, each with a snippet and its `.md` URL.

```json
{ "name": "get_tokens", "arguments": { "name": "accent", "room": "paper" } }
```

Returns `--k-accent` with its light value, its dark value and, for Paper, the room's pencil colour, plus `--k-accent-soft` and `--k-on-accent`.

```json
{ "name": "get_component", "arguments": { "name": "Breadcrumb" } }
```

Returns the Breadcrumb spec with `import { Breadcrumb } from '@/components/ui/Breadcrumb'`, its props, its HTML, tokens and rules.

```json
{ "name": "audit_code", "arguments": { "code": "<div onClick={open} style={{ color: '#98633f', fontSize: 13 }}>Scene 12</div>" } }
```

Returns three issues on line 1: a clickable `div`, a colour literal and a px font size, each with the fix.

## What it does not do

- `audit_code` reads lines and simple tag structure, not a syntax tree. It misses things a person would see (a layout that breaks at 320, a word that judges the writer) and can flag a rare false positive. A clean audit is not a review: see [Readiness tests](https://kwark.space/designSystem/agents/readiness.md) and [Contributing](https://kwark.space/designSystem/contributing.md).
- It does not write files. It only reads the system and reports.
- It sends nothing anywhere. Reading from `kwark.space` fetches public files only; the code you audit stays on your machine.

## For the Kwark repository

The source is `design-system/mcp/kwark-design-mcp.mjs`. The built site serves a copy at `/designSystem/mcp/kwark-design-mcp.mjs`. Run `node design-system/mcp/kwark-design-mcp.mjs --self-test` after changing it. It replaces the v3 server in `scripts/kwark-design-mcp.mjs`; the tool names changed (see [Releases](https://kwark.space/designSystem/releases.md)).

## AI readiness test

**Task:** Connect the Kwark MCP server to Cursor and Claude Code for a team repository, and show the first three tool calls an agent should make before building a dialog.

**Give the agent:** This page.

**Constraint:** Absolute paths. Only the five tools listed here.

**A reliable answer:**
- Downloads the file and runs --self-test
- Gives .mcp.json and .cursor/mcp.json with command node and an absolute path
- Calls get_page with agents.md first
- Then get_component for dialog and get_tokens for what it needs
- Ends with audit_code on the result
