vsc-lsp-mcp: Instructions file for Codex

项目结构

• src/index.ts：VS Code Extension Host 入口，构建为 dist/index.js
• src/mcp/index.ts：当前 VS Code 窗口的启动编排，依次启动内部 Instance Server、确保共享 Broker 存在并注册 VS Code MCP provider
• src/broker/main.ts：独立 Broker 子进程入口，构建为 dist/broker.js，不属于 VS Code Extension Host
• src/broker/：共享 MCP Broker，负责单实例锁、稳定外部端口、MCP session、实例发现和请求转发
• src/instance/：每个 VS Code 窗口的内部服务、实例注册表和路由规则
• src/mcp/：在当前 VS Code 窗口内执行的 MCP/LSP 操作与 VS Code MCP provider
• src/protocol.ts：Broker 与内部 Instance Server 之间共享的请求类型和协议描述
• src/filePermissions.ts：注册表、状态文件和启动锁共用的私有文件权限常量
• src/lsp/：对 VS Code LSP 能力的封装，负责定义、引用、补全、重命名、调用层级等操作
• src/transform/：将 VS Code / LSP 返回结果转换成 JSON 或 Markdown
• src/utils/：通用工具，目前主要是日志输出
• l10n/：运行时代码字符串的本地化资源，配合 vscode.l10n.t 使用
• package.nls*.json：package.json 中扩展描述、配置项等静态贡献点的本地化资源
• dist/：tsup 构建产物，不手写维护

多实例架构

项目包含两个构建入口和两个独立进程：

VS Code Extension Host
src/index.ts -> src/mcp/index.ts
  ├─ 启动当前窗口的 Instance Server
  ├─ 将窗口信息写入共享注册表
  ├─ 复用或启动独立 Broker
  └─ 注册 VS Code MCP provider

独立 Broker 进程
src/broker/main.ts -> src/broker/server.ts
  ├─ 对外提供单个 /mcp 地址
  ├─ 从注册表发现所有 VS Code 窗口
  ├─ 按 instanceId 或最长工作区路径前缀选择实例
  └─ 将请求转发到目标窗口的内部 loopback 端点

• src/index.ts 是 VS Code 直接加载的唯一扩展入口，对应 package.json 的 main: ./dist/index.js
• src/broker/main.ts 由 src/broker/ensure.ts 通过独立 Node 子进程启动，不由 VS Code 直接加载
• tsup.config.ts 必须同时产出 dist/index.js 和 dist/broker.js
• 外部 MCP 客户端只连接共享 Broker，不直接连接各窗口的内部端口
• Broker 使用固定外部端口；端口被占用时必须明确失败，不能回退到客户端未知的其他端口
• 每个窗口使用随机内部端口和随机 token，仅监听 127.0.0.1
• Broker 生命周期必须与任意单个 VS Code 窗口解耦，关闭首个窗口不能导致其他窗口断线
• 多实例首版只承诺本机桌面 file: 工作区，不要未经设计直接宣称支持 Remote SSH、WSL、Dev Container 或虚拟工作区

推荐阅读顺序

理解启动与请求链路时按以下顺序阅读，不要从工具实现或注册表细节开始：

1. src/index.ts
2. src/mcp/index.ts
3. src/instance/server.ts
4. src/broker/ensure.ts
5. src/broker/main.ts
6. src/broker/server.ts
7. src/broker/tools.ts
8. src/instance/router.ts
9. src/instance/registry.ts

请求链路为：外部 MCP 客户端 -> 共享 Broker -> 实例路由 -> 目标 VS Code Instance Server -> LSP/Workspace 操作 -> Broker 原样返回结果