Sunra.ai Mcp Server

Sunra MCP Server

English | 简体中文

一个模型上下文协议（MCP）服务，提供用于与 Sunra.ai 服务交互的工具。

安装

从 npm 安装（推荐）

npx @sunra/mcp-server --help

本地开发

git clone https://github.com/sunra-ai/sunra-clients.git
cd sunra-clients/mcp-server
npm install
npm run build

使用方法

命令行选项

sunra-mcp-server [options]

Options:
  -t, --transport <type>   Transport type: 'stdio' or 'http' (default: stdio)
  -p, --port <number>      Port for HTTP transport (default: 3000)
  -h, --host <string>      Host for HTTP transport (default: localhost)
  --help                   Show this help message

Examples:
  sunra-mcp-server                           # Start with stdio transport
  sunra-mcp-server --transport http          # Start with HTTP transport on port 3000
  sunra-mcp-server -t http -p 8080           # Start with HTTP transport on port 8080

用于 Cursor IDE

将以下内容添加到 .cursor/mcp.json 文件中：

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

用于 Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中：

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

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

功能

• 基础工具：提交、查询状态、获取结果、取消和订阅操作
• 模型管理：列出、搜索 AI 模型，并获取模型架构信息
• 文件管理：将文件上传到 Sunra.ai
• 身份验证：安全管理 API 密钥
• 多种传输方式：支持 stdio（用于 Claude Desktop）和 HTTP（用于 Cursor）

工具

基础操作

• submit - 向模型端点提交请求
• status - 检查请求状态
• result - 获取已完成请求的结果
• cancel - 取消待处理的请求
• subscribe - 提交请求并等待完成

模型管理

• list-models - 列出所有可用模型
• search-models - 按名称或描述搜索模型
• model-schema - 获取特定模型端点的输入和输出架构

文件管理

• upload - 将文件上传到 Sunra.ai 存储

身份验证

• set-sunra-key - 配置 Sunra.ai API 密钥

使用示例

模型架构工具

model-schema 工具现在接受格式为 owner/model/endpoint 的模型 slug，并且只返回输入和输出架构：

# Get schema for a specific model endpoint
model-schema --modelSlug "black-forest-labs/flux-kontext-max/text-to-image"

引用解析

该工具会自动解析 OpenAPI $ref 引用，以提供完整展开的架构。例如，如果原始 OpenAPI 架构包含：

{
  "schema": {
    "$ref": "#/components/schemas/TextToVideoInput"
  }
}

该工具会解析此引用并返回实际的架构定义：

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "prompt": {
        "type": "string",
        "description": "Text prompt for video generation"
      },
      "duration": {
        "type": "integer",
        "enum": [5, 10],
        "description": "Duration of the video in seconds"
      }
    },
    "required": ["prompt"]
  }
}

该工具可处理：

• ✅ 简单引用（#/components/schemas/SchemaName）
• ✅ 对象和数组中的嵌套引用
• ✅ 循环引用（标记为 $circular: true）
• ✅ 缺失的引用（优雅回退到原始 $ref）

响应格式

响应格式：

{
  "success": true,
  "modelSlug": "black-forest-labs/flux-kontext-max/text-to-image",
  "owner": "black-forest-labs",
  "model": "flux-kontext-max",
  "endpoint": "text-to-image",
  "inputSchema": {
    "type": "object",
    "properties": {
      "prompt": {
        "type": "string",
        "description": "Text prompt for image generation"
      }
    },
    "required": ["prompt"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Request ID"
      },
      "status": {
        "type": "string",
        "description": "Request status"
      },
      "output": {
        "type": "object",
        "description": "Generated output"
      }
    }
  }
}

开发

运行测试

npm test

构建

npm run build

启动服务

npm start

配置

将 Sunra.ai API 密钥设置为环境变量：

export SUNRA_KEY="your-api-key-here"

或者在运行时使用 set-sunra-key 工具。

发布

要发布到 npm：

npm run build
npm publish

API 参考

详细的 API 文档请参阅 Sunra.ai API 文档。