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)

code

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)

code

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)

code

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