KB

Cloud MCP knowledge base · v1.0.0-rc.1

UX knowledge your AI agent can cite.

A versioned, queryable UI/UX knowledge base delivered over the Model Context Protocol. 73 cited topic docs, 6 workflow stage packs, session-scoped retrieval, and citation verification — so proposals rest on fetched rules instead of invented ones.

View on GitHubConnect in 2 minutes
  • 73topic docs
  • 6stage packs
  • 7MCP tools
  • 35unit tests

The problem

Generic AI UI looks like a template because the model is guessing.

Invented rules

Models hallucinate UX guidance, spacing, and accessibility advice with no source.

Prompt bloat

Pasting an entire style guide into every prompt wastes tokens and drifts over time.

Uncited proposals

Reviewers cannot tell which rules a design actually followed.

How it works

Four steps, one session, every claim traceable.

  1. 01

    Start a session

    Call start_session with the feature. The server returns a session ID, the KB version, and feature-routed doc IDs.

  2. 02

    Load a stage pack

    Call get_stage_pack before each stage. Core rules plus stage docs, within a token budget.

  3. 03

    Fetch what you need

    Use search_kb and get_doc for extra topics. Only fetched IDs can be cited.

  4. 04

    Verify citations

    Call verify_citations before submitting. It flags unfetched, unknown, and deprecated IDs.

What's inside

73topic documents
6stage packs
10feature routes
7MCP tools
3resources
35unit tests

Domains: visual, components, interaction, accessibility, responsive, information architecture, UX writing, design systems, evaluation, SaaS patterns.

Tool reference

Seven tools, three resources. Search returns metadata; retrieve the full doc before relying on a rule.

start_session

feature

Creates a session; returns ID, KB version, suggested docs.

get_stage_pack

sessionId, stage

Core rules + stage docs + routed docs; records fetches.

get_doc

sessionId, id

One published document by ID.

search_kb

query, domain?, limit?

Ranked ID / title / summary hits.

get_checklist

ids[]

CHECK items only. Retrieving is not performing.

verify_citations

sessionId, citedIds[]

Unfetched, unknown, and deprecated IDs.

report_gap

topic, context

Upserts a missing-topic report.

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

Connect an agent

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

stdio needs no API key — it provisions an internal stdio-local key. HTTP requires a Bearer key and enforces revocation, version pinning, and a per-key rate limit.

Why it is different

  • Citations are tied to fetch history. verify_citations flags unfetched, unknown, and deprecated IDs before submission.
  • Stage budgets. Packs report token estimates and mark over-budget packs instead of silently overflowing.
  • Session ownership. Sessions belong to the API key that created them; another key gets SESSION_FORBIDDEN.
  • Release pinning. A key can be frozen to a release; mismatched deployments return 409.
  • Gap reporting. Missing topics are recorded with counts instead of being papered over.
  • Reviewed Markdown is the trust boundary. A bad doc is the risk; review is the control.

Architecture

Agent  ->  MCP Server (stdio / HTTP)
            ->  Core Services
                ->  Content Repository  ->  Markdown content/
                ->  KbStore
                    ->  MemoryStore (dev/tests)
                    ->  PrismaStore (Postgres)
                ->  Auth, rate limit, sessions, citations, gaps

Core owns the logic; MCP, REST, and admin are thin wrappers over the same services.

Testing

pnpm lint:kb:strict   # 0 errors, 0 warnings across 73 docs
pnpm typecheck        # tsc, both packages
pnpm test             # 35 core unit tests
pnpm build            # builds stdio + web
pnpm smoke            # stdio end-to-end (7 tools + 3 resources)
pnpm smoke:http       # HTTP auth, pinning, revocation, 429

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

FAQ

Does this replace my design system?

No. Project design-system files override the KB on tokens, brand, components, and voice. UX-KB supplies general UX rules.

Do I need Postgres?

No. The server reads Markdown directly. Postgres persists API keys, sessions, usage, compliance, and gaps.

Is it free and self-hostable?

Yes. MIT licensed. Run it locally over stdio or HTTP, or host the Node server yourself.

Can it hallucinate rules?

It is instructed to cite fetched IDs and to call report_gap instead of inventing rules for missing topics.