# PingCode MCP

讓 VS Code、Cursor、Qoder、ZCode 等 Coding Agent 安全連接 PingCode：讀取 Wiki、工作項目、Test Case 與測試庫上下文，並以 Preview → Approval → Commit 流程控管寫入與同步。適合 UAT 規劃、需求追蹤和測試資料維護，不提供任意 REST API 代理。

## 支援範圍

支援 Wiki、Task／工作項目、Test Case、測試庫、Project、Ship、Relation、使用者與成員角色的讀取，以及受控的 Task／Test Case、Project、Test Library、Ship、Relation、成員角色與需求模組寫入流程。寫入固定要求獨立權限、Preview、有效 Approval、幂等與稽核。

不支援 Wiki 寫入、Task／Project／Test Library／Idea 刪除或任意 PingCode REST API 代理；也不會主動刪除關係另一端資源。

## 快速安裝（推薦）

需要 Node.js 20 以上，以及在 PingCode 建立的 **enterprise 應用程式憑據**。npm 套件是 scoped package `@xurenxiang1219/pingcode-mcp`；請保留 scope，避免安裝到另一個同名套件。

### 1. 設定 PingCode 憑據

有兩種方式，選一種即可。

**推薦：使用私有環境檔**

將 `.env.stdio.local.example` 複製到只供本機使用的位置（例如 `/absolute/private/path/pingcode-mcp.env`），填入：

```env
PINGCODE_AUTH_MODE=enterprise
PINGCODE_CLIENT_ID=your-pingcode-client-id
PINGCODE_CLIENT_SECRET=your-pingcode-client-secret
```

**懶人模式：直接放進 Client 的 `env`**

不想另外建立環境檔時，可以直接在 MCP 設定的 `env` 中加入：

```json
"env": {
  "PINGCODE_AUTH_MODE": "enterprise",
  "PINGCODE_CLIENT_ID": "your-pingcode-client-id",
  "PINGCODE_CLIENT_SECRET": "your-pingcode-client-secret"
}
```

這種方式最省事，但 Secret 會以明文保存在 Client 設定檔，只建議用於個人本機；不要提交、同步或分享該設定。stdio 模式會在程序記憶體中產生短效 Approval Secret，不需要手動產生或貼上 Approval Token。

### 2. 連接 MCP Client

#### VS Code

在終端機執行以下命令，將 Server 加入 VS Code 的 MCP 設定。請把環境檔路徑換成你的絕對路徑：

```bash
code --add-mcp '{"name":"pingcode","command":"npx","args":["-y","@xurenxiang1219/pingcode-mcp","--stdio","--env-file","/absolute/private/path/pingcode-mcp.env"]}'
```

不想建立環境檔時，也可以直接在命令中傳入憑據：

```bash
code --add-mcp '{"name":"pingcode","command":"npx","args":["-y","@xurenxiang1219/pingcode-mcp","--stdio"],"env":{"PINGCODE_AUTH_MODE":"enterprise","PINGCODE_CLIENT_ID":"your-pingcode-client-id","PINGCODE_CLIENT_SECRET":"your-pingcode-client-secret"}}'
```

直接傳入的 Secret 會保存在 VS Code MCP 設定中，只建議用於個人本機；不要提交、同步或分享該設定。

也可以在工作區 `.vscode/mcp.json` 使用相同的 stdio Server；本 repository 已提供可直接使用的範例。

#### Cursor、Qoder、ZCode

這些 Client 使用 `mcpServers` 設定。將下列區塊放入各自的 MCP 設定檔（或在設定介面新增同等欄位），並替換環境檔的絕對路徑：

```json
{
  "mcpServers": {
    "pingcode": {
      "command": "npx",
      "args": [
        "-y",
        "@xurenxiang1219/pingcode-mcp",
        "--stdio",
        "--env-file",
        "/absolute/private/path/pingcode-mcp.env"
      ]
    }
  }
}
```

不想建立環境檔時，使用下面的完整設定，直接填入 Client ID 與 Client Secret：

```json
{
  "mcpServers": {
    "pingcode": {
      "command": "npx",
      "args": ["-y", "@xurenxiang1219/pingcode-mcp", "--stdio"],
      "env": {
        "PINGCODE_AUTH_MODE": "enterprise",
        "PINGCODE_CLIENT_ID": "your-pingcode-client-id",
        "PINGCODE_CLIENT_SECRET": "your-pingcode-client-secret"
      }
    }
  }
}
```

如 Client 不支援 `--env-file` 參數，也可改用 `env` 傳入 `PINGCODE_ENV_FILE`，讓 Server 從私有環境檔讀取：

```json
{
  "mcpServers": {
    "pingcode": {
      "command": "npx",
      "args": ["-y", "@xurenxiang1219/pingcode-mcp", "--stdio"],
      "env": {
        "PINGCODE_ENV_FILE": "/absolute/private/path/pingcode-mcp.env"
      }
    }
  }
}
```

### 3. 啟動與首次寫入

啟動後先使用 Preview Tool 檢視變更，再由 Agent 呼叫對應的 Commit Tool。Server 會驗證 Preview hash、Approval Context、會話綁定、request hash、幂等鍵並記錄 `auditId`；是否顯示額外的 MCP Client 確認由 `PINGCODE_WRITE_CONFIRMATION` 控制（預設 `required`）。

stdio 本機模式不要求使用者手動生成 Approval Token；是否顯示額外確認由 `PINGCODE_WRITE_CONFIRMATION` 決定。

## 認證與環境變數

最小 stdio 設定只有以下三項：

| 變數 | 說明 |
| --- | --- |
| `PINGCODE_AUTH_MODE` | stdio 使用 `enterprise` |
| `PINGCODE_CLIENT_ID` | PingCode 應用程式 Client ID |
| `PINGCODE_CLIENT_SECRET` | PingCode 應用程式 Client Secret；建議放在私有環境檔或 Secret Manager，個人本機可直接設在 Client `env` |

程式也支援 `--env-file /path/to/file`、`--env-file=/path/to/file`，以及 `PINGCODE_ENV_FILE`。未指定時才會嘗試目前 package 目錄下的 `.env`。

## 進階：從原始碼執行

適合需要修改程式、執行測試或使用工作區 `.vscode/mcp.json` 的情境：

```bash
git clone https://github.com/xurenxiang1219/pingcode-mcp.git
cd pingcode-mcp
npm ci
cp .env.stdio.local.example .env
# 編輯 .env，填入 PINGCODE_CLIENT_ID 與 PINGCODE_CLIENT_SECRET
npm run build
```

完成後可在 VS Code 開啟此資料夾。`.vscode/mcp.json` 會以 `${workspaceFolder}/dist/index.js --stdio` 啟動 Server，並讀取同資料夾的 `.env`。

也可以直接啟動 npm 套件：

```bash
npx -y @xurenxiang1219/pingcode-mcp --stdio --env-file /absolute/private/path/pingcode-mcp.env
```

首次發佈由 package 維護者執行 `npm login` 後再執行 `npm publish --access public`；本 repository 不會在開發或測試時自動發佈。

## 工具

### 唯讀與上下文

- `pingcode_uat_runtime_info`
- `pingcode_wiki_list_spaces`
- `pingcode_wiki_list_pages`
- `pingcode_wiki_get_requirement_context`
- `pingcode_task_list`
- `pingcode_task_get`
- `pingcode_test_case_list`
- `pingcode_test_case_get`
- `pingcode_project_list`
- `pingcode_work_item_metadata_get`
- `pingcode_test_library_list`
- `pingcode_test_library_get`
- `pingcode_test_case_metadata_get`
- `pingcode_user_list`
- `pingcode_role_list`
- `pingcode_user_search`
- `pingcode_project_context_get`
- `pingcode_project_context_save`
- `pingcode_ship_product_list`
- `pingcode_ship_product_get`
- `pingcode_ship_idea_list`
- `pingcode_ship_product_idea_list`
- `pingcode_ship_idea_get`
- `pingcode_ship_product_suite_list`
- `pingcode_ship_product_suite_get`
- `pingcode_relation_list`
- `pingcode_relation_get`
- `pingcode_member_role_get`

### Preview、Commit 與受控寫入

- `pingcode_test_case_delete_preview` / `pingcode_test_case_delete_commit`
- `pingcode_test_case_bulk_create_preview` / `pingcode_test_case_bulk_create_commit`
- `pingcode_ship_product_sync_preview` / `pingcode_ship_product_sync_commit`
- `pingcode_ship_idea_sync_preview` / `pingcode_ship_idea_sync_commit`
- `pingcode_task_sync_preview` / `pingcode_task_sync_commit`
- `pingcode_test_case_sync_preview` / `pingcode_test_case_sync_commit`
- `pingcode_ship_product_suite_create_preview` / `pingcode_ship_product_suite_create_commit`
- `pingcode_ship_product_suite_remove_preview` / `pingcode_ship_product_suite_remove_commit`
- `pingcode_relation_sync_preview` / `pingcode_relation_sync_commit`
- `pingcode_member_role_update_preview` / `pingcode_member_role_update_commit`
- `pingcode_project_create_preview` / `pingcode_project_create_commit`
- `pingcode_test_library_create_preview` / `pingcode_test_library_create_commit`

## 安全機制與限制

- 唯讀與 Preview Tool 不修改 PingCode；所有 Commit Tool 都需要有效 Approval、不可變 request hash、Preview 證據、Approval Context、會話綁定和 idempotency key。
- PingCode 寫入請求不自動重試；結果不確定時，先用對應唯讀 Tool 回讀確認。
- Test Case 刪除必須先 Preview，再由獨立 Commit Tool 執行；完成後 MCP 會回讀確認用例不存在，並保留 Approval、hash、幂等鍵與稽核資料。
- 資源名稱、ID、成員與其他候選都必須來自 PingCode 目錄或使用者明確確認，不得猜測，也不得用空字串、`@` 或 `*` 作為通配符。
- 需要建立 `private` 專案或重用既有上下文時，Agent 必須先取得使用者確認；沒有確認的唯一候選也不能直接套用。
- Client ID、Client Secret、Token、Cookie 與客戶資料只應放在本機私有環境或 Secret Manager，不要提交、同步或分享。

## 本機開發驗證

```bash
npm run typecheck
npm test
npm run build
```