STARWARCLOUD STARWAR.AI
返回市场
代码桥接

代码桥接

作者：eLyiN66 星标更新：2025-09-09
安装使用来源：spider==github.com

项目介绍

Codex Bridge

CI 状态 PyPI 版本 MIT 许可证 Python 3.10+ MCP 兼容 Codex CLI

一个轻量级的MCP（模型上下文协议）服务器，使AI编码助手能够通过官方CLI与OpenAI的Codex AI进行交互。适用于Claude Code、Cursor、VS Code和其他兼容MCP的客户端。设计简单、可靠且无缝集成。

✨ 功能

  • 直接Codex CLI集成：使用官方Codex CLI实现零API成本
  • 简单的MCP工具：两个核心功能用于基本查询和文件分析
  • 无状态操作：无需会话、缓存或复杂的状态管理
  • 生产就绪：强大的错误处理功能，支持配置超时时间（默认：90秒）
  • 最小依赖：仅需mcp>=1.0.0和Codex CLI
  • 易于部署：支持uvx和传统的pip安装
  • 通用MCP兼容性：适用于任何兼容MCP的AI编码助手

🚀 快速开始

前提条件

  1. 安装Codex CLI：

    npm install -g @openai/codex-cli

  2. 认证Codex：

    codex

  3. 验证安装：

    codex --version

安装

🎯 推荐：PyPI安装

# 从PyPI安装
pip install codex-bridge

# 添加到Claude Code（推荐）
claude mcp add codex-bridge -s user -- uvx codex-bridge

替代方案：从源代码安装

# 克隆仓库
git clone https://github.com/shelakh/codex-bridge.git
cd codex-bridge

# 构建并本地安装
uvx --from build pyproject-build
pip install dist/*.whl

# 添加到Claude Code
claude mcp add codex-bridge -s user -- uvx codex-bridge

开发安装

# 克隆并以开发模式安装
git clone https://github.com/shelakh/codex-bridge.git
cd codex-bridge
pip install -e .

# 添加到Claude Code（开发模式）
claude mcp add codex-bridge-dev -s user -- python -m src

🌐 多客户端支持

Codex Bridge适用于任何兼容MCP的AI编码助手——同一服务器通过不同的配置方法支持多个客户端。

支持的MCP客户端

  • Claude Code ✅ （默认）
  • Cursor ✅
  • VS Code ✅
  • Windsurf ✅
  • Cline ✅
  • Void ✅
  • Cherry Studio ✅
  • Augment ✅
  • Roo Code ✅
  • Zencoder ✅
  • 任何兼容MCP的客户端 ✅

配置示例

<details> <summary><strong>Claude Code</strong>（默认）</summary> 
# 推荐安装
claude mcp add codex-bridge -s user -- uvx codex-bridge

# 开发安装
claude mcp add codex-bridge-dev -s user -- python -m src
</details> <details> <summary><strong>Cursor</strong></summary>

全局配置（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

项目特定配置（项目中的.cursor/mcp.json）：

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

前往：设置 → Cursor 设置 → MCP → 添加新的全局MCP服务器

</details> <details> <summary><strong>VS Code</strong></summary>

配置（工作区中的.vscode/mcp.json）：

{
  "servers": {
    "codex-bridge": {
      "type": "stdio",
      "command": "uvx",
      "args": ["codex-bridge"]
    }
  }
}

替代方案：通过扩展

  1. 打开扩展视图（Ctrl+Shift+X）
  2. 搜索MCP扩展
  3. 使用命令uvx codex-bridge添加自定义服务器
</details> <details> <summary><strong>Windsurf</strong></summary>

在Windsurf MCP配置中添加：

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}
</details> <details> <summary><strong>Cline</strong>（VS Code扩展）</summary>
  1. 打开Cline并点击顶部导航栏中的MCP服务器
  2. 选择已安装标签页 → 高级MCP设置
  3. 在cline_mcp_settings.json中添加：
{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}
</details> <details> <summary><strong>Void</strong></summary>

前往：设置 → MCP → 添加MCP服务器

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}
</details> <details> <summary><strong>Cherry Studio</strong></summary>
  1. 导航至设置 → MCP服务器 → 添加服务器
  2. 填写服务器详情：
    • 名称：codex-bridge
    • 类型：STDIO
    • 命令：uvx
    • 参数：["codex-bridge"]
  3. 保存配置
</details> <details> <summary><strong>Augment</strong></summary>

使用UI：

  1. 点击汉堡菜单 → 设置 → 工具
  2. 点击**+ 添加MCP**按钮
  3. 输入命令：uvx codex-bridge
  4. 名称：Codex Bridge

手动配置：

"augment.advanced": { 
  "mcpServers": [ 
    { 
      "name": "codex-bridge", 
      "command": "uvx", 
      "args": ["codex-bridge"],
      "env": {}
    }
  ]
}
</details> <details> <summary><strong>Roo Code</strong></summary>
  1. 转到设置 → MCP服务器 → 编辑全局配置
  2. 在mcp_settings.json中添加：
{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}
</details> <details> <summary><strong>Zencoder</strong></summary>
  1. 转到Zencoder菜单（...） → 工具 → 添加自定义MCP
  2. 添加配置：
{
  "command": "uvx",
  "args": ["codex-bridge"],
  "env": {}
}
  1. 点击安装按钮
</details> <details> <summary><strong>其他安装方法</strong></summary>

对于基于pip的安装：

{
  "command": "codex-bridge",
  "args": [],
  "env": {}
}

对于开发/本地测试：

{
  "command": "python",
  "args": ["-m", "src"],
  "env": {},
  "cwd": "/path/to/codex-bridge"
}

对于npm风格的安装（如果需要）：

{
  "command": "npx",
  "args": ["codex-bridge"],
  "env": {}
}
</details>

通用用法

一旦与任何客户端配置好，可以使用相同的两个工具：

  1. 询问一般问题："这个代码库中使用了哪些认证模式？"
  2. 分析特定文件："检查这些认证文件的安全问题"

服务器实现相同——只有客户端配置不同！

⚙️ 配置

超时配置

默认情况下，Codex Bridge对所有CLI操作使用90秒的超时时间。对于较长的查询（大文件、复杂分析），可以通过CODEX_TIMEOUT环境变量配置自定义超时时间。

Git仓库检查

默认情况下，Codex CLI要求位于Git仓库或受信任目录内。如果需要在非Git仓库目录中使用Codex Bridge，可以设置CODEX_SKIP_GIT_CHECK环境变量。

⚠️ 安全警告：仅在控制目录结构的受信任环境中启用此标志。

示例配置：

<details> <summary><strong>Claude Code</strong></summary> 
# 添加自定义超时（120秒）
claude mcp add codex-bridge -s user --env CODEX_TIMEOUT=120 -- uvx codex-bridge

# 禁用Git仓库检查（针对非Git目录）
claude mcp add codex-bridge -s user --env CODEX_SKIP_GIT_CHECK=true -- uvx codex-bridge

# 同时配置两者
claude mcp add codex-bridge -s user --env CODEX_TIMEOUT=120 --env CODEX_SKIP_GIT_CHECK=true -- uvx codex-bridge
</details> <details> <summary><strong>手动配置（mcp_settings.json）</strong></summary> 
{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {
        "CODEX_TIMEOUT": "120",
        "CODEX_SKIP_GIT_CHECK": "true"
      }
    }
  }
}
</details>

配置选项：

CODEX_TIMEOUT：

  • 默认值：90秒（未配置时）
  • 范围：任意正整数（秒）
  • 建议：大多数查询60-120秒，大型文件分析120-300秒
  • 无效值：回退到90秒并发出警告

CODEX_SKIP_GIT_CHECK：

  • 默认值：false（启用Git仓库检查）
  • 有效值："true"、"1"、"yes"（不区分大小写）以禁用检查
  • 使用场景：在非Git仓库目录中工作
  • 安全：仅在控制的受信任目录中使用

🛠️ 可用工具

consult_codex

直接CLI桥接，用于简单查询，默认生成结构化的JSON输出。

参数：

  • query（字符串）：发送给Codex的问题或提示
  • directory（字符串）：查询的工作目录（默认：当前目录）
  • format（字符串）：输出格式 - "text"、"json" 或 "code"（默认："json"）
  • timeout（可选整数）：超时时间（秒）（建议：60-120，默认：90）

示例：

consult_codex(
    query="查找此代码库中的认证模式",
    directory="/path/to/project",
    format="json",  # 默认格式
    timeout=90      # 默认超时时间
)

consult_codex_with_stdin

CLI桥接，带有stdin内容，适合管道友好型执行。

参数：

  • stdin_content（字符串）：作为stdin的内容（文件内容、差异、日志）
  • prompt（字符串）：处理stdin内容的提示
  • directory（字符串）：查询的工作目录
  • format（字符串）：输出格式 - "text"、"json" 或 "code"（默认："json"）
  • timeout（可选整数）：超时时间（秒）（建议：60-120，默认：90）

consult_codex_batch

批量处理多个查询——非常适合CI/CD自动化。

参数：

  • queries（列表）：包含'query'和可选'timeout'的查询字典列表
  • directory（字符串）：所有查询的工作目录
  • format（字符串）：输出格式 - 目前仅支持"json"批量处理

示例：

consult_codex_with_stdin(
    stdin_content=open("src/auth.py").read(),
    prompt="分析此认证文件并提出改进建议",
    directory="/path/to/project",
    format="json",  # 结构化输出
    timeout=120     # 为详细分析提供更多时间
)

📋 使用示例

基本代码分析

# 简单的研究查询
consult_codex(
    query="这个项目中使用了哪些认证模式？",
    directory="/Users/dev/my-project"
)

详细文件审查

# 分析特定文件
with open("/Users/dev/my-project/src/auth.py") as f:
    auth_content = f.read()
    
consult_codex_with_stdin(
    stdin_content=auth_content,
    prompt="审查此文件并提出安全改进意见",
    directory="/Users/dev/my-project",
    format="json",  # 结构化输出
    timeout=120     # 为详细分析提供更多时间
)

批量处理

# 一次处理多个查询
consult_codex_batch(
    queries=[
        {"query": "分析认证模式", "timeout": 60},
        {"query": "审查数据库实现", "timeout": 90},
        {"query": "检查安全漏洞", "timeout": 120}
    ],
    directory="/Users/dev/my-project",
    format="json"  # 批量处理始终为JSON
)

🏗️ 架构

核心设计

  • CLI优先：直接调用codex命令的子进程
  • 无状态：每个工具调用都是独立的，没有会话状态
  • 可配置超时：默认执行时间为90秒（可配置）
  • 结构化输出：默认为JSON格式，便于集成
  • 简单的错误处理：清晰的错误消息，快速失败策略

项目结构

codex-bridge/
├── src/
│   ├── __init__.py              # 入口点
│   ├── __main__.py              # 模块执行入口点
│   └── mcp_server.py            # 主MCP服务器实现
├── .github/                     # GitHub模板和工作流
├── pyproject.toml              # Python包配置
├── README.md                   # 此文件
├── CONTRIBUTING.md             # 贡献指南
├── CODE_OF_CONDUCT.md          # 社区标准
├── SECURITY.md                 # 安全政策
├── CHANGELOG.md               # 版本历史
└── LICENSE                    # MIT许可证

🔧 开发

本地测试

# 以开发模式安装
pip install -e .

# 直接运行
python -m src

# 测试CLI可用性
codex --version

与Claude Code集成

当通过MCP协议正确配置时，服务器会自动与Claude Code集成。

🔍 故障排除

CLI不可用

# 安装Codex CLI
npm install -g @openai/codex-cli

# 认证
codex auth login

# 测试
codex --version

连接问题

  • 验证Codex CLI是否已正确认证
  • 检查网络连接
  • 确保Claude Code MCP配置正确
  • 确认codex命令在PATH中

常见错误信息

  • "CLI不可用"：Codex CLI未安装或不在PATH中
  • "需要认证"：运行codex auth login
  • "超时后X秒"：查询耗时过长，尝试增加超时时间或将其拆分为更小的部分

🤝 贡献

我们欢迎社区贡献！请阅读我们的贡献指南，了解如何开始。

快速贡献指南

  1. 分叉仓库
  2. 创建功能分支
  3. 进行更改
  4. 如适用，请添加测试
  5. 提交拉取请求

📄 许可证

本项目采用MIT许可证——详见LICENSE文件。

🔄 版本历史

查看CHANGELOG.md以获取详细的版本历史。

🆘 支持

  • 问题：通过GitHub Issues报告错误或请求功能
  • 讨论：加入社区讨论
  • 文档：可以在docs/目录中创建附加文档

重点：一个简单、可靠的桥梁，通过官方CLI连接Claude Code和Codex AI。