Kwark. Design System
Open Kwark

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.

For agents

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 divs, 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:

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:

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:

{
  "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:

{
  "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):

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

Codex

In ~/.codex/config.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:

{
  "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:

{ "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.

{ "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.

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

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

{ "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 and Contributing.
  • 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).

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

Give this Markdown to your coding agent or share its URL.

Open .mdllms.txt
Loading…