ONES MCP Server

ONES项目管理平台的Model Context Protocol (MCP)服务器，让AI智能体能够实时查询和管理ONES上的缺陷、需求和任务。

功能特性

• 查询项目工作项（缺陷、需求、任务）
• 按迭代、状态、指派人等多维度过滤
• 查看工作项详情
• 更新工作项状态
• 添加评论
• 批量操作
• 高级搜索

快速开始

1. 安装

# 全局安装
npm install -g ones-mcp

# 或使用npx直接运行
npx ones-mcp

2. 配置环境变量

复制 .env.example 为 .env 并填入你的ONES配置：

cp .env.example .env

⚠️ 支持两种认证方式（二选一）

| 方式 | 配置项 | 优点 | 缺点 | |------|--------|------|------| | 账号密码模式（推荐） | ONES_USERNAME + ONES_PASSWORD | 自动登录，Token自动刷新 | 需保存账号密码 | | Token模式 | ONES_USER_ID + ONES_TOKEN + ONES_CSRF_TOKEN | 不暴露密码 | Token会过期，需手动更新 |

方式1：账号密码模式（推荐）

# ONES平台基础URL（必填）
ONES_BASE_URL=http://your-ones-domain.com

# 团队UUID（必填）
ONES_TEAM_UUID=your-team-uuid

# 项目UUID（必填）
ONES_PROJECT_UUID=your-project-uuid

# ONES登录用户名
ONES_USERNAME=your-username

# ONES登录密码
ONES_PASSWORD=your-password

配置完成后，启动时会自动登录并获取Token，Token过期也会自动刷新。

方式2：Token模式

# ONES平台基础URL（必填）
ONES_BASE_URL=http://your-ones-domain.com

# 团队UUID（必填）
ONES_TEAM_UUID=your-team-uuid

# 项目UUID（必填）
ONES_PROJECT_UUID=your-project-uuid

# 用户ID - 从Cookie中获取 ones-uid 值
ONES_USER_ID=your-user-id

# 登录令牌 - 从Cookie中获取 ones-lt 值
ONES_TOKEN=your-login-token

# CSRF令牌 - 从Cookie中获取 ct 值
ONES_CSRF_TOKEN=your-csrf-token

如何获取Token（Token模式专用）

1. 登录你的ONES平台
2. 打开浏览器开发者工具（F12）
3. 切换到 Application → Cookies
4. 查找以下Cookie值：
   • ones-lt → 填入 ONES_TOKEN
   • ct → 填入 ONES_CSRF_TOKEN
   • ones-uid → 填入 ONES_USER_ID

3. 启动MCP服务器

# 全局安装后
ones-mcp

# 或在项目目录中
npm start

4. 在Claude Desktop中配置

编辑Claude Desktop配置文件：

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

账号密码模式（推荐）：

{
  "mcpServers": {
    "ones": {
      "command": "npx",
      "args": ["ones-mcp"],
      "env": {
        "ONES_BASE_URL": "http://your-ones-domain.com",
        "ONES_TEAM_UUID": "your-team-uuid",
        "ONES_PROJECT_UUID": "your-project-uuid",
        "ONES_USERNAME": "your-username",
        "ONES_PASSWORD": "your-password"
      }
    }
  }
}

Token模式：

{
  "mcpServers": {
    "ones": {
      "command": "npx",
      "args": ["ones-mcp"],
      "env": {
        "ONES_BASE_URL": "http://your-ones-domain.com",
        "ONES_TEAM_UUID": "your-team-uuid",
        "ONES_PROJECT_UUID": "your-project-uuid",
        "ONES_USER_ID": "your-user-id",
        "ONES_TOKEN": "your-login-token",
        "ONES_CSRF_TOKEN": "your-csrf-token"
      }
    }
  }
}

使用示例

查询缺陷

// AI智能体可以这样调用
get_defects({
  status: "待回归",
  assignee: "王巍巍"
})

查询指定迭代的任务

get_sprint_items({
  sprint_name: "28预算执行V2.3.4",
  item_type: "defect",
  status: "进行中"
})

更新工作项状态

update_workitem_status({
  workitem_uuid: "abc123",
  new_status: "已完成"
})

添加评论

add_comment({
  workitem_uuid: "abc123",
  content: "问题已修复，请验证"
})

可用工具

| 工具名 | 描述 | 示例参数 | |--------|------|----------| | query_project_items | 查询项目工作项 | project_uuid, sprint_name, item_type, status, assignee | | list_sprints | 列出所有迭代 | project_uuid | | get_sprint_items | 获取迭代工作项 | sprint_uuid, item_type, status | | search_workitems | 高级搜索 | keyword, project_uuid, item_type, status, assignee, start_date, end_date | | get_work_item_detail | 获取工作项详情 | uuid | | update_workitem_status | 更新工作项状态 | workitem_uuid, new_status | | update_workitem_fields | 更新工作项字段 | workitem_uuid, fields | | add_comment | 添加评论 | workitem_uuid, content |

配置说明

基础配置（必填）

• ONES_BASE_URL: ONES平台地址
• ONES_TEAM_UUID: 团队UUID（从URL中获取）
• ONES_PROJECT_UUID: 项目UUID（从URL中获取）

认证配置（二选一）

方式1 - 账号密码模式（推荐）：

• ONES_USERNAME: ONES登录用户名
• ONES_PASSWORD: ONES登录密码

方式2 - Token模式：

• ONES_USER_ID: 用户ID（ones-uid cookie值）
• ONES_TOKEN: 登录令牌（ones-lt cookie值）
• ONES_CSRF_TOKEN: CSRF令牌（ct cookie值）

可选配置

• ONES_DEFAULT_SPRINT: 默认迭代名称
• ONES_LOG_LEVEL: 日志级别（debug, info, warn, error）

从URL获取UUID

ONES项目URL格式：

http://ones.example.com/project/#/team/{TEAM_UUID}/project/{PROJECT_UUID}/component/.../sprint/{SPRINT_UUID}/tasks

例如：

http://ones.example.com/project/#/team/JoCYxPUy/project/CfTQPdoHlC5YGuhp/component/HsqcY2kw/sprint/HRbZJHkH/tasks

从中可以提取：

• 团队UUID: JoCYxPUy
• 项目UUID: CfTQPdoHlC5YGuhp
• 迭代UUID: HRbZJHkH

常见问题

Q: Token过期了怎么办？

A: 推荐使用账号密码模式，Token会自动刷新，无需手动处理。如果使用Token模式，需要重新登录ONES并更新 .env 中的Token值。

Q: 权限不足怎么办？

A: 确保你的ONES账号有访问该项目的权限。如果问题持续，请联系项目管理员。

Q: 支持哪些ONES版本？

A: 支持所有使用标准REST API的ONES版本。

Q: 如何查询多个项目？

A: 可以在查询时指定 project_uuid 参数，或者为每个项目配置单独的MCP实例。

开发和贡献

# 克隆项目
git clone https://github.com/yourusername/ones-mcp.git

# 安装依赖
cd ones-mcp
npm install

# 开发模式
npm run dev

# 运行测试
npm test

欢迎提交Issue和Pull Request！

许可证

MIT License - 详见 LICENSE 文件

作者

Wang Weiwei

更新日志

详见 CHANGELOG.md

相关链接

• npm主页
• ONES官网
• MCP协议
• GitHub仓库