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
KWARK_DS_DIR, if set: a folder holding the built site, or a URL of one.- The built site beside the file. Inside the Kwark repository that is
public/designSystem/, so the server always matches your local build. - 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_codereads 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.spacefetches 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