CODEX-MCP-CONFIG.md•6.14 kB
# Codex MCP 服务器配置指南
## 概述
本指南将帮助你在 Codex 中配置禅道 MCP 服务器，以便通过 AI 助手操作禅道项目管理系统的 API。
## 前置要求
1. 确保禅道 MCP 服务器已构建完成
2. 确认禅道服务器正在运行（http://localhost）
3. 准备有效的禅道访问 token
## 配置步骤
### 方法一：通过环境变量配置（推荐）
#### 1. 创建配置脚本
在项目根目录创建 `start-mcp.sh`（Linux/Mac）或 `start-mcp.bat`（Windows）：
**Linux/Mac (start-mcp.sh):**
```bash
#!/bin/bash
# 设置环境变量
export ZENDTAO_BASE_URL="http://localhost"
export ZENDTAO_TOKEN="你的_禅道_token_在这里"
# 启动 MCP 服务器
node dist/index.js
```
**Windows (start-mcp.bat):**
```batch
@echo off
REM 设置环境变量
set ZENDTAO_BASE_URL=http://localhost
set ZENDTAO_TOKEN=你的_禅道_token_在这里
REM 启动 MCP 服务器
node dist/index.js
pause
```
#### 2. 赋予执行权限（Linux/Mac）
```bash
chmod +x start-mcp.sh
```
### 方法二：通过 .env 文件配置
#### 1. 复制环境变量文件
```bash
cp .env.example .env
```
#### 2. 编辑 .env 文件
```env
ZENDTAO_BASE_URL=http://localhost
ZENDTAO_TOKEN=你的_禅道_token_在这里
ZENDTAO_TIMEOUT=30000
ZENDTAO_RETRY=3
ZENDTAO_RETRY_DELAY=1000
```
#### 3. 创建启动脚本（Linux/Mac）
```bash
#!/bin/bash
# 加载环境变量
source .env
# 启动 MCP 服务器
node dist/index.js
```
### 方法三：直接配置（不推荐用于生产）
直接在命令行中启动：
```bash
# Linux/Mac
ZENDTAO_BASE_URL=http://localhost ZENDTAO_TOKEN=你的_token node dist/index.js
# Windows
set ZENDTAO_BASE_URL=http://localhost
set ZENDTAO_TOKEN=你的_token
node dist/index.js
```
## 获取禅道 Token
### 步骤 1: 登录禅道
1. 在浏览器中打开 http://localhost
2. 使用管理员账号登录（如 s000001）
### 步骤 2: 获取 zentaosid
1. 打开浏览器开发者工具（F12）
2. 切换到 Application（应用）标签
3. 在左侧 Storage 下选择 Cookies
4. 选择 http://localhost 域名
5. 找到 `zentaosid` 条目
6. 双击复制 Value 列的值
**示例 token**:
```
s000001:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```
### 步骤 3: 验证 token
运行测试以确认 token 有效：
```bash
node dist/index.js
```
如果看到 "连接验证成功"，则 token 有效。
## 在 Codex 中配置
### 1. 找到 Codex 配置目录
根据你的操作系统：
- **Linux**: `~/.config/codex/mcp-servers/`
- **Mac**: `~/Library/Application Support/Codex/mcp-servers/`
- **Windows**: `%APPDATA%\Codex\mcp-servers\`
### 2. 创建服务器配置文件
在 MCP 服务器目录中创建 `zendao.json`:
```json
{
"name": "zendao-mcp",
"description": "禅道项目管理 MCP 服务器",
"command": "node",
"args": ["/完整/路径/到/zendao-mcp/dist/index.js"],
"env": {
"ZENDTAO_BASE_URL": "http://localhost",
"ZENDTAO_TOKEN": "你的_禅道_token_在这里"
},
"cwd": "/完整/路径/到/zendao-mcp/",
"timeout": 30000
}
```
**重要提示**:
- 将 `/完整/路径/到/zendao-mcp/` 替换为实际的项目路径
- 将 `你的_禅道_token_在这里` 替换为真实的 token
### 3. 获取完整路径
**Linux/Mac:**
```bash
pwd
# 输出: /完整/路径/到/zendao-mcp
```
**Windows:**
```cmd
cd
REM 输出: C:\完整\路径\到\zendao-mcp
```
## 验证配置
### 1. 启动 MCP 服务器
```bash
# 确保在项目目录中
cd /path/to/zendao-mcp
# 启动服务器
npm start
```
### 2. 在 Codex 中测试
1. 重启 Codex
2. 尝试调用 MCP 工具，例如：
- 获取项目列表
- 创建新任务
- 查看项目详情
### 3. 常见问题诊断
如果遇到连接问题，检查：
#### 检查 1: 禅道服务器是否运行
```bash
curl -I http://localhost
# 应该返回 200 OK
```
#### 检查 2: Token 是否有效
在浏览器中打开开发者工具，查看 Network 标签：
1. 任意操作禅道
2. 查看请求的 Cookie 头
3. 确认 `zentaosid` 存在
#### 检查 3: 网络连通性
```bash
# 从 MCP 服务器所在机器测试
telnet localhost 80
# 或
nc -vz localhost 80
```
## 可用的 MCP 工具
配置成功后，你可以在 Codex 中使用以下工具：
### 项目管理
- `get_projects` - 获取项目列表
- `get_project_by_id` - 获取项目详情
- `create_project` - 创建新项目
### 任务管理
- `get_tasks` - 获取任务列表
- `create_task` - 创建新任务
- `update_task_status` - 更新任务状态
### 批量操作
- `batch_create_tasks` - 批量创建任务
## 示例使用
在 Codex 中，你可以这样使用：
```
我需要查看当前所有的项目
→ 调用 get_projects 工具
我需要创建一个新任务：名称为"测试任务"，属于项目 ID 123
→ 调用 create_task 工具，参数为 {"name": "测试任务", "project": 123}
```
## 故障排除
### 问题 1: 连接失败
```
错误: Request failed with status code 401
```
**解决方案**:
- 确认 token 未过期（重新登录禅道获取新 token）
- 检查 token 格式是否正确
- 确认 .env 文件中的 token 与实际 token 一致
### 问题 2: 项目/任务不存在
```
错误: 未找到 ID 为 X 的项目
```
**解决方案**:
- 确认 ID 正确
- 检查项目是否已被删除
### 问题 3: 权限不足
```
错误: 权限不足，无法创建任务
```
**解决方案**:
- 使用管理员账号
- 联系管理员分配必要权限
### 问题 4: MCP 服务器启动失败
```
错误: Cannot find module
```
**解决方案**:
- 确保已运行 `npm run build`
- 检查路径是否正确
- 确认 Node.js 版本 >= 16.0.0
## 性能优化
### 缓存配置
默认情况下：
- 查询操作缓存 5 分钟
- 用户列表缓存 30 分钟
- 详情数据缓存 10 分钟
可以通过修改 `src/utils/cache.ts` 调整 TTL。
### 并发限制
默认最多 10 个并发请求，可在批量操作时调整 `maxConcurrency` 参数。
## 支持
如需帮助：
1. 查看 README.md 了解详细文档
2. 检查项目 issue 列表
3. 查看禅道 API 文档
---
**注意**: 请妥善保管你的 token，不要提交到版本控制系统！