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

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "storybook": {
+      "type": "http",
+      "url": "http://localhost:6006/mcp"
+    }
+  }
+}

AGENTS.md

@@ -0,0 +1,53 @@
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## Frontend work: query the Storybook MCP before writing UI code
+
+UI code lives in `packages/ui` (shared components) and `apps/desktop` (desktop
+app). Before writing or modifying UI code, discover what already exists through
+the Storybook MCP server instead of reading component sources to guess props
+and usage:
+
+1. Start Storybook on demand (dev-only server; nothing auto-starts it):
+
+   ```
+   npm --workspace @maka/desktop run storybook -- --no-open
+   ```
+
+2. Connect to the MCP endpoint at `http://localhost:6006/mcp` (loopback
+   only, by design). Agent clients that read the root `.mcp.json` discover
+   it automatically; other clients (e.g. Codex, Cursor) need a one-time
+   registration in their own MCP config pointing at the same URL. The
+   endpoint only responds while Storybook is running; if it is unreachable,
+   start it as above.
+
+3. Query, then write:
+
+   - `list-all-documentation` — every documented story/component
+   - `get-documentation-for-story` — props and usage for one story
+   - `get-documentation` — docs entry for a component
+
+Prefer composing existing `packages/ui` components. Introduce a new component
+only when nothing existing fits, and give it a story so it becomes discoverable
+through the same interface. Avoid adding third-party UI dependencies without a
+clear need.

apps/desktop/.storybook/main.ts

@@ -35,6 +35,24 @@ const config: StorybookConfig = {
     '../../../packages/ui/stories/**/*.stories.@(ts|tsx)',
     resolve(REPO_ROOT, 'apps/desktop/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: {},

apps/desktop/package.json

@@ -13,7 +13,7 @@
     "prepare:dev-app": "node scripts/prepare-dev-app.mjs",
     "dev": "node scripts/dev.mjs",
     "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",
     "build": "npm run build:resources && npm run build:main && npm run build:preload && npm run build:overlay && npm run build:renderer",
@@ -66,6 +66,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",