UX-KB — UI/UX Designer Agent Knowledge Base

Cloud MCP knowledge base + UI/UX design agent. 73 cited topic docs, 6 workflow stage packs, session-scoped retrieval, citation verification, API keys, rate limits, and usage/gap logging. Built with TypeScript, Prisma, and Postgres.

Live page: https://ux-kb-site.vercel.app

Why UX-KB

Generic AI output looks like a template: default gradients, five-card grids, weak hierarchy, no accessibility, and rules invented on the fly. UX-KB turns UX guidance into a queryable, versioned, citable knowledge base that an agent must read before proposing a design.

• Rules are fetched, not memorized. Every proposal cites doc IDs that were actually retrieved in the session.

• Stage packs load only the rules relevant to the current workflow stage, with token budgets, instead of dumping the whole catalogue.

• Feature routing pulls in extra docs for the specific thing being designed.

• Citation verification proves a cited ID was fetched — and flags unfetched, unknown, and deprecated IDs before submission.

• Gap reporting records missing topics instead of letting the agent invent rules.

Related MCP server: open-design-system-mcp-starter

What's inside

Content release candidate: 1.0.0-rc.1 (content/release.json).

Architecture

flowchart LR
    A[AI Agent] -->|MCP stdio/HTTP| B[MCP Server]
    B --> C[Core Services]
    C --> D[Content Repository]
    D --> E[Markdown content/]
    C --> F[KbStore]
    F --> G[MemoryStore dev/tests]
    F --> H[PrismaStore Postgres]
    C --> I[Auth, rate limit, sessions, citations, gaps]

• MCP is the delivery layer; core owns the logic. REST and admin (Phase 4) reuse the same services.

• Agents read only published, immutable releases. Each session pins one KB version.

• Project design-system files override the KB on tokens, brand, components, and voice.

Quick start (no database)

cd ux-kb
pnpm install
pnpm lint:kb:strict   # 0 errors, 0 warnings
pnpm test             # 23 unit tests
pnpm smoke            # 7 tools + 3 resources over MCP stdio
pnpm dev:mcp          # stdio MCP server

Node.js ≥ 20 and pnpm 10 are required. Postgres is optional for local dev.

Connect an agent

Claude Code (stdio)

claude mcp add ux-kb -- node --import tsx \
  /absolute/path/to/ux-kb/apps/mcp-server/src/index.ts

Or with the built server (pnpm build first):

claude mcp add ux-kb -- node /absolute/path/to/ux-kb/apps/mcp-server/dist/index.js

Cursor / Claude Desktop

{
  "mcpServers": {
    "ux-kb": {
      "command": "node",
      "args": ["--import", "tsx", "/absolute/path/to/ux-kb/apps/mcp-server/src/index.ts"]
    }
  }
}

Streamable HTTP (with API key)

MCP_DEV_KEY=dev-local-key pnpm dev:mcp:http   # http://127.0.0.1:3333/mcp

claude mcp add --transport http ux-kb http://127.0.0.1:3333/mcp \
  --header "Authorization: Bearer dev-local-key"

Tool reference

Resources: kb://doc/{id}, kb://pack/{stage}, kb://core.

Stages: need_check, research, audit, proposal, critique, implement.

Session workflow

1. Call start_session once per task.

2. Call get_stage_pack before each stage; get_doc for extra topics.

3. Call verify_citations before submitting — it compares cited IDs against the session's fetch history.

4. Call report_gap when the KB lacks a topic instead of inventing a rule.

get_stage_pack reports an estimated token count and marks over-budget packs (characters / 4, not a model-specific tokenizer).

Database (optional, for persisted auth/usage/gaps)

cp .env.example .env        # set DATABASE_URL and KEY_HASH_SECRET
pnpm db:generate
pnpm db:push
pnpm db:seed
pnpm kb:keys create --name laptop --rate-limit 120

KB_STORE=db (or a non-empty DATABASE_URL) selects PrismaStore; KB_STORE=memory forces the in-memory store used by tests and smoke:http. The seed is idempotent.

Testing

pnpm lint:kb:strict   # 0 errors, 0 warnings across 73 docs
pnpm typecheck        # tsc, both packages
pnpm test             # 23 core unit tests
pnpm build            # tsup bundle
pnpm smoke            # stdio end-to-end
pnpm smoke:http       # HTTP auth, pinning, revocation, 429

See docs/testing.md for the full manual test guide.

Project structure

ux-kb/
  content/                 Markdown knowledge base (source of truth)
  prisma/schema.prisma     DB schema (docs, versions, releases, keys, usage, gaps)
  prisma/seed.ts           content/ -> Postgres
  packages/core/src/
    schemas/               zod front matter, packs, routes, releases
    content/               path resolution, parser, repository, token estimate
    services/              docs, packs + routing, search, release, auth,
                           rate limit, sessions/citations, gaps
    store/                 KbStore boundary: memory + Prisma implementations
    lint/                  doc + catalog linter
    cli/                   lint, info, key/gap commands
  apps/mcp-server/src/     MCP server (stdio + stateless HTTP)
  apps/mcp-server/scripts/ smoke.ts (stdio), http-smoke.ts (auth/429)
  apps/site/               Public landing page (Vercel)

Security and limitations

• The server trusts reviewed Markdown. A bad doc becomes an instruction the agent follows, so review is the security boundary.

• Citation verification proves fetch history, not that a source semantically supports a claim.

• Rate limiting is in-process; horizontal scaling needs a shared limiter.

• Usage logs store tool arguments — avoid sending secrets in feature, context, or query text.

• Token estimates are approximate (±15% for prose); pack budgets are advisory.

Roadmap

• Phase 4: admin docs, packs, releases (draft → review → publish)

• Phase 5: usage, compliance, and gap observability

• Phase 6: agent files, critic, evals, Playwright/axe

• Phase 7: CI regression and content expansion from ranked gaps

Contributing

Issues and PRs welcome. Before submitting:

1. Keep doc changes minimal and justified.

2. Write docs in your own words — never paste copyrighted source text.

3. Run pnpm lint:kb:strict, pnpm typecheck, and pnpm test.

License

Released under the MIT License. Content is a release candidate and may change between versions.