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。

MCP 工具

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

Related MCP server: mcp-sofa

安裝

需求：Node.js 18+。

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

Discord 端準備（一次性）

1. 在 Discord Developer Portal 建立一個 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 放進系統環境變數：

   export PYTHIA_COURIER_TOKEN="你的-bot-token"

2. 複製 .mcp.json.example 到 consumer 專案根目錄，改名為 .mcp.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 提問。

選填參數

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

開發

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）；定位是低頻、高價值的知識查詢。