feat(storybook): expose component docs to agents via official MCP addon (#3527)

[chinawch007]

Summary

Agents writing UI code in this repo had no machine-readable interface to
learn which components exist and how to use them, so they grepped and read
component sources to guess props and usage. This PR self-hosts Storybook's
official MCP addon at http://localhost:6006/mcp, exposing the docs
toolset only, so agents can query the existing story catalog before
writing code.

• apps/desktop: install @storybook/addon-mcp and register it in
  .storybook/main.ts with toolsets: { dev: false, test: false, docs: true }
  (test toolset needs @storybook/addon-vitest and stays a follow-up per
  the issue)
• new root .mcp.json registering the endpoint for agent clients
• new root AGENTS.md: start Storybook on demand, query
  list-all-documentation / get-documentation before writing UI code,
  prefer existing packages/ui components

Fixes #3527

Verification

Manual verification succeeded against a running dev server:

• npm --workspace @maka/desktop run storybook -- --no-open boots
  unchanged; existing stories render as before

• MCP initialize over POST /mcp returns a session id

• tools/list exposes exactly the three docs tools — list-all-documentation,
  get-documentation, get-documentation-for-story — confirming the
  dev/test toolsets are off:

  tool count: 3
  - list-all-documentation
  - get-documentation
  - get-documentation-for-story
  

• all three tools return real content, e.g. get-documentation for
  primitives-toast returns the story list with usage snippets

• npm run lint and npm run format:check pass

Not run / known gaps: full npm run build and npm test (config-only
change, no unit suite covers Storybook config); desktop-workspace
typecheck reports 40 pre-existing errors that reproduce identically on
clean main in this environment (stale workspace dists) — none touch the
changed files, which typecheck clean.

Review focus

• .mcp.json uses the "type": "http" + "url" client convention
  (Claude Code / Cursor-class agent CLIs), not an MCP spec format; it is
  dev-time tooling config, unrelated to packages/mcp's product config.
  $schema is omitted — no official schema covers this client format.
• .github/copilot-instructions.md (code-review guidance only) and the new
  AGENTS.md cover disjoint topics; AGENTS.md is the cross-tool
  canonical location. Mirroring into copilot-instructions.md is left as a
  maintainer decision.

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope: ZCode authored the config and documentation changes and
ran the verification above; the human contributor reviewed the result and
performed the final verification on a live server.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[Astro-Han]

I reviewed this head and found blocking issues.

[P2] MCP addon docs-only claim is not a server boundary and the endpoint is exposed on LAN

@storybook/addon-mcp replaces options via X-MCP-Toolsets (main.ts:45). The live tools/list with a dev header changes from 3 docs tools to 4 dev tools. The storybook script does not bind to loopback, so *:6006 is reachable from 10.7.0.13:6006 without auth — an on-LAN caller can re-enable the dev toolset and obtain a filesystem existence oracle (/etc/passwd vs pathNotFound).

Fix: bind to loopback (and --exact-port) and intersect request-selected toolsets with the configured allowlist; cover with header-injection tests.

[P2] Root .mcp.json is not discovered by Codex

AGENTS.md claims the endpoint is registered, but Codex discovers via .codex/config.toml [mcp_servers], not the Claude-style root JSON. Result: Codex sees the mandatory query instruction but has no tools.

Fix: ship a real project config for each claimed client or narrow the claim; verify via actual client discovery.

Checks on d75281cb67 are test: failure (unrelated CLI EOF backoff flake, but still red — not green). Code issues are independent of CI.

简体中文

存在局域网暴露与 Codex 发现失败两项阻断。