Giime MCP Server

封装后端 /v1/mcp/* 接口的 MCP Server，供 Kiro/Cursor 通过 MCP 协议操作需求、Bug、版本、项目、统计等研发管理功能。

架构

Kiro/Cursor <-> (MCP stdio) <-> giime-mcp-server (Node.js) <-> (HTTP) <-> Hyperf 后端

认证方式：通过 X-Dingtalk-User-Id + X-Business-Domain-Id Header 注入用户身份和业务域。

Tools (36)

需求查询（4）

| Tool | 说明 | |------|------| | get_pending_demands | 获取待开发需求列表（approved 状态，按业务域权限过滤） | | get_my_demands | 获取分配给我的需求（developing/testing 状态） | | get_demand_detail | 获取需求详情（含产品方案、项目、版本、子需求、AI分析、开发者统计） | | search_demands | 搜索需求（多条件过滤，status enum 校验） |

需求操作（5）

| Tool | 说明 | |------|------| | start_development | 开始开发（approved → developing） | | submit_testing | 提交测试（developing → testing），支持变更摘要 | | report_test_result | 报告测试结果，通过→pending_release / 不通过→developing，支持关联 Bug | | release_demand | 发布上线（pending_release → released） | | confirm_research | 确认研究型需求工时并开始研究（pending → developing），仅创建人可操作 |

需求管理（5）

| Tool | 说明 | |------|------| | create_demand | 创建需求（产品经理/业务人员提需求） | | update_demand | 更新需求（修改标题、描述、优先级等） | | get_pending_review | 获取待评审需求列表（产品经理/管理员评审用） | | approve_demand | 评审通过需求（pending → approved） | | reject_demand | 驳回需求（pending → rejected） |

需求分配（1）

| Tool | 说明 | |------|------| | assign_demand | 分配需求负责人 |

AI 分析（2）

| Tool | 说明 | |------|------| | get_demand_ai_analysis | 获取需求 AI 分析结果（技术方案、测试用例、评审建议、产品方案等） | | get_demand_test_cases | 获取需求关联的测试用例列表 |

Bug 管理（7）

| Tool | 说明 | |------|------| | create_bug | 创建 Bug | | get_bug_list | 获取 Bug 列表（支持状态/严重等级/关键词筛选） | | get_bug_detail | 获取 Bug 详情 | | start_fix_bug | 开始修复 Bug（开发人员领取） | | fix_bug | 提交 Bug 修复（开发完成，提交给测试验证） | | verify_close_bug | 验证通过并关闭 Bug（测试人员验证） | | verify_failed_bug | 验证不通过，打回修复 |

版本管理（7）

| Tool | 说明 | |------|------| | get_versions | 获取项目版本列表 | | get_version_detail | 获取版本详情和统计 | | check_version_health | 版本发布前健康检查（需求完成情况、是否逾期） | | activate_version | 激活版本（待开始 → 进行中） | | generate_release_notes | 自动生成版本 Release Notes（按需求类型分组） | | release_version | 发布版本（自动批量上线需求） | | create_version | 快速创建项目版本 |

项目（2）

| Tool | 说明 | |------|------| | get_projects | 获取项目列表（默认日常迭代类型） | | get_project_overview | 获取项目概览（需求、版本、统计） |

统计（2）

| Tool | 说明 | |------|------| | get_my_stats | 个人价值统计（交付量、交付周期、一次通过率等） | | get_team_stats | 团队价值统计 |

调试（1）

| Tool | 说明 | |------|------| | get_server_config | 查看当前 MCP Server 配置（脱敏） |

配置

支持 npx（推荐）、Docker 和 Node.js 三种部署方式。

npx 部署（推荐）

无需安装，在 .kiro/settings/mcp.json 中添加：

{
  "mcpServers": {
    "project_mcp": {
      "command": "npx",
      "args": ["-y", "project-mcp@latest"],
      "env": {
        "GIIME_API_BASE": "https://project.giikin.com",
        "GIIME_DINGTALK_USER_ID": "你的钉钉用户ID"
      }
    }
  }
}

Docker 部署

cd project-mcp
docker build -t giime-mcp-server:latest .

{
  "mcpServers": {
    "project_mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GIIME_API_BASE=http://host.docker.internal:9501",
        "-e", "GIIME_DINGTALK_USER_ID=你的钉钉用户ID",
        "giime-mcp-server:latest"
      ]
    }
  }
}

Node.js 部署

{
  "mcpServers": {
    "project_mcp": {
      "command": "node",
      "args": ["project-mcp/index.js"],
      "env": {
        "GIIME_API_BASE": "http://192.168.4.72:9501",
        "GIIME_DINGTALK_USER_ID": "你的钉钉用户ID"
      }
    }
  }
}

环境变量

| 变量 | 说明 | 默认值 | 必填 | |------|------|--------|------| | GIIME_API_BASE | 后端 API 地址 | https://project.giikin.com | 否 | | GIIME_DINGTALK_USER_ID | 钉钉用户ID | — | 是 | | GIIME_BUSINESS_DOMAIN_ID | 业务域ID（不填则获取所有有权限的数据） | — | 否 |

启动时校验必填环境变量，缺失时输出警告到 stderr（不阻断启动）。

工作流

需求开发流程

1. get_pending_demands        → 查看待开发需求
2. get_demand_detail          → 获取需求详情（含产品方案、AI分析）
3. get_demand_test_cases      → 查看测试用例（了解验收标准）
4. start_development          → 开始开发（approved → developing）
5. AI IDE 辅助开发、测试、联调
6. submit_testing             → 提交测试（可附带 change_summary）
7. report_test_result         → 报告测试结果（不通过可先 create_bug 再关联）
8. release_demand             → 发布上线

研究型需求流程

1. create_research_demand     → 创建研究型需求（AI 自动评估工时，保持 pending）
2. get_demand_detail          → 查看 AI 评估的工时和难度系数
3. confirm_research           → 确认工时并开始研究（pending → developing）
4. 执行研究工作
5. complete_research          → 完成研究（developing → released，跳过测试）

版本发布流程

1. create_version             → 创建版本（或 get_versions 查看已有版本）
2. activate_version           → 激活版本（待开始 → 进行中）
3. check_version_health       → 发布前健康检查
4. generate_release_notes     → 自动生成 Release Notes
5. release_version            → 发布版本（自动批量上线需求）

Bug 修复流程

1. get_bug_list               → 查看 Bug 列表
2. get_bug_detail             → 获取 Bug 详情
3. start_fix_bug              → 领取 Bug 开始修复
4. fix_bug                    → 提交修复（附修复说明）
5. verify_close_bug           → 测试验证通过关闭（或 verify_failed_bug 打回）

需求评审流程（产品经理）

1. get_pending_review         → 查看待评审需求
2. get_demand_detail          → 查看需求详情
3. get_demand_ai_analysis     → 查看 AI 分析结果
4. approve_demand / reject_demand → 通过或驳回
5. assign_demand              → 分配负责人

项目结构

project-mcp/
├── index.js          # MCP Server 主入口（tool 注册）
├── api-client.js     # HTTP 客户端（认证注入、超时、错误处理）
├── package.json      # 依赖管理（@modelcontextprotocol/sdk ^1.12.1）
├── Dockerfile        # Docker 镜像构建（node:18-alpine）
├── .dockerignore
├── .npmignore
└── .gitignore

开发注意事项

• 工具注册使用 server.registerTool() API（server.tool() 在 SDK v1.12+ 已弃用）
• 查询类工具添加 annotations: { readOnlyHint: true }
• 写操作工具添加 destructiveHint / idempotentHint 语义标注
• HTTP 请求超时 30s，自动注入认证 Header
• getConfig 脱敏处理（钉钉ID 只显示前4位）
• Docker 测试命令：

  echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | docker run --rm -i giime-mcp-server:latest

npm 发布

包名：giime-mcp-server，发布到 npmjs.org。

# 发布前确保 .npmrc 中配置了 token（已在 .gitignore 中排除）
# .npmrc 内容：
#   //registry.npmjs.org/:_authToken=<NPM_TOKEN>
#   registry=https://registry.npmjs.org/

npm publish --access public

更新日志

V1.3.0

• 新增 confirm_research 工具：确认研究型需求工时并开始研究（pending → developing）
• 更新 create_research_demand 描述：研究型需求创建后保持 pending，需 confirm_research 确认
• 新增研究型需求工作流文档
• Tools 总数从 35 扩展到 36

V1.2.1

• 修正 get_bug_list 分页参数 page_size → per_page，与后端 BugRepository 对齐
• 修正 get_my_stats / get_team_stats 参数 date_range → period + project_id + business_domain_id，与后端 ValueStatsService 对齐
• npm 包名 giime-mcp-server（MCP 配置中通过 npx 引用）

V1.2.0

• 新增需求管理工具（create_demand, update_demand, get_pending_review, approve_demand, reject_demand, assign_demand）
• 新增 Bug 完整 CRUD 工具（get_bug_list, get_bug_detail, start_fix_bug, fix_bug, verify_close_bug, verify_failed_bug）
• 新增 create_version 工具
• Tools 总数从 22 扩展到 35

V1.1.0

• 全部工具迁移到 server.registerTool() 新 API，添加 annotations 语义标注
• 新增 start_development、get_demand_test_cases、activate_version 工具
• release_version 新增 release_completed_demands 参数
• search_demands 的 status 参数改为 enum 校验
• api-client.js 增强：HTTP 状态码检查、30s 超时、网络异常友好提示、JSON 解析保护
• 启动时校验必填环境变量