AI代码生成服务器

Codex CLI MCP 服务器

一个全面的模型上下文协议服务器，为AI代理提供由OpenAI的Codex CLI驱动的高级代码生成、审计和调试工具。该服务器包含10种专用工具，覆盖完整的软件开发生命周期。

概述

这个MCP服务器为AI代理提供 10种综合工具 涵盖完整的软件开发生命周期：规划、实施、评审、调试、安全审计、对话辅助和系统管理。每种工具都旨在通过丰富的上下文和结构化响应，最大限度地发挥Codex CLI的功能。

非常适合需要以下条件的经纪人：

• 具有情境感知的战略实施规划
• 基于架构指导的精确代码生成
• 带有可操作反馈的质量代码审查
• 带根本原因分析的智能调试
• 全面的安全审计和合规检查
• 交互式对话辅助与头脑风暴
• 实时会话与健康监测

主要特点

• 持久化代理容器每个代理都拥有自己的长运行Codex CLI环境
• 上下文保持保持完整的对话历史和工作区状态
• 集装箱管理使用监控工具实现完整的生命周期管理
• 实时协作与始终运行的Codex实例进行直接通信
• 准备就绪，可用于生产使用持久化存储的Docker Compose编排
• 轻松集成用于无缝代理连接的标准MCP协议

建筑学

graph TB
    A[AI Agent 1] --> B[MCP Server Container]
    C[AI Agent 2] --> B
    D[AI Agent N] --> B

    B --> E[Persistent Agent Manager]
    E --> F[Agent 1 Codex Container<br/>Always Running]
    E --> G[Agent 2 Codex Container<br/>Always Running]
    E --> H[Agent N Codex Container<br/>Always Running]

    B --> I[Container Management Tools]
    B --> J[Persistence Manager]
    J --> K[Agent Data Storage]

快速入门

先决条件

• Docker 引擎 20.10+ 使用 Docker Compose 2.0+ 版本
• Python 3.12及以上版本 （用于开发和本地测试）
• 认证方法 （选择一个）：
  • ChatGPT订阅服务 （推荐）- 使用您现有的ChatGPT配额
  • OpenAI API密钥 - 按请求分别计费
• Git（一种分布式版本控制系统） 用于克隆仓库
• 最低系统要求：
  • 4GB 内存（建议8GB，以支持多个代理）
  • 2个CPU核心（建议4个核心）
  • 10GB免费磁盘空间用于容器和数据

安装

1. 克隆仓库

   复制

   git clone https://github.com/your-org/codex-mcp-server.git
   cd codex-mcp-server
   

2. 配置身份验证 （选择一种方法）

   方法A：ChatGPT订阅OAuth（推荐）

   复制

   # No configuration needed - authenticate after starting the server
   # This uses your ChatGPT subscription quota
   

   方法B：OpenAI API密钥

   复制

   # Create .env file with your OpenAI API key
   echo "OPENAI_API_KEY=your-openai-api-key-here" > .env
   

3. 部署持久化代理架构

   复制

   # Start the MCP server and persistent infrastructure
   docker-compose --profile codex-mcp up -d
   

4. 验证部署

   复制

   # Check services are running
   docker-compose ps
   
   # Check server health
   curl http://localhost:8210/health
   

MCP客户端连接

采用持续运行的代理架构，代理连接到容器化的MCP服务器，而不是运行本地进程。

克劳德编码配置

claude mcp add --transport sse codex-mcp http://localhost:8210/sse --scope user

克劳德桌面配置

将此添加到您的Claude桌面MCP设置中：

{
  "mcpServers": {
    "codex-mcp": {
      "type": "sse",
      "url": "http://localhost:8210/sse"
    }
  }
}

MCP 检测器

npx @modelcontextprotocol/inspector http://localhost:8210

手动测试

# Test health endpoint
curl http://localhost:8210/health

# Test agent creation
curl -X POST http://localhost:8210/tools/codex_chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello Codex", "agent_id": "test_agent"}'

OAuth 认证设置

建议：使用您的ChatGPT Plus订阅，而不是单独的OpenAI API计费！

零配置OAuth服务器会自动检测并使用您系统中现有的OAuth令牌，无需手动配置！

快速OAuth设置（最高效）

步骤1：在您的主机系统上使用Codex CLI进行身份验证

# Install Codex CLI globally (if not already installed)
npm install -g @openai/codex

# Authenticate with your ChatGPT account
codex auth login

步骤2：构建并启动MCP服务器

#Build the MCP Server
docker-compose --profile codex-mcp up -d --build 

然后启动mcp服务：

# The server automatically detects and uses your OAuth tokens
docker-compose --profile codex-mcp up -d

步骤3：验证OAuth是否正常工作

# Check that containers are using OAuth (not API key)
docker logs codex-mcp-server | grep -i oauth

# You should see: "Injecting OAuth tokens for ChatGPT subscription authentication"

就是这个！ 自动OAuth检测的工作原理如下：

• 自动检测 OAuth令牌在 ~/.codex/auth.json
• 自动挂载 从Windows主机到Linux容器的令牌
• 自动注射 将令牌放入每个代理容器中
• 自动切换 关于您的ChatGPT Plus订阅

无需配置文件！无需设置环境变量！ 该系统检测到您现有的Codex CLI认证信息，即可直接使用。

验证OAuth集成

检查您的订阅详情：

# See what authentication method is active
docker exec [container-name] cat ~/.codex/auth.json | head -5

# Should show: "OPENAI_API_KEY": null and "tokens": {...}

监控代理容器：

# Watch agent startup to confirm OAuth injection
docker logs -f [agent-container-name]

# Look for: "OAuth tokens injected successfully"

替代设置方法

如果您本地没有安装Codex CLI：

1. 使用集成的认证脚本

   复制

   # Clone the repository first
   git clone https://github.com/your-org/codex-mcp-server.git
   cd codex-mcp-server
   
   # Run OAuth authentication
   python auth.py login
   

2. 手动设置令牌

   复制

   # Create OAuth directory
   mkdir -p ~/.codex
   
   # Add your ChatGPT tokens (get from browser dev tools)
   echo '{"tokens": {"access_token": "your-token"}}' > ~/.codex/auth.json
   

自动OAuth检测的工作原理

服务器采用智能自动检测技术，实现零配置：

# 1. Server starts and checks for OAuth tokens automatically
docker-compose --profile codex-mcp up -d

# 2. Detection happens in this order:
#    ~/.codex/auth.json (Windows/Linux/Mac)
#    $USERPROFILE/.codex/auth.json (Windows)
#    $HOME/.codex/auth.json (Linux/Mac)
#    Environment variables (fallback)

# 3. If OAuth found: Uses ChatGPT subscription
# 4. If no OAuth: Falls back to API key

智能路径检测：

• Windows： C:\Users\YourName\.codex\auth.json
• Linux/苹果系统： ~/.codex/auth.json
• **Docker（注：Docker是一个用于开发、部署和运行应用程序的开源平台，它使用容器化技术来打包应用程序及其依赖，以便在任何环境中一致地运行。）**自动从主机挂载到 /app/.codex

OAuth 配置选项（可选）

如有需要，覆盖自动检测：

# Authentication preferences (usually not needed)
CODEX_AUTH_METHOD=auto                       # auto (default), api_key, or oauth
CODEX_PREFER_OAUTH=true                      # Prefer OAuth over API key (default)

# Custom OAuth directory (if tokens are elsewhere)
CODEX_AUTH_DIR=/custom/path/to/codex/dir

# OAuth client settings (for manual auth script only)
OAUTH_CLIENT_ID=codex-cli                    # OAuth client identifier
OAUTH_CALLBACK_PORT=8765                     # Local callback server port
OAUTH_AUTO_OPEN_BROWSER=true                 # Auto-open browser for auth

OAuth的优势

为何选择OAuth而非API密钥：

• 使用现有的ChatGPT Plus订阅 （不单独计费）
• 更高的速率限制 与API密钥相比
• 更安全 （令牌自动刷新）
• 更优的配额管理 通过ChatGPT界面
• 简化计费 （一次订阅，畅享所有）

解决OAuth问题

OAuth不起作用？请检查以下内容：

1. 验证OAuth令牌是否存在：

   复制

   # Check host system has OAuth tokens
   ls -la ~/.codex/auth.json
   cat ~/.codex/auth.json | grep -i "access_token"
   

2. 确认集装箱安装：

   复制

   # Check if tokens are mounted in main container
   docker exec codex-mcp-server ls -la /app/.codex/
   docker exec codex-mcp-server cat /app/.codex/auth.json | head -5
   

3. 验证代理注入：

   复制

   # Check agent containers have injected tokens
   docker exec [agent-container] cat ~/.codex/auth.json | head -5
   
   # Should show OAuth tokens, not API key
   

常见问题及解决方法：

• **“未找到OAuth令牌”**跑 codex auth login 首先在主机系统上
• **“只读文件系统”**正常 - 令牌被注入，未在代理中挂载
• 仍在使用API密钥检查日志中的OAuth注入成功消息
• **“ChatGPT 配额已超限”**您的订阅已达到限制，请等待重置

如需切换，请返回API密钥：

# Set API key in .env file
echo "OPENAI_API_KEY=your-api-key" > .env
echo "CODEX_PREFER_OAUTH=false" >> .env

# Restart server
docker-compose --profile codex-mcp restart

配置

环境变量

通过环境变量配置服务器行为 .env 文件：

|

|

| 启用持久化代理容器 | 否 |

• |*如果不使用OAuth认证，则此为必填项 /data/agents/ 持久存储
• **该系统为以下内容创建持久卷：**代理数据 /config/ ：
• - 单个代理的工作区服务器配置 /data/sessions/ :

- 服务器配置文件

会话数据 : - 会话元数据

MCP 工具

• plan (task, repo_context?, constraints?) 服务器提供 PlanResponse 10款全面的MCP工具

• implement (task, target_files, context_files?, requirements?) 对于AI代理： ImplementResponse 核心开发工作流程（4种工具）

• review (content, rubric?, focus_areas?) → ReviewResponse 制定包含文件目标和架构决策的结构化实施计划

• fix (failing_tests?, error_output?, context_files?, symptoms?) → FixResponse 生成带有差异、解释和集成说明的精确代码更改

→

• chat (message, context?, previous_messages?, reference_files?) 通过内联注释、评分和可操作的建议分析代码质量 ChatResponse →

• audit (code, file_paths?, focus_areas?, severity_threshold?, compliance_standards?) 针对问题进行调试，采用针对性修复、根本原因分析和预防策略 AuditResponse 高级分析工具（3种工具）

• debug (error_message, code_context?, stack_trace?, environment_info?, reproduction_steps?) → DebugResponse 交互式对话AI助手，助力头脑风暴、获取第二意见及提供指导

→

• list_sessions (agent_id?) 基于CWE/CVE的综合安全与质量审计及合规性检查 Dict →

• get_my_session_info () 智能调试辅助，具备根本原因分析及多种解决方案途径 Dict 会话管理（2种工具）

→

• health_check () 列出带有状态和元数据的活跃 Codex CLI 会话 HealthCheckResponse →

获取当前会话的详细信息，包括容器ID和活动状态

系统监控（1种工具）

• **→**服务器健康状态、运行时间、活跃会话和系统信息
• 安全特性容器隔离
• 每个代理一个容器代理容器之间的完全隔离
• 非root权限执行所有容器均以非特权用户身份运行

资源限制

• CPU和内存配额防止资源耗尽网络隔离
• 容器仅通过MCP服务器进行通信数据安全
• 运行时注入容器镜像中不包含任何秘密信息
• 只读挂载配置文件以只读方式挂载

工作区隔离

• 为每个代理分配独立的工作目录持久化存储
• 使用适当权限安全挂载卷访问控制
• 代理边界代理无法访问其他代理容器

文件系统隔离

为每个代理分配独立的持久工作区

# Test persistent architecture
python test_persistent_simple.py

# Check container status
docker-compose ps

# View logs
docker-compose logs codex-mcp-server

认证

# Install development dependencies (if modifying source)
pip install -r requirements-dev.txt

# Rebuild containers after changes
docker-compose --profile codex-mcp build --no-cache

# Restart services
docker-compose --profile codex-mcp restart

所有操作均需OpenAI API密钥

发展

• 运行测试本地开发 http://localhost:8210/health 监测
• 健康检查服务器健康状况 get_agent_status ：
• - 服务器状态代理状态

使用

• 个体代理的工具容器指标 docker-compose logs codex-mcp-server
• 每个代理的实时CPU和内存跟踪记录日志
• 容器日志:

代理日志

• 单个代理容器的日志可用结构化日志记录 list_active_agents 带有相关ID的JSON格式日志
• 管理工具活性成分
• ：- 显示所有正在运行的代理 cleanup_inactive_agents 资源使用情况

特定代理的CPU和内存指标

1. 清理
2. ： git checkout -b feature/amazing-feature
3. - 移除失效的代理
4. 做出贡献
5. 为仓库创建分支（或“克隆仓库”）

创建一个特性分支：

• 遵循附带指南中的开发工作流程
• 确保测试通过并保持覆盖率
• 提交一个拉取请求
• 开发指南
• 保持文件行数不超过500行（根据需要拆分为多个模块）

为所有新功能编写测试

遵循PEP8编码规范

全程使用类型提示

# Check Docker daemon
docker info

# Verify services
docker-compose ps

# Check logs
docker-compose logs codex-mcp-server

为所有函数编写符合Google风格的文档字符串（docstrings）

# Verify API key in .env file
cat .env

# Test server health
curl http://localhost:8210/health

故障排除

# List active agents
curl http://localhost:8210/tools/list_active_agents

# Check specific agent
curl http://localhost:8210/tools/get_agent_status \
  -d '{"agent_id": "your_agent_id"}'

# Manual cleanup
curl http://localhost:8210/tools/cleanup_inactive_agents

常见问题

# Check what's using port 8210
netstat -ano | findstr :8210

# Change port in docker-compose.yml if needed
# Then restart: docker-compose --profile codex-mcp up -d

容器启动失败

认证错误 代理容器问题 端口冲突

许可证

• 这个项目采用MIT许可证授权——详见 许可证
• 文件中包含详细信息。 致谢
• OpenAI Codex 命令行界面（CLI） - 底层的CLI工具

FastMCP

• - MCP服务器框架 模型上下文协议
• - 协议规范 相关项目
• Codex CLI（命令行界面） - 官方OpenAI Codex命令行界面（CLI）

MCP服务器