# CM E2E MCP 使用指南

本頁可直接提供給 AI agent 閱讀。原始 Markdown：`https://e2e.cc-sustain.com/mcp-guide.md`。說明頁：`https://e2e.cc-sustain.com/mcp-guide`。

## 使用自己的登入帳號安裝 Agent 並執行測試

`cm-e2e` MCP 支援瀏覽器核准登入，不需要把密碼或瀏覽器 Session 貼進對話。MCP client 必須支援 MCP URL-mode Elicitation；使用者登入與核准後，Agent enrollment 和執行會套用該帳號權限。建立 Agent 任何已登入會員都可使用；建立 run 需要 `operator` 或 `admin` 角色。

1. 在 MCP client 呼叫 `cm-e2e.login`。client 會開啟 CM E2E 授權頁。
2. 使用者在授權頁登入 Console，按「授權這個 MCP 工作階段」。授權只套用到目前 MCP client 工作階段；密碼不會送給 MCP tool 或模型。
3. 呼叫 `cm-e2e.enroll_agent`，提供顯示名稱及平台（`windows`、`wsl2`、`linux` 或 `macos`）。工具會以目前登入者建立 Agent，並回傳一次性 Token 和安裝指令。不要把 Token 貼到公開位置。
4. 確認指令要在實際跑測試的主機執行。若 agent 可操作該主機終端機，執行回傳的完整指令；否則請使用者在目標主機執行。Windows 會跳 UAC，WSL／Linux 可能需要 sudo，需由使用者核准。
5. 呼叫 `cm-e2e.check_agent` 或 `list_agents` 確認 Agent 已 online。
6. 呼叫 `cm-e2e.list_environments` 和 `list_test_targets` 選擇帳號可用的環境與 targets，再呼叫 `cm-e2e.start_e2e_run`，並將 `agent` 設為剛建立的 Agent code、id 或顯示名稱。
7. 用 `cm-e2e.wait_e2e_run` 等待，再用 `get_e2e_run_result` 查看結果。完成後可呼叫 `cm-e2e.logout` 清除這個 MCP 工作階段的授權；這不會登出瀏覽器 Console。

可以直接交給 AI agent 的指令：

> 請閱讀 https://e2e.cc-sustain.com/mcp-guide.md，使用 `cm-e2e.login` 開啟安全登入流程，讓我在瀏覽器登入並核准。接著用我的帳號建立本地 Agent，依安裝指令在我指定的電腦安裝註冊，確認 Agent online，並指定這台 Agent 執行我指定的環境和測試。不要索取或輸出我的密碼或 Agent Token；若需要終端機存取、UAC、sudo 或其他管理員權限，先讓我確認。

如果 MCP client 不支援 URL-mode Elicitation，請使用下方 Console 登入頁的「執行 Agent」流程建立和安裝；登入後可在「執行測試」選擇該 Agent 執行。安裝指令必須在目標主機執行，讀取本文件本身不會遠端安裝軟體。

`cm-e2e.login` 授權完成後，這個 MCP session 的 API 呼叫都使用登入者的 Console Session 與權限。未登入的舊用法仍使用 `MCP_API_USERNAME`／`MCP_API_PASSWORD` 設定的共用服務帳號；入口仍須限制為可信任網路。`cm-e2e-generator` 不使用 Controller 會員 Session。

## 連線資訊

| 服務 | Streamable HTTP URL | 用途 |
|---|---|---|
| `cm-e2e` | `https://e2e.cc-sustain.com/mcp` | 執行測試、查詢結果、診斷與安裝執行 Agent |
| `cm-e2e-generator` | `https://e2e.cc-sustain.com/mcp-generator` | 預覽、產生與驗證 E2E 測試 |

這兩個 URL 是 MCP 傳輸端點，不能當一般網頁打開。請在支援 Streamable HTTP 的 MCP client 中註冊，或直接把本頁交給 agent，請它依自己的 client 設定 MCP。專案根目錄的 `.mcp.json` 已有以下設定：

```json
{
  "mcpServers": {
    "cm-e2e": {
      "type": "http",
      "url": "https://e2e.cc-sustain.com/mcp"
    },
    "cm-e2e-generator": {
      "type": "http",
      "url": "https://e2e.cc-sustain.com/mcp-generator"
    }
  }
}
```

本機開發時，改用 `http://localhost:23000/mcp` 與 `http://localhost:23000/mcp-generator`。MCP endpoint 的傳輸層不要求網頁登入；可以呼叫 `cm-e2e.login` 以 Console 帳號核准目前 session，或使用設定的共用服務帳號。入口仍應限制在可信任的辦公室、VPN 或內網 IP。這份公開文件不含帳密或 Token。

## 常用流程

1. `cm-e2e.health_check`：確認 API 與執行服務可用。
2. `cm-e2e.login`：讓使用者以自己的 Console 帳號登入並授權此 session（需要支援 URL-mode Elicitation 的 MCP client）。
3. `cm-e2e.list_environments`：列出目前登入者可用的環境；同名時可用 `environment_id` 指定。
4. `cm-e2e.list_test_targets`：列出可執行測試，必要時用 `get_test_target_detail` 看細節。
5. `cm-e2e.start_e2e_run`：傳入環境名稱 `env`、測試 `targets`，以及選填的 Agent code、id 或顯示名稱 `agent`。例如 `{"env":"develop","targets":["tests/e2e/test_login.py::test_smoke"],"agent":"agent-workstation"}`；實際 nodeid 與 Agent 以工具列出的為準。
6. `cm-e2e.wait_e2e_run`：用回傳的 `run_id` 等待完成。
7. `cm-e2e.get_e2e_run_result`：取得結果；失敗時再用 `get_failure_digest`、`get_failure_artifact_hints` 或 `read_artifact_text` 看證據。

產生測試時，先呼叫 `cm-e2e-generator.get_e2e_project_rules` 與 `get_supported_workflow_schema`，用 `preview_e2e_test` 檢查，再用 `create_e2e_test` 建立。新測試的 nodeid 可交給 `cm-e2e.start_e2e_run` 執行。建立操作會寫入專案，請依使用者要求執行。

## 疑難排解

- 連不到端點：確認目前網路位於允許的辦公室／VPN／內網 IP 範圍，並檢查 `/mcp/health` 與 `/mcp-generator/health`。
- `login` 無法開啟授權頁：確認 MCP client 支援 URL-mode Elicitation，並可開啟 Controller 網站。
- `login` 完成後仍回報登入過期：再呼叫一次 `login`；Console Session 到期時需要重新核准。
- API 權限不足：確認目前登入者角色；建立 run 需要 `operator` 或 `admin`。
- 找不到環境：先呼叫 `list_environments`；使用者只能看到自己擁有或共用的環境。
- 需要完整產生測試規則：呼叫 generator 的 `get_e2e_project_rules`，不要只依賴本頁摘要。