vscode-mcp-server: Instructions file for Codex

AGENTS.md

Guide for AI agents working in this repository.

Project

A VS Code extension that exposes VS Code as an MCP server: debugger, terminal, LSP, file, workspace and command tools, reachable by MCP clients such as opencode, Claude and Cursor. One VS Code window becomes the cluster leader (HTTP on 127.0.0.1:9876) and other windows join as workers over the leader's HTTP member channel, so a single endpoint reaches every window.

• Package name, publisher and version live in package.json and RELEASE.md
• Runtime: Node (extension host), TypeScript, CommonJS output (module: commonjs, outDir: out)
• Entry: src/extension.ts (activate/deactivate), MCP server in src/mcp/server.ts

package.json has no "type": "module" and no files array on purpose: VS Code loads the extension as CommonJS, and packaging is governed by .vscodeignore (which ships out/** and drops src/**, node_modules/**). Do not "modernize" this to ESM or add files without reworking packaging.

Architecture

src/
  extension.ts            # activate(): cluster role, MCP server lifecycle
  mcp/
    server.ts             # McpServer: JSON-RPC, tools/list, tools/call, SSE
    transport.ts          # initialize negotiation, protocol version
    executor.ts           # tool execution against the vscode API
    cluster/
      bootstrap.ts        # startup decision: join, elect, promote
      election.ts         # port probing / leader health
      leader.ts           # routing: cluster target resolution + proxying
      worker.ts           # joins the leader, executes forwarded calls
      memberTransport.ts  # HTTP member channel (CALL/RESULT frames)
      protocol.ts         # frame types
      constants.ts        # ports, timings, retry budgets
    tools/                # one module per tool family, registered by index.ts
      workspace.ts        # file read/write/edit, list_files, search paths
      search.ts           # search_files (grep)
      debug.ts            # debugger tools
      navigation.ts       # go-to-definition, references, hover, rename
      lsp.ts, editors.ts, terminal.ts, commands.ts, configuration.ts, logs.ts
utils/
  path.ts                 # resolvePath, boundary and symlink handling
  openEditors.ts          # open-editor / workspace state snapshots
  timeout.ts, metrics.ts, jsonc.ts, serverLog.ts
test/                     # vitest unit suites (src/test, excludes e2e)
  e2e/                    # real-VS-Code suites (RUN_E2E gated)