mcp-server: Instructions file for Codex

AGENTS.md — mcp-server 專案指南

本檔案供 AI 與開發者快速進入狀況。詳細設計說明見 docs/ARCHITECTURE.md。

專案概述

MCP (Model Context Protocol) Server：以 FastAPI 提供 /mcp HTTP 端點，讓 LLM 客戶端 （如 Claude Code、Claude Desktop）能呼叫本機工具。目前僅提供 execute_shell（Linux Shell 命令執行）。 客戶端連接方式（Claude Code 原生 HTTP；Claude Desktop 需 mcp-remote 橋接）詳見 README 第 4 節。

• 版本：4.0.0
• Python：>= 3.10
• 執行方式：本地直接執行（無容器化部署）
• 認證：單一 AUTH_KEY（Bearer Token）

目錄結構

mcp-server/
├── src/mcp_server/
│   ├── __main__.py            # 入口：日誌初始化、顯示 AUTH_KEY、啟動 uvicorn
│   ├── app.py                 # FastAPI 應用、/mcp 路由、MCP 協議分發
│   ├── config.py              # 全域配置（AUTH_KEY、路徑、伺服器、執行限制）
│   ├── security.py            # Bearer Token 驗證（hmac.compare_digest）
│   ├── schemas.py             # MCPError（協議層錯誤）
│   ├── utils.py               # format_tool_result()（ExecutionResult → MCP 回應）
│   ├── base/
│   │   └── logging_config.py  # 統一日誌（console 彩色 + RotatingFileHandler）
│   ├── tools/
│   │   ├── __init__.py        # 動態掃描目錄、自動註冊所有工具
│   │   ├── base.py            # ToolRegistry 單例與 @registry.register
│   │   ├── schemas.py         # ExecutionResult（工具回傳格式）
│   │   └── execute_shell/     # 目前唯一的工具
│   └── start.sh               # 啟動腳本（安裝 mcp_server 後執行 python -m mcp_server）
├── docs/
│   ├── ARCHITECTURE.md        # 詳細架構與開發範式
│   └── SELF_HEALING_MEMO.md   # 故障排除備忘錄
├── .env.example               # 環境變數範本
├── pyproject.toml             # 套件依賴與工具設定（ruff / pyright）；版本號唯一來源
└── workspace/                 # 執行工作目錄（服務啟動時建立並清空，不進版控）

認證機制

• 金鑰來源：環境變數 AUTH_KEY。
• 未設定時：config.py 以 secrets.token_urlsafe(32) 隨機產生，僅存在於記憶體， __main__.py 會於啟動時在 console 顯示；重啟即變更。
• 客戶端必須帶：Authorization: Bearer <AUTH_KEY>。
  • 缺少或格式錯誤 → 401
  • 金鑰不符 → 403
• 驗證邏輯在 security.py 的 verify_api_key()，使用 hmac.compare_digest 常數時間比較。
• 失敗次數限制：同一來源 IP 於 60 秒內失敗達 10 次即回 429（Retry-After: 60），避免暴力嘗試。
• 已移除多金鑰（MCP_API_KEYS）、Tool 權限白名單／排除清單與 Gmail 帳號綁定機制。

安全模型

• 唯一的存取控制是 AUTH_KEY（加上監聽位址）。本服務的設計目的就是執行任意 shell， 因此不提供命令黑名單——子字串黑名單容易被引號、變數、$IFS 等方式繞過，只會給人錯誤的安全感。
• 因此：AUTH_KEY 等同於機器上的 shell 權限，務必只使用於可信任網段（建議 MCP_HOST=127.0.0.1）， 且不得寫進版控。
• 日誌不記錄金鑰本身（Authorization 格式錯誤時僅記錄 scheme）。