# 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
