🔍 PingCode 项目健康度监控

让 PM 在 Claude Code 或 IM 群里一眼看清项目状态 —— 聚合、风控、自动告警。

这是什么？

对接 PingCode Open API，提供两个入口：

入口	场景	实现
MCP Server	PM 在 Claude Code 里直接对话查询	fastmcp stdio 模式，5 个工具
IM 机器人	PM 在企微/钉钉群里 @bot 查询	FastAPI + 钉钉 Stream WebSocket

同一套代码、同一份配置，两种输出格式（Markdown 表格 vs 群聊简短消息）。

┌──────────────┐     ┌──────────────────────────┐     ┌──────────────┐
│  Claude Code │────▶│  MCP Server (stdio)      │────▶│              │
│  (PM 本地)   │     │  src/server.py           │     │              │
└──────────────┘     └──────────────────────────┘     │   PingCode   │
                                                       │   Open API   │
┌──────────────┐     ┌──────────────────────────┐     │              │
│  钉钉/企微群 │────▶│  Bot (HTTP + Stream)     │────▶│              │
│  (群里 @bot) │     │  src/bot.py              │     │              │
└──────────────┘     └──────────────────────────┘     └──────────────┘
                            │
                            ▼
                     ┌──────────────┐
                     │  Web 管理后台 │
                     │  :8080/admin │
                     └──────────────┘

功能一览

5 个 MCP 工具

工具	用途	例
list_pingcode_projects	列出所有项目	"看看有哪些项目"
get_project_health	项目健康度仪表盘	"XX项目 状态怎么样"
get_sprint_status	Sprint / 迭代进度	"XX项目 冲刺进度"
get_risk_items	风险项明细	"哪些逾期了"
query_work_items	灵活查询	"张三有哪些未完成的 task"

群机器人能力

• 在企微/钉钉群里 @机器人 XX项目 健康度 → 自动回复
• 支持模糊项目名匹配（"储能BMS" → 自动找到对应项目）
• 可选 DeepSeek AI 兜底（规则匹配不上时用自然语言理解）
• 风险自动推送（red/yellow → 群里弹告警）

Web 管理后台

浏览器打开 http://localhost:8080/admin：

• PingCode 认证配置 + 一键测试连接
• 健康度阈值、状态标签自定义
• 通知推送、Bot、隧道、AI 所有配置
• 保存即时生效，无需重启

快速开始

1. 安装

git clone https://github.com/YOUR_USER/pingcode-health-mcp.git
cd pingcode-health-mcp

# 推荐：使用虚拟环境
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate

pip install -e .

2. 配置

三种方式任选一种：

# 方式 A: CLI 配置向导（推荐新手）
python -m src.setup

# 方式 B: Web 管理后台（推荐有桌面环境）
python -m src.bot
# → 浏览器会自动打开 http://localhost:8080/admin
# → 在页面上填写 PingCode 凭证，点击"保存配置"

# 方式 C: 手动编辑
cp config.example.yaml config.yaml
# 编辑 config.yaml，填写 pingcode.client_id 和 client_secret

3. 连接 Claude Code

编辑项目根目录的 .claude/mcp.json（或 Claude Code 全局设置）：

{
  "mcpServers": {
    "pingcode-health": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/pingcode-health-mcp",
      "description": "PingCode 项目健康度监控"
    }
  }
}

重启 Claude Code，就可以直接问 "帮我看看 XX 项目的健康度"。

4. 部署到服务器（Bot 用）

# 上传代码到服务器
scp -r . user@your-server:/opt/pingcode-health/

# SSH 到服务器，运行部署脚本
ssh user@your-server
cd /opt/pingcode-health
sudo bash deploy/setup.sh

# 填写配置后启动
sudo systemctl start pingcode-bot

项目结构

pingcode-health-mcp/
├── README.md
├── pyproject.toml              # 依赖 + 入口点
├── config.example.yaml         # 配置模板
├── .env.example                # 环境变量模板
├── mcp.md                      # 需求文档
├── setup.py                    # CLI 配置向导入口
│
├── src/
│   ├── server.py               # MCP Server — 5 个 tool
│   ├── pingcode_client.py      # PingCode API — OAuth2 认证 + 分页 + 缓存
│   ├── health.py               # 健康度聚合引擎 — 统计 + 风险评级
│   ├── notifier.py             # Webhook 推送 — 企微/钉钉/飞书
│   ├── bot.py                  # Bot HTTP 服务 + Web 管理后台
│   ├── dingtalk_stream_bot.py  # 钉钉 Stream 模式机器人
│   ├── dingtalk_crypto.py      # 钉钉加解密
│   ├── config.py               # 配置管理 — YAML + 环境变量
│   ├── models.py               # 数据模型
│   ├── tunnel.py               # 内网穿透 — cloudflared / ngrok
│   └── setup.py                # CLI 配置向导
│
├── tests/
│   └── test_health.py
│
└── deploy/
    └── setup.sh                # Ubuntu 部署脚本 + systemd

配置参考

配置项	环境变量	config.yaml	必填
Client ID	PINGCODE_CLIENT_ID	pingcode.client_id	✅
Client Secret	PINGCODE_CLIENT_SECRET	pingcode.client_secret	✅
Base URL	PINGCODE_BASE_URL	pingcode.base_url	❌
Webhook URL	NOTIFICATION_WEBHOOK_URL	notification.webhook_url	❌
通知类型	NOTIFICATION_TYPE	notification.type	❌
钉钉 AppKey	DINGTALK_APP_KEY	bot.dingtalk_app_key	❌
钉钉 AppSecret	DINGTALK_APP_SECRET	bot.dingtalk_app_secret	❌
AI API Key	DEEPSEEK_API_KEY	ai.api_key	❌
监听端口	PORT	bot.port	❌

常见问题

Q: PingCode Client ID / Secret 在哪找？ 登录 PingCode 开放平台 → 应用管理 → 创建"自研应用" → 选择 OAuth2 client_credentials 模式 → 复制凭证。

Q: 钉钉回调 URL 验证失败？ 确保事件订阅和消息接收都切换为 Stream 模式（不要混用 HTTP 模式），且"开发管理" Tab 中没有残留的 HTTP 地址配置。

Q: MCP Server 连不上？ 检查 config.yaml（或环境变量）中 client_id 和 client_secret 是否已填写。运行 python -m src.setup 可诊断。

Q: 内网 Bot 怎么让企微/钉钉回调到？ 在 config.yaml 中设置 tunnel.enabled: true，Bot 启动时自动启动 cloudflared / ngrok 隧道。

Q: 需要监控多个项目的健康度？ list_pingcode_projects 列出所有项目 → 用 project_id 逐个查，或让 AI 批量调用。

License

MIT