apache · chinawch007 · Aug 24, 2026 · Aug 25, 2026 · Sep 3, 2026
diff --git a/.mcp.json b/.mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "storybook": {
+      "type": "http",
+      "url": "http://localhost:6006/mcp"
+    }
+  }
+}
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.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.

diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.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)；请在它的基础上填写，不要整段替换。

diff --git a/LICENSE b/LICENSE
@@ -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

diff --git a/apps/desktop/.storybook/main.ts b/apps/desktop/.storybook/main.ts
@@ -35,6 +35,24 @@ const config: StorybookConfig = {
     '../../../packages/ui/stories/**/*.stories.@(ts|tsx)',
     '../stories/**/*.stories.@(ts|tsx)',
   ],
+  addons: [
+    {
+      name: '@storybook/addon-mcp',
+      options: {
+        // Issue #3527: agents get a queryable component-docs interface.
+        // Docs is the default toolset selection, not an allowlist: the addon
+        // lets callers override it per request via the X-MCP-Toolsets
+        // header, so the security boundary is the dev server's loopback
+        // binding (see the storybook script in package.json). dev/test stay
+        // off by default; test additionally needs @storybook/addon-vitest.
+        toolsets: {
+          dev: false,
+          test: false,
+          docs: true,
+        },
+      },
+    },
+  ],
   framework: {
     name: '@storybook/react-vite',
     options: {},

diff --git a/apps/desktop/package.json b/apps/desktop/package.json
@@ -18,7 +18,7 @@
     "dev": "node scripts/dev.mjs",
     "dev:peer": "npm run prepare:runtime-host-peer && node scripts/dev.mjs --runtime-host-peer",
     "dev:hmr": "node scripts/dev.mjs",
-    "storybook": "storybook dev -p 6006 -c .storybook",
+    "storybook": "storybook dev -p 6006 -c .storybook --host 127.0.0.1 --exact-port",
     "build-storybook": "storybook build -c .storybook --output-dir storybook-static",
     "smoke:storybook": "node ../../scripts/storybook-visual-smoke.mjs",
     "check:architecture": "node --test scripts/check-renderer-architecture.test.mjs && node scripts/check-renderer-architecture.mjs",
@@ -79,6 +79,7 @@
     "@maka/ui": "0.1.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@playwright/test": "^1.62.1",
+    "@storybook/addon-mcp": "^0.7.0",
     "@storybook/react-vite": "^10.5.10",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",

diff --git a/package-lock.json b/package-lock.json
diff --git a/patches/@storybook+addon-mcp+0.7.0.patch b/patches/@storybook+addon-mcp+0.7.0.patch
@@ -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());