mcp-stub-to-ground-truth

name	mcp-stub-to-ground-truth
description	This skill should be used when MCP stubs or broken control_request flows need to be replaced with ground-truth implementations aligned to extension.js and cli.js, or when MCP-related UI behavior (missing tool outputs, spinner stuck, empty MCP list) needs debugging.

Mcp Stub To Ground Truth

[Created by Codex: 019bd6fe-9c71-7c43-aa42-b69a3ceb5a46]

Overview

Provide a repeatable workflow for replacing MCP stubs with compliant control_request handling and for diagnosing broken MCP UI behavior. Use extension.js and cli.js as ground truth, and treat webview behavior as a secondary constraint.

When To Use

Use when any of these occur:

• MCP panels show empty or stale server lists.
• Tool permission prompts never appear.
• Spinner never stops or assistant output never renders.
• MCP tools run in the CLI but the webview does not update.
• Control_request/control_response traffic is stubbed, dropped, or faked.

Workflow: Stub → Ground Truth

1) Load Ground Truth

• Read ~/.vscode/extensions/anthropic.claude-code-*/extension.js.
• Read ~/swe/claude-code-*/cli.js.
• Read src/public/webview/index.js for request/response shapes and channel expectations.
• Extract exact request/response subtypes and schemas.

2) Inventory Stubs And Drops

• Search for any shim logic that returns {success: true} without a CLI control_request.
• Search for control_request, control_response, control_cancel_request drops.
• Identify MCP requests stubbed in the webview-to-extension request handler.
• Identify channel/session routing that broadcasts to the wrong client.

3) Implement Bidirectional Control Plane

• Route CLI → shim control_request to webview request handlers.
• Route webview responses back to CLI as control_response.
• Route CLI control_cancel_request to cancel webview prompts.
• Replace stubbed webview request handlers with real CLI control_request forwarding.

4) Implement MCP Control Surface

• Map get_mcp_servers → CLI control_request subtype mcp_status.
• Map mcp_set_servers (if surfaced) → CLI control_request subtype mcp_set_servers.
• Map mcp_message round-trip: CLI control_request subtype mcp_message ↔ SDK transport.
• Always forward CLI errors back to the webview response.

5) Enforce Channel/Session Correctness

• Create channels only on launch_claude.
• Do not auto-spawn on io_message for unknown channel IDs.
• Route io_message only to the client that launched that channel.
• Remove channel registration on close_channel.

6) Validate With Logs

• Confirm control_request and control_response appear in both extension_to_cli.jsonl and cli_to_extension.jsonl.
• Confirm webview receives tool_permission_request when CLI emits can_use_tool.
• Confirm message_stop and result arrive for assistant output.
• Confirm no Session not found warnings for the active channel.

Mapping Table: Webview ↔ CLI Control Requests

Webview request type	CLI control_request subtype	Response type
get_mcp_servers	mcp_status	get_mcp_servers_response
set_model	set_model	set_model_response
set_permission_mode	set_permission_mode	set_permission_mode_response
set_thinking_level	set_max_thinking_tokens	set_thinking_level_response
rewind_code	rewind_files	rewind_code_response

Sequence Diagrams (MCP Control Requests)

A) MCP Status Query (Webview → CLI → Webview)

Webview            Shim/Extension              CLI
   |  get_mcp_servers  |                        |
   |------------------>| handleRequest          |
   |                   | control_request:mcp_status
   |                   |----------------------->|
   |                   |<-----------------------| control_response:success {mcpServers}
   |<------------------| get_mcp_servers_response

B) MCP Message Round-Trip (CLI → Extension → SDK → CLI)

CLI                  Shim/Extension          SDK MCP Server
 | control_request:mcp_message                 |
 |------------------------->| locate transport |
 |                          |----------------->| JSON-RPC request
 |                          |<-----------------| JSON-RPC response
 |<-------------------------| control_response:success {mcp_response}

C) MCP-Related Permission Prompt (CLI → Webview → CLI)

CLI                  Shim/Extension            Webview
 | control_request:can_use_tool                 |
 |------------------------->| request:tool_permission_request |
 |                          |------------------------------->|
 |                          |<-------------------------------| response:tool_permission_response
 |<-------------------------| control_response:success {behavior,...}

Debug Checklist (Failure → Likely Cause)

• Spinner stuck, no assistant output
  • Check for missing message_stop or result in webview logs.
  • Check for Session not found warnings (wrong channel routing).
• MCP list empty
  • Verify mcp_status control_request is sent and control_response returned.
• Tool prompts missing
  • Verify can_use_tool reaches webview as tool_permission_request.
• MCP tool runs in CLI but webview shows nothing
  • Verify control_response is not dropped and is routed back to webview.

Required Log Files

Check these files side-by-side:

• ~/centralized-logs/claude-vscode-shim/extension_to_cli.jsonl
• ~/centralized-logs/claude-vscode-shim/cli_to_extension.jsonl
• ~/centralized-logs/claude-vscode-shim/extension_to_webview.jsonl
• ~/centralized-logs/claude-vscode-shim/webview_to_extension.jsonl