Agent Platform — Phase 1 MCP

本目錄依照 AI Agent + MCP Server 建置說明 v0.1.md 建立。目前已完成單一 Analysis MCP Server、兩個工具、stdio 與 localhost Streamable HTTP transport，以及兩種 transport 的整合測試。

目前架構

mcp_server/
├── mcp_servers/
│   └── analysis/
│       ├── server.py
│       └── tests/
├── .env.example
├── .gitignore
├── AGENTS.md
├── README.md
└── requirements.txt

目前提供：

• add(a, b)：兩數相加。
• calculate_average(values)：計算非空數列的算術平均值。

安裝

需要 Python 3.10 以上；目前已在 Python 3.12 驗證。

cd /home/mingkang/mcp_server
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

執行 MCP Server（Streamable HTTP）

source .venv/bin/activate
python mcp_servers/analysis/server.py

預設 endpoint：

http://127.0.0.1:8001/mcp

Server 刻意只監聽 localhost；目前沒有驗證、授權與 TLS，不得改用 0.0.0.0 對外公開。

如需直接啟動 stdio transport：

python mcp_servers/analysis/server.py --transport stdio

不要在 stdio Server 中把一般日誌寫到 stdout，以免破壞 MCP 訊息。

執行測試

source .venv/bin/activate
pytest

測試包含 Python 函式單元測試，以及真正啟動 stdio 和 Streamable HTTP MCP 子行程後進行 initialize、tools/list、tools/call 的整合測試。HTTP 測試使用動態 localhost port，避免與開發中的 8001 衝突。

MCP Inspector

環境已具備 Node.js 與 npx 時可執行：

source .venv/bin/activate
mcp dev mcp_servers/analysis/server.py

Inspector 應顯示 add 與 calculate_average。建議測試：

• add：a=5, b=7，預期 12。
• calculate_average：values=[10,20,30]，預期 20。
• calculate_average：values=[]，預期回報 values cannot be empty。

下一個 checkpoint

stdio、Inspector 與 localhost Streamable HTTP 驗收通過後，下一步是串接單一 OpenAI Agent。目前 PyPI 的 openai-agents==0.19.4 宣告相依 mcp>=1.19,<2，與本專案採用的 mcp==2.0.0 不相容；因此尚未安裝 Agents SDK，也不以忽略相依條件的方式強行混裝。

.env 已建立且被 Git 忽略；日後 Agent 階段再填入 OPENAI_API_KEY，切勿提交金鑰。