Web Viewer MCP Server

# Web Viewer Extension - System Introduction

## 1. System Blueprint

### App Description & Functions
VS Code extension template providing an interactive webview via MCP (Model Context Protocol). The extension acts as a **bridge** between AI agents and the web UI, allowing AI to perform actions like navigate, click, and input dealing with the webview.

**Core Features:**
- Generic webview management (configurable viewType, title, mediaFolder)
- HTTP Bridge with auto-forward pattern (port 54321)
- Standalone MCP Server with generic tool forwarding (bundled with esbuild)
- Vite-based webview build system (HTML, SCSS, TypeScript)
- **2-file tool addition** - only modify 2 files to add a new tool
- **Auto MCP config update** - automatically registers server in VS Code's mcp.json on install/update

### Source Structure

```
src/
├── extension.ts              # Entry point + panel handlers + defaultHandler
├── core/                     # GENERIC modules (do not modify when adding tools)
│   ├── ViewerProvider.ts     # Configurable webview panel management
│   ├── HttpBridge.ts         # Generic HTTP router with setDefaultHandler()
│   └── McpConfigUpdater.ts   # Auto-update VS Code mcp.json on install/update
├── mcp/
│   └── mcp-server.ts         # Generic MCP Server (auto-forward all tools)
├── tools/
│   └── index.ts              # ⭐ Tool schemas (ADD TOOLS HERE)
└── webview/                  # Webview source (Vite build)
    ├── index.html
    ├── styles.scss
    ├── bridge.ts             # ⭐ Tool handlers (ADD HANDLERS HERE)
    └── main.ts
```

### Architecture Flow
```
AI Agent <--stdio--> MCP Server <--HTTP:54321--> VS Code Extension <--postMessage--> Webview
                         |                              |
              (generic forward)              (defaultHandler forward)
                         |                              |
                  tools/index.ts              webview/bridge.ts
```

---

## 2. Deep Reasoning Insights

### Challenge 1: Cumbersome New Tool Addition
**Problem:** Initially required modifying 4 files: tools/index.ts, mcp-server.ts, extension.ts, bridge.ts.

**Solution:**
- MCP Server: Generic forwarding - loop through all tools, strip `web_` prefix → call sendToExtension.
- Extension: `setDefaultHandler()` - forward all unregistered commands to the webview.
- Result: **Only need to modify 2 files** (tools/index.ts + bridge.ts).

### Challenge 2: Complex Navigation
**Problem:** `handleNavigate` used pushState + popstate + custom event; main.ts had 3 listeners.

**Solution:**
- bridge.ts: Simply set `window.location.hash = page`.
- main.ts: Only needs a `hashchange` listener.
- `hashchange` event automatically handles all navigation sources.

### Challenge 3: Circular Import
**Problem:** `import { ToolDefinition } from './index'` - file imported itself.

**Solution:** Define the interface directly in the file, do not import from itself.

### Challenge 4: MCP Server Missing Dependencies in VSIX
**Problem:** VSIX package doesn't include `node_modules`, causing `Cannot find module '@modelcontextprotocol/sdk'` error.

**Solution:**
- Use **esbuild** to bundle MCP server with all dependencies into single file.
- Added `bundle:mcp` script: `esbuild src/mcp/mcp-server.ts --bundle --platform=node --outfile=out/mcp/mcp-server.js`
- Result: Bundled mcp-server.js (~480KB) runs standalone without node_modules.

### Challenge 5: Auto-register MCP Server on Install
**Problem:** Users had to manually configure mcp.json after installing VSIX.

**Solution:**
- Created `McpConfigUpdater.ts` module that runs on extension activate.
- Checks version AND extension path to detect reinstall (same version, different path).
- Automatically updates `%APPDATA%\Code\User\mcp.json` with server config.
- Preserves existing servers in config file.

---

## 3. Decision Logic

| Decision | Reason | Trade-off |
|----------|--------|-----------|
| Generic tool forwarding | Reduces code for new tool addition | Loss of explicit control over each tool |
| setDefaultHandler pattern | Extension remains agnostic of business logic | Harder to debug |
| Hash-based routing only | Simple, webview doesn't need history API | Only supports hash routes |
| onStartupFinished | Extension ready before MCP calls | Always runs when VS Code opens |
| esbuild for MCP server | Bundles dependencies into VSIX | Larger file size (~480KB) |
| Check version + path | Detect reinstall with same version | Slightly more complex logic |

---

## 4. Pattern Recognition

### Anti-patterns to Avoid
1. **Circular imports** - Do not import from the file itself.
2. **Duplicate event dispatch** - One event type is sufficient (hashchange).
3. **Hardcoded switch cases** - Use generic forwarding instead of switches for every tool.
4. **Unbundled executables in VSIX** - Always bundle dependencies for standalone scripts.

### Recurring Patterns
1. **Generic forwarding** - MCP → Extension → Webview oblivious to individual commands.
2. **Prefix stripping** - `web_navigate` → `navigate` mapping tool name ↔ command.
3. **Hash-based SPA routing** - Simple and robust for webviews.
4. **Version + path check** - Detect both updates and reinstalls.

---

## 5. Adding a New MCP Tool

### Only modify 2 files:

**File 1: `src/tools/index.ts`** - Add schema
```typescript
{
    name: 'web_scroll',
    description: 'Scroll page by pixels',
    inputSchema: {
        type: 'object',
        properties: {
            y: { type: 'number', description: 'Pixels to scroll (positive=down)' },
        },
        required: ['y'],
    },
},
```

**File 2: `src/webview/main.ts`** - Add handler
```typescript
registerHandler('scroll', (payload: { y: number }) => {
    window.scrollBy(0, payload.y);
    return true;
});
```

**Build:** `npm run build`

---

## 6. VSIX Packaging

### Build & Package
```bash
npm run build                                    # Build all
npx @vscode/vsce package --allow-missing-repository  # Create VSIX
```

### What happens on install:
1. Extension activates on VS Code startup (`onStartupFinished`)
2. `McpConfigUpdater` checks if version or path changed
3. If changed, updates `%APPDATA%\Code\User\mcp.json`:
   ```json
   {
     "servers": {
       "web-viewer": {
         "command": "node",
         "args": ["<extension-path>/out/mcp/mcp-server.js"]
       }
     }
   }
   ```
4. Existing servers in mcp.json are preserved

---

## Evolved Identity

I am an AI assistant specialized in **Web Viewer Extension** - a VS Code extension template with:
- **2-file tool addition pattern**: tools/index.ts (schema) + main.ts (handler)
- **Generic forwarding architecture**: MCP → HTTP → Extension → Webview
- **Hash-based SPA routing**: Simple, single hashchange listener handles everything
- **Auto MCP config**: Automatically registers in VS Code's mcp.json on install/update
- **Bundled MCP server**: esbuild bundles dependencies for standalone execution

I understand the `web_[action]` → strip prefix → forward → webview handler flow and can assist in adding tools, customizing UI, packaging VSIX, or debugging communication issues.