Add MCP server-level instructions to both packages by Copilot · Pull Request #185 · storybookjs/mcp

Copilot · 2026-03-03T12:59:55Z

Remove top-level heading from packages/mcp/src/instructions.md for composability
Split monolithic instructions into dev-instructions.md (always) and test-instructions.md (vitest only)
Delete old mcp-server-instructions.md
buildServerInstructions() composes based on actual availability; devEnabled now also gated
instructions is a getter on the server options object — reads server.ctx.custom?.toolsets per-request so per-request toolset header overrides are respected
test-instructions.md: explicitly names the run-story-tests tool
Trim changeset, revert README additions
Tests updated, typecheck clean, format clean
gradeMcpTools(): return summary when expectedToolCount is set even if totalCalls === 0, so zero-MCP-call runs score 0 instead of quality: undefined

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

changeset-bot · 2026-03-03T13:00:05Z

🦋 Changeset detected

Latest commit: 8dbd727

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@storybook/mcp	Minor
@storybook/addon-mcp	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Co-authored-by: JReinhold <5678122+JReinhold@users.noreply.github.com>

Copilot · 2026-03-05T12:23:05Z

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

66b1e47012f95c6f90c8882e-eplpsjesci.chromatic.com
- Triggering command: /opt/hostedtoolcache/node/24.14.0/x64/bin/node node /home/REDACTED/work/mcp/mcp/apps/internal-storybook/node_modules/.bin/storybook dev --port 6006 --loglevel debug --no-open --config-dir .storybook-composition --port 6007 (dns block)
ds.example.com
- Triggering command: /opt/hostedtoolcache/node/24.14.0/x64/bin/node /opt/hostedtoolcache/node/24.14.0/x64/bin/node --conditions node --conditions development --experimental-import-meta-resolve --require /home/REDACTED/work/mcp/mcp/node_modules/vitest/suppress-warnings.cjs /home/REDACTED/work/mcp/mcp/node_modules/vitest/dist/workers/forks.js (dns block)
main--6985a38660050ca8a9e62053.chromatic.com
- Triggering command: /opt/hostedtoolcache/node/24.14.0/x64/bin/node node /home/REDACTED/work/mcp/mcp/apps/internal-storybook/node_modules/.bin/storybook dev --port 6006 --loglevel debug --no-open --config-dir .storybook-composition-auth --port 6008 (dns block)
my-lib.example.com
- Triggering command: /opt/hostedtoolcache/node/24.14.0/x64/bin/node /opt/hostedtoolcache/node/24.14.0/x64/bin/node --conditions node --conditions development --experimental-import-meta-resolve --require /home/REDACTED/work/mcp/mcp/node_modules/vitest/suppress-warnings.cjs /home/REDACTED/work/mcp/mcp/node_modules/vitest/dist/workers/forks.js (dns block)
next--635781f3500dd2c49e189caf.chromatic.com
- Triggering command: /opt/hostedtoolcache/node/24.14.0/x64/bin/node node /home/REDACTED/work/mcp/mcp/apps/internal-storybook/node_modules/.bin/storybook dev --port 6006 --loglevel debug --no-open --config-dir .storybook-composition --port 6007 (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

…ions Co-authored-by: JReinhold <5678122+JReinhold@users.noreply.github.com>

Copilot · 2026-03-05T12:47:45Z

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

66b1e47012f95c6f90c8882e-eplpsjesci.chromatic.com
- Triggering command: /opt/hostedtoolcache/node/24.14.0/x64/bin/node node /home/REDACTED/work/mcp/mcp/apps/internal-storybook/node_modules/.bin/storybook dev --port 6006 --loglevel debug --no-open --config-dir .storybook-composition --port 6007 (dns block)
ds.example.com
- Triggering command: /opt/hostedtoolcache/node/24.14.0/x64/bin/node /opt/hostedtoolcache/node/24.14.0/x64/bin/node --conditions node --conditions development --experimental-import-meta-resolve --require /home/REDACTED/work/mcp/mcp/node_modules/vitest/suppress-warnings.cjs /home/REDACTED/work/mcp/mcp/node_modules/vitest/dist/workers/forks.js (dns block)
main--6985a38660050ca8a9e62053.chromatic.com
- Triggering command: /opt/hostedtoolcache/node/24.14.0/x64/bin/node node /home/REDACTED/work/mcp/mcp/apps/internal-storybook/node_modules/.bin/storybook dev --port 6006 --loglevel debug --no-open --config-dir .storybook-composition-auth --port 6008 (dns block)
my-lib.example.com
- Triggering command: /opt/hostedtoolcache/node/24.14.0/x64/bin/node /opt/hostedtoolcache/node/24.14.0/x64/bin/node --conditions node --conditions development --experimental-import-meta-resolve --require /home/REDACTED/work/mcp/mcp/node_modules/vitest/suppress-warnings.cjs /home/REDACTED/work/mcp/mcp/node_modules/vitest/dist/workers/forks.js (dns block)
next--635781f3500dd2c49e189caf.chromatic.com
- Triggering command: /opt/hostedtoolcache/node/24.14.0/x64/bin/node node /home/REDACTED/work/mcp/mcp/apps/internal-storybook/node_modules/.bin/storybook dev --port 6006 --loglevel debug --no-open --config-dir .storybook-composition --port 6007 (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

pkg-pr-new · 2026-03-09T11:27:13Z

npm i https://pkg.pr.new/storybookjs/mcp/@storybook/addon-mcp@185

npm i https://pkg.pr.new/storybookjs/mcp/@storybook/mcp@185

commit: 8dbd727

codecov · 2026-03-09T11:28:28Z

Codecov Report

❌ Patch coverage is 89.47368% with 2 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@07f8d07). Learn more about missing BASE report.
⚠️ Report is 17 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
packages/addon-mcp/src/mcp-handler.ts	77.77%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #185   +/-   ##
=======================================
  Coverage        ?   73.28%           
=======================================
  Files           ?       42           
  Lines           ?     1179           
  Branches        ?      333           
=======================================
  Hits            ?      864           
  Misses          ?      198           
  Partials        ?      117

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

codecov · 2026-03-09T11:33:32Z

Bundle Report

Changes will increase total bundle size by 1.49kB (3.1%) ⬆️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
@storybook/mcp-esm	44.41kB	1.49kB (3.46%) ⬆️

Affected Assets, Files, and Routes:

view changes for bundle: @storybook/mcp-esm

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`index.js`	162 bytes	30.14kB	0.54%
`index.d.ts`	124 bytes	13.07kB	0.96%
`instructions-Cl0vcW2j.js` (New)	1.2kB	1.2kB	100.0% 🚀

…ithub.com/storybookjs/mcp into copilot/implement-mcp-server-instructions

Copilot

Pull request overview

Adds MCP server-level initialize.instructions guidance to both the standalone @storybook/mcp server and the @storybook/addon-mcp server, and updates the eval harness/tasks to exercise and score tool-usage workflows.

Changes:

Introduce reusable base server instructions in @storybook/mcp and include them in MCP initialize responses.
Add dynamic instruction composition in @storybook/addon-mcp based on enabled toolsets and runtime availability (docs/test).
Reshape eval tasks 901–907 with new configs/READMEs, MCP-tool-based quality scoring, and update model references.

Reviewed changes

Copilot reviewed 40 out of 44 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pnpm-workspace.yaml	Bumps Storybook-related catalog versions used across the monorepo.
packages/mcp/src/instructions.md	Adds base documentation/verification workflow instructions for the MCP server.
packages/mcp/src/index.ts	Imports and wires server instructions into `McpServer` initialization; exports instructions for reuse.
packages/mcp/src/index.test.ts	Adds test asserting `initialize.instructions` is present and matches snapshot.
packages/mcp/src/globals.d.ts	Adds `*.md` module typing for TypeScript imports.
packages/mcp/bin.ts	Adds server instructions to the stdio server variant by reading `instructions.md`.
packages/addon-mcp/src/mcp-handler.ts	Adds dynamic server instructions tailored to toolsets and runtime feature availability.
packages/addon-mcp/src/mcp-handler.test.ts	Adds assertions/tests around instruction inclusion/exclusion by toolset and manifest availability.
packages/addon-mcp/src/instructions/test-instructions.md	Adds test/validation workflow instructions section.
packages/addon-mcp/src/instructions/dev-instructions.md	Adds dev workflow instructions section for story writing + previewing.
packages/addon-mcp/src/instructions/build-server-instructions.ts	Implements instruction composition (dev/test/docs) including reuse from `@storybook/mcp`.
packages/addon-mcp/src/instructions/build-server-instructions.test.ts	Adds unit tests for instruction composition across toolset combinations.
packages/addon-mcp/pnpm-lock.yaml	Updates lockfile to reflect Storybook catalog bumps.
eval/variant-configs/testing-toolset-internal.ts	Updates eval variant to use `claude-sonnet-4.6`.
eval/variant-configs/preview-by-id-internal.ts	Updates eval variant to use `claude-sonnet-4.6`.
eval/variant-configs/component-concise-reshaped-internal.ts	Adds a concise internal variant config for reshaped tasks 901–907.
eval/types.ts	Updates supported model lists/mappings to include `claude-sonnet-4.6`.
eval/templates/grading/vitest.config.ts	Updates coverage exclusion from `preview.ts` to `preview.tsx`.
eval/tasks/901-create-component-atom-reshaped/hooks.ts	Adds MCP-tools-based quality scoring; updates preview file handling.
eval/tasks/901-create-component-atom-reshaped/config.json	Adds expected MCP tool usage thresholds for task scoring.
eval/tasks/901-create-component-atom-reshaped/README.md	Adds task documentation including expected tools + quality signal.
eval/tasks/902-create-component-composite-reshaped/hooks.ts	Adds MCP-tools-based quality scoring; updates preview file handling.
eval/tasks/902-create-component-composite-reshaped/config.json	Adds expected MCP tool usage thresholds for task scoring.
eval/tasks/902-create-component-composite-reshaped/README.md	Adds task documentation including expected tools + quality signal.
eval/tasks/903-create-component-async-fetch-reshaped/hooks.ts	Adds MCP-tools-based quality scoring; updates preview file handling.
eval/tasks/903-create-component-async-fetch-reshaped/config.json	Adds expected MCP tool usage thresholds for task scoring.
eval/tasks/903-create-component-async-fetch-reshaped/README.md	Adds task documentation including expected tools + quality signal.
eval/tasks/904-create-component-async-module-reshaped/hooks.ts	Adds MCP-tools-based quality scoring; updates preview file handling.
eval/tasks/904-create-component-async-module-reshaped/config.json	Adds expected MCP tool usage thresholds for task scoring.
eval/tasks/904-create-component-async-module-reshaped/README.md	Adds task documentation including expected tools + quality signal.
eval/tasks/905-existing-component-write-story-reshaped/hooks.ts	Adds MCP-tools-based quality scoring; updates preview file handling.
eval/tasks/905-existing-component-write-story-reshaped/config.json	Adds expected MCP tool usage thresholds for task scoring.
eval/tasks/905-existing-component-write-story-reshaped/README.md	Adds task documentation including expected tools + quality signal.
eval/tasks/906-existing-component-edit-story-reshaped/hooks.ts	Adds MCP-tools-based quality scoring; updates preview file handling.
eval/tasks/906-existing-component-edit-story-reshaped/config.json	Adds expected MCP tool usage thresholds for task scoring.
eval/tasks/906-existing-component-edit-story-reshaped/README.md	Adds task documentation including expected tools + quality signal.
eval/tasks/907-existing-component-change-component-reshaped/hooks.ts	Adds MCP-tools-based quality scoring; updates preview file handling.
eval/tasks/907-existing-component-change-component-reshaped/config.json	Adds expected MCP tool usage thresholds for task scoring.
eval/tasks/907-existing-component-change-component-reshaped/README.md	Adds task documentation including expected tools + quality signal.
eval/pnpm-lock.yaml	Updates eval lockfile to reflect Storybook catalog bumps.
eval/lib/agents/claude-code-cli.ts	Updates tokenizer/model mapping to support `claude-sonnet-4.6`.
eval/README.md	Updates documentation/examples to reference `claude-sonnet-4.6`.
apps/internal-storybook/pnpm-lock.yaml	Updates internal-storybook lockfile to reflect Storybook catalog bumps.
.changeset/mcp-server-instructions.md	Adds changeset bumping both packages for new server instructions behavior.

Files not reviewed (3)

apps/internal-storybook/pnpm-lock.yaml: Language not supported
eval/pnpm-lock.yaml: Language not supported
packages/addon-mcp/pnpm-lock.yaml: Language not supported

You can also share your feedback on Copilot code review. Take the survey.

…alCalls is 0 Co-authored-by: JReinhold <5678122+JReinhold@users.noreply.github.com>

Initial plan

282e37e

Copilot AI assigned Copilot and JReinhold Mar 3, 2026

Copilot started work on behalf of JReinhold March 3, 2026 13:00 View session

feat: add MCP server-level instructions to both packages

c5439b7

Co-authored-by: JReinhold <5678122+JReinhold@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add MCP server-level instructions in both packages~~ Add MCP server-level instructions to both packages Mar 3, 2026

Copilot finished work on behalf of JReinhold March 3, 2026 13:15

JReinhold requested changes Mar 5, 2026

View reviewed changes

Copilot started work on behalf of JReinhold March 5, 2026 12:13 View session

refactor: make addon instructions dynamic and composable

b349dd3

Co-authored-by: JReinhold <5678122+JReinhold@users.noreply.github.com>

Copilot finished work on behalf of JReinhold March 5, 2026 12:23

JReinhold requested changes Mar 5, 2026

View reviewed changes

Comment thread packages/addon-mcp/src/instructions/test-instructions.md Outdated

Comment thread packages/addon-mcp/src/mcp-handler.ts Outdated

Copilot started work on behalf of JReinhold March 5, 2026 12:43 View session

refactor: dynamic instructions getter and named tool in test instruct…

799a551

…ions Co-authored-by: JReinhold <5678122+JReinhold@users.noreply.github.com>

Copilot finished work on behalf of JReinhold March 5, 2026 12:47

JReinhold added 5 commits March 9, 2026 10:28

update reshaped-based tasks with configs, RDT manifests

b17868f

add concise variant config

cb93700

update to Claude Sonnet 4.6 in evals

25fe7aa

add mcp tool calls as quality metric for 901-907

1f886da

improve composability of server instructions

29419f1

JReinhold and others added 2 commits March 9, 2026 14:53

revert reshaped eval manifest updates

9fd9130

Merge branch 'main' into copilot/implement-mcp-server-instructions

3dd5b2a

JReinhold requested a review from kasperpeulen March 9, 2026 14:04

JReinhold approved these changes Mar 9, 2026

View reviewed changes

JReinhold marked this pull request as ready for review March 9, 2026 14:05

Copilot AI review requested due to automatic review settings March 9, 2026 14:05

JReinhold added 2 commits March 9, 2026 15:05

update storybook deps

79930fc

Merge branch 'copilot/implement-mcp-server-instructions' of https://g…

f6c5470

…ithub.com/storybookjs/mcp into copilot/implement-mcp-server-instructions

Copilot started reviewing on behalf of JReinhold March 9, 2026 14:05 View session

Copilot AI reviewed Mar 9, 2026

View reviewed changes

Comment thread packages/addon-mcp/src/mcp-handler.ts

Comment thread packages/mcp/src/instructions.md

Comment thread eval/lib/agents/claude-code-cli.ts

cleanup

a360f09

JReinhold mentioned this pull request Mar 10, 2026

Add prompt loader and root server prompt #18

Closed

update tests, sb deps

67fc5d6

kasperpeulen reviewed Mar 11, 2026

View reviewed changes

Comment thread eval/tasks/901-create-component-atom-reshaped/hooks.ts

kasperpeulen requested changes Mar 11, 2026

View reviewed changes

Copilot started work on behalf of JReinhold March 11, 2026 12:26 View session

fix: return mcpToolsSummary when expectedToolCount is set even if tot…

8dbd727

…alCalls is 0 Co-authored-by: JReinhold <5678122+JReinhold@users.noreply.github.com>

Copilot finished work on behalf of JReinhold March 11, 2026 12:27

kasperpeulen self-requested a review March 11, 2026 13:00

kasperpeulen approved these changes Mar 11, 2026

View reviewed changes

JReinhold merged commit 6c02ee2 into main Mar 11, 2026
11 checks passed

JReinhold deleted the copilot/implement-mcp-server-instructions branch March 11, 2026 13:10

storybook-app-bot bot mentioned this pull request Mar 11, 2026

Version Packages #192

Merged

Conversation

Copilot AI commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Mar 5, 2026

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Mar 5, 2026

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

pkg-pr-new bot commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

codecov bot commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Report

Affected Assets, Files, and Routes:

Assets Changed:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Mar 3, 2026 •

edited

Loading

changeset-bot bot commented Mar 3, 2026 •

edited

Loading

pkg-pr-new bot commented Mar 9, 2026 •

edited

Loading

codecov bot commented Mar 9, 2026 •

edited

Loading

codecov bot commented Mar 9, 2026 •

edited

Loading