CLI: Show MCP workflow instructions in AI help#35164
Conversation
kasperpeulen
added
feature request
ci:normal
kasperpeulen
force-pushed
the
kasper/ai-cli-mcp-instructions
branch
4 times, most recently
from
1533c5b to
6844c03
Compare
kasperpeulen
force-pushed
the
kasper/ai-cli-mcp-instructions
branch
from
6844c03 to
b423f76
Compare
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
💤 Files with no reviewable changes (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughThe MCP client gains two exported types ( ChangesMCP server metadata from initialize handshake
Sequence Diagram(s)sequenceDiagram
participant buildStorybookCommandsHelp
participant listMcpToolsWithServerMetadata
participant sendJsonRpcRequest
participant initializeMcpSession
participant McpServer as MCP Server
rect rgba(70, 130, 180, 0.5)
note over buildStorybookCommandsHelp,McpServer: Tool list + metadata fetch
buildStorybookCommandsHelp->>listMcpToolsWithServerMetadata: fetch tools + metadata
listMcpToolsWithServerMetadata->>sendJsonRpcRequest: tools/list
sendJsonRpcRequest->>initializeMcpSession: POST initialize
initializeMcpSession->>McpServer: initialize request
McpServer-->>initializeMcpSession: response (Mcp-Session-Id header + body)
initializeMcpSession->>initializeMcpSession: parse instructions from result
initializeMcpSession-->>sendJsonRpcRequest: { sessionId, serverMetadata }
sendJsonRpcRequest->>McpServer: POST tools/list (Mcp-Session-Id)
McpServer-->>sendJsonRpcRequest: tools result
sendJsonRpcRequest-->>listMcpToolsWithServerMetadata: { result, serverMetadata }
listMcpToolsWithServerMetadata-->>buildStorybookCommandsHelp: { tools, serverMetadata }
end
buildStorybookCommandsHelp->>buildStorybookCommandsHelp: check serverMetadata.instructions
note right of buildStorybookCommandsHelp: Render "Storybook workflow instructions" block if present and non-empty
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes ✨ Finishing Touches📝 Generate docstrings
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@code/core/src/cli/ai/mcp/client.ts`:
- Around line 178-180: When the response is not OK in the MCPClient (at the if
(!response.ok) check around line 178-180), the response body is not being
drained before returning early. This can cause connection reuse issues on
repeated failures. Before returning the early exit with null sessionId and empty
serverMetadata, drain the response body by calling response.body?.cancel() or
reading the response text/blob to ensure the underlying HTTP connection is
properly cleaned up.
In `@code/core/src/cli/ai/mcp/run-tool.test.ts`:
- Around line 254-263: Move the listMcpToolsWithServerMetadata mock behavior
setup from inline within test bodies into a beforeEach block. Establish the base
mock implementation with mockResolvedValue in beforeEach using a default fixture
object, then in individual tests override only the specific fixture values that
need to be different for that particular test case rather than re-declaring the
entire mock implementation each time.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 0060f74d-524c-431a-b9bd-0d6c604b0c0f
📒 Files selected for processing (4)
code/core/src/cli/ai/mcp/client.test.tscode/core/src/cli/ai/mcp/client.tscode/core/src/cli/ai/mcp/run-tool.test.tscode/core/src/cli/ai/mcp/run-tool.ts
kasperpeulen
force-pushed
the
kasper/ai-cli-mcp-instructions
branch
from
b423f76 to
6a0a51c
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@code/core/src/cli/ai/mcp/run-tool.ts`:
- Around line 207-210: The condition at lines 207-210 in the run-tool.ts file
returns unavailable when serverMetadata.instructions is missing or empty, which
suppresses the entire command from being listed. Instead of returning
unavailable, the code should allow the command to be included in the list but
simply omit or skip the workflow section when instructions are absent. Modify
the logic to handle missing instructions gracefully by excluding only the
workflow-related portion of the response while still providing the command
help/availability. The same pattern applies at lines 212-222, where similar
handling of missing instructions should be implemented to ensure commands remain
available even when workflow instructions are not provided.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 51f8f5ff-7286-4cf3-bd2e-0fc7237c4e2a
📒 Files selected for processing (3)
code/core/src/cli/ai/mcp/client.tscode/core/src/cli/ai/mcp/run-tool.test.tscode/core/src/cli/ai/mcp/run-tool.ts
🚧 Files skipped from review as they are similar to previous changes (2)
- code/core/src/cli/ai/mcp/run-tool.test.ts
- code/core/src/cli/ai/mcp/client.ts
kasperpeulen
force-pushed
the
kasper/ai-cli-mcp-instructions
branch
from
6a0a51c to
f91b919
Compare
kasperpeulen
force-pushed
the
kasper/ai-cli-mcp-instructions
branch
from
f91b919 to
1aaf82d
Compare
|
The workflow instructions shown in `storybook ai --help` ride on the MCP `initialize` handshake, which used a tight 3s best-effort budget (telemetry garnish). A slow or still-starting dev server could drop the instructions while the separate `tools/list` request succeeded, making help show "no instructions" even though the server has them. - Give the handshake the full request budget (REQUEST_TIMEOUT_MS) on every path. The only thing that slows it is the dev server starting up, which the command must wait through anyway, so the tighter budget bought nothing. - Assert the instructions are present (invariant) instead of degrading to an "unavailable" note: addon-mcp gates instructions and tools on the same toolsets, so with commands present their absence can only be a contract bug. - Drop the now-impossible empty-instructions test.
`sendJsonRpcRequest` and `parseInitializeServerMetadata` both parsed the JSON-RPC envelope and checked for parse failure / error / missing result. Extract a single `unwrapJsonRpcResult` helper: the command path throws on the reported error, the best-effort initialize-metadata parse falls back to empty.
|
Update — implemented ( Landed a simpler fix than the timeout-threading proposed above: instead of giving the help path its own Missing instructions are now an Note: this also moves command execution's handshake off the 3s budget (it came from the telemetry handshake in #35131) — called out in the PR description. |
Package BenchmarksCommit: The following packages have significant changes to their size or dependencies:
|
| Before | After | Difference | |
|---|---|---|---|
| Dependency count | 72 | 72 | 0 |
| Self size | 21.04 MB | 21.02 MB | 🎉 -20 KB 🎉 |
| Dependency size | 36.12 MB | 36.12 MB | 0 B |
| Bundle Size Analyzer | Link | Link |
@storybook/cli
| Before | After | Difference | |
|---|---|---|---|
| Dependency count | 203 | 203 | 0 |
| Self size | 802 KB | 802 KB | 🎉 -84 B 🎉 |
| Dependency size | 89.20 MB | 89.18 MB | 🎉 -20 KB 🎉 |
| Bundle Size Analyzer | Link | Link |
@storybook/codemod
| Before | After | Difference | |
|---|---|---|---|
| Dependency count | 196 | 196 | 0 |
| Self size | 32 KB | 32 KB | 🎉 -36 B 🎉 |
| Dependency size | 87.69 MB | 87.67 MB | 🎉 -20 KB 🎉 |
| Bundle Size Analyzer | Link | Link |
create-storybook
| Before | After | Difference | |
|---|---|---|---|
| Dependency count | 73 | 73 | 0 |
| Self size | 1.08 MB | 1.08 MB | 0 B |
| Dependency size | 57.16 MB | 57.14 MB | 🎉 -20 KB 🎉 |
| Bundle Size Analyzer | node | node |
2 participants
Closes #35163
What I did
initialize.result.instructionsfrom the existing MCP handshake used bystorybook ai.storybook ai --helpbefore the dynamicStorybook commandslist.tools/list, preserve the existing degraded help states (no Storybook, addon missing/starting/erroring, server unreachable, no commands), and leave feature-flag-off behavior unchanged.initializemetadata on the full request budget so a slow or still-starting dev server can't drop the instructions whiletools/listsucceeds — the only thing that slows the handshake is the dev server starting up, which the command waits through anyway.initializehandshake budget for command execution (3s -> full request budget); the 3s originated with the telemetry handshake in Telemetry forstorybook ai <command>CLI (ai-command event + clientInfo segmentation) #35131.0.0.0-pr-35164-sha-fe7f4278against thestorybookjs/mcpinternal Storybook: feature-flagged help rendersStorybook workflow instructionsbeforeStorybook commandsand keeps the dynamic command list fromtools/list; feature-flag-off help remains unchanged.9f2d2ff(explicit tool-list type and initialize metadata tests for malformed/SSE responses).Checklist for Contributors
Testing
The changes in this PR are covered in the following automated tests:
Manual testing
Caution
This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly. Thanks!
@storybook/addon-mcpinstalled and ready.STORYBOOK_FEATURE_AI_CLI=1 storybook ai --help.# Storybook workflow instructionssection (from the MCPinitializeresponse) before the# Storybook commandslist.tools/listoutput.unavailablenote when no Storybook is running, MCP is missing/starting/erroring, or the command server cannot be reached.storybook aiwithoutSTORYBOOK_FEATURE_AI_CLI=1still exposes the pre-existingsetupbehavior only.Documentation
MIGRATION.MD
Checklist for Maintainers
When this PR is ready for testing, make sure to add
ci:normal,ci:mergedorci:dailyGH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found incode/lib/cli-storybook/src/sandbox-templates.tsDeclare whether manual QA will be needed for this PR during the next release, through
qa:neededorqa:skipMake sure this PR contains one of the labels below:
Available labels
bug: Internal changes that fixes incorrect behavior.maintenance: User-facing maintenance tasks.dependencies: Upgrading (sometimes downgrading) dependencies.build: Internal-facing build tooling & test updates. Will not show up in release changelog.cleanup: Minor cleanup style change. Will not show up in release changelog.documentation: Documentation only changes. Will not show up in release changelog.feature request: Introducing a new feature.BREAKING CHANGE: Changes that break compatibility in some way with current major version.other: Changes that don't fit in the above categories.🦋 Canary release
This pull request has been released as version
0.0.0-pr-35164-sha-1aaf82d2. Try it out in a new sandbox by runningnpx storybook@0.0.0-pr-35164-sha-1aaf82d2 sandboxor in an existing project withnpx storybook@0.0.0-pr-35164-sha-1aaf82d2 upgrade.More information
0.0.0-pr-35164-sha-1aaf82d2kasper/ai-cli-mcp-instructions1aaf82d21781531257)To request a new release of this pull request, mention the
@storybookjs/coreteam.core team members can create a new canary release here or locally with
gh workflow run --repo storybookjs/storybook publish.yml --field pr=35164Summary by CodeRabbit