Merge pull request #35 from storybookjs/improve-readmes

Improve READMEs

Author: JReinhold

.changeset/deep-ways-dress.md

@@ -0,0 +1,5 @@
+---
+'@storybook/addon-mcp': patch
+---
+
+Improve documentation around tool usage and setup

.changeset/wide-candies-build.md

@@ -0,0 +1,5 @@
+---
+'@storybook/addon-mcp': patch
+---
+
+Specify that only Storybook 9 or above is supported

README.md

@@ -105,8 +105,6 @@ pnpm --filter @storybook/mcp build
 
 ### Testing
 
-Currently, only the `mcp` package has automated tests:
-
 ```bash
 # Watch tests
 pnpm test
@@ -118,8 +116,6 @@ pnpm test run
 pnpm test run --coverage
 ```
 
-The `addon-mcp` package relies on manual testing via the internal Storybook instance.
-
 ### Debugging MCP Servers
 
 Use the MCP Inspector to debug and test MCP server functionality:
@@ -131,6 +127,45 @@ pnpm inspect
 
 This uses the configuration in `.mcp.inspect.json` to connect to your local MCP servers.
 
+Alternatively, you can also use these `curl` comamnds to check that everything works:
+
+```bash
+# test that the mcp server is running
+# use port 6006 to test the addon-mcp server instead
+curl -X POST \
+  http://localhost:13316/mcp      \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/list",
+    "params": {}
+  }'
+
+# test a specific tool call
+curl -X POST http://localhost:13316/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 2,
+    "method": "tools/call",
+    "params": {
+      "name": "list-all-components",
+      "arguments": {}
+    }
+  }'
+```
+
+### Debugging with Storybook
+
+You can start the Storybook with
+
+```bash
+pnpm storybook
+```
+
+This will build everything and start up Storybook with addon-mcp, and you can then connect your coding agent to it at `http://localhost:6006/mcp` and try it out.
+
 ### Formatting
 
 ```bash

packages/addon-mcp/README.md

@@ -4,7 +4,7 @@ This Storybook addon runs an MCP (Model Context Protocol) server to help develop
 
 It enables a workflow where for each UI component created, the agent will automatically generate and link to example stories. These stories let you visually verify the new UI in each of its key states, and provide documentation and component tests.
 
-The server currently exposes two tools: one to provide UI development instructions to the agent, and the other to retrieve story URLs directly from your running Storybook.
+The addon provides tools to improve agents' UI development capabilities, retrieve story URLs, and access component documentation.
 
 > [!IMPORTANT]
 > This addon currently only supports Vite-based Storybook setups, such as [`@storybook/react-vite`](https://storybook.js.org/docs/get-started/frameworks/react-vite), [`@storybook/nextjs-vite`](https://storybook.js.org/docs/get-started/frameworks/nextjs#with-vite), and [`@storybook/sveltekit`](https://storybook.js.org/docs/get-started/frameworks/sveltekit).
@@ -17,6 +17,9 @@ The server currently exposes two tools: one to provide UI development instructio
 
 ### Installation and Setup
 
+> [!NOTE]
+> This addon requires Storybook 9.0 or higher.
+
 Use Storybook's CLI to automatically install and configure the addon:
 
 ```bash
@@ -36,7 +39,7 @@ The MCP server will be available at `<your_storybook_dev_server_origin>/mcp` whe
 ### Configuring Your Agent
 
 > [!NOTE]
-> This addon is primarily tested with Claude Code. While it should work with other MCP clients, Claude Code is our main target for compatibility and testing.
+> This addon is primarily tested with Claude Code and GitHub Copilot. While it should work with other MCP clients, Claude Code is our main target for compatibility and testing.
 
 #### Claude Code Setup
 
@@ -64,6 +67,8 @@ Before doing any UI, frontend or React development, ALWAYS call the storybook MC
 
 #### Other MCP Clients
 
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=storybook-mcp&config=eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0OjYwMDYvbWNwIn0%3D)
+
 This addon should work with any MCP-compatible client that supports the `tool` capability and the `streamable-http` transport. Here are setup guides for other popular clients:
 
 - [GitHub Copilot](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp/extend-copilot-chat-with-mcp)
@@ -82,11 +87,15 @@ For clients not listed above, consult their documentation for MCP server configu
 
 ## Usage
 
-This addon provides two main MCP tools that your agent can use. The goal is that the agent uses these tools automatically when doing UI development, but agents are unreliable and unpredictable, so sometimes you might need to explicitly tell it to use the tools.
+This addon provides MCP tools that your agent can use. The goal is that the agent uses these tools automatically when doing UI development, but agents are unreliable and unpredictable, so sometimes you might need to explicitly tell it to use the tools.
 
 **If you are prompting from an IDE like VSCode or Cursor, be sure to use `Agent` mode and `sonnet-4.5` or better.**
 
-### 1. UI Building Instructions (`get_ui_building_instructions`)
+### Core Tools
+
+These tools are always available when the addon is installed:
+
+#### 1. UI Building Instructions (`get_ui_building_instructions`)
 
 Provides agents with standardized instructions for UI component development within your project. This tool returns guidelines for:
 
@@ -96,7 +105,7 @@ Provides agents with standardized instructions for UI component development with
 
 The instructions ensure agents follow your project's conventions when creating or modifying UI components and their corresponding stories.
 
-### 2. Get Story URLs (`get_story_urls`)
+#### 2. Get Story URLs (`get_story_urls`)
 
 Allows agents to retrieve direct URLs to specific stories in your Storybook. The agent can request URLs for multiple stories by providing:
 
@@ -113,50 +122,49 @@ Agent calls tool, gets response:
 http://localhost:6006/?path=/story/example-button--primary
 ```
 
-## Contributing
+### Component Documentation Tools (Experimental)
 
-We welcome contributions to improve Storybook's agent integration, within or outside of this addon! Here's how you can help:
+These additional tools are available when the **experimental** component manifest feature is enabled. They provide agents with detailed documentation about your UI components.
 
-1. **Ideas and feature requests**: If you have ideas for what else we could do to improve the Storybook experience when using agents, please [start a discussion](https://github.com/storybookjs/mcp/discussions/new?category=ideas) in this repository.
+**Requirements:**
 
-2. **Report Issues**: If you find bugs, please open an issue on our [GitHub repository](https://github.com/storybookjs/mcp), but keep in mind that this is currently highly experimental, explorative and probably filled with bugs.
+- Storybook v10.1 or later (prereleases), currently available as [canary version `0.0.0-pr-32810-sha-af0645cd`](https://www.npmjs.com/package/storybook/v/0.0.0-pr-32810-sha-af0645cd)
+- React-based framework (`react-vite`, `nextjs-vite`)
+- Feature flag `features.experimentalComponentsManifest` set to `true` in `.storybook/main.js`
 
-3. **Development Setup**:
+**To enable:**
 
-   This repository uses a monorepo structure with [pnpm workspaces](https://pnpm.io/workspaces) and [Turborepo](https://turborepo.com) for task orchestration.
+```javascript
+// .storybook/main.js
+export default {
+	// ... other config
+	features: {
+		experimentalComponentsManifest: true,
+	},
+};
+```
 
-   ```bash
-   # Clone the repository
-   git clone https://github.com/storybookjs/mcp.git
-   cd addon-mcp
+#### 3. List All Components (`list-all-components`)
 
-   # Install dependencies (installs for all packages in the workspace)
-   pnpm install
+Returns a list of all available UI components in your component library. Useful for the LLM as discovery and understanding what components are available to use.
 
-   # Build all packages
-   pnpm build
+#### 4. Get Component Documentation (`get-component-documentation`)
 
-   # Start development (runs the addon-mcp package)
-   pnpm start
-   ```
+Retrieves detailed documentation for specific components, including:
 
-   The main addon package is located in `packages/addon-mcp`.
+- Component documentation
+- Usage examples
 
-4. **Testing**: Run the MCP inspector to test the server functionality (requires that the Storybook dev server is running):
+The agent provides component IDs to retrieve their documentation.
 
-```bash
-pnpm run inspect
-```
+## Contributing
+
+We welcome contributions to improve Storybook's agent integration, within or outside of this addon! Here's how you can help:
 
-Run the unit test suite:
+1. **Ideas and feature requests**: If you have ideas for what else we could do to improve the Storybook experience when using agents, please [start a discussion](https://github.com/storybookjs/mcp/discussions/new?category=ideas) in this repository.
 
-```bash
-# Run tests in watch mode
-pnpm test
+2. **Report Issues**: If you find bugs, please open an issue on our [GitHub repository](https://github.com/storybookjs/mcp), but keep in mind that this is currently highly experimental, explorative and probably filled with bugs.
 
-# Run tests once
-pnpm test run
+3. **Development**:
 
-# Run tests with coverage
-pnpm test run --coverage
-```
+See [the monorepo readme](https://github.com/storybookjs/mcp#-quick-start).

packages/addon-mcp/package.json

@@ -51,7 +51,7 @@
 		"vitest": "catalog:"
 	},
 	"peerDependencies": {
-		"storybook": "*"
+		"storybook": ">=9.0.0"
 	},
 	"publishConfig": {
 		"access": "public"