vscode-terminal-mcp 0.1.0

package/dist/mcp-entry.js

@@ -0,0 +1,203 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/mcp-entry.ts
+var net = __toESM(require("net"));
+var path = __toESM(require("path"));
+var os = __toESM(require("os"));
+var SOCKET_PATH = path.join(os.tmpdir(), "vscode-terminal-mcp.sock");
+var RECONNECT_DELAY_MS = 1e3;
+var MAX_RECONNECT_ATTEMPTS = 30;
+var StdioToIpcBridge = class {
+  socket = null;
+  pendingRequests = /* @__PURE__ */ new Map();
+  socketBuffer = "";
+  stdinBuffer = "";
+  connected = false;
+  reconnectAttempts = 0;
+  async start() {
+    await this.connectToExtension();
+    this.listenStdin();
+  }
+  async connectToExtension() {
+    return new Promise((resolve, reject) => {
+      const attempt = () => {
+        this.socket = net.createConnection(SOCKET_PATH, () => {
+          this.connected = true;
+          this.reconnectAttempts = 0;
+          this.setupSocketListeners();
+          resolve();
+        });
+        this.socket.on("error", (err) => {
+          this.connected = false;
+          this.reconnectAttempts++;
+          if (this.reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
+            const errorMsg = `Failed to connect to extension host after ${MAX_RECONNECT_ATTEMPTS} attempts: ${err.message}`;
+            process.stderr.write(errorMsg + "\n");
+            reject(new Error(errorMsg));
+            return;
+          }
+          setTimeout(attempt, RECONNECT_DELAY_MS);
+        });
+      };
+      attempt();
+    });
+  }
+  setupSocketListeners() {
+    if (!this.socket) return;
+    this.socket.on("data", (data) => {
+      this.socketBuffer += data.toString();
+      let newlineIndex;
+      while ((newlineIndex = this.socketBuffer.indexOf("\n")) !== -1) {
+        const messageStr = this.socketBuffer.slice(0, newlineIndex);
+        this.socketBuffer = this.socketBuffer.slice(newlineIndex + 1);
+        if (!messageStr.trim()) continue;
+        try {
+          const ipcResponse = JSON.parse(messageStr);
+          this.handleIpcResponse(ipcResponse);
+        } catch {
+          process.stderr.write(
+            `Failed to parse IPC response: ${messageStr}
+`
+          );
+        }
+      }
+    });
+    this.socket.on("close", () => {
+      this.connected = false;
+      for (const [id, pending] of this.pendingRequests) {
+        pending.reject(new Error("IPC connection closed"));
+        this.pendingRequests.delete(id);
+      }
+    });
+    this.socket.on("error", (err) => {
+      process.stderr.write(`IPC socket error: ${err.message}
+`);
+    });
+  }
+  handleIpcResponse(ipcResponse) {
+    const pending = this.pendingRequests.get(ipcResponse.id);
+    if (!pending) {
+      return;
+    }
+    this.pendingRequests.delete(ipcResponse.id);
+    if (ipcResponse.error) {
+      const errorResponse = {
+        jsonrpc: "2.0",
+        id: ipcResponse.id,
+        error: ipcResponse.error
+      };
+      this.writeStdout(errorResponse);
+    } else {
+      const successResponse = {
+        jsonrpc: "2.0",
+        id: ipcResponse.id,
+        result: ipcResponse.result
+      };
+      this.writeStdout(successResponse);
+    }
+  }
+  listenStdin() {
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      this.stdinBuffer += chunk;
+      let newlineIndex;
+      while ((newlineIndex = this.stdinBuffer.indexOf("\n")) !== -1) {
+        const messageStr = this.stdinBuffer.slice(0, newlineIndex);
+        this.stdinBuffer = this.stdinBuffer.slice(newlineIndex + 1);
+        if (!messageStr.trim()) continue;
+        try {
+          const jsonRpc = JSON.parse(messageStr);
+          this.handleJsonRpcRequest(jsonRpc);
+        } catch {
+          const errorResponse = {
+            jsonrpc: "2.0",
+            id: void 0,
+            error: { code: -32700, message: "Parse error" }
+          };
+          this.writeStdout(errorResponse);
+        }
+      }
+    });
+    process.stdin.on("end", () => {
+      this.shutdown();
+    });
+  }
+  handleJsonRpcRequest(message) {
+    if (!this.connected || !this.socket) {
+      if (message.id !== void 0) {
+        const errorResponse = {
+          jsonrpc: "2.0",
+          id: message.id,
+          error: {
+            code: -32603,
+            message: "Extension host not connected"
+          }
+        };
+        this.writeStdout(errorResponse);
+      }
+      return;
+    }
+    const ipcRequest = {
+      id: String(message.id ?? `notif-${Date.now()}`),
+      method: message.method,
+      params: message.params
+    };
+    if (message.id !== void 0) {
+      this.pendingRequests.set(ipcRequest.id, {
+        resolve: () => {
+        },
+        reject: (err) => {
+          const errorResponse = {
+            jsonrpc: "2.0",
+            id: message.id,
+            error: {
+              code: -32603,
+              message: err instanceof Error ? err.message : String(err)
+            }
+          };
+          this.writeStdout(errorResponse);
+        }
+      });
+    }
+    this.socket.write(JSON.stringify(ipcRequest) + "\n");
+  }
+  writeStdout(message) {
+    process.stdout.write(JSON.stringify(message) + "\n");
+  }
+  shutdown() {
+    if (this.socket) {
+      this.socket.destroy();
+      this.socket = null;
+    }
+    process.exit(0);
+  }
+};
+var bridge = new StdioToIpcBridge();
+bridge.start().catch((err) => {
+  process.stderr.write(`Fatal: ${err.message}
+`);
+  process.exit(1);
+});
+//# sourceMappingURL=mcp-entry.js.map

package/icon.svg

@@ -0,0 +1,65 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#1e1e1e"/>
+      <stop offset="100%" style="stop-color:#252526"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#0098ff"/>
+      <stop offset="100%" style="stop-color:#007acc"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Background rounded square -->
+  <rect x="8" y="8" width="240" height="240" rx="28" ry="28" fill="url(#bg)"/>
+
+  <!-- VSCode-style bottom panel area -->
+  <rect x="24" y="56" width="208" height="176" rx="8" ry="8" fill="#1e1e1e" stroke="#3c3c3c" stroke-width="1.5"/>
+
+  <!-- Tab bar -->
+  <rect x="24" y="56" width="208" height="32" rx="8" ry="0" fill="#2d2d2d"/>
+  <rect x="24" y="76" width="208" height="12" fill="#2d2d2d"/>
+
+  <!-- Active tab -->
+  <rect x="24" y="56" width="96" height="32" rx="8" ry="0" fill="#1e1e1e"/>
+  <rect x="24" y="76" width="96" height="12" fill="#1e1e1e"/>
+  <!-- Active tab bottom border (VSCode blue accent) -->
+  <rect x="24" y="86" width="96" height="2" fill="#007acc"/>
+
+  <!-- Tab icon: terminal symbol -->
+  <polyline points="36,66 44,72 36,78" fill="none" stroke="#cccccc" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="50" y="77" font-family="Segoe UI, Arial, sans-serif" font-size="11" fill="#cccccc" font-weight="500">TERMINAL</text>
+
+  <!-- Inactive tab -->
+  <text x="134" y="77" font-family="Segoe UI, Arial, sans-serif" font-size="11" fill="#6e6e6e">OUTPUT</text>
+
+  <!-- Terminal content area -->
+  <!-- Prompt line 1 -->
+  <text x="36" y="116" font-family="Consolas, monospace" font-size="13" fill="#6a9955">~</text>
+  <text x="48" y="116" font-family="Consolas, monospace" font-size="13" fill="#cccccc">$</text>
+  <text x="62" y="116" font-family="Consolas, monospace" font-size="13" fill="#ce9178">npm run build</text>
+
+  <!-- Output lines -->
+  <text x="36" y="138" font-family="Consolas, monospace" font-size="11" fill="#608b4e">✓</text>
+  <text x="50" y="138" font-family="Consolas, monospace" font-size="11" fill="#858585">compiled successfully</text>
+
+  <text x="36" y="156" font-family="Consolas, monospace" font-size="11" fill="#608b4e">✓</text>
+  <text x="50" y="156" font-family="Consolas, monospace" font-size="11" fill="#858585">tests passed</text>
+
+  <!-- Current prompt line -->
+  <text x="36" y="182" font-family="Consolas, monospace" font-size="13" fill="#6a9955">~</text>
+  <text x="48" y="182" font-family="Consolas, monospace" font-size="13" fill="#cccccc">$</text>
+
+  <!-- Blinking cursor -->
+  <rect x="62" y="170" width="8" height="16" rx="1" fill="#007acc">
+    <animate attributeName="opacity" values="1;0.3;1" dur="1s" repeatCount="indefinite"/>
+  </rect>
+
+  <!-- MCP connection dot top-right -->
+  <circle cx="216" cy="68" r="4" fill="#28c840"/>
+
+  <!-- Bottom status bar -->
+  <rect x="24" y="220" width="208" height="12" rx="0" ry="0" fill="#007acc"/>
+  <text x="32" y="229" font-family="Segoe UI, Arial, sans-serif" font-size="8" fill="#ffffff">MCP: 1 session</text>
+  <text x="184" y="229" font-family="Segoe UI, Arial, sans-serif" font-size="8" fill="#ffffff">bash</text>
+</svg>

package/package.json

@@ -0,0 +1,124 @@
+{
+  "name": "vscode-terminal-mcp",
+  "displayName": "Terminal MCP Server",
+  "description": "MCP server that provides visible terminal sessions in VSCode for Claude Code and subagents",
+  "version": "0.1.0",
+  "publisher": "sirlordt",
+  "license": "MIT",
+  "author": "sirlordt",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sirlordt/vscode-terminal-mcp.git"
+  },
+  "homepage": "https://github.com/sirlordt/vscode-terminal-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/sirlordt/vscode-terminal-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "terminal",
+    "vscode",
+    "claude",
+    "claude-code",
+    "model-context-protocol",
+    "ai-tools"
+  ],
+  "mcpName": "io.github.sirlordt/vscode-terminal-mcp",
+  "icon": "icon.png",
+  "engines": {
+    "vscode": "^1.99.0"
+  },
+  "categories": [
+    "Other"
+  ],
+  "activationEvents": [
+    "onStartupFinished"
+  ],
+  "main": "./dist/extension.js",
+  "contributes": {
+    "mcpServers": {
+      "vscode-terminal-mcp": {
+        "type": "stdio",
+        "command": "node",
+        "args": [
+          "${extensionPath}/dist/mcp-entry.js"
+        ]
+      }
+    },
+    "configuration": {
+      "title": "Terminal MCP",
+      "properties": {
+        "terminalMcp.blockedCommands": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [
+            "rm -rf /",
+            "mkfs",
+            "dd if=",
+            ":(){ :|:& };:"
+          ],
+          "description": "Commands that are never allowed to execute"
+        },
+        "terminalMcp.allowedDirectories": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [],
+          "description": "Allowed working directories (empty = unrestricted)"
+        },
+        "terminalMcp.defaultTimeoutMs": {
+          "type": "number",
+          "default": 30000,
+          "description": "Default timeout for command execution in milliseconds"
+        },
+        "terminalMcp.maxConcurrentSessions": {
+          "type": "number",
+          "default": 10,
+          "description": "Maximum number of concurrent terminal sessions"
+        },
+        "terminalMcp.maxOutputLines": {
+          "type": "number",
+          "default": 10000,
+          "description": "Maximum number of output lines to buffer per session"
+        },
+        "terminalMcp.idleTimeoutMs": {
+          "type": "number",
+          "default": 300000,
+          "description": "Auto-close idle sessions after this many milliseconds (0 = disabled)"
+        }
+      }
+    }
+  },
+  "scripts": {
+    "vscode:prepublish": "npm run build",
+    "build": "node esbuild.config.mjs",
+    "watch": "node esbuild.config.mjs --watch",
+    "lint": "eslint src/ --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "package": "vsce package"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.9.0",
+    "strip-ansi": "^7.1.0",
+    "uuid": "^9.0.0",
+    "zod": "^3.24.0",
+    "zod-to-json-schema": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "@types/uuid": "^9.0.0",
+    "@types/vscode": "^1.99.0",
+    "@vscode/test-electron": "^2.4.0",
+    "@vscode/vsce": "^2.26.0",
+    "esbuild": "^0.21.0",
+    "eslint": "^8.57.0",
+    "prettier": "^3.2.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}

package/research/01-mcp-sdk-patterns.md

@@ -0,0 +1,54 @@
+# MCP SDK - Patterns and Architecture
+
+## Base Protocol
+- JSON-RPC 2.0 as message format
+- 3-component architecture: **Server** (exposes capabilities), **Client** (consumes), **Host** (manages communication - Claude Desktop, VSCode)
+
+## Package @modelcontextprotocol/sdk
+- Core: `@modelcontextprotocol/server` and `@modelcontextprotocol/client`
+- Transports: `@modelcontextprotocol/node` (HTTP), Express, Hono
+- Requires `zod` as peer dependency for schema validation
+- Setup with ES Modules (`"type": "module"`)
+
+## 3 Protocol Primitives
+1. **Tools** - Executable functions the LLM can invoke with structured parameters
+2. **Resources** - Data sources (databases, APIs, filesystem)
+3. **Prompts** - Predefined templates for interactions
+
+## Request Structure (JSON-RPC 2.0)
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "<unique-id>",
+  "method": "tools/call",
+  "params": {
+    "name": "<tool-name>",
+    "arguments": {}
+  }
+}
+```
+
+## Tool Definition
+Each tool requires:
+- `name` - Unique identifier
+- `title` - Human-readable name
+- `description` - Functionality explanation
+- `inputSchema` - JSON Schema (defined with Zod)
+- Handler function - Executes logic and returns results
+
+## Supported Transports
+
+### stdio (Standard I/O)
+- Ideal for local servers
+- Communication via process stdin/stdout
+- Auto-discovery in VSCode extensions
+
+### SSE (Server-Sent Events over HTTP)
+- POST for client->server
+- Supports streaming
+- Standard HTTP authentication (bearer tokens, API keys, OAuth)
+
+## Connection Lifecycle
+1. **Initialization** - Capability exchange and version negotiation
+2. **Operation** - Normal tool execution and resource access
+3. **Termination** - Orderly connection shutdown

package/research/02-vscode-terminal-api.md

@@ -0,0 +1,36 @@
+# VSCode Terminal API - Capabilities and Limitations
+
+## Terminal Creation
+```typescript
+const terminal = vscode.window.createTerminal('MyTerminal');
+terminal.sendText("command", addNewLine);
+terminal.show();
+```
+
+## Pseudoterminal Interface (Custom PTY)
+```typescript
+interface Pseudoterminal {
+  open(): void;
+  close(): void;
+  handleInput(data: string): void;
+  onDidWrite: Event<string>;        // Writes data to terminal UI
+  setDimensions(cols, rows): void;
+  onDidClose: Event<number | void>;
+}
+
+vscode.window.createTerminal({ pty: myPseudoterminal });
+```
+
+## Critical Limitation
+The standard Terminal API **does NOT provide direct output reading** from integrated terminals.
+`sendText()` sends text to the shell, but capturing output requires workarounds.
+
+## Shell Integration API (VSCode 1.93+)
+- `onDidStartTerminalShellExecution` - Event fired when a command starts
+- `execution.read()` - AsyncIterable<string> with output chunks
+- `execution.exitCode` - Thenable<number | undefined>
+- Requires active shell integration (automatic in bash/zsh/PowerShell)
+
+## Recommended Strategy
+1. **Primary**: Shell Integration API (when available)
+2. **Fallback**: Polling-based output stabilization detection

package/research/03-vscode-mcp-integration.md

@@ -0,0 +1,43 @@
+# VSCode Extension as MCP Server
+
+## Native Support (VSCode 1.99+)
+- Extensions can serve as MCP servers
+- Auto-discovery by Claude Code / Copilot without additional configuration
+- Communication via **stdio** by default
+
+## Declaration in package.json
+```jsonc
+{
+  "contributes": {
+    "mcpServers": {
+      "server-name": {
+        "type": "stdio",
+        "command": "node",
+        "args": ["${extensionPath}/dist/mcp-entry.js"]
+      }
+    }
+  }
+}
+```
+
+## Key Architectural Problem
+`contributes.mcpServers` launches a **child process** separate from the extension host.
+The VSCode Terminal API (`vscode.window.createTerminal`, Shell Integration) is only
+available **within the extension host process**.
+
+## Solution: IPC Bridge
+```
+[Claude Code] --stdio--> [mcp-entry.js (shim)] --IPC--> [Extension Host (Terminal API)]
+```
+
+- `mcp-entry.js`: Thin stdio-to-IPC bridge. Reads JSON-RPC from stdin, forwards via Unix socket.
+- `extension.ts`: In activate(), creates IPC server (Unix domain socket), instantiates MCP Server with handlers, processes forwarded requests.
+
+## Workspace Configuration
+`.vscode/mcp.json` or `settings.json` file for per-team configuration.
+
+## Existing MCP Servers in the Environment
+1. **desktop-commander** (v0.2.38) - Command execution, files
+2. **playwright-mcp** - Browser automation
+3. **context7** - Contextual documentation
+4. **chrome-devtools-mcp** (v0.20.2) - DevTools

package/research/04-desktop-commander-referencia.md

@@ -0,0 +1,45 @@
+# Desktop Commander MCP - Implementation Reference
+
+## Overview
+Desktop Commander is the most relevant MCP as a reference. It implements command
+execution with output capture, session management, and security.
+
+## Exposed Tools
+- **Terminal**: `execute_command`, `read_output`, `force_terminate`, `list_sessions`, `list_processes`
+- **Filesystem**: `read_file`, `write_file`, `move_file`, `search`
+- **Code editing**: `edit_block` (surgical text replacement)
+
+## Security Patterns
+- Two execution modes:
+  1. **Safe mode** - Executable allowlist without shell interpretation
+  2. **Legacy mode** - Command string allowlist/blocklist
+- Command validation before execution
+- Timeout control
+- Working directory restrictions
+- Stdin support with timeout protection
+
+## Configuration
+```json
+{
+  "blockedCommands": ["rm -rf /", "mkfs", "dd if="],
+  "defaultShell": "/bin/bash",
+  "allowedDirectories": ["/home/user/projects"],
+  "fileReadLineLimit": 1000,
+  "fileWriteLineLimit": 1000
+}
+```
+
+## Differences with Our Solution
+| Aspect | Desktop Commander | Our MCP |
+|--------|------------------|---------|
+| Visibility | No visible terminal | Visible terminal in VSCode |
+| Integration | Independent process | Embedded in VSCode extension |
+| Output | Captured text only | Text + visual terminal |
+| Subagents | Not designed for this | Native support with agentId |
+| Context | Loses visual context | User sees the execution |
+
+## Lessons Applied
+1. Circular buffer for output with pagination
+2. Dangerous command blocklist by default
+3. Configurable timeout with partial return
+4. Session management with Map<id, session>

package/server.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+  "name": "io.github.sirlordt/vscode-terminal-mcp",
+  "title": "Terminal MCP Server",
+  "description": "MCP server that executes commands in visible VSCode terminal tabs with full output capture, session reuse, long-running process support, and subagent isolation.",
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registry": "npm",
+      "name": "vscode-terminal-mcp"
+    }
+  ]
+}