# Agent Platform — Phase 1 MCP

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

## 目前架構

```text
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 驗證。

```bash
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）

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

預設 endpoint：

```text
http://127.0.0.1:8001/mcp
```

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

如需直接啟動 stdio transport：

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

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

## 執行測試

```bash
source .venv/bin/activate
pytest
```

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

## MCP Inspector

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

```bash
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`，切勿提交金鑰。