# MCP Stub To Ground Truth

> 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.

- Skill: `tankygranny05/mcp-stub-to-ground-truth` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tankygranny05/mcp-stub-to-ground-truth`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tankygranny05/mcp-stub-to-ground-truth/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tankygranny05 (https://skillmd.com/u/tankygranny05)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/tankygranny05/mcp-stub-to-ground-truth

---


# 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`