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,50 @@
+<!--
+  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` (registered for
+   agents in the root `.mcp.json`). 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,21 @@ 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 toolset only; dev/test toolsets are deliberate follow-ups
+        // (test additionally needs @storybook/addon-vitest).
+        toolsets: {
+          dev: false,
+          test: false,
+          docs: true,
+        },
+      },
+    },
+  ],
   framework: {
     name: '@storybook/react-vite',
     options: {},

apps/desktop/package.json

@@ -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",