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

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 .

# 方式 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

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

# 上传代码到服务器
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