# xiaozhi-mcp

本地 MCP（Model Context Protocol）框架，用來把自建的工具透過小智AI（xiaozhi.me）的 MCP 接入點，提供給語音智能體使用。

## 架構

小智AI 雲端 (wss://) ↔ `mcp_pipe.py`（橋接器）↔ `server.py`（本地 FastMCP Server，stdio）

## 安裝

```bash
uv sync
```

## 設定

1. 登入 [xiaozhi.me](https://xiaozhi.me) 控制台，進入智能體的配置角色頁面，取得該智能體專屬的 MCP 接入點網址（`wss://...`）。
2. 複製 `.env.example` 為 `.env`，填入取得的網址：

```
MCP_ENDPOINT=wss://your-actual-endpoint
```

3.（若要使用 `web_search` 工具）到 [SerpApi](https://serpapi.com/) 註冊取得 API Key，填入 `.env`：

```
SERPAPI_KEY=your-actual-serpapi-key
```

## 執行

```bash
uv run mcp_pipe.py server.py
```

看到 log 出現 `Successfully connected to WebSocket server` 代表已連上小智AI 的 MCP 接入點。

## 驗證

橋接器顯示連線成功，不代表工具真的能被呼叫到。請開啟與小智AI 的對話，直接要求它算一個算式，例如「幫我算 8 的平方根」，確認小智AI 回覆的結果是正確的計算結果（8 的平方根約為 2.828），就代表 `calculator` 工具已經透過橋接器被成功呼叫、算完並回傳。

## 新增工具

在 `server.py` 中用 `@mcp.tool()` 裝飾一個函式即可新增工具，同一個 server 可以有多個工具，`mcp_pipe.py` 不需要修改。工具名稱與參數命名要清楚（避免縮寫），並用 docstring 說明用途與使用時機，讓大模型知道何時該呼叫它。回傳值建議控制在 1024 bytes 以內。

目前內建的 `web_search` 工具會呼叫 [SerpApi](https://serpapi.com/) 做 Google 搜尋：優先回傳 Google 的直接解答框內容（`answer_box`，例如天氣、單位換算、簡單問答）或 `knowledge_graph` 摘要，都沒有的話才退回最相關那一筆搜尋結果的摘要（避免回傳內容過長）；需要在 `.env` 設定 `SERPAPI_KEY` 才能使用，沒設定時會回傳 `{"success": false, "error": "SERPAPI_KEY not configured"}`。

## 安全性

`server.py` 內建的 `calculator` 工具，是用 `eval()` 直接執行傳入的 Python 運算式，且沒有做任何沙箱或白名單限制，等同於可以執行任意 Python 程式碼（包含存取檔案系統、匯入任意模組等）。這個工具只是官方範例，目的是快速驗證「小智AI ↔ `mcp_pipe.py` ↔ `server.py`」這條連線鏈路是否打通，並不適合留在正式使用的環境中。建議在確認連線成功、換上真正需要的工具後，就把 `calculator` 移除；在那之前，也不要讓橋接器在無人看管的情況下長時間掛著執行。