VSCode Operator

A TypeScript VS Code extension that exposes native editor context as Language Model Tools, enabling Copilot Agent to autonomously operate VS Code (read diagnostics, query hover/LSP info, execute commands).

It also starts a local MCP bridge inside the Extension Host so external MCP clients can discover and call the currently registered VS Code language model tools.

Simple Intro (For Marketplace)

VSCode Operator connects AI assistants to real VS Code context. It exposes diagnostics, hover/completion capabilities, command execution, and debugger control/introspection as tools, and provides a built-in local MCP bridge so external MCP clients can discover and call the same toolset in your live editor session.

For detailed architecture and design decisions, see ARCHITECTURE.md.

Tools

Core Editor Tools

Debugger Tools (AI Can Operate Debugger)

Recommended Low-Roundtrip Debug Flow

When you want AI to inspect paused state with fewer MCP calls, use:

1. vscodeOperator_debugSnapshot first (single-call context capture)
2. vscodeOperator_debugControl only when you need to continue/step/pause
3. vscodeOperator_debugEvaluate for targeted follow-up expressions
4. Before starting a new debug run, always stop any stale prior session unless you intentionally want to reuse it

Example snapshot call:

{
  "maxScopes": 4,
  "maxVariablesPerScope": 80,
  "evaluateExpressions": ["this", "req", "res.statusCode"],
  "evaluateContext": "watch"
}

Agent Prompt Templates (Debugger)

Use the following prompt templates to make AI prefer fewer roundtrips.

Minimal snapshot-first template:

Use VSCode Operator debugger tools.
1) Call vscodeOperator_debugSnapshot first.
2) Summarize current paused state from topFrame/scopes/variables.
3) Only if needed, call vscodeOperator_debugControl or vscodeOperator_debugEvaluate.
4) Before starting a new debug session, stop any previous session unless it is clearly the one you should keep using.
5) After finishing the investigation, stop the debug session if it is no longer needed.
Avoid unnecessary extra tool calls.

Snapshot + targeted evaluate template:

Use vscodeOperator_debugSnapshot with:
- maxScopes=4
- maxVariablesPerScope=80
- evaluateExpressions=["this", "req", "res.statusCode"]

Then:
1) Explain the current execution location and likely root cause.
2) If one key value is still missing, do one vscodeOperator_debugEvaluate call only.
3) Propose the next debugging action (continue/stepOver/stepInto) with reason.
4) If a fresh run is needed, stop the previous debug session before starting the next one.
5) If the old session may have been misused, do not trust it; stop it first and restart cleanly.

Debug Session Hygiene

To avoid AI accidentally reusing stale debugger state:

1. Before the second and later debug launches, stop the previous session unless you explicitly want to continue it.
2. If previous debug results may have been misapplied, stop the old session before doing any new inspection.
3. After a debugging task is complete, stop the session to avoid contaminating the next task.
4. Treat "stop old session before new debugStart" as the default safe policy.

MCP Bridge

Architecture

VSCode Operator uses a proxy + bridge architecture to support multiple VS Code workspaces simultaneously:

• Proxy Server: Listens on fixed port 19191, routes MCP requests to appropriate workspace bridges based on workspacePath parameter
• Bridge Server: Each VS Code instance runs its own bridge (auto-assigned port 19192+), queries its local tools and registers with the proxy

Endpoints & Configuration

• Proxy endpoint: http://127.0.0.1:19191/mcp (stable, connect here)
• Bridge registers at: Each bridge auto-discovers an available port and registers with the proxy
• Health check: http://127.0.0.1:19191/health
• Commands: VSCode Operator: Show MCP Bridge Status, VSCode Operator: Restart MCP Bridge
• Settings: vscodeOperator.mcpBridge.enabled, vscodeOperator.mcpBridge.host, vscodeOperator.mcpBridge.port, vscodeOperator.mcpBridge.path

Multi-Workspace Usage

When multiple VS Code instances are running:

1. Each runs its own MCP bridge server (auto-assigned port 19192+)
2. All bridges register with the central proxy on port 19191
3. MCP clients connect to the proxy endpoint: http://127.0.0.1:19191/mcp
4. Include workspacePath parameter in tool calls to route to correct bridge:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vscodeOperator_hoverAtPosition",
    "arguments": {
      "workspacePath": "/absolute/path/to/projectA",
      "line": 10,
      "column": 5
    }
  }
}

Customize Proxy Port

Default proxy port is 19191. To change it:

{
  "vscodeOperator.mcpBridge.port": 20191
}

Note: Only the first instance uses the configured port. Additional instances auto-increment (19192, 19193, etc.).

Development

npm install
npm run compile   # tsc -p ./ → dist/
npm run watch     # incremental compile during development

Press F5 to launch an Extension Development Host. Copilot Agent can then invoke registered tools automatically based on context (see .github/copilot-instructions.md).

The local MCP bridge starts automatically on activation unless vscodeOperator.mcpBridge.enabled is disabled.