PMS MCP Server

基于 Model Context Protocol (MCP) 的 PMS 数据库查询服务，支持通过 AI 助手查询 PMS 数据库表结构、字段说明，并自动生成 SQL 查询语句。

1. 项目简介

PMS MCP Server 是一个通过 MCP 协议提供 PMS 数据库查询服务的工具。它能够帮助 AI 助手（如 Claude、Cursor）理解 PMS 系统的数据库结构，自动生成精确的 SQL 查询语句，并提供项目管理相关的专业建议。

核心特性：

• 支持中英文表名混合查询
• 自动生成可执行的 SQL 语句
• 理解禅道（ZenTao）数据模型
• 提供效能统计数据解读

2. 核心功能

| 类型 | 名称 | 说明 | |------|------|------| | 工具 | getDbInfo | 获取所有数据库表信息 | | 工具 | getTableInfo | 获取指定表的详细信息（支持中英文表名） | | 提示词 | system-description | 资深项目管理专家助手 | | 资源 | ddl-sql | PMS 数据库完整 DDL 语句 |

3. 技术栈

• 语言：TypeScript
• 运行时：Node.js >= 18
• 协议：Model Context Protocol (MCP)
• 核心依赖：
  • @modelcontextprotocol/sdk ^1.29.0
  • zod ^3.25.76

4. 快速开始

4.1 环境要求

• Node.js >= 18
• pnpm >= 8

4.2 安装

# 克隆项目
git clone <repository-url>
cd pms-mcp

# 安装依赖
pnpm install

4.3 运行

# 开发模式（热重载）
pnpm dev

# 生产模式
pnpm build
pnpm start

4.4 调试

使用 MCP Inspector 进行调试：

pnpm inspect

5. MCP 客户端配置

5.1 Claude Desktop

找到 Claude Desktop 配置文件：

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

添加服务器配置：

{
  "mcpServers": {
    "pms": {
      "command": "node",
      "args": ["<项目路径>/dist/index.js"]
    }
  }
}

5.2 Cursor

1. 打开 Cursor 设置（Settings）
2. 进入 MCP Server 配置
3. 添加新服务器：

{
  "mcpServers": {
    "pms": {
      "command": "node",
      "args": ["<项目路径>/dist/index.js"]
    }
  }
}

5.3 其他 MCP 客户端

通用配置：

| 配置项 | 值 | |--------|-----| | Command | node | | Args | <项目路径>/dist/index.js |

6. 功能详解

6.1 工具 (Tools)

getDbInfo

获取所有数据库表信息，返回 PMS 系统可用的数据表列表。

使用场景：了解 PMS 系统有哪些数据表可用

调用示例：

用户：列出所有可用的数据表
助手：调用 getDbInfo 工具

getTableInfo

获取指定表的详细信息，包括字段说明、表属性、DDL 语句等。

参数：

| 参数 | 类型 | 说明 | |------|------|------| | tableName | string | 表名（支持中英文） |

支持的中英文表名映射：

| 英文表名 | 中文表名 | |----------|----------| | bug_data | 缺陷数据信息表 | | developer_efficiency_stats | 开发工程师效能统计数据表 | | dingtalk_attendance | 打卡数据信息表 | | gitlab_commit_stats | 提交代码数据信息表 | | leave_attendance_detail | 请假考勤明细数据表 | | product_driven_data | 产品驱动数据信息表 | | project_sprint_analysis | 项目迭代任务与需求分析统计表 | | staff_leave_info | 请假数据信息表 | | story_task_detail_stats | 需求任务明细数据表 | | tester_efficiency_stats | 测试工程师效能统计数据表 | | weekly_person_report_data | 周报人员明细表 | | weekly_report_data | 周报数据统计表 | | work_dates | 工作日历表 | | zentao_product_project | 产品项目关系表 | | zentao_product_sprint_daily_snapshot | 产品迭代每日快照表 | | zentao_product_sprint_pmo_weekly | 产品迭代PMO周度汇总表 | | zentao_story_detail | 禅道需求信息表 | | zentao_story_sprint_snapshot | 故事-迭代状态快照表 | | zentao_task | 禅道任务信息表 | | zentao_task_effort | 禅道任务日志信息表 |

使用场景：查询表结构、字段说明、表属性

调用示例：

用户：获取 bug_data 表的完整结构
助手：调用 getTableInfo({ tableName: "bug_data" })
或
用户：获取缺陷表的详细信息
助手：调用 getTableInfo({ tableName: "缺陷数据信息表" })

6.2 提示词 (Prompts)

system-description

资深项目管理专家助手，能够帮助用户：

• 理解 PMS 数据库结构和关系
• 生成精确的 SQL 查询语句
• 解读禅道数据模型
• 分析效能统计数据

6.3 资源 (Resources)

ddl-sql (ddl://sql)

PMS 数据库完整 DDL 语句资源，可以通过 MCP 协议的资源访问接口获取。

MIME 类型：application/sql

7. 数据库表说明

7.1 表清单（共20张）

缺陷管理

| 表名 | 说明 | |------|------| | bug_data | 缺陷数据信息表 |

效能统计

| 表名 | 说明 | |------|------| | developer_efficiency_stats | 开发工程师效能统计数据表 | | tester_efficiency_stats | 测试工程师效能统计数据表 |

考勤管理

| 表名 | 说明 | |------|------| | dingtalk_attendance | 打卡数据信息表 | | leave_attendance_detail | 请假考勤明细数据表 | | staff_leave_info | 请假数据信息表 | | work_dates | 工作日历表 |

代码数据

| 表名 | 说明 | |------|------| | gitlab_commit_stats | 提交代码数据信息表 |

产品驱动

| 表名 | 说明 | |------|------| | product_driven_data | 产品驱动数据信息表 |

项目迭代

| 表名 | 说明 | |------|------| | project_sprint_analysis | 项目迭代任务与需求分析统计表 |

禅道相关

| 表名 | 说明 | |------|------| | zentao_product_project | 产品项目关系表 | | zentao_product_sprint_daily_snapshot | 产品迭代每日快照表 | | zentao_product_sprint_pmo_weekly | 产品迭代PMO周度汇总表 | | zentao_story_detail | 禅道需求信息表 | | zentao_story_sprint_snapshot | 故事-迭代状态快照表 | | zentao_task | 禅道任务信息表 | | zentao_task_effort | 禅道任务日志信息表 |

周报

| 表名 | 说明 | |------|------| | weekly_person_report_data | 周报人员明细表 | | weekly_report_data | 周报数据统计表 |

需求任务

| 表名 | 说明 | |------|------| | story_task_detail_stats | 需求任务明细数据表 |

7.2 核心表关系

产品 (zentao_product_*)
  └── 项目 (zentao_product_project)
        └── 迭代 (zentao_product_sprint_*)
              ├── 需求 (zentao_story_*)
              │     └── 关联缺陷 (bug_data.story_id)
              └── 任务 (zentao_task)
                    ├── 关联缺陷 (bug_data.task_id)
                    └── 任务工时 (zentao_task_effort)

关系说明：

• 一个产品下有多个项目
• 一个项目下有多个迭代
• 一个迭代下有多个需求和任务
• 缺陷可以关联需求或任务
• 任务有工时记录

7.3 关键业务字段

| 字段前缀 | 含义 | 示例 | |----------|------|------| | sprint_* | 迭代相关 | sprint_name, sprint_id | | story_* | 需求相关 | story_name, story_id, story_points | | task_* | 任务相关 | task_name, task_id, task_consumed | | bug_* | 缺陷相关 | bug_title, bug_id | | dept* | 部门相关 | dept, deptName | | account | 账号 | opened_by, assigned_to | | estimate | 预估工时 | task_estimate | | consumed | 消耗工时 | task_consumed | | story_points | 故事点 | original_story_points |

7.4 禅道数据模型关键状态

需求状态 (story_status)：

• wait / 待锁定
• planning / 计划中
• developed / 开发中
• tested / 测试中
• closed / 已关闭

任务状态 (task_status)：

• wait / 待开始
• doing / 进行中
• done / 已完成
• closed / 已关闭

缺陷状态 (status)：

• open / 打开
• assigned / 已分配
• resolved / 已解决
• closed / 已关闭

8. 使用示例

示例1：查询项目缺陷

用户问：查询项目 PROJECT_CODE 的所有未关闭缺陷

助手答： 根据您的需求，我为您生成以下 SQL 查询：

SELECT bug_id, bug_title, severity, priority, status,
       opened_by_name, opened_date, assigned_to_name
FROM bug_data
WHERE project_code = 'PROJECT_CODE'
  AND status != 'closed'
ORDER BY opened_date DESC;

如需查看缺陷关联的需求详情，可以使用联表查询：

SELECT b.bug_id, b.bug_title, b.severity,
       s.story_name, s.story_stage_cn
FROM bug_data b
LEFT JOIN zentao_story_detail s ON b.story_id = s.story_id
WHERE b.project_code = 'PROJECT_CODE'
  AND b.status != 'closed';

示例2：查询开发者效能

用户问：查看开发者 DEVELOPER_ACCOUNT 2024年1月的效能数据

助手答： 查询开发者 DEVELOPER_ACCOUNT 2024年1月的效能数据：

SELECT account, name, month, 
       story_count, original_story_points,
       actual_hours, bug_fix_rate
FROM developer_efficiency_stats
WHERE account = 'DEVELOPER_ACCOUNT'
  AND month >= '2024-01-01'
  AND month <= '2024-01-31';

同时查看该开发者该月的任务完成情况：

SELECT t.task_name, t.task_status, t.task_consumed,
       t.project_name, t.sprint_name
FROM zentao_task t
WHERE t.account = 'DEVELOPER_ACCOUNT'
  AND DATE_FORMAT(t.task_finish_time, '%Y-%m') = '2024-01';

示例3：获取表结构

用户问：获取 bug_data 表的完整结构

助手答： 调用 getTableInfo 工具后，返回结果包含：

表名：bug_data（缺陷数据信息表）

主要字段：

| 字段名 | 类型 | 说明 | |--------|------|------| | bug_id | bigint | 缺陷ID | | bug_title | text | 缺陷标题 | | severity | tinyint | 严重程度 | | priority | tinyint | 优先级 | | status | text | 状态 | | story_id | bigint | 关联需求ID | | task_id | bigint | 关联任务ID | | opened_by_name | text | 创建人 | | opened_date | datetime | 创建时间 | | assigned_to_name | text | 指派人 | | resolved_by_name | text | 解决人 |

示例4：查询迭代进度

用户问：查询迭代 SPRINT_ID 的需求和任务完成情况

助手答：

SELECT sprint_name, story_id, story_estimate, task_id,
       task_name, consumed, story_reviewed_date, story_closed_date
FROM story_task_detail_stats
WHERE sprint_id = 'SPRINT_ID';

示例5：查询团队周报数据

用户问：查看某团队的周报汇总

助手答：

SELECT wrd.account, wrd.name, wrd.week_date,
       wrd.story_points_completed, wrd.tasks_completed,
       wrd.bugs_fixed, wrd.hours_worked
FROM weekly_person_report_data wrd
WHERE wrd.dept = 'DEPT_CODE'
  AND wrd.week_date >= '2024-01-01';

9. 注意事项

1. 表名支持：getTableInfo 支持中英文表名混合查询，使用中文表名时系统会自动匹配对应的英文表

2. SQL 生成：助手生成的 SQL 语句仅供参考，实际使用前请验证语法和业务逻辑

3. 数据权限：实际数据访问权限取决于配置的数据库账号权限，本工具仅提供结构查询能力

4. 版本要求：Node.js >= 18

5. 编码格式：项目使用 UTF-8 编码，确保数据库和终端环境使用相同编码

10. 项目结构

pms-mcp/
├── src/
│   ├── index.ts           # 主入口
│   ├── tools/             # 工具定义
│   ├── prompts/           # 提示词定义
│   ├── resources/         # 资源定义
│   ├── utils/             # 工具函数
│   └── resourses/         # 静态资源
│       ├── ddl.md         # 数据库表文档
│       └── ddl.sql        # DDL SQL文件
├── package.json
├── tsconfig.json
└── README.md

11. 许可证

MIT License

作者：rhymedys ([email protected])