boos
e0a5f57793
Vendor the rebranded BoosAPI Desktop client (Tauri + Vue) into metapi as a monorepo subdirectory under desktop/. Source only — node_modules, dist, Cargo target and the upstream .git history are excluded. desktop/ keeps its own independent Cargo workspace (desktop/src-tauri with crates/*); it is not part of the backend boosapi crate, so a `cargo check` at the metapi root still compiles only the backend. Build the desktop app from desktop/src-tauri per desktop/README.md. Note: app icons are still placeholder assets pending the final BoosAPI logo. The updater signing keys live outside the repo and are not included.
200 lines
5.2 KiB
Markdown
200 lines
5.2 KiB
Markdown
# MCP 伺服器
|
||
|
||
## 什麼是 MCP？
|
||
|
||
[Model Context Protocol（MCP）](https://modelcontextprotocol.io/)是一種開放協定，讓 AI 模型能夠與外部工具和資料來源互動。透過 MCP，模型可以在對話中呼叫檔案操作、網頁擷取、資料庫查詢等各種工具，大幅擴展 AI 的實際能力。
|
||
|
||
BoosApi 內建了 MCP 客戶端，您可以連接各種 MCP 伺服器來為 AI 對話增加工具呼叫能力。
|
||
|
||
## 傳輸協定
|
||
|
||
BoosApi 支援三種 MCP 傳輸協定，適用於不同的部署場景：
|
||
|
||
| 協定 | 連線方式 | 適用場景 | 設定參數 |
|
||
|------|---------|---------|---------|
|
||
| **Stdio** | 本機子程序 | 透過 `npx`、`uvx`、自訂指令啟動的本機工具 | `command` + `args` |
|
||
| **SSE** | Server-Sent Events | 遠端託管的 MCP 伺服器 | `url` |
|
||
| **StreamableHTTP** | HTTP 串流傳輸 | 遠端 HTTP 伺服器，支援雙向串流 | `url` |
|
||
|
||
::: info Stdio vs 遠端
|
||
大部分 MCP 伺服器以 Stdio 模式執行——BoosApi 在本機啟動一個程序並透過標準輸入/輸出通訊。如果您連接的是遠端部署的伺服器，則使用 SSE 或 StreamableHTTP 協定。
|
||
:::
|
||
|
||
## 新增 MCP 伺服器
|
||
|
||
### 表單建立
|
||
|
||
1. 進入 **設定 → MCP 伺服器**
|
||
2. 點擊 **新增 MCP 伺服器**
|
||
3. 填寫基本資訊：
|
||
- **名稱** — 為伺服器取一個易識別的名稱
|
||
- **傳輸協定** — 選擇 Stdio、SSE 或 StreamableHTTP
|
||
4. 根據所選協定填寫相應設定：
|
||
- **Stdio**：填寫啟動指令（如 `npx`、`uvx`）和參數
|
||
- **SSE / StreamableHTTP**：填寫伺服器 URL
|
||
5. 儲存後 BoosApi 會自動連接並取得可用工具清單
|
||
|
||
### JSON 匯入
|
||
|
||
如果您有現成的 MCP 設定（如從其他工具匯出），可以直接貼上 JSON 快速匯入。BoosApi 支援標準的 `mcpServers` 設定格式。
|
||
|
||
#### Stdio 協定格式
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"my-tool": {
|
||
"command": "npx",
|
||
"args": ["-y", "@some/mcp-server"],
|
||
"env": {
|
||
"API_KEY": "your-key"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### SSE 協定格式
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"remote-server": {
|
||
"type": "sse",
|
||
"url": "https://example.com/sse"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### StreamableHTTP 協定格式
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"http-server": {
|
||
"type": "streamablehttp",
|
||
"url": "https://example.com/mcp"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
::: tip 批次匯入
|
||
您可以在一個 JSON 中包含多個伺服器，BoosApi 會一次性全部匯入。
|
||
:::
|
||
|
||
## 設定範例
|
||
|
||
以下是一些常用 MCP 伺服器的設定範例。
|
||
|
||
### 網頁擷取 — mcp-server-fetch
|
||
|
||
使用 `uvx` 啟動網頁擷取工具，讓 AI 能夠讀取網頁內容：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"fetch": {
|
||
"command": "uvx",
|
||
"args": ["mcp-server-fetch"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 檔案系統操作 — filesystem server
|
||
|
||
使用 `npx` 啟動檔案系統伺服器，允許 AI 讀寫指定目錄的檔案：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"filesystem": {
|
||
"command": "npx",
|
||
"args": [
|
||
"-y",
|
||
"@modelcontextprotocol/server-filesystem",
|
||
"/Users/您的使用者名稱/Documents"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
::: warning 安全提示
|
||
檔案系統伺服器會授予 AI 對指定目錄的讀寫權限。請只暴露必要的目錄路徑，避免將根目錄或敏感目錄暴露給模型。
|
||
:::
|
||
|
||
### 遠端 SSE 伺服器
|
||
|
||
連接遠端部署的 MCP 伺服器：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"remote-tools": {
|
||
"type": "sse",
|
||
"url": "https://mcp.example.com/sse"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 自訂 Stdio 伺服器（帶環境變數）
|
||
|
||
執行自訂的 MCP 伺服器，透過環境變數傳遞設定：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"custom-tool": {
|
||
"command": "python",
|
||
"args": ["/path/to/your/server.py"],
|
||
"env": {
|
||
"DATABASE_URL": "postgres://localhost:5432/mydb",
|
||
"API_TOKEN": "your-token"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 內建工具
|
||
|
||
BoosApi 開箱即用地提供了一些內建 MCP 工具伺服器，無需額外安裝：
|
||
|
||
### @boosapi/fetch — 網頁擷取
|
||
|
||
| 工具 | 說明 |
|
||
|------|------|
|
||
| `fetch_url` | 擷取指定 URL 的頁面內容，提取文字 |
|
||
| `fetch_markdown` | 擷取指定 URL 並轉換為 Markdown 格式 |
|
||
|
||
### @boosapi/search-file — 檔案操作
|
||
|
||
| 工具 | 說明 |
|
||
|------|------|
|
||
| `read_file` | 讀取指定路徑的檔案內容 |
|
||
| `list_directory` | 列出指定目錄下的檔案和資料夾 |
|
||
| `search_files` | 依模式搜尋相符的檔案 |
|
||
|
||
::: tip
|
||
內建工具伺服器在 MCP 伺服器清單中預設顯示，可以直接在對話中啟用使用，無需任何額外設定。
|
||
:::
|
||
|
||
## 工具循環上限
|
||
|
||
在 設定 -> 對話 中，MCP 工具呼叫最大輪次 用於限制單次回覆中模型連續呼叫工具的輪數。較低數值可減少耗時和成本，較高數值適合更長的自動化工具流程。
|
||
|
||
## 工具執行面板
|
||
|
||
當模型在對話中呼叫 MCP 工具時，BoosApi 會在訊息中顯示工具執行面板，其中包含：
|
||
|
||
- **工具名稱** — 被呼叫的工具和所屬伺服器
|
||
- **輸入參數** — 模型傳給工具的參數
|
||
- **執行狀態** — 等待確認、執行中、已完成或失敗
|
||
- **回傳結果** — 工具執行後回傳的資料
|
||
|
||
點擊面板可以展開查看完整的輸入和輸出資訊，方便除錯和了解 AI 的工具使用行為。
|