内容
# CodexDiagnosticBridge
CodexDiagnosticBridge 用来把 VS Code 的诊断信息交给 Codex。安装完成后，你可以让 Codex 直接读取“问题”（Problems）面板中的错误、警告和提示，不需要再手动复制。
它由两部分组成：
- VS Code 扩展负责收集诊断信息，并写入本地临时文件。
- MCP server 负责把这些信息提供给 Codex。
另外，v1.1.0 新增了全局 LSP 桥 `codex-lsp`。它可以连接本机的语言服务器，让 Codex 使用诊断、补全、悬停和跳转定义等能力。具体用法见第 9 节。
## 发布版本
- **v1.1.0**：新增全局 LSP 桥 `codex-lsp`，支持诊断、补全、悬停和跳转定义；可自动识别 VS Code 自带的 JSON、HTML、CSS、Markdown 和 TypeScript 语言服务器；支持通过 `disabled` 禁用自动发现的服务器。同时修复了 glob 路径重复、诊断 URI 匹配失败和 stdin 退出时响应被截断的问题。
https://github.com/SZ1145141919180/VS-CODE-codex-mcp-/releases/tag/v1.1.0
- **v1.0.0**：提供 VS Code 扩展和 MCP server，让 Codex 可以读取“问题”面板中的错误、警告和提示。
https://github.com/SZ1145141919180/VS-CODE-codex-mcp-/releases/tag/v1.0.0
---
## 1. 工作原理
VS Code 扩展通过 `vscode.languages.getDiagnostics()` 获取当前工作区的诊断信息，然后写入临时快照文件。MCP server 读取这份快照，并通过 MCP 资源和工具提供给 Codex。
数据直接来自 VS Code，不会模拟或补全不存在的诊断信息。
```text
VS Code 问题面板 → 扩展写入临时文件 → MCP server → Codex
```
## 2. 项目结构
```text
CodexDiagnosticBridge
├── vscode-extension/ ← VS Code 扩展，负责收集诊断信息
├── mcp-server/ ← MCP server，负责把诊断信息提供给 Codex
├── lsp-server/ ← 全局 LSP 桥，提供诊断、补全、悬停和定义跳转
├── .codex/ ← Codex 配置文件
└── README.md ← 项目说明
```
## 3. 环境要求
使用前请确认以下环境已经准备好：
- Windows
- VS Code
- Node.js，运行 `node --version` 能正常显示版本号
- Codex CLI，运行 `codex --version` 能正常显示版本号
## 4. 安装
整个过程通常需要几分钟。
### 第 1 步：安装 VS Code 扩展
#### 方法 A：安装 VSIX 文件
适合日常使用。
1. 找到 `vscode-extension` 目录中的 `codex-diagnostic-bridge-1.0.0.vsix`。
2. 打开 VS Code，按 `Ctrl+Shift+P` 打开命令面板。
3. 输入并选择 `Extensions: Install from VSIX...`。
4. 选择 `.vsix` 文件并完成安装。
5. 再次打开命令面板，执行 `Developer: Reload Window`。
如果目录中没有 `.vsix` 文件，可以按照第 7 节的说明自行打包。
#### 方法 B：使用扩展调试模式
适合开发和调试扩展。
用 VS Code 打开 `vscode-extension` 目录，然后按 `F5`。运行期间不要关闭新打开的扩展开发宿主窗口。
#### 检查扩展是否运行
在 VS Code 中新建终端，然后执行：
```powershell
Get-NetTCPConnection -State Listen -LocalPort 38421
```
如果能看到监听记录，说明扩展已经启动本地服务。
扩展默认监听 `127.0.0.1:38421`。如果该端口已被另一个健康的 CodexDiagnosticBridge 实例占用，扩展会复用该实例；如果端口被其他程序占用，则回退到 `38422`。
### 第 2 步：注册 MCP server
在 PowerShell 中执行下面的命令，并把路径替换为项目所在的实际路径：
```powershell
codex mcp add codex-diagnostic-bridge -- node "你的项目路径\mcp-server\server.js"
```
例如：
```powershell
codex mcp add codex-diagnostic-bridge -- node "C:\Users\你\CodexDiagnosticBridge\mcp-server\server.js"
```
执行下面的命令检查注册结果：
```powershell
codex mcp list
```
列表中出现 `codex-diagnostic-bridge ... enabled`，说明 MCP server 已经注册并启用。
### 第 3 步：验证连接
注册后需要**新建一个 Codex 会话**。已经打开的会话通常不会加载刚注册的 MCP server。
在新会话中输入：
```text
用 read_mcp_resource 读取 codex-diagnostic-bridge 服务器的 diagnostics://summary
```
如果返回类似下面的内容，说明连接正常：
```json
{"errors": 0, "warnings": 0, "infos": 0}
```
数值为 0 只表示 VS Code 当前没有对应的诊断信息，不是连接失败。
## 5. 日常使用
保持 VS Code 打开，扩展会自动更新诊断快照。之后可以在 Codex 会话中直接提出下面这些请求：
| 目的 | 对 Codex 说 |
| --- | --- |
| 查看全部诊断 | `用 read_mcp_resource 读取 codex-diagnostic-bridge 服务器的 diagnostics://workspace` |
| 查看诊断统计 | `用 read_mcp_resource 读取 codex-diagnostic-bridge 服务器的 diagnostics://summary` |
| 读取诊断并开始修复 | `先读 diagnostics://summary，再读 diagnostics://workspace，然后开始修` |
> 在 Codex 0.146.x 中，`get_error_summary` 一类 MCP 工具可能不会直接出现在工具列表中，这是工具延迟加载的表现。使用上面的 MCP 资源读取方式可以获得相同的数据。
## 6. 常见问题
### 返回 `[]`，或者统计结果全部为 0
先查看 VS Code 的“问题”面板。如果面板中没有诊断信息，返回空数组或全 0 是正常结果。
可以临时在 JavaScript 文件中写入 `const x = ;`，等待 VS Code 产生语法错误后再次读取。测试结束后记得删除这行代码。
### Codex 找不到工具或 MCP server
依次检查：
1. 运行 `codex mcp list`，确认 `codex-diagnostic-bridge` 的状态为 `enabled`。
2. 确认当前 Codex 会话是在注册 MCP server 之后新建的。
3. 确认 VS Code 正在运行。
4. 使用第 4 节中的端口命令检查扩展服务。
### 端口被占用
扩展会先检查 `38421` 上是否已经运行了健康的 CodexDiagnosticBridge 实例。如果是，会直接复用；如果不是，则尝试监听 `38422`。
### 如何卸载
先在 VS Code 扩展面板中找到 `codex-diagnostic-bridge` 并卸载，然后执行：
```powershell
codex mcp remove codex-diagnostic-bridge
```
### 修改扩展代码后没有生效
修改完成后，需要重新打包并安装扩展，然后执行 `Developer: Reload Window`。具体命令见第 7 节。
## 7. 开发说明
### 主要文件
- `vscode-extension/extension.js`：扩展入口，负责收集诊断信息、启动本地 HTTP 服务并写入临时快照。
- `vscode-extension/package.json`：VS Code 扩展清单。
- `mcp-server/server.js`：MCP server，无第三方运行时依赖，可直接使用 Node.js 启动。
### 重新打包扩展
```powershell
cd vscode-extension
npx --yes @vscode/vsce package --allow-missing-repository
code --install-extension codex-diagnostic-bridge-1.0.0.vsix --force
```
安装完成后，在 VS Code 中执行 `Developer: Reload Window`。
### 诊断数据格式
```json
[
{
"file": "C:/path/to/file.js",
"diagnostics": [
{
"line": 10,
"column": 5,
"severity": "error",
"message": "Cannot find name 'foo'.",
"source": "ts"
}
]
}
]
```
`severity` 的取值包括：`error`、`warning`、`information` 和 `hint`。
## 8. 许可证
MIT
---
## 9. 全局 LSP 接入（codex-lsp）
`codex-lsp` 让 Codex 可以通过 LSP 协议访问本机已配置或自动发现的语言服务器，从而使用诊断、补全、悬停和跳转定义等能力。它不依赖 VS Code 保持打开。
```text
Codex → codex-lsp（MCP）→ 本机语言服务器（LSP stdio）→ 返回结果
```
### 注册 codex-lsp
在 PowerShell 中执行：
```powershell
codex mcp add codex-lsp -- node "你的项目路径\lsp-server\lsp-bridge.js"
codex mcp list
```
看到 `codex-lsp ... enabled` 表示注册成功。注册后需要新建 Codex 会话，工具才会被加载。
### 使用方式
| 目的 | 对 Codex 说 |
| --- | --- |
| 查看可用语言服务器 | `用 codex-lsp 的 lsp_list_servers 工具列一下` |
| 查询文件诊断 | `用 lsp_diagnostics 查 C:\...\main.lua 的诊断` |
| 查询指定位置的补全 | `用 lsp_completion 查 <文件> 第 508 行第 25 列` |
| 查看指定位置的信息 | `用 lsp_hover 查 <文件> 第 508 行第 8 列` |
| 跳转到定义 | `用 lsp_definition 查 <文件> <行> <列>` |
`line` 和 `column` 都从 **1** 开始，与编辑器显示的位置一致。
也可以直接读取以下资源：
- `lsp://servers`：返回可用语言服务器的 JSON 数据。
- `lsp://diagnostics/<URL编码的绝对路径>`：返回指定文件的诊断信息。
### 自动发现的语言服务器
自动发现分为两类：
- **VS Code 自带的语言服务器**：JSON、HTML、CSS/SCSS/LESS、Markdown，以及存在 tsserver 时的 TypeScript。兼容新版 `root\<hash>\resources\app` 和经典目录结构。
- **通过用户扩展安装的语言服务器**：例如 sumneko Lua，以及以扩展形式安装的 JSON 或 TypeScript 语言服务器。
### 添加其他语言服务器
编辑 `lsp-server\lsp-servers.json`，加入对应配置。例如，添加 Python 语言服务器：
```json
{
"id": "python",
"languageId": "python",
"extensions": [".py"],
"command": "C:\\path\\pyright-langserver.exe",
"args": ["--stdio"],
"cwd": "C:\\path"
}
```
如果语言服务器由 JavaScript 编写，例如 `typescript-language-server`，请设置 `nodeScript: true`：
```json
{
"id": "typescript",
"nodeScript": true,
"languageId": "typescript",
"extensions": [".ts", ".js"],
"args": ["C:\\path\\cli.js", "--stdio"]
}
```
### 禁用自动发现的服务器
如果不希望使用某个自动发现的服务器，可以在 `lsp-servers.json` 中加入 `disabled`。例如，禁用 TypeScript：
```json
{
"disabled": ["typescript"]
}
```
### 排查问题
- **上传项目或更换电脑后是否需要修改配置**：Lua 等常见语言服务器由自动发现机制处理，`lsp-servers.json` 默认可以保持为空。手动配置的路径在本机不存在时，会自动回退到发现结果。
- **第一次查询需要 30 到 60 秒**：语言服务器冷启动时需要加载元数据，属于正常情况。同一会话中的后续请求通常会更快，诊断请求的等待上限为 60 秒。
- **`.luarc.json` 是否生效**：每次查询都以文件所在目录作为 workspace 根目录，因此 Lua 的 `.luarc.json` 和 `typings/` 会被自动加载。
- **修改 `lsp-bridge.js` 后没有生效**：新建 Codex 会话。MCP server 会随会话启动，旧会话仍在运行原来的进程。
- **同时处理多个项目中的同类文件**：每个项目目录会启动独立的语言服务器实例，并在退出时自动清理。
---
## 10. 更新日志
### v1.1.0（2026-08-09）
- 新增全局 LSP 桥 `codex-lsp`（`lsp-server/`），Codex 可以通过 MCP 直接访问本机语言服务器，不依赖 VS Code 保持打开。
- 新增工具：`lsp_list_servers`、`lsp_diagnostics`、`lsp_completion`、`lsp_hover`、`lsp_definition`。
- 新增资源：`lsp://servers`、`lsp://diagnostics/{filePath}`。
- 位置参数从 1 开始。
- 自动识别 VS Code 自带的 JSON、HTML、CSS/SCSS/LESS、Markdown 和 TypeScript 语言服务器（存在 tsserver 时）。
- 兼容新版 `root\<hash>\resources\app` 和经典目录结构，也支持通过用户扩展安装的语言服务器，例如 sumneko Lua。
- `lsp-servers.json` 改为空模板，常见语言服务器通过自动发现加载。
- 手动配置的路径不存在时，会自动回退到发现结果。
- 新增 `disabled` 数组，用于禁用自动发现的语言服务器。
- 修复自动发现 glob 重复拼接目录前缀的问题。
- 修复 LSP 诊断 URI 与本地 URI 的大小写或百分号编码不一致时无法匹配的问题。
- 修复 stdin 关闭时响应可能被截断的问题，程序会等待进行中的请求完成后再退出。
- 注册命令：
```powershell
codex mcp add codex-lsp -- node "<项目路径>\lsp-server\lsp-bridge.js"
```
### v1.0.0
- 提供 VS Code 扩展和 MCP server，通过 MCP 资源和工具把“问题”面板中的错误、警告和提示交给 Codex 读取。
连接信息
猜你喜欢
暂无推荐服务器