fix(storybook): scope MCP guidance to documented catalog (#3527)

Keep Storybook on demand while moving its startup guidance into the contributor docs. Patch the addon instructions so the incremental catalog remains useful without hiding undocumented Astryx APIs.

Generated-by: Codex

Author: chinawch007

AGENTS.md

@@ -78,6 +78,21 @@ npx knip --workspace packages/ui
 
 Architecture is documented in [ARCHITECTURE.md](./ARCHITECTURE.md); evaluation commands and contracts live in [`packages/eval`](./packages/eval).
 
+### Storybook component documentation
+
+Storybook and its MCP endpoint are development-only and start on demand:
+
+```sh
+npm --workspace @maka/desktop run storybook -- --no-open
+```
+
+The MCP endpoint is then available at `http://localhost:6006/mcp`; the root
+`.mcp.json` registers it for clients that support repository MCP configuration.
+Its component catalog is incremental rather than exhaustive. For UI work,
+query Storybook documentation first. If the needed API is not documented there,
+follow [DESIGN.md](./DESIGN.md) and verify Astryx components and props against
+Astryx's official API or published type declarations. Never guess props.
+
 ## Pull requests
 
 Opening a pull request pre-fills [`pull_request_template.md`](./.github/pull_request_template.md); fill it in rather than replacing it.

CONTRIBUTING.md

@@ -78,6 +78,20 @@ npx knip --workspace packages/ui
 
 架构说明见 [ARCHITECTURE.zh-CN.md](./ARCHITECTURE.zh-CN.md)；Eval 的命令与 contract 见 [`packages/eval`](./packages/eval)。
 
+### Storybook 组件文档
+
+Storybook 及其 MCP 端点仅用于开发，并按需启动：
+
+```sh
+npm --workspace @maka/desktop run storybook -- --no-open
+```
+
+启动后，MCP 端点位于 `http://localhost:6006/mcp`；支持仓库级 MCP 配置的客户端
+会通过根目录的 `.mcp.json` 注册它。当前组件目录会逐步补充，并不完整。进行 UI
+开发时应优先查询 Storybook 文档；如果所需 API 尚无文档，则遵循
+[DESIGN.md](./DESIGN.md)，并根据 Astryx 官方 API 或已发布的类型声明核实 Astryx
+组件及其 props，切勿猜测 props。
+
 ## Pull Request
 
 开 PR 时会自动填充 [`pull_request_template.md`](./.github/pull_request_template.md)；请在它的基础上填写，不要整段替换。

CONTRIBUTING.zh-CN.md

@@ -308,6 +308,40 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 
+Storybook MCP addon dependency patch
+
+Source: https://www.npmjs.com/package/@storybook/addon-mcp/v/0.7.0
+Repository: https://github.com/storybookjs/mcp/tree/main/packages/addon-mcp
+Version: 0.7.0
+Dependency patch: patches/@storybook+addon-mcp+0.7.0.patch
+Copyright (c) 2023 Storybook contributors
+License: MIT
+
+Maka redistributes a source patch that replaces the addon's documentation
+workflow instructions. The following MIT License applies to that material:
+
+MIT License
+
+Copyright (c) 2023 Storybook contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
 node-pty dependency patch
 
 Source: https://www.npmjs.com/package/node-pty/v/1.2.0-beta.15

LICENSE

@@ -0,0 +1,13 @@
+diff --git a/node_modules/@storybook/addon-mcp/dist/preset.js b/node_modules/@storybook/addon-mcp/dist/preset.js
+index 956b95c..5f82bf8 100644
+--- a/node_modules/@storybook/addon-mcp/dist/preset.js
++++ b/node_modules/@storybook/addon-mcp/dist/preset.js
+@@ -748 +748 @@ var legacy_test_instructions_default = "## Validation Workflow\n\n- After editin
+-var review_docs_instructions_default = "## Documentation Workflow\n\n**CRITICAL: Never hallucinate component properties!** Undocumented props do not exist — never assume them from naming or other libraries; verify every prop via these tools, not source or types in node_modules.\n\n1. Call **list-all-documentation** once at task start for component and docs IDs.\n2. Call **get-documentation** with an `id` from that list for props and usage examples.\n\nOnly reference IDs returned by these tools — never guess; scope multi-source requests with `storybookId`.\n";
++var maka_docs_instructions_default = "## Documentation Workflow\n\nUse Storybook documentation tools first to discover documented components, props, and examples. This catalog is incremental and incomplete: missing documentation does not mean a component or prop does not exist.\n\n1. Call **list-all-documentation** once at task start for available component and docs IDs.\n2. Call **get-documentation** with an `id` from that list for props and usage examples.\n3. Call **get-documentation-for-story** for additional details about a documented story variant.\n\nFor gaps, follow the repository's **DESIGN.md**. Verify Astryx components and props against Astryx's official API or published type declarations. Never guess props from names, conventions, or unrelated libraries. Only reference Storybook IDs returned by these tools; scope multi-source requests with `storybookId`.\n";
+@@ -773 +773 @@ function buildServerInstructions(options) {
+-	const sections = [options.docsEnabled ? "Follow these workflows when working with UI and/or Storybook. Answer questions about component props, API, or usage with the documentation tools — never from source or type definitions." : "Follow these workflows when working with UI and/or Storybook."];
++	const sections = ["Follow these workflows when working with UI and/or Storybook."];
+@@ -783 +783 @@ function buildServerInstructions(options) {
+-	if (options.docsEnabled) sections.push((reviewEnabled ? review_docs_instructions_default : STORYBOOK_MCP_INSTRUCTIONS).trim());
++	if (options.docsEnabled) sections.push(maka_docs_instructions_default.trim());

patches/@storybook+addon-mcp+0.7.0.patch

@@ -27,6 +27,18 @@ Keep this directory small. Prefer product code that uses the dependency's
 published API; only patch for bugs that block shipping and cannot be worked
 around at the call site.
 
+## `@storybook/addon-mcp@0.7.0`
+
+The upstream MCP instructions treat Storybook documentation as an exhaustive
+catalog and prohibit consulting source or type declarations. Maka's catalog is
+incremental, so that advice would incorrectly hide existing components and
+props. The patch keeps Storybook documentation first, states the coverage gap,
+and directs agents to `DESIGN.md` plus Astryx's official API or published types
+for missing documentation without guessing props.
+
+Delete when the addon supports project-owned instructions that can replace its
+default documentation workflow.
+
 ## `@tufjs/models@5.0.0` and `@sigstore/core@4.0.1`
 
 The published ECDSA verification paths rely on Node choosing a digest when