Skip to main content
Glama

Design Knowledge MCP

An MCP server that gives AI agents reliable, token-efficient context from scattered design-system knowledge: guidelines, component specs, decision records, research, and team-specific overrides that often disagree.

Status: early. Baseline retrieval and evals work; hybrid search, reranking, and remote deployment are next. See CLAUDE.md for the roadmap.

The problem

Design organizations accumulate knowledge in many places. Once teams start building their own AI tools, each one gets its own copy, and the copies drift. An agent can't tell that a 2023 team doc was replaced by a 2026 decision, or that a spacing override applies to one app only. It answers confidently anyway.

This project treats that as a context architecture problem: what reaches the agent, in what shape, with what provenance, at what token cost.

Related MCP server: Design Systems MCP Server

How it works

Layer

Tool

For

Structured lookup

get_component

Exact facts: component API, variants, sizes, design tokens, plus every team's guidance doc for that component

Semantic search

search_knowledge

Open-ended questions: guidance, rationale, decisions, research

Progressive disclosure

get_document

Full section only when a snippet isn't enough

Orientation

list_sources

What the knowledge base covers

Search runs as a staged pipeline:

  1. L0 candidates — BM25 over heading-based chunks, each prefixed with a contextual header (team, status, scope, date). Synonym expansion maps "CTA" / "big purple button" to "primary button".

  2. L1 metadata ranking — superseded and deprecated content hidden by default; status and scope weighting.

  3. L2 rerank — planned.

  4. Shaping — max two sections per document, snippets instead of full text, a token budget, and notes that flag team-local overrides and hidden outdated content.

Every tool call is logged to logs/tool-calls.jsonl with latency, result count, and tokens returned.

Corpus

Third-party sources are fetched at build time, not committed:

  • IBM Carbon (Apache-2.0): component usage, style, and accessibility guidelines

  • Adobe Spectrum design data (Apache-2.0): component API schemas and design tokens

  • GitHub Primer (MIT): architecture decision records with real status fields

On top of these, corpus/synthetic/ contains a small fictional org (Lending, Credit Card, Brand, Research Ops, Design Ops) with deliberate mess: a team-local override, a deprecated doc, informal research language, and a decision log that supersedes earlier guidance.

Getting started

npm install
npm run fetch-corpus
npm run search -- "how long should toasts stay on screen"
npm run eval

Use it in Claude Code

The repo includes .mcp.json, so opening the folder in Claude Code offers to enable the design-knowledge server. Then ask things like:

  • "What padding should primary buttons have, and does any team override it?"

  • "Should payment confirmation toasts auto-dismiss?"

Use it in Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "design-knowledge": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/design-knowledge-mcp/src/server.ts"],
      "env": { "DKM_ROOT": "/absolute/path/to/design-knowledge-mcp" }
    }
  }
}

Evals

evals/questions.json holds questions with known correct sections, tagged by type (fact, synonym, conflict, freshness, decision, research). npm run eval reports recall@5, hit@1, MRR, tokens per search, and outdated content leaking into results. Results are saved to evals/results/ so changes can be compared over time.

Run

recall@5

hit@1

MRR

tokens/search

outdated leaks

Baseline (BM25 + metadata)

0.857

0.571

0.696

519

0

License

MIT for this project's code and synthetic content. Fetched sources keep their own licenses.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Design contract layer for AI agents. Scans Figma, code, Storybook, and token files, reconciles conflicts, and serves a single machine-readable source of truth so every agent gets the same authoritative design rules before it builds. Local-first.
      9
      33 npm
      21
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Provides deterministic, read-only design knowledge for AI coding agents to help them choose visual directions, plan UI states, and compose design tokens, all without network access.
      6
      250 npm
      29
      MIT