feat(design-system): add DS MCP server + AI knowledge base [AR-58799] by aroba-dn · Pull Request #401 · drivenets/design-system

aroba-dn · 2026-04-22T08:22:41Z

Summary

Add an AI-accessible component knowledge base to the DriveNets Design System via the Storybook MCP addon and a standalone MCP server.

This enables AI coding agents (Cursor, Claude, etc.) to programmatically query DS component documentation, props, stories, and usage examples — instead of re-scanning the DS codebase on every interaction.

How it works

DS developers write components + stories + JSDoc
        |
        v
storybook build (CI, with @storybook/addon-mcp)
        |
        v
addon-mcp auto-generates manifests/components.json + docs.json
(extracted from TypeScript types, JSDoc, stories, MDX docs)
        |
        v
CI deploys storybook-static/ (incl. manifests/) to GitHub Pages
        |
        v
MCP server fetches manifests from GitHub Pages on each request
        |
        v
AI agents query components via MCP protocol (Streamable HTTP)

Nobody manually maintains the manifest files. They are a build artifact generated from the source code — TypeScript prop types, JSDoc comments, story files, and MDX docs.

What's included

Storybook upgrade & addon

Upgraded Storybook from 10.2 to 10.3.5
Added @storybook/addon-mcp to .storybook/main.ts addons
No changes needed to CI deploy — existing GitHub Pages workflow picks up manifests/ automatically

MCP server (`tools/mcp-server/`)

A standalone TypeScript MCP server using @storybook/mcp + srvx:

src/server.ts — serves component knowledge via 3 MCP tools:
- list-all-documentation — discover all components and docs entries
- get-documentation — get full props, stories, code snippets for a component
- get-documentation-for-story — get a specific story variant
Supports both stateless and session-based MCP protocol
Supports remote mode (fetches from GitHub Pages) and local mode (MANIFESTS_DIR env var)
Dockerfile — multi-stage build (compile TS → slim runtime image on node:24-alpine)
docker-compose.yml — ready for container deployment
ARCHITECTURE.md — maintainer documentation covering manifest generation, server design, and deployment
test-manifests/ — sample data mirroring real DS components for local testing

AI knowledge base (`.ai/`)

OVERVIEW.md — DS architecture, conventions, and agent instructions
MCP_TOOLS.md — recommended MCP workflow (tool schemas are auto-discovered at runtime)
ARCHITECTURE.md, IMPLEMENTATION.md, CONTRIBUTING.md — repo structure and patterns
features/ — detailed docs on styling, Ark UI integration, component patterns
operations.md, testing.md — build pipeline, testing, and CI details

Deployment

Phase A (now): Developers run the MCP server locally:

cd tools/mcp-server && npm install && npm run dev

Then add to .cursor/mcp.json:

{
  "mcpServers": {
    "ds-storybook-mcp": {
      "url": "http://localhost:9200/mcp"
    }
  }
}

Phase B (planned): Deployed as a Docker container behind a centralized MCP gateway. Developers update one URL. No code changes needed.

Test evidence

All 3 MCP tools tested end-to-end (initialize → tools/list → tools/call):

Test	Result
`GET /health`	`{"status":"healthy","server":"ds-storybook-mcp"}`
MCP `initialize`	Session created, serverInfo returned
MCP `tools/list`	3 tools discovered
`list-all-documentation`	All components returned
`get-documentation`	Full props, stories, code snippets
Stateless mode (no session)	Works — compatible with proxy-based deployments

An independent AI sub-agent successfully connected, discovered components, retrieved docs, and generated correct JSX using only MCP-provided props.

Jira

Epic: AR-58799

Ticket	Description	Status
AR-58800	Upgrade Storybook to 10.3+	Done
AR-58801	Install @storybook/addon-mcp	Done
AR-58804	Create MCP server	Done
AR-58806	Verify manifests	Done
AR-58810	Create .ai/ knowledge base	Done

Notes

The enrichment phase (AR-58802: JSDoc, AR-58803: MDX docs) will follow in a separate PR to improve manifest quality
DAP-side integration (MCP config + AGENTS.md update) tracked separately under AR-58808 and AR-58809

The lockfile specifiers were out of sync with the Storybook 10.3 upgrade. Also adds the required changeset entry and removes unintended changes to .husky/pre-commit and root package.json. Made-with: Cursor

- Exclude tools/ from root tsconfig, eslint, and knip (standalone project) - Add srvx, Streamable, EPIPE to cspell local dictionary - Run oxfmt to fix formatting across all changed files - Add --no-warn-ignored to lint-staged eslint to handle excluded files Made-with: Cursor

Regenerated lockfile from scratch to eliminate esbuild version duplication introduced by the Storybook 10.3 upgrade. Made-with: Cursor

iromanchuk-dn · 2026-04-22T11:20:55Z

+- All component names are prefixed with `Ds` (e.g., `DsButton`, `DsTable`)
+- Components use CSS custom properties for theming (e.g., `--dn-color-primary`)
+- Props follow controlled/uncontrolled patterns (React standard)
+- `design: 'v1.2'` prop on some components enables newer design variants


It will not exist soon, better remove this.

- Dockerfile: node:20 → node:24 to match .nvmrc, fix lockfile ref - Remove TEST_EVIDENCE.md (content already in PR description) - Slim MCP_TOOLS.md to workflow-only (tool schemas auto-discovered via MCP) - Add test-manifests/README.md clarifying these are fixtures, not maintained data Made-with: Cursor

iromanchuk-dn · 2026-04-22T15:32:35Z

I think the whole description will need to change once we migrate to new tokens and remove old ones.

iromanchuk-dn · 2026-04-22T15:37:00Z

+### Versioned Components
+
+Components undergoing a design revision have a `versions/` directory:
+
+```
+src/components/ds-button/
+  index.ts                              # Exports based on design prop
+  ds-button.types.ts                    # Union type switching between versions
+  versions/
+    ds-button-new/                      # v1.2 design
+      ds-button-new.tsx
+      ds-button-new.types.ts
+      ds-button-new.module.scss
+      ds-button-new.stories.tsx
+    ds-button-legacy/                   # Original design
+      ...
+```
+
+The top-level component switches between versions based on a `design: 'v1.2'` prop.


It is no longer the case. We will not follow this approach starting from v1 which is in the branch next. I suggest to remove this section.

iromanchuk-dn

Great job!
Docs in .ai folder are usefull even for a human.

… [AR-58799]

Merge upstream main (AR-58802 JSDoc, AR-58803 onBlur, AR-55986 tokens sync) into the MCP branch. Only conflict was the cspell word list — merged all entries from both sides. Made-with: Cursor

feat(design-system): add ds mcp ai knowledge base [AR-58799]

3d2f1cf

github-actions Bot added documentation Improvements or additions to documentation design-system labels Apr 22, 2026

fix: sync pnpm-lock.yaml and add changeset for MCP addon

e7cf75d

The lockfile specifiers were out of sync with the Storybook 10.3 upgrade. Also adds the required changeset entry and removes unintended changes to .husky/pre-commit and root package.json. Made-with: Cursor

github-actions Bot added the dependencies label Apr 22, 2026

aroba-dn requested a review from StyleShit as a code owner April 22, 2026 08:35

github-actions Bot added the tooling label Apr 22, 2026

fix: regenerate pnpm-lock.yaml to resolve dedupe check

c35ef4f

Regenerated lockfile from scratch to eliminate esbuild version duplication introduced by the Storybook 10.3 upgrade. Made-with: Cursor