ai-mcp-server：多 API Key 多模型能力的本地 MCP 橋樑

術語解釋

0. 審查結論與交付門禁

本輪契約變更：MCP tool 從 4 個升級為 6 個

2026-06-28 決策：將現有實作中的 model_performance 與 add_models 正式納入 v1 MCP 公共契約，避免設計文檔、協作指引、README、驗收腳本與 server.py 分離。6 個 tool 是本期刻意上限；後續新增 tool 必須先回到本 PRD 更新設計與驗收。

本輪發布阻斷修復

2026-06-28 發布審查後修復以下阻斷項；本表是設計與實施同步的發布準入記錄。

已確認決策

會構成驗收假通過的情況

• 只跑 pytest 通過但 MCP client 拉不起來 server，或拉起來後 tool list 為空。
• 探活返回「全部 true」但其實 vision / tool_call 走的是 fallback（如 4xx 被當成 ok）。
• capability resolver 返回的能力與實際 invoke 結果不一致。
• api_key 在 SQLite 中以明文落盤、或在日誌 / 錯誤訊息中出現。
• 「不做」清單（streaming、自動重試、自動 fallback）被悄悄做了。

1. 產品價值

目標用戶與場景

• 目標用戶：手上同時持有多個 LLM API key（OpenAI、DeepSeek、Moonshot、SiliconFlow、OpenRouter、Together、vLLM、Ollama…）的開發者，並使用至少一個 MCP client（Claude Desktop / Cursor / Cline）。
• 核心 Job：在不切換 Agent 配置的前提下，按任務性質讓 Agent 自動挑選最合適的模型（長上下文走 Gemini、視覺走 GPT-4o、推理走 DeepSeek-R1、便宜對話走國產、Embedding 走 BGE 等）。

當前痛點

產品價值（用戶可見）

• 登記一次，所有 key 與模型即可被 Agent 統一發現與調用。
• Agent 透過 list_models 按能力篩選，透過 invoke_model 透傳調用，不被服務語義污染。
• 能力標籤可被「探活」驗證，避免「以為能用」。
• 所有 key 本地加密儲存，無雲端、無遙測。

成功信號

• 同一個 Claude Desktop 會話中，Agent 能在 vision 問題上自動選 GPT-4o、在長文檔問題上自動選 Gemini，不需要用戶手動切換 client model 設定。
• endpoint probe --all 跑完後，至少 90% 的模型能拿到 ≥1 個探活確認的 capability。
• 本地 SQLite 中 api_key 欄位無明文，strings db.sqlite3 | grep sk- 無命中。

2. 範圍

假設與待用戶確認項

• 假設：用戶能接受首次啟動時自動建立 ~/.ai-mcp-server/ 目錄並向系統 keyring 寫入 master key。
• 已落地：assets/probe/digit_1.wav 已納入倉庫，並可由 scripts/generate_probe_assets.py 重建；stt 探活不再依賴用戶手工補檔。
• 待確認：LiteLLM metadata 是內建一份 snapshot 進 wheel，還是首次運行時從 GitHub 拉取？默認傾向「內建 snapshot + 可選 ai-mcp meta refresh 拉取最新版」。

3. 現況與差距

當前倉庫狀態

• 已具備 pyproject.toml、src/ai_mcp_server/、tests/、assets/probe/、docs/、CI 與發布 workflow。
• 三入口已落地：ai-mcp CLI、ai-mcp-server stdio MCP server、ai-mcp ui Web UI。
• 本 PRD 是設計與實施同步的源頭文件；發布審查發現的阻斷項需先回寫本文件，再落到 source/test。

外部生態現況

差距

• 無任何代碼基線，從零開始。
• assets/probe/digit_1.wav 已提供；若安裝包或本地資產缺失，stt 探活仍需自動降級為 skip，不影響其他能力探活。

4. 目標旅程

4.1 首次安裝與登記

1. 用戶 uv tool install ai-mcp-server 安裝。
2. 首次運行任意 ai-mcp 命令時自動建立 ~/.ai-mcp-server/ 與 SQLite。
3. 首次需要加密時自動生成 master key 並寫入系統 keyring。
4. 用戶執行 ai-mcp endpoint add 完成登記，緊接著 ai-mcp endpoint probe 探活。

4.2 Agent 透過 MCP 調用

1. MCP client 啟動時拉起 ai-mcp-server 進程（stdio）。
2. client 收到 instructions：「請先調用 usage_guide 取得能力說明」。
3. Agent 視任務需要調用 list_models 篩選能力。
4. 如 endpoint 不提供 /v1/models，Agent 先向用戶確認後可調用 add_models 手動登記。
5. 如多個模型能力相近，Agent 可調用 model_performance 查看近期成功率與延遲作為選擇依據。
6. Agent 帶上選定的 endpoint + model 調用 invoke_model。
7. MCP server 找對應 adapter，透傳請求；響應原樣返回。

4.3 異常與兜底

5. 產品方案

5.1 CLI 命令

# endpoint 管理
ai-mcp endpoint add --name <n> --base-url <url> --key <k> [--provider openai-compat]
ai-mcp endpoint list [--json]
ai-mcp endpoint show <name>
ai-mcp endpoint remove <name>

# 模型與能力
ai-mcp endpoint probe <name> [--capability text_chat,vision,...]
ai-mcp endpoint probe --all
ai-mcp model list [--endpoint <name>] [--capability vision] [--min-context 128000]
ai-mcp model show <endpoint> <model_id>
ai-mcp model override <endpoint> <model_id> --capability vision=true
ai-mcp model override <endpoint> <model_id> --context-length 200000

# metadata
ai-mcp meta refresh        # 拉取最新 LiteLLM metadata

# MCP server
ai-mcp-server              # stdio 啟動（給 MCP client 用）

5.2 MCP Tool 規格

usage_guide

list_models

出參：模型陣列，每個元素含 endpoint, model_id, capabilities, context_length, probe_status, capability_source（標明每個 capability 來自哪一來源）。

invoke_model

出參：透傳上游響應 + 附加 _meta: {endpoint, model, latency_ms, upstream_status}。錯誤時返回 {error: {status, body}}，不拋出。TTS 成功時二進位音訊以 body.audio_base64 返回，並附 audio_bytes_len 與 content_type。

model_performance

出參：模型陣列，每個元素含 endpoint, model_id, full_id, call_count, success_count, success_rate, avg_first_byte_ms, avg_prompt_tokens, avg_output_tokens, window_days。此 tool 只讀本地聚合性能資料，不做成本估算、不替 Agent 自動路由。

refresh_endpoint

出參：{enqueued, plan, note}。此 tool 只入隊，不等待所有 probe 同步完成；MCP server 進程內 worker 或 CLI worker 會異步消化。

add_models

出參：{endpoint, added, count} 或 {error}。Agent 使用此 tool 前應先向用戶確認模型 id、context length 與能力來源，避免憑空登記不存在模型。

5.3 能力路由建議（給 Agent 的引導）

不在服務側做路由；服務只提供能力標籤與篩選 API。usage_guide 中向 Agent 提示常見的選擇模式，例如「長文檔 → 按 context_length 排序」「視覺問題 → 篩 capability=vision」。

5.4 Web 管理 UI（ai-mcp ui）

本地單用戶管理頁面，純後端 Jinja2 模板渲染；預設綁定 127.0.0.1、本機無認證；設置 AI_MCP_UI_TOKEN 後，除 static assets 外所有 route（含 /jobs/stream SSE）均需 ?token=...。UI 進程 in-process 調用 application/*，與 CLI / MCP 共享同一份業務邏輯。

# 啟動
ai-mcp ui [--host 127.0.0.1] [--port 8765]
# 控制台輸出：
#   ai-mcp ui ready at http://127.0.0.1:8765/
#   按 Ctrl+C 退出

5.5 UI 頁面清單（9 個，全為 MVP）

寫操作以 form POST 提交，UI route 直接 in-process 調 application/*；不走 subprocess、不走 HTTP 反代到 MCP server。SSE 用於 /jobs 與 /endpoints/<name> 中的探活進度刷新。

5.6 探活異步化流程

探活不再阻塞觸發者；改為「入隊 → worker 認領 → 寫回結果」三段式。

1. 入隊：UI / CLI / MCP 任一入口都可 INSERT INTO probe_jobs，狀態 pending，無 claimed_by。
2. 認領（樂觀鎖）：
   • worker 啟動時生成 instance_id = uuid4()。
   • UPDATE probe_jobs SET claimed_by=instance_id, claimed_at=now, status='claiming' WHERE id=? AND claimed_by IS NULL。
   • 等 0.5 秒；SELECT claimed_by FROM probe_jobs WHERE id=?；如仍是自己 → status='running' 進入執行，否則 noop。
3. 執行：跑 provider 探活 → 寫 probe_runs raw 響應 → 更新 models.capabilities_json（透過 resolver）→ UPDATE probe_jobs SET status='done', finished_at=now。
4. lease 超時回退：背景定期掃描 status IN ('claiming','running') AND lease_until < now，重置為 pending, claimed_by=NULL（孤兒任務恢復）。
5. 失敗：探活內部錯誤 → status='failed'，error 欄位記原因；不重試（用戶自行重新入隊）。

Worker 承擔：(δ) ai-mcp-server MCP 進程內以 asyncio task 常駐輪詢 + (γ) ai-mcp endpoint probe CLI 也跑 worker loop 直到佇列清空。兩者用同一份 worker 代碼，靠樂觀鎖避免並發雙跑。

6. 架構擴展

6.1 整體架構

1. 入口層：三個獨立進程入口共享 application/*。server.py（stdio MCP）；cli.py（typer CLI）；web/app.py（FastAPI + Jinja2，由 ai-mcp ui 子命令拉起 uvicorn）。
2. 編排層 application/：endpoint 管理、模型發現、capability 解析、probe_jobs 入隊與消化；無 IO 細節。CLI / UI / MCP route 都直接 import。
3. Worker 層：application/worker.py 提供 claim_one() / run_loop()；MCP server 進程啟動時 asyncio task 常駐輪詢，CLI endpoint probe 也跑直到 queue 清空。
4. Provider 層 providers/：ABC + OpenAICompat 實作；負責協議格式、HTTP 細節、錯誤碼透傳。
5. Capability 層：static_map（內建表）、litellm_meta（拉取/快取）、resolver（四來源融合）。
6. Probe 層：每能力一個模組，輸入 (adapter, model_id) → ProbeResult。
7. Storage 層：sqlite3（連線時設 PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000）+ Fernet + keyring；DAO 函數薄。
8. 架構原則「解讀 X」：三進程不共享記憶體、各自 in-process 調 application；共享真相在 SQLite（WAL 多進程併發安全）。

6.2 倉庫結構

ai-mcp-server/
├── pyproject.toml
├── AGENTS.md
├── docs/prd/ai-mcp-server-v1/index.html
├── assets/probe/
│   ├── digit_1.png         # vision 探活素材
│   └── digit_1.wav         # stt 探活素材
├── src/ai_mcp_server/
│   ├── __init__.py
│   ├── server.py           # MCP server 入口 (ai-mcp-server)
│   ├── cli.py              # CLI 入口 (ai-mcp; 含 ui / endpoint / model / meta / worker 子命令)
│   ├── application/
│   │   ├── endpoint_service.py
│   │   ├── model_discovery.py
│   │   ├── probe_jobs.py        # enqueue / claim / lease / list
│   │   ├── worker.py            # claim_one / run_loop / lease_sweeper
│   │   ├── capability_query.py
│   │   └── meta_service.py
│   ├── providers/
│   ├── capability/
│   ├── probes/
│   ├── storage/
│   │   ├── db.py                # WAL + busy_timeout + migration
│   │   ├── crypto.py
│   │   └── dao.py
│   ├── web/
│   │   ├── app.py               # FastAPI app factory
│   │   ├── routes/
│   │   │   ├── dashboard.py
│   │   │   ├── endpoints.py
│   │   │   ├── models.py
│   │   │   ├── overrides.py
│   │   │   ├── probes.py
│   │   │   ├── jobs.py          # 含 SSE endpoint
│   │   │   └── meta.py
│   │   ├── templates/           # Jinja2
│   │   │   ├── base.html
│   │   │   ├── dashboard.html
│   │   │   └── ...
│   │   └── static/              # 樸素 CSS，不引入前端構建
│   ├── models/
│   └── utils/
└── tests/{unit,integration,conftest.py}

6.3 代碼變更影響矩陣

6.4 對外契約

• CLI 契約：見 §5.1，命令名與參數穩定；新增子命令不破壞既有。
• MCP tool 契約：6 個 tool 的 name、入參 schema、出參結構為穩定契約；演進時新增可選欄位、不刪除既有欄位。
• Provider 契約：上游 API 響應原樣透傳；僅附加 _meta，不修改 body。

7. 數據與資料庫規劃

7.1 ER 視圖

1. endpoints 是根表，主鍵 id；存 (name 唯一, base_url, api_key_enc, provider_type, created_at)。
2. models 多對一引用 endpoints；(endpoint_id, model_id) 聯合主鍵；存 capability 探活結果與 metadata 緩存。
3. overrides 多對一引用 models；(endpoint_id, model_id, capability_key) 聯合主鍵；存用戶手動覆寫。
4. probe_runs 記錄歷次探活的 raw 響應，便於追溯；無 FK，按 (endpoint_id, model_id) 字串關聯。
5. probe_jobs 探活任務佇列；含 claimed_by（worker instance_id）、claimed_at、lease_until、status；UI / CLI / MCP 任一入隊。

7.2 Schema

-- endpoints
CREATE TABLE endpoints (
  id            INTEGER PRIMARY KEY AUTOINCREMENT,
  name          TEXT NOT NULL UNIQUE,
  base_url      TEXT NOT NULL,
  api_key_enc   BLOB NOT NULL,        -- Fernet ciphertext
  provider_type TEXT NOT NULL DEFAULT 'openai-compat',
  created_at    TEXT NOT NULL DEFAULT (datetime('now')),
  updated_at    TEXT NOT NULL DEFAULT (datetime('now'))
);

-- models
CREATE TABLE models (
  endpoint_id        INTEGER NOT NULL REFERENCES endpoints(id) ON DELETE CASCADE,
  model_id           TEXT NOT NULL,
  capabilities_json  TEXT NOT NULL DEFAULT '{}',  -- {cap: {value, source, probed_at}}
  context_length     INTEGER,
  raw_meta_json      TEXT,                         -- 上游 /v1/models 原始 item
  last_discovered_at TEXT NOT NULL DEFAULT (datetime('now')),
  PRIMARY KEY (endpoint_id, model_id)
);

-- overrides
CREATE TABLE overrides (
  endpoint_id    INTEGER NOT NULL,
  model_id       TEXT NOT NULL,
  capability_key TEXT NOT NULL,         -- e.g. 'vision', 'context_length'
  value_json     TEXT NOT NULL,
  updated_at     TEXT NOT NULL DEFAULT (datetime('now')),
  PRIMARY KEY (endpoint_id, model_id, capability_key)
);

-- probe_runs
CREATE TABLE probe_runs (
  id           INTEGER PRIMARY KEY AUTOINCREMENT,
  endpoint_id  INTEGER NOT NULL,
  model_id     TEXT NOT NULL,
  capability   TEXT NOT NULL,
  ok           INTEGER NOT NULL,
  latency_ms   INTEGER,
  raw_json     TEXT,
  error        TEXT,
  ran_at       TEXT NOT NULL DEFAULT (datetime('now'))
);
CREATE INDEX idx_probe_runs_lookup ON probe_runs(endpoint_id, model_id, capability, ran_at);

-- probe_jobs (探活任務佇列)
CREATE TABLE probe_jobs (
  id            INTEGER PRIMARY KEY AUTOINCREMENT,
  endpoint_id   INTEGER NOT NULL REFERENCES endpoints(id) ON DELETE CASCADE,
  model_id      TEXT NOT NULL,
  capability    TEXT NOT NULL,        -- 待探活的 capability key
  status        TEXT NOT NULL DEFAULT 'pending',
                  -- pending | claiming | running | done | failed
  priority      INTEGER NOT NULL DEFAULT 0,
  claimed_by    TEXT,                  -- worker instance_id (UUID)
  claimed_at    TEXT,
  lease_until   TEXT,                  -- claim 後預估完成時限，超時可被回退
  finished_at   TEXT,
  error         TEXT,
  created_at    TEXT NOT NULL DEFAULT (datetime('now'))
);
CREATE INDEX idx_probe_jobs_pending ON probe_jobs(status, priority DESC, id ASC)
  WHERE status='pending';
CREATE INDEX idx_probe_jobs_lease ON probe_jobs(status, lease_until)
  WHERE status IN ('claiming','running');

-- 連線初始化
PRAGMA journal_mode=WAL;
PRAGMA busy_timeout=5000;

-- migrations
CREATE TABLE _schema_version (version INTEGER PRIMARY KEY);

7.3 變更與兼容性

7.4 加密、回滾、隱私

• 加密：api_key_enc 使用 Fernet（AES-128-CBC + HMAC）；master key 來自 env AI_MCP_MASTER_KEY > 系統 keyring > 首次運行自動生成並寫入 keyring。
• 回滾：MVP schema 不需 down migration；直接刪除 ~/.ai-mcp-server/db.sqlite3 重建即可（用戶會被警示）。
• 遺留可讀性：master key 一旦遺失，所有 api_key_enc 不可解密 → CLI 在加密失敗時提示用戶 re-add endpoint。
• 隱私：無遙測；所有 IO 限於本機 SQLite、本機 keyring、向用戶登記的 base_url 發 HTTPS。
• 日誌：所有日誌路徑禁止輸出 api_key 明文與 Authorization header；錯誤響應原樣冒泡時需 mask 上游 echo back 的 key（如有）。

8. 實施計劃

分 9 個里程碑，每個獨立可測。

8.1 依賴與順序

• M1 → M2 → M3 / M5（可並行）→ M4 → M6 → M7 → M8 / M9（可並行）。
• M7 依賴 M6 的 probe_jobs 表與 enqueue API。
• M8 / M9 都依賴 M7 的 worker；M8 用內建 task，M9 不啟動 worker（只入隊）。

8.2 回滾

• 任何里程碑失敗，回退至上一里程碑 tag；MVP 階段 SQLite 直接刪庫重建。

9. 開發風險（Developer Reality）

10. 測試與驗收

10.1 測試矩陣

10.2 真實串通驗收（硬門禁）

1. 登記至少 2 個真實 endpoint（如 OpenRouter + 本地 Ollama）：
   uv run ai-mcp endpoint add --name openrouter --base-url https://openrouter.ai/api/v1 --key sk-...
2. 跑探活：uv run ai-mcp endpoint probe --all（CLI 模式：入隊 + 同步消化 worker loop），預期 ≥90% model 拿到至少 1 個 ok 的 capability。
3. 用 mcp inspector 拉起：npx @modelcontextprotocol/inspector uv run ai-mcp-server，校驗 6 個 tool 出現、schema 正確。
4. 啟動 web UI：uv run ai-mcp ui，瀏覽器打開 http://127.0.0.1:8765/，依序驗證 9 個頁面渲染正常。
5. 在 UI 的「Endpoint 詳情」點「探活」→ /jobs 頁面看 SSE 進度條推進 → 跑完後 Models 表 capability 標籤更新。
6. 並發驗證：UI 點探活的同時，CLI 也跑 ai-mcp endpoint probe --all，預期無雙跑（樂觀鎖生效），所有 job 最終都 done 或 failed。
7. 在 Claude Desktop 配置：

   {
     "mcpServers": {
       "ai-mcp": {
         "command": "uv",
         "args": ["run", "--directory", "/path/to/ai-mcp-server", "ai-mcp-server"]
       }
     }
   }

8. 在 Claude Desktop 對話中依次驗證：
   • chat 透傳：要求 Claude 透過 invoke_model 走 OpenRouter 上某 chat model，得到回答。
   • vision 透傳：傳一張圖，要求 Claude 路由到具備 vision 能力的 model 進行識別。
   • embedding 透傳：要求 Claude 透過 invoke_model 取一段文字的 embedding，返回向量長度正確。
   • model_performance：要求 Claude 查詢近期模型成功率與首字延遲，確認返回本地聚合指標。
   • refresh_endpoint：透過 MCP 調用此 tool 入隊；確認 MCP server 進程內的背景 worker 自動消化並寫回。
   • add_models：對不暴露 /v1/models 的測試 endpoint 手動登記一個模型，確認 list_models 可見。
9. 驗證 ~/.ai-mcp-server/db.sqlite3 中 api_key_enc 為二進位密文：strings db.sqlite3 | grep -E '^sk-' 無命中。

10.3 不能宣告完成的情況

• 10.2 任一步驟未跑通，僅靠 pytest 通過不算完成。
• 探活對至少一個真實 endpoint 全部失敗。
• api_key 在任何路徑（DB / 日誌 / stderr / MCP 響應）以明文出現。

11. 安全、隱私與權限

• 敏感資料：api_key 加密儲存；master key 在 system keyring 或 env；任何路徑禁止明文輸出。
• 留存：所有資料只在本機；無雲端、無遙測。
• 日誌脫敏：日誌中 Authorization header 與 api_key 字段強制 mask；錯誤透傳前掃描上游 echo 並 mask。
• 權限：MCP server 本身為當前用戶進程；無多用戶 / 無權限分層。
• 濫用風險：用戶可能用 invoke_model 跑昂貴模型（如 image_gen）→ usage_guide 中明示「該操作可能產生上游費用」，但服務側不做攔截。
• 探活費用透明：CLI endpoint probe 在執行涉及付費能力（image_gen / tts）前提示用戶確認。

12. 風險、開放問題與決策

12.1 主要風險與緩解

12.2 開放問題

• LiteLLM metadata 是內建 snapshot 還是首次遠端拉取？（默認 snapshot + 可選 refresh）
• 是否在 list_models 出參中暴露上游 raw_meta_json？（默認否，按需展開）
• 是否提供 ai-mcp-server --http 模式給遠端 MCP client？（默認 P2+ 階段）

12.3 已確認決策

見 §0「已確認決策」表格。

13. 完成定義（Definition of Done）

文檔與發布

• README 含安裝、CLI 範例、Claude Desktop 配置範例、故障排查。
• 本 PRD 與 AGENTS.md 隨倉庫一起發布。
• CHANGELOG 由 update-changelog skill 自動維護。

回滾開關

• 用戶可隨時刪除 ~/.ai-mcp-server/ 與 system keyring 中的 ai-mcp-server 條目，徹底重置。
• MCP client 端只需從配置中移除 ai-mcp 條目即可解除接入。