Better PingCode MCP

PingCode MCP server 与 CLI (pingcode)。完整覆盖 PingCode 开放 API——449 个按文档生成的专用 tools / CLI actions，覆盖全部 API 域，外加面向工作项与工作空间上下文的高阶封装 tools。

English version: README.md

安装 / 运行

无需安装，直接用 npx -y：

# 运行 CLI
npx -y @arthuratlas/better-pingcode --help

# 启动 MCP server
npx -y @arthuratlas/better-pingcode --mcp

也可以全局安装：

npm install -g @arthuratlas/better-pingcode
pingcode --help
pingcode --mcp
pingcode init

CLI 用法

认证

使用 pingcode init 一步完成认证并配置 MCP 客户端：

pingcode init --client-id ID --client-secret SECRET

查看状态：

pingcode auth status

工作空间上下文

交互式设置：

pingcode context init

非交互式设置：

pingcode context set-current-project PROJECT_ID_OR_NAME
pingcode context set-current-sprint SPRINT_ID_OR_NAME
pingcode context set-current-user USER_ID_OR_NAME
pingcode context list

工作项

# 列出我的待办任务
pingcode workitem list --assignee @me --state 进行中 --compact

# 按标识符查询
pingcode workitem get SCR-123 --compact

# 创建任务
pingcode workitem create --title "Fix login" --type task --project "Core" --sprint "Sprint 1" --dry-run

# 更新状态
pingcode workitem update SCR-123 --state 已完成 --dry-run

API 域（按文档生成）

官方文档中的每个 API 操作都有对应的 CLI 模块 action。域：pjm（项目、工作项、看板、迭代、发布、配置）、ship（产品、工单、需求）、testhub（测试库、用例、计划、执行）、wiki（空间、页面）、devops（仓库、提交、PR、构建、部署）、directory（成员、部门、团队、角色、日志）、common（评论、附件、工时、关联、评审）。

# 列出一个域的全部 action
pingcode pjm --help

# 查看某个 action 的参数
pingcode pjm workitem-tag-create --help

# 执行（使用文档规范路径，如 /v1/pjm/...）
pingcode pjm workitem-delete --workitem_id W123 --dry-run
pingcode wiki space-create --scope_type user --name 文档 --identifier docs
pingcode common comment-list --principal_type workitem --principal_id W123
pingcode testhub testcase-list --fetch-all
pingcode common attachment-upload --principal_type workitem --principal_id W123 --file ./报告.pdf

参数 flag 与文档 API 参数一一对应。--dry-run 预览请求；--compact 精简输出；--fetch-all 自动翻页拉全列表。

初始化

一条命令完成认证并配置支持的 AI 客户端：

# 1. 输入 client id/secret，2. 选择客户端，3. 确认
pingcode init

# 非交互式：认证并配置所有客户端
pingcode init --all --yes --client-id ID --client-secret SECRET

# 配置指定客户端
pingcode init --tool codex --tool opencode

# 仅预览，不写入文件
pingcode init --all --dry-run

交互式选择快捷键：

• ↑ / ↓ 移动光标
• Space 勾选 / 取消勾选
• Backspace 删除搜索过滤字符
• Enter 确认选择
• 二次确认后才会真正写入文件

该命令会更新每个工具的全局（用户级）MCP 配置：

• Codex: ~/.codex/config.toml
• OpenCode: ~/.config/opencode/opencode.json
• Oh My Pi: ~/.omp/agent/mcp.json

其他 MCP server 的现有配置会被保留；pingcode 条目会增量地添加或替换。

MCP 用法

添加到你的 MCP 客户端配置（例如 Claude Desktop、Cursor、Cline）：

{
  "mcpServers": {
    "pingcode": {
      "command": "npx",
      "args": ["-y", "@arthuratlas/better-pingcode@latest", "--mcp"],
      "env": {
        "PINGCODE_CLIENT_ID": "your-client-id",
        "PINGCODE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

MCP server 从 MCP host 提供的环境中读取 PINGCODE_CLIENT_ID 和 PINGCODE_CLIENT_SECRET。你也可以在 tool 参数中传入 base_url、client_id、client_secret。

可用 Tools

高阶封装（工作空间上下文、标识符解析、缓存）：

• pingcode_auth_status、pingcode_auth_get_authorization_url、pingcode_auth_exchange_code
• pingcode_list_projects、pingcode_list_sprints、pingcode_list_users
• pingcode_context_set、pingcode_context_get
• pingcode_workitem_list、pingcode_workitem_get、pingcode_workitem_create、pingcode_workitem_update

按文档生成（449 个专用 tools，每个对应一个文档 API 操作，例如）：

• pingcode_pjm_workitem_delete / pingcode_pjm_workitem_batch_update / pingcode_pjm_workitem_search
• pingcode_pjm_workitem_tag_create — 给工作项加标签
• pingcode_ship_ticket_search — queryDSL 工单搜索
• pingcode_testhub_testcase_create、pingcode_testhub_testrun_status_list
• pingcode_wiki_page_create、pingcode_wiki_page_content_replace
• pingcode_devops_product_repo_pr_list、pingcode_devops_deploy_create
• pingcode_common_comment_list、pingcode_common_attachment_upload、pingcode_common_workload_create
• pingcode_directory_user_create、pingcode_security_audit_log_list

每个 tool 的 schema 与文档参数一一对应（含枚举值），支持 dry_run，默认返回原始 API 响应（可选 compact）。列表类 tool 支持 fetch_all。

域过滤（可选）

tool 数量较多时，客户端可以只暴露部分域。设置 PINGCODE_MCP_DOMAINS（逗号分隔）：

"env": { "PINGCODE_MCP_DOMAINS": "pjm,wiki,common" }

MCP 认证流程

1. 让 agent 调用 pingcode_auth_get_authorization_url。
2. 在浏览器中打开返回的 URL 并授权。
3. 用授权码调用 pingcode_auth_exchange_code。
4. 后续 tool 调用会使用缓存的用户 token。

如果你只需要企业级 token 访问，只需确保设置了 PINGCODE_CLIENT_ID 和 PINGCODE_CLIENT_SECRET；server 会自动使用 client_credentials。

说明

• 需要 Node.js >=18。
• 不需要安装 skill/markdown；agent 直接通过 MCP 连接。
• Token 缓存：~/.cache/bpingcode/token.json
• 工作空间缓存：.bpingcode/cache.json
• 生成接口清单可用 node scripts/generate-endpoints.js 基于在线文档重建（src/endpoints.js 为生成文件，请勿手改）。
• 部分操作需要 token 具备相应权限（HTTP 403 100027）；请为 PingCode 应用开通对应 scope，或改用用户 token。