feat(mcp): expose plan / verify / list_projects on wizard-mcp-server#258
Closed
kelsonpw wants to merge 2 commits intokelsonpw/agent-ui-hintsfrom
Closed
feat(mcp): expose plan / verify / list_projects on wizard-mcp-server#258kelsonpw wants to merge 2 commits intokelsonpw/agent-ui-hintsfrom
kelsonpw wants to merge 2 commits intokelsonpw/agent-ui-hintsfrom
Conversation
The external MCP server (`amplitude-wizard mcp serve`) already exposes the read-only agent-ops functions over stdio so third-party AI coding agents can call them directly instead of shelling out and parsing NDJSON. This PR adds the three new agent-ops landed in #255 / #257 to that surface so they're MCP-callable too. New tools: plan_setup → runPlan(installDir) Runs detection + builds + persists a WizardPlan. Documented as no-writes; returns { plan, detected }. verify_setup → runVerify(installDir) Cheap, no-network SDK / API-key / framework check. Returns { outcome: pass|fail, failures: [...] }. list_projects → runProjectsList({ query?, limit?, offset? }) Paginated, search-filtered project list. Surfaces a `warning` field on the auth-required path so MCP clients can route to a login flow instead of treating it as an error. Surface stays read-only — `apply` is intentionally NOT exposed. The sub-agent contract is "outer agent inspects → re-invokes the CLI to write," which keeps the responsibility for destructive operations on the user-facing CLI where flags and exit codes can gate them properly. Tests: +8 in wizard-mcp-server.test.ts (1311 total). Suite green. Stacked on #257. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
🧙 Wizard CIRun the Wizard CI and test your changes against wizard-workbench example apps by replying with a GitHub comment using one of the following commands: Test all apps:
Test all apps in a directory:
Test an individual app:
Show more apps
Results will be posted here when complete. |
6 tasks
…ashes (#259) * feat(agent): apply --resume — resumable Claude SDK sessions across crashes When `apply` runs the inner Claude SDK agent, capture the session id from the first system/init message and persist it on the plan. A subsequent `apply --plan-id <id> --yes --resume` passes that id to the SDK as `resume:`, rehydrating the conversation instead of starting a fresh agent that has to redo SDK install + package detection + file reads. Surface area: WizardPlan now optionally carries: agentSessionId — UUID of the prior SDK session agentSessionUpdatedAt — when it was captured apply --resume — opt-in flag; pulls agentSessionId from the persisted plan and forwards to the spawned child via AMPLITUDE_WIZARD_RESUME_SESSION_ID. When the plan has no captured session yet, logs a structured warning and falls through to a fresh run (right default for the very first apply against a plan). applyPlanPatch(planId, p) — partial-update helper for plans on disk; best-effort, returns null on miss. getApplyContextFromEnv() — agent-runner reads { planId, resumeSessionId } from env vars set by `apply` so the spawn boundary stays decoupled from the SDK call site. Both vars optional — fresh runs work. Wiring in agent-runner: pass `resumeSessionId` and `onSessionStart` into `runAgent`. The latter fires once on system/init and patches the plan with the SDK-assigned session id (handles both fresh runs AND forks from a resumed session, which the SDK gives a new id). Wiring in agent-interface: two new optional `runAgent` config fields (`onSessionStart`, `resumeSessionId`). Surgical change — adds 6 lines to the SDK message loop and 1 line to the query options. Tests: +8 in agent-plans.test.ts (1319 total). Suite green. Smoke tests: $ wizard plan --json → planId X (no agentSessionId) $ wizard apply --plan-id X --yes → first run; captures session $ wizard apply --plan-id X --resume --yes → second run; resumes $ wizard apply --plan-id Y --resume --yes → warns "no captured session", runs fresh Stacked on #258. Closes the design-doc gap on mid-`apply` work loss (SIGINT, network drop, terminal crash). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix: replace vendor name 'Claude SDK' with 'agent' in CLI help text Applied via @cursor push command --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Cursor Agent <cursoragent@cursor.com>
This was referenced Apr 26, 2026
Collaborator
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The external MCP server (
amplitude-wizard mcp serve,src/lib/wizard-mcp-server.ts) already exposes the read-only agent-ops functions over stdio so third-party AI coding agents (Claude Code, Cursor, Codex) can call them as typed tools instead of shelling out to the CLI and parsing NDJSON. This PR registers the three new agent-ops landed in #255 (plan/verify) and #257 (projects list) on that surface so they're MCP-callable too.Stacked on #257. Read-only by design —
applyis intentionally NOT exposed. The sub-agent contract is "outer agent inspects → re-invokes the CLI to write," which keeps responsibility for destructive operations on the user-facing CLI where flags + exit codes can gate them properly.New tools
plan_setuprunPlan(installDir){ plan, detected }.verify_setuprunVerify(installDir){ outcome: 'pass' | 'fail', failures: [...] }.list_projectsrunProjectsList({ query?, limit?, offset? })warningfield on the auth-required path so MCP clients can route to a login flow instead of treating it as an error.What an outer agent sees
The
plan_setupdescription explicitly flags "no files are touched" so the LLM picking the tool doesn't assume calling it executes the install.Test plan
pnpm test— 1311 passed, 17 skipped (8 new tests in wizard-mcp-server.test.ts, 19 total)pnpm tsc --noEmitcleanpnpm lintcleannpx amplitude-wizard mcp servelists 7 tools via MCPlist_toolsmcp__amplitude-wizard__list_projectswith a query, get back a paginated resultWhy not also expose
apply?Keeping the MCP surface read-only is deliberate:
--yes/--forcematrix gates writes today. Exposingapplyover MCP would mean re-encoding that gate inside the tool's input schema, plus a parallel "are you sure" dance in the protocol. That's a regression in clarity.apply --plan-id <id> --yesis idempotent, scriptable, and emits structured NDJSON. MCP clients justspawn(['amplitude-wizard', 'apply', '--plan-id', planId, '--yes'])and stream the events. No new protocol needed.applyisn't on the surface.cc @amplitude/growth
🤖 Generated with Claude Code
Note
Medium Risk
Medium risk because it adds a new resume path that threads session IDs through CLI env vars into the Claude SDK and persists them into on-disk plans; mistakes could cause confusing apply behavior or stale-session loops.
Overview
Adds three new read-only MCP tools on the external
wizard mcp servesurface:plan_setup,verify_setup, andlist_projects, each wrapping the correspondingagent-opsfunction with typed input schemas.Enhances
wizard applywith an optional--resumeflag and plan persistence updates so apply runs can capture the Claude SDKsession_idinto the stored plan and later resume an interrupted agent session by forwardingAMPLITUDE_WIZARD_RESUME_SESSION_IDinto the agent runner/SDK.Updates the agent interface/runner to accept
resumeSessionId, emitonSessionStart, and patch the plan on session start; expands unit tests to cover MCP tool registration/forwarding and plan patching/env apply context helpers.Reviewed by Cursor Bugbot for commit a90692a. Bugbot is set up for automated code reviews on this repo. Configure here.