内容
# MCP 敏捷代理
Python 版 MCP（模型上下文協議）伺服器，將 Trello 操作暴露為 AI 代理（如 **Claude Code**、**OpenCode**、Claude Desktop、Cursor 等）的工具。
## ✨ 特色
- **🧠 智能模糊匹配** — AI 無需知道精確的 ID 或名稱。"移動到當前衝刺" 可以使用近似值。
- **🛠️ 專注於軟體工程** — 為工程流程設計的工具：按名稱在列表中建立卡片、移動卡片、在卡片上留言。
- **Markdown-First** — 清潔的回應，無雜訊。
## 工具
| 工具 | 描述 |
| -------------- | ---------------------------------------- |
| `create_card` | 在列表中建立卡片（按名稱） |
| `move_card` | 在列表之間移動卡片 |
| `add_comment` | 在卡片上留言 |
| `list_cards` | 按列表分組列出所有卡片 |
| `board_status` | 摘要：按列表計算卡片數量 |
## 安裝
### 前置條件：uv
安裝前唯一需要的軟體。沒有它，選項 A 的 `uvx` 命令將不存在。
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
（Windows：`powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`。）無需單獨安裝 Python/pip — `uv` 可以自行處理。
### 選項 A — uvx（推薦，不需要克隆任何內容）
運行互動式精靈 — 它會解釋如何獲取 Trello 的 API 金鑰/令牌，並將所有內容保存在 `~/.config/mcp-agile-agent/.env` 中：
```bash
uvx --from git+https://github.com/vick1st/mcp-agile-agent mcp-agile-agent setup
```
完成 — 無需其他手動安裝步驟。將您的 MCP 客戶端指向下面的命令（請參閱每個客戶端的章節）。
### 選項 B — 本地克隆（貢獻程式碼）
```bash
git clone https://github.com/vick1st/mcp-agile-agent
cd mcp-agile-agent
python3 -m venv .venv
source .venv/bin/activate # Linux/Mac
pip install -e .
mcp-agile-agent setup # 與選項 A 相同的精靈
```
### 驗證
```bash
mcp-agile-agent
```
如果登錄顯示 `TrelloClient initialized` 和 `MCP Trello Server starting...`，則表示正常（`Ctrl+C` 退出）。
所有客戶端都使用 **相同的命令**，無需絕對路徑，也無需克隆儲存庫：
```
command: uvx
args: ["--from", "git+https://github.com/vick1st/mcp-agile-agent", "mcp-agile-agent"]
```
憑證已儲存在 `~/.config/mcp-agile-agent/.env` 中（由 `mcp-agile-agent setup` 完成），因此無需在每個客戶端重複金鑰 — 除非您希望按專案隔離（請參閱下面的環境變數替代方案）。
## 在 OpenCode 中設定
`opencode.json`（專案根目錄）或 `~/.config/opencode/mcp.json`（全域）：
```json
{
"mcpServers": {
"mcp-agile-agent": {
"command": "uvx",
"args": ["--from", "git+https://github.com/vick1st/mcp-agile-agent", "mcp-agile-agent"]
}
}
}
```
或透過 CLI：
```bash
opencode mcp add mcp-agile-agent -- uvx --from git+https://github.com/vick1st/mcp-agile-agent mcp-agile-agent
```
重新啟動 OpenCode 工作階段 — 工具將自動出現。
## 在 Claude Code 中設定
`.mcp.json`（專案）或透過 CLI：
```json
{
"mcpServers": {
"mcp-agile-agent": {
"command": "uvx",
"args": ["--from", "git+https://github.com/vick1st/mcp-agile-agent", "mcp-agile-agent"]
}
}
}
```
```bash
claude mcp add mcp-agile-agent -- uvx --from git+https://github.com/vick1st/mcp-agile-agent mcp-agile-agent
```
## 在 Claude Desktop 中設定
最後一種情況 — 需要管理原生應用程式。編輯 `~/.config/claude-desktop/claude_desktop_config.json`（Linux）或等效檔案，並使用上述相同的 `command`/`args` 區塊。
## 替代方案：直接在客戶端設定憑證（無需運行 `setup`）
如果您的 MCP 客戶端支援每個伺服器的 `env` 欄位，則可以跳過精靈並直接在設定中傳遞變數（適用於 CI 或多個看板）：
```json
{
"mcpServers": {
"mcp-agile-agent": {
"command": "uvx",
"args": ["--from", "git+https://github.com/vick1st/mcp-agile-agent", "mcp-agile-agent"],
"env": {
"TRELLO_API_KEY": "...",
"TRELLO_TOKEN": "...",
"TRELLO_BOARD_ID": "..."
}
}
}
}
```
**如何獲取憑證：**
1. 存取 https://trello.com/power-ups/admin
2. 建立/開啟您的 Power-Up → 複製 **API 金鑰**
3. 在瀏覽器中開啟：`https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&key=SUA_API_KEY` → 授權 → 複製令牌
4. `TRELLO_BOARD_ID`：從看板 URL 中獲取，`https://trello.com/b/{BOARD_ID}/看板名稱`
## 故障排除
**`uvx: command not found`** — 安裝 uv：`curl -LsSf https://astral.sh/uv/install.sh | sh`。
**`invalid key` 调用任意工具** — 金鑰重新生成或從舊門戶複製。請在 https://trello.com/power-ups/admin 確認。
**`invalid app token` / `token not found`** — 令牌複製錯誤。請勿將 "Segredo"（API secret）與 "Token"（透過授權 URL 生成）混淆。
**`LIST_NOT_FOUND` / `CARD_NOT_FOUND`** — 模糊匹配嘗試近似值，截止值為 0.75。如果失敗，請使用 `list_cards` 查看精確名稱。
**Claude/OpenCode 無法看到工具** — 編輯設定後請完全重新啟動工作階段。
## 結構
```
src/mcp_agile_agent/
├── cli.py # 控制台腳本的進入點（伺服器或 `setup`）
├── setup_wizard.py # 互動式憑證精靈
├── server.py # MCP 協議，工具註冊
├── trello/client.py # HTTP + 認證 + 與 Trello 的模糊匹配
├── tools/ # 非同步處理程序，每個 MCP 工具一個
└── config/settings.py # 載入並驗證憑證（環境變數 / .env）
```
