# Web Viewer - VS Code Extension Template

VS Code extension template for displaying webview with MCP Server integration for AI agents.

## Features

- 📱 **Web Viewer**: Display HTML/SPA in VS Code tab
- 🤖 **MCP Server**: Standalone server for AI agents (Claude, Cursor, Gemini)
- 🔧 **Tools**: Open, close, navigate, click, input, scroll, get state
- 📦 **Resources**: State, DOM structure
- ⚡ **2-file tool addition**: Only modify 2 files to add new tools
- 🔄 **Auto MCP Config**: Automatically registers in VS Code's mcp.json on install

## Installation

### From VSIX (Recommended)

1. Download `web-viewer-0.0.1.vsix`
2. In VS Code: `Ctrl+Shift+P` → "Extensions: Install from VSIX..."
3. Select the VSIX file
4. Reload VS Code
5. MCP server is automatically configured! ✨

### From Source

```bash
npm install
npm run build
```

## Scripts

| Script | Description |
|--------|-------------|
| `npm run build` | Build all (webview + extension + MCP bundle) |
| `npm run build:webview` | Build webview with Vite |
| `npm run bundle:mcp` | Bundle MCP server with esbuild |
| `npm run dev:webview` | Watch mode for webview |
| `npm run compile` | Compile TypeScript extension |

## Running the Extension

1. Open project in VS Code
2. Press `F5` to launch Extension Development Host
3. Extension auto-starts (onStartupFinished)
4. Run command `Open Web viewer` from Command Palette

## MCP Server

### Auto Configuration

When you install the extension, it automatically adds the MCP server to:
- **Windows**: `%APPDATA%\Code\User\mcp.json`
- **macOS**: `~/Library/Application Support/Code/User/mcp.json`
- **Linux**: `~/.config/Code/User/mcp.json`

You can also manually trigger this with: `Ctrl+Shift+P` → "Web viewer: Update MCP Configuration"

### Tools

| Tool | Description |
|------|-------------|
| `web_open` | Open Web viewer tab |
| `web_close` | Close Web viewer tab |
| `web_navigate` | Navigate to route |
| `web_click` | Click element by CSS selector |
| `web_input` | Input text into form field |
| `web_scroll` | Scroll page (y pixels) |
| `web_get_state` | Get current state |

### Resources

| URI | Description |
|-----|-------------|
| `web://state` | Current state (URL, title, forms, links) |
| `web://dom` | DOM structure |

## Project Structure

```
├── media/                    # Build output (Vite)
├── src/
│   ├── extension.ts          # Entry point
│   ├── core/                 # Generic modules (don't modify)
│   │   ├── ViewerProvider.ts
│   │   ├── HttpBridge.ts
│   │   └── McpConfigUpdater.ts  # Auto-update mcp.json
│   ├── mcp/
│   │   └── mcp-server.ts     # MCP server (don't modify)
│   ├── tools/
│   │   └── index.ts          # ⭐ Tool schemas
│   └── webview/
│       ├── bridge.ts         # Core handlers (don't modify)
│       └── main.ts           # ⭐ Custom handlers
├── vite.config.ts
└── package.json
```

## Adding New Tools (2 files only)

### 1. Schema: `src/tools/index.ts`

```typescript
{
    name: 'web_scroll',
    description: 'Scroll page by pixels',
    inputSchema: {
        type: 'object',
        properties: {
            y: { type: 'number', description: 'Pixels to scroll' },
        },
        required: ['y'],
    },
},
```

### 2. Handler: `src/webview/main.ts`

```typescript
registerHandler('scroll', (payload: { y: number }) => {
    window.scrollBy(0, payload.y);
    return true;
});
```

> **Note**: Tool name `web_scroll` → handler name `scroll` (prefix `web_` is auto-stripped)

### 3. Build

```bash
npm run build
```

## Packaging VSIX

```bash
# Build and package
npm run build
npx @vscode/vsce package --allow-missing-repository

# Install locally
code --install-extension web-viewer-0.0.1.vsix
```

## Architecture

```
AI Agent <--stdio--> MCP Server <--HTTP:54321--> VS Code Extension <--postMessage--> Webview
                         |                              |                               |
                  tools/index.ts              extension.ts                      bridge.ts
                  (auto-forward)           (defaultHandler)                     main.ts
```

## Commands

| Command | Description |
|---------|-------------|
| `Web viewer: Open Web viewer` | Open the webview panel |
| `Web viewer: Update MCP Configuration` | Manually update mcp.json |

## License

MIT