Adopt Storybook's official MCP addon to give agents a queryable component interface

Problem

When an agent writes frontend code in this repo, it has no machine-readable way to learn which components exist or how to use them. It falls back to reading component source to guess props and patterns, which burns tokens and produces rework: duplicated components, wrong props, hand-rolled values where tokens belong. Humans review out the damage afterwards.

Our existing tooling covers the verification side (visual-contract harness, CDP-based Storybook smoke, a11y tree audit, file-level Astryx surface inventory). The production side — "what can I reuse and how do I use it" — has no agent-facing interface.

External evidence that closing this gap pays off: BILL's A/B experiment grounding agents in their design system cut token usage 31–63% per task and improved first-pass component fidelity (https://www.bill.com/engineering/how-we-made-our-design-system-bilingual).

Desired outcome

An agent doing UI work queries the design system before writing code: list available components, read props and usage docs, and later run interaction tests on its own stories.

Concretely:

Install @storybook/addon-mcp (official, self-hosted: it serves our own Storybook at http://localhost:6006/mcp, no third-party service).
Register the MCP endpoint in our agent configurations and add usage guidance to AGENTS.md (query docs before writing frontend code).
Start with the docs toolset only.

Follow-up, not in scope: the testing toolset (run-story-tests) needs @storybook/addon-vitest; adopt once the MCP feature leaves preview.

Alternatives or workarounds

Status quo: agents grep source. Works, but this is exactly the expensive path the BILL numbers measure.
Wrap our own surface-inventory generator as a custom MCP server: same idea, more to build and maintain; the official addon is configuration, not construction.
Wait until the feature leaves preview: viable; the proposal limits exposure to the docs toolset, and the addon is dev-only tooling that is trivial to remove.

Risk: Storybook's MCP/manifests are in preview; the API may change. Exposure is limited to a dev dependency plus agent config.

中文对照

问题：Agent 写前端时没有机器可读的方式了解有哪些现成组件、怎么用，只能翻源码猜，费 token 且产出需要返工（重复造组件、props 用错、绕过 token 手写样式）。现有工具链只覆盖验证侧（契约 harness、CDP 冒烟、a11y 审计、文件级盘点），生产侧（“能复用什么、怎么用”）没有 Agent 接口。外部证据：BILL 的对照实验显示，给 Agent 接上设计系统后 token 省 31–63%，组件一次用对。

期望结果：Agent 写前端前先查组件清单和用法文档。具体：装官方 @storybook/addon-mcp（自托管，数据全是自己的）；在 agent 配置和 AGENTS.md 里登记使用指引；先只开 docs toolset。testing toolset 依赖 @storybook/addon-vitest，等 preview 稳定后作为后续跟进。

备选方案：维持现状（翻源码，正是被实测为贵的路径）；自研 MCP 包装 inventory 生成器（同理但要多建多养）；等 preview 结束再接（可行，提案已把暴露面限制在 docs toolset，且只是开发依赖，随时可移除）。

风险：Storybook 的 MCP/manifests 处于 preview，API 可能变。

I'd like to take this issue. Here is my proposed plan:

Approach

Install the addon: add @storybook/addon-mcp as a devDependency in apps/desktop (the workspace that owns the Storybook config). We're already on Storybook 10.5 / @storybook/react-vite, which satisfies the addon's requirements (≥10.3, React-only).
Register it in apps/desktop/.storybook/main.ts, with only the docs toolset enabled:
```
addons: [
  {
    name: '@storybook/addon-mcp',
    options: { toolsets: { dev: false, test: false, docs: true } },
  },
],
```
This serves the MCP endpoint from the existing dev server at http://localhost:6006/mcp (self-hosted, per the issue).
Register the endpoint for agents: add a root .mcp.json pointing at http://localhost:6006/mcp so agent clients pick it up automatically. The endpoint is on-demand — it only responds while npm --workspace @maka/desktop run storybook is running; nothing auto-starts with the product or an agent session.
Agent guidance: add a root AGENTS.md instructing agents to start Storybook and consult the MCP tools (list-all-documentation, get-documentation) before writing UI code in packages/ui or apps/desktop, instead of grepping component sources.

Goals / acceptance criteria

Storybook boots unchanged and existing stories render as before.
The MCP endpoint exposes exactly the 3 docs tools; dev and test toolsets stay off.
The tools return real documentation entries for our existing stories (verified via MCP Inspector).
An agent session in this repo can discover and consult component docs through MCP.
Repo checks pass: npm run lint, npm run format:check, npm run typecheck; and I'll confirm npm run check:third-party-notices is unaffected (the addon is dev-only and not shipped).

Out of scope (follow-ups)

The test toolset (run-story-tests): needs @storybook/addon-vitest and portable stories — separate follow-up per the issue.
Autodocs / per-component MDX coverage. Our stories glob only matches *.stories.@(ts|tsx) today, so the docs toolset will initially expose story-level docs. Expanding that surface changes what agents see and deserves its own discussion.
No product-code changes and no new runtime dependencies — the only new dependency is the dev-only addon itself.

One caveat worth noting: the MCP addon is currently marked "preview" by Storybook, so the API may change in future releases; I'll pin the version and keep the config minimal to limit exposure.

Feedback welcome — happy to adjust before starting. I'll start when this issue is assigned to me.