Merge next to main

.changeset/config.json

@@ -7,5 +7,5 @@
 	"access": "public",
 	"baseBranch": "main",
 	"updateInternalDependencies": "patch",
-	"ignore": ["@storybook/mcp-internal-storybook"]
+	"ignore": ["@storybook/mcp-internal-storybook", "@storybook/mcp-eval*"]
 }

.changeset/upset-worlds-bow.md

@@ -0,0 +1,5 @@
+---
+'@storybook/addon-mcp': patch
+---
+
+Improve visibility into which toolsets are available

.github/actions/setup-node-and-install/action.yml

@@ -1,22 +1,20 @@
 name: 'Setup Node.js and Dependencies'
-description: 'Sets up Node.js, caches and installs dependencies'
+description: 'Sets up Node.js, caches, installs dependencies and turbo cache'
 
 runs:
   using: 'composite'
   steps:
-    - name: Setup Node.js
-      uses: actions/setup-node@v4
-      with:
-        node-version-file: '.nvmrc'
-
     - name: Install pnpm
-      uses: pnpm/action-setup@v4
+      uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
 
-    - name: Setup Node.js
-      uses: actions/setup-node@v4
+    - name: Use Node.js 24
+      uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
       with:
-        node-version: 24
-        cache: 'pnpm'
+        cache: pnpm
+        node-version-file: '.nvmrc'
+
+    - name: Cache for Turbo
+      uses: rharkor/caching-for-turbo@2b4b5b14a8d16b8556a58993a8ac331d56d8906d # v2.3.2
 
     - name: Install dependencies
       shell: bash

.github/copilot-instructions.md

@@ -35,7 +35,8 @@ The addon supports configuring which toolsets are enabled:
       toolsets: {
         dev: true,      // get-story-urls, get-ui-building-instructions
         docs: true,  // list-all-components, get-component-documentation
-      }
+      },
+      experimentalFormat: 'markdown'  // Output format: 'markdown' (default) or 'xml'
     }
   }
   ```
@@ -61,12 +62,23 @@ The `@storybook/mcp` package (in `packages/mcp`) is framework-agnostic:
 
 - Uses `tmcp` with HTTP transport and Valibot schema validation
 - Factory pattern: `createStorybookMcpHandler()` returns a request handler
-- Context-based: handlers accept `StorybookContext` to override source URLs and provide optional callbacks
+- Context-based: handlers accept `StorybookContext` which includes the HTTP `Request` object and optional callbacks
 - **Exports tools and types** for reuse by `addon-mcp` and other consumers
+- **Request-based manifest loading**: The `request` property in context is passed to tools, which use it to determine the manifest URL (defaults to same origin, replacing `/mcp` with the manifest path)
+- **Optional manifestProvider**: Custom function to override default manifest fetching behavior
+  - Signature: `(request: Request, path: string) => Promise<string>`
+  - Receives the `Request` object and a `path` parameter (currently always `'./manifests/components.json'`)
+  - The provider determines the base URL (e.g., mapping to S3 buckets) while the MCP server handles the path
+  - Returns the manifest JSON as a string
 - **Optional handlers**: `StorybookContext` supports optional handlers that are called at various points, allowing consumers to track usage or collect telemetry:
   - `onSessionInitialize`: Called when an MCP session is initialized
   - `onListAllComponents`: Called when the list-all-components tool is invoked
   - `onGetComponentDocumentation`: Called when the get-component-documentation tool is invoked
+- **Output Format**: The `format` property in context controls output format:
+  - `'markdown'` (default): Token-efficient markdown with adaptive formatting
+  - `'xml'`: Legacy XML format
+  - Format is configurable via addon options or directly in `StorybookContext`
+  - Formatters are implemented in `packages/mcp/src/utils/manifest-formatter/` with separate files for XML and markdown
 
 ## Development Environment
 
@@ -89,9 +101,39 @@ The `@storybook/mcp` package (in `packages/mcp`) is framework-agnostic:
 
 **Testing:**
 
-- Only `packages/mcp` has tests (Vitest with coverage)
-- Run `pnpm test run --coverage` in mcp package
-- Prefer TDD when adding new tools
+- **Unit tests**: Both `packages/mcp` and `packages/addon-mcp` have unit tests (Vitest with coverage)
+  - Run `pnpm test run --coverage` in individual package directories
+  - Run `pnpm test:run` at root to run all unit tests
+  - Prefer TDD when adding new tools
+- **E2E tests**: `apps/internal-storybook/tests` contains E2E tests for the addon
+  - Run `pnpm test` in `apps/internal-storybook` directory
+  - Tests verify MCP endpoint works with latest Storybook prereleases
+  - Uses inline snapshots for response validation
+  - **When to update E2E tests**:
+    - Adding or modifying MCP tools (update tool discovery snapshots)
+    - Changing MCP protocol implementation (update session init tests)
+    - Modifying tool responses or schemas (update tool-specific tests)
+    - Adding new toolsets or changing toolset behavior (update filtering tests)
+  - **Running tests**:
+    - `pnpm test` in apps/internal-storybook - run E2E tests
+    - `pnpm vitest run -u` - update snapshots when responses change
+    - Tests start Storybook server automatically, wait for MCP endpoint, then run
+  - **Test structure**:
+    - `mcp-endpoint.e2e.test.ts` - MCP protocol and tool tests
+    - `check-deps.e2e.test.ts` - Storybook version validation
+
+**Formatting and checks (CRITICAL):**
+
+- **ALWAYS format code after making changes**: Run `pnpm run format` before committing
+- **ALWAYS run checks after formatting**: Run `pnpm run check` to ensure all checks pass
+- **Fix any failing checks**: Analyze check results and fix issues until all checks pass
+- **This is mandatory for every commit** - formatting checks will fail in CI if not done
+- The workflow is:
+  1. Make your code changes
+  2. Run `pnpm run format` to format all files
+  3. Run `pnpm run check` to verify all checks pass
+  4. Fix any failing checks and repeat step 3 until all pass
+  5. Commit your changes
 
 **Type checking:**
 
@@ -221,11 +263,12 @@ export { addMyTool, MY_TOOL_NAME } from './tools/my-tool.ts';
   - Checks `features.experimentalComponentsManifest` flag
   - Checks for `experimental_componentManifestGenerator` preset
   - Only registers `addListAllComponentsTool` and `addGetComponentDocumentationTool` when enabled
-- Context includes `source` URL pointing to `/manifests/components.json` endpoint
+- Context includes `request` (HTTP Request object) which tools use to determine manifest location
+- Default manifest URL is constructed from request origin, replacing `/mcp` with `/manifests/components.json`
 - **Optional handlers for tracking**:
   - `onSessionInitialize`: Called when an MCP session is initialized, receives context
   - `onListAllComponents`: Called when list tool is invoked, receives context and manifest
-  - `onGetComponentDocumentation`: Called when get tool is invoked, receives context, input, found components, and not found IDs
+  - `onGetComponentDocumentation`: Called when get tool is invoked, receives context, input with componentId, and optional foundComponent
   - Addon-mcp uses these handlers to collect telemetry on tool usage
 
 **Storybook internals used:**
@@ -288,6 +331,7 @@ For detailed package-specific guidance, see:
 
 - `packages/addon-mcp/**` → `.github/instructions/addon-mcp.instructions.md`
 - `packages/mcp/**` → `.github/instructions/mcp.instructions.md`
+- `eval/**` → `.github/instructions/eval.instructions.md`
 
 ## Documentation resources
 

.github/instructions/addon-mcp.instructions.md

@@ -133,7 +133,7 @@ pnpm storybook  # From root - starts internal-storybook with addon in dev mode
 
 ### Formatting
 
-Use Prettier at the root level:
+Use prettier at the root level:
 
 ```bash
 pnpm format  # From root
@@ -149,17 +149,24 @@ Launches the MCP inspector for debugging the addon's MCP server using the config
 
 ### Testing
 
-The addon has comprehensive unit tests covering all utilities and tools:
+The addon has comprehensive unit tests covering all utilities and tools. Tests can be run at the package level or from the monorepo root:
 
 ```bash
+# From the package directory
 pnpm test          # Run tests in watch mode
 pnpm test run      # Run tests once
 pnpm test run --coverage  # Run tests with coverage report
+
+# From the monorepo root (runs tests across all packages)
+pnpm test          # Run all tests in watch mode
+pnpm test:run      # Run all tests once
+pnpm test:ci       # Run tests with coverage and CI reporters
 ```
 
 **Test Infrastructure:**
 
-- **Framework**: Vitest 3.2.4 with @vitest/coverage-v8
+- **Framework**: Vitest with @vitest/coverage-v8
+- **Configuration**: Root-level vitest.config.ts with per-package projects
 - **Fixtures**: JSON fixtures in `fixtures/` directory for story index data
 
 **Test Coverage Baseline:**
@@ -212,11 +219,11 @@ When adding new functionality:
 3. Mock external dependencies (fetch, logger, telemetry)
 4. Use fixtures for complex data structures
 5. Test both success and error paths
-6. Run `pnpm test run --coverage` to verify coverage
+6. Run `pnpm test run --coverage` (from package) or `pnpm test:ci` (from root) to verify coverage
 
 **CI Integration:**
 
-Tests run automatically on PRs and main branch pushes via `.github/workflows/check.yml` as the `test-addon-mcp` job.
+Tests run automatically on PRs and main branch pushes via `.github/workflows/check.yml` in the `test` job, which runs `pnpm turbo run test:ci` across all packages.
 
 ## Code Style and Conventions
 
@@ -229,7 +236,7 @@ Tests run automatically on PRs and main branch pushes via `.github/workflows/che
 
 ### Code Style
 
-- Use Prettier for formatting (inherited from root config)
+- Use prettier for formatting (inherited from root config)
 - Prefer async/await over callbacks
 - Export types and interfaces explicitly
 - Use descriptive variable and function names
@@ -410,7 +417,6 @@ This addon implements MCP using `tmcp`:
 
 - `storybook` - Peer dependency (Storybook framework)
 - `valibot` - Schema validation for tool inputs/outputs
-- `ts-dedent` - Template string formatting
 - `tsdown` - Build tool (rolldown-based)
 - `vite` - Peer dependency for middleware injection