# pythia-mcp

讓任何支援 MCP 的 agent（Claude Code、Cursor、自製 agent…）透過 Discord 查詢 wiki-query bot 知識庫。

Discord 是唯一傳輸層 — 不開放任何自架對外端點，也不修改現有的問答 bot。pythia-mcp 以自己的 Discord bot 身分（courier）在指定頻道開 thread 發問，輪詢收集問答 bot（oracle）的回答後組合回傳。

```
Consumer agent ──MCP(stdio)── pythia-mcp ──Discord REST── oracle bot（不修改）
```

詳細需求見 [REQUIREMENTS.md](REQUIREMENTS.md)。

## MCP 工具

| 工具 | 說明 |
|------|------|
| `wiki_ask(question, thread_id?)` | 在主頻道 tag oracle bot 提問，由它開討論串回答（單次約 10–60 秒）；回答結尾附 thread_id，帶回 thread_id 即可在同一討論串追問（同 session 上下文） |
| `wiki_status()` | 唯讀健檢：連線、guild/頻道可達、oracle 成員、頻道權限 |
| `wiki_threads()` | 列出當前問答討論串（進行中 + 最近封存） |
| `wiki_read_thread(thread_id)` | 讀取指定討論串完整問答（含起始問題），標註 courier / oracle / other 角色 |

前提：oracle bot 的互動模式必須是「在主頻道被 mention 後，自行從該訊息開 thread 回答」。

## 安裝

需求：Node.js 18+。

```bash
git clone https://github.com/HsYihung/pythia-mcp.git
cd pythia-mcp
npm install
npm run build
```

## Discord 端準備（一次性）

1. 在 [Discord Developer Portal](https://discord.com/developers/applications) 建立一個 application 與 bot，作為 courier 身分，取得 bot token。
2. 在 Bot 設定頁開啟 **Message Content Intent**（否則讀不到回答內容）。
3. 邀請 bot 進目標伺服器，並在發問頻道給它四項權限（不需要任何管理權限；thread 由 oracle bot 開，不需要 Create Public Threads）：
   - View Channel
   - Send Messages
   - Read Message History
   - Send Messages in Threads
4. 記下三個 ID（Discord 開發者模式右鍵複製）：伺服器 guild ID、發問頻道 ID、問答 bot 的 user ID。

## 接入 consumer 專案

1. 把 courier bot token 放進系統環境變數：

   ```bash
   export PYTHIA_COURIER_TOKEN="你的-bot-token"
   ```

2. 複製 [.mcp.json.example](.mcp.json.example) 到 consumer 專案根目錄，改名為 `.mcp.json`，填入實際值：

   ```json
   {
     "mcpServers": {
       "pythia": {
         "command": "node",
         "args": ["/absolute/path/to/pythia-mcp/dist/index.js"],
         "env": {
           "PYTHIA_COURIER_TOKEN": "${PYTHIA_COURIER_TOKEN}",
           "PYTHIA_GUILD_ID": "在哪個伺服器發問",
           "PYTHIA_ORACLE_CHANNEL_ID": "發問頻道 ID",
           "PYTHIA_ORACLE_BOT_ID": "問答 bot 的 user ID"
         }
       }
     }
   }
   ```

   token 一律用 `${PYTHIA_COURIER_TOKEN}` 引用環境變數，不要明文寫進 `.mcp.json`（`${VAR}` 展開是 Claude Code 的行為；其他 MCP client 若不支援，可改由啟動環境直接繼承該變數）。

3. 重啟 MCP client 後先呼叫 `wiki_status` 確認五項檢查全綠，再用 `wiki_ask` 提問。

### 選填參數

| 環境變數 | 預設 | 說明 |
|----------|------|------|
| `PYTHIA_SILENCE_TIMEOUT_SECONDS` | 10 | 收到第一則回覆後，靜默超過此秒數視為回答結束 |
| `PYTHIA_OVERALL_TIMEOUT_SECONDS` | 180 | 單一問題總逾時（含 bot 思考時間） |
| `PYTHIA_POLL_INTERVAL_SECONDS` | 2 | REST 輪詢間隔 |

啟動時會驗證所有設定與權限，任何缺漏都會直接報出可行動的錯誤訊息（缺哪個變數、缺什麼權限、哪個 ID 錯）。

## 開發

```bash
npm test          # vitest,46 個測試,全部離線(fake client + 虛擬時鐘)
npm run build     # tsc → dist/
npm run dev       # tsx 直接跑 src/index.ts
```

## 已知限制（設計取捨）

- 單次問答延遲約 10–60 秒（oracle agent 推理時間），consumer 端 MCP 工具逾時需設寬。
- 靜默判定可能在 oracle 分段極慢時提早收單，可用 `PYTHIA_SILENCE_TIMEOUT_SECONDS` 調整。
- 高並發場景不適用（Discord rate limit）；定位是低頻、高價值的知識查詢。