# 🤖 Codex MCP Server
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
> **连接您的 AI 助手与本地强大的 Codex 引擎**
这是一个符合 **Model Context Protocol (MCP)** 标准的服务器，旨在充当桥梁，让 **Claude Code**、**Cursor**、**Trae**、**Gemini CLI** 等现代 AI 客户端能够安全地调用本地环境中的 **Codex Agent** 进行代码审查与修复。
---
## 🌟 核心价值
通过本项目，您的 AI 助手将获得“第二大脑”，实现：
- 🔍 **全项目深度审查**：不再局限于单个文件，而是理解整个代码库的上下文。
- 🛠️ **自动化智能重构**：基于项目架构进行安全的、系统级的代码修改。
- 🐛 **上下文感知修复**：精准定位 Bug 根源，而非仅修复表面错误。
---
## 💻 客户端支持
完美适配支持 MCP 协议的主流 AI 编程工具：
| 客户端 | 支持情况 | 备注 |
| :--- | :---: | :--- |
| 💎 **Gemini CLI** | ✅ 完美支持 | 需配置 `.gemini/settings.json` |
| 🟣 **Claude Desktop** | ✅ 完美支持 | 支持 Claude 4.5 Sonnet / Opus |
| 🖱️ **Cursor** | ✅ 完美支持 | 在 Features > MCP 中配置 |
| 🚀 **Trae** | ✅ 完美支持 | 兼容标准 MCP 协议 |
| 🆚 **VS Code** | ✅ 支持 | 需配合 MCP 扩展使用 |
---
## ✨ 功能特性
* **🛡️ 企业级安全 (Secure Local Execution)**
封装本地 `codex` 二进制文件，严格遵循您系统的权限和沙盒设置，确保代码安全。
* **🧠 记忆增强 (Continuous Context)**
通过智能的 `session_id` 管理，维护多轮对话的历史上下文，支持迭代式的代码改进。
* **📂 全局视野 (Project-Level Awareness)**
提供专用工具 `review_project`，轻松处理跨文件夹、跨模块的复杂架构变更。
* **⚡ 极速响应 (High Performance)**
专为 Agent 通信优化的低延迟架构，让审查过程行云流水。
---
## 🚀 快速开始
### 1. 环境准备
* **Node.js**: v16 或更高版本
* **Codex CLI**: 确保你已安装 `codex` 并启用过codex CLI完成了认证。
### 2. 安装与构建
```bash
# 1. 克隆仓库
git clone <your-repo-url>
cd Coagent
# 2. 安装依赖
npm install
# 3. 编译项目
npm run build
```
> 💡 **提示**: 编译后的产物将位于 `dist/` 目录下。
---
## ⚙️ 配置指南
为了获得最佳体验，我们**强烈建议**将此 MCP 服务器配置为**项目级别**。
### 标准配置 (JSON)
无论您使用哪种客户端，请参考以下配置结构：
```json
{
"mcpServers": {
"codex-reviewer": {
"command": "node",
"args": ["<您的项目绝对路径>/dist/index.js"],
"description": "Codex Project Reviewer"
}
}
}
```
> ⚠️ **注意**: 请将 `<您的项目绝对路径>` 替换为本仓库实际的完整路径（例如：`E:\Project\Codex_Reviewer`）。Windows 路径请注意转义`\\`反斜杠。
### 常见客户端配置文件路径
* **Gemini CLI**: `[项目根目录]/.gemini/settings.json`
* **VS Code**: `[项目根目录]/.vscode/mcp.json`
* **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (MacOS)
* **其余客户端**: `自行查找文档查看相应的项目级mcp和rules的配置规范`
---
## 🤖 最佳实践：自动化审查流
**想让 AI 自动帮您检查代码？**
将以下规则写入您的项目规则文件（如 `.cursorrules`, `.gemini/GEMINI.md`, 或 Claude Projects Instructions），即可实现**全自动化的代码质量守护**。
### 📋 推荐规则模板
```markdown
# Code Review Workflow
## Mandatory Review Process
After modifying code (using `write_file`, `replace`, `edit_file`, etc.), you **MUST** immediately call the Codex MCP tool to verify the work.
1. **Complex Changes**: Use `review_project` for multi-file changes or system refactoring.
2. **Simple Edits**: Use `review_file` for single-file syntax/logic checks.
## Protocol
- **Context**: You MUST provide a detailed `change_description` explaining *what* changed and *why*.
- **Memory**: You MUST generate and maintain a consistent `session_id` for the duration of a task.
```
---
## 🛠️ 工具列表
您可以在对话中直接调用以下工具：
| 工具名称 | 图标 | 类型 | 用途 |
| :--- | :---: | :---: | :--- |
| **`review_project`** | 🏢 | **核心** | **系统级审查** - 扫描全项目，处理复杂逻辑与架构变更。 |
| **`review_file`** | 📄 | 轻量 | **文件级审查** - 快速检查单文件语法、风格与逻辑错误。 |
| **`review_code_changes`** | 💬 | 通用 | **通用审查** - 发送任意代码片段进行分析。 |
| **`continue_review`** | 🔄 | 会话 | **多轮对话** - 针对之前的审查结果进行追问或微调。 |
---
## 📄 许可证
本项目基于 [MIT License](LICENSE) 开源。
---
<div align="center">
<sub>Built with ❤️ for the AI Developer Community</sub>
</div>
