> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 伺服器

> 了解如何將 SUNRA 的 MCP 伺服器與 Cursor、VS Code、Cline、Windsurf 和其他開發環境整合，以實現無縫的 AI 模型存取。

# 設定 SUNRA MCP 伺服器

SUNRA 模型內容協定 (MCP) 伺服器提供與熱門開發環境的無縫整合，讓您可以直接從您的編輯器或 IDE 存取 SUNRA 的 AI 模型。本指南將引導您完成各種工具的 MCP 伺服器設定。

## 什麼是 MCP？

模型內容協定 (MCP) 是 AI 助理安全存取外部資源和工具的標準化方式。SUNRA MCP 伺服器可讓您：

* **列出和搜尋** SUNRA 上可用的 AI 模型
* **提交請求**至任何模型端點
* **檢查狀態**並從佇列系統擷取結果
* **上傳檔案**並管理模型結構描述
* **無縫管理 API 驗證**

## 先決條件

在設定 MCP 伺服器之前，請確保您已具備：

1. 已安裝 **Node.js** (版本 18 或更高)
2. 從[您的儀表板](https://sunra.ai/dashboard/api-tokens)取得的 **SUNRA API 金鑰**
3. 您偏好的編輯器/IDE 已安裝

## 安裝

SUNRA MCP 伺服器可作為 npm 套件提供：

```bash theme={null}
npm install -g @sunra/mcp-server
```

或直接使用 npx (建議)：

```bash theme={null}
npx @sunra/mcp-server
```

## 按編輯器設定

### Cursor

Cursor 透過其設定檔支援 MCP。在您的專案根目錄中建立或更新 `.cursor/mcp.json`：

```json theme={null}
{
  "mcpServers": {
    "sunra-mcp-server": {
      "command": "npx",
      "args": ["@sunra/mcp-server"]
    }
  }
}
```

**替代的全域設定**在您的使用者設定中：

1. 開啟 Cursor 設定
2. 導覽至「MCP 伺服器」
3. 新增一個新伺服器，並包含：
   * **名稱**：`sunra-mcp-server`
   * **指令**：`npx`
   * **參數**：`@sunra/mcp-server`

### VS Code

對於具有 MCP 支援的 VS Code (需要相容的擴充功能)：

建立 `.vscode/mcp.json`：

```json theme={null}
{
  "mcpServers": {
    "sunra-mcp-server": {
      "command": "npx",
      "args": ["@sunra/mcp-server"],
      "env": {
        "SUNRA_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Cline

Cline 透過其設定支援 MCP 伺服器。新增至您的 Cline 設定：

```json theme={null}
{
  "mcpServers": {
    "sunra": {
      "command": "npx",
      "args": ["@sunra/mcp-server"],
      "description": "SUNRA AI 模型存取"
    }
  }
}
```

### Windsurf

對於 Windsurf IDE，在工作區設定中設定 MCP：

```json theme={null}
{
  "mcp": {
    "servers": {
      "sunra-mcp-server": {
        "command": "npx",
        "args": ["@sunra/mcp-server"],
        "timeout": 30000
      }
    }
  }
}
```

### Claude Desktop

新增至您的 Claude Desktop 設定檔：

**macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**：`%APPDATA%\Claude\claude_desktop_config.json`

```json theme={null}
{
  "mcpServers": {
    "sunra-mcp-server": {
      "command": "npx",
      "args": ["@sunra/mcp-server"]
    }
  }
}
```

### 其他與 MCP 相容的工具

對於任何其他支援 MCP 的工具，請使用此通用設定模式：

```json theme={null}
{
  "mcpServers": {
    "sunra-mcp-server": {
      "command": "npx",
      "args": ["@sunra/mcp-server"],
      "env": {
        "SUNRA_KEY": "${SUNRA_KEY}"
      }
    }
  }
}
```

## 環境設定

### 設定您的 API 金鑰

您可以透過多種方式設定您的 SUNRA API 金鑰：

#### 選項 1：環境變數 (建議)

```bash theme={null}
export SUNRA_KEY="your-api-key-here"
```

對於 Windows：

```cmd theme={null}
set SUNRA_KEY=your-api-key-here
```

#### 選項 2：設定檔

有些編輯器允許您直接在 MCP 設定中設定環境變數：

```json theme={null}
{
  "mcpServers": {
    "sunra-mcp-server": {
      "command": "npx",
      "args": ["@sunra/mcp-server"],
      "env": {
        "SUNRA_KEY": "your-api-key-here"
      }
    }
  }
}
```

#### 選項 3：執行階段設定

MCP 伺服器也支援在執行階段使用 `set-sunra-key` 工具設定 API 金鑰。

## 可用的 MCP 工具

設定完成後，您將可以透過您的 AI 助理存取這些工具：

### 模型管理

* `list-models` - 瀏覽所有可用的 AI 模型
* `search-models` - 依關鍵字尋找模型
* `model-schema` - 取得特定模型的輸入/輸出結構描述

### 請求管理

* `submit` - 提交請求至模型端點
* `status` - 檢查請求狀態和日誌
* `result` - 擷取已完成的結果
* `cancel` - 取消執行中的請求
* `subscribe` - 提交並等待完成

### 檔案管理

* `upload` - 上傳檔案至 SUNRA 儲存空間

## 使用範例

### 列出可用模型

```
使用 list-models 工具向我顯示有哪些可用的 AI 模型。
```

### 生成圖像

```
使用 submit 工具，透過 black-forest-labs/flux-1.1-pro/text-to-image 端點生成圖像。
使用提示：「日落時寧靜的山景」
```

### 檢查請求狀態

```
檢查請求 ID：pd_xxxxxx 的狀態
```

## 疑難排解

### 常見問題

**找不到 MCP 伺服器**

* 確保已安裝 Node.js 且可存取
* 嘗試全域安裝：`npm install -g @sunra/mcp-server`
* 驗證指令路徑是否正確

**驗證錯誤**

* 檢查您的 SUNRA\_KEY 環境變數是否已設定
* 在 [SUNRA 儀表板](https://sunra.ai/dashboard/api-tokens) 驗證您的 API 金鑰是否有效
* 嘗試使用 `set-sunra-key` 工具設定金鑰

**連線逾時**

* 增加您設定中的逾時值
* 檢查您的網際網路連線
* 驗證 SUNRA API 狀態

**權限錯誤**

* 確保設定檔具有適當的檔案權限
* 嘗試使用適當的使用者權限執行

### 取得協助

如果您遇到問題：

1. 檢查 [SUNRA 文件](https://docs.sunra.ai)
2. 檢閱您編輯器的 MCP 文件
3. 在 [GitHub](https://github.com/sunra-ai/sunra-clients/issues) 上提出問題

## 後續步驟

設定好您的 MCP 伺服器後：

1. **探索模型**：使用 `list-models` 查看所有可用的 AI 功能
2. **嘗試範例**：從簡單的文字轉圖像或文字轉影片生成開始
3. **建構工作流程**：結合多個模型以建立複雜的 AI 管線
4. **監控使用情況**：在 [SUNRA 儀表板](https://sunra.ai/dashboard/) 中追蹤您的 API 使用情況

MCP 整合讓您可以輕鬆地將強大的 AI 模型直接整合到您的開發工作流程中，從而在您的應用程式中實現快速原型設計和無縫的 AI 驅動功能。