Spiral MCP 服务器

这是为 Spiral API 实现的 Model Context Protocol (MCP) 服务器，使用 Python 编写。它提供了一个标准化接口来与 Spiral 的语言模型进行交互。

安装

mcp install src/server.py --name "spiral-writing-tool" --with pydantic --with requests --with beautifulsoup4 --with httpx

设置

1. 创建并激活虚拟环境：

python3 -m venv venv
source venv/bin/activate  # 在 Windows 上，使用 `venv\Scripts\activate`

2. 安装依赖项：

uv pip install -r requirements.txt

3. 在根目录下创建一个 .env 文件，并添加你的 Spiral API 密钥：

SPIRAL_API_KEY=your_api_key_here

你可以从 https://app.spiral.computer/api 获取你的 API 密钥。

运行服务器

启动服务器：

python src/server.py

服务器将默认运行在 3000 端口。你可以通过设置 PORT 环境变量来更改端口。

测试工具

要直接测试 MCP 工具：

python src/test_tools.py

这将对所有可用工具进行测试，以验证其功能。

MCP 工具

服务器实现了四个强大的 MCP 工具：

list_models

列出所有可用的 Spiral 模型及其功能和元数据。

示例响应：

{
    "models": [
        {
            "id": "model-id",
            "name": "model-name",
            "description": "Model description",
            "input_format": "text",
            "output_format": "text",
            "capabilities": {
                "completion": true
            }
        }
    ]
}

generate

使用指定的 Spiral 模型生成文本。

参数：

• model: 要使用的 Spiral 模型的 ID 或别名
• prompt: 作为输入的文本

示例：

{
    "model": "model_id_or_slug",
    "prompt": "Your input text here"
}

generate_from_file

使用一个文件中的内容从 Spiral 模型生成文本。这对于处理较大的文档或保持格式一致很有用。

参数：

• model: 要使用的 Spiral 模型的 ID 或别名
• file_path: 作为输入的文件路径

示例：

{
    "model": "model_id_or_slug",
    "file_path": "path/to/your/input.txt"
}

generate_from_url

从 URL 中的内容使用 Spiral 模型生成文本。此工具可以自动提取网页中的文章内容。

参数：

• model: 要使用的 Spiral 模型的 ID 或别名
• url: 要获取内容的 URL
• extract_article: 是否提取文章内容或使用完整的 HTML（默认：true）

示例：

{
    "model": "model_id_or_slug",
    "url": "https://example.com/article",
    "extract_article": true
}

错误处理

服务器处理了各种错误情况，包括：

• 无效的 API 密钥
• 模型未找到
• 输入过长
• 请求速率限制 exceeded
• URL 获取失败
• 文件读取错误
• 服务器错误
• 请求超时

每个错误都会返回一个清晰的错误消息，以帮助诊断问题。

环境变量

• SPIRAL_API_KEY: 你的 Spiral API 密钥（必需）
• PORT: 服务器端口（可选，默认为 3000）
• TIMEOUT: 请求超时时间（以秒为单位，默认为 30）

功能

• 强大的错误处理：全面的错误处理和日志记录，涵盖所有操作
• 文章提取：智能提取网页中的文章内容
• 灵活的输入源：支持文本、文件和 URL 作为输入
• 异步操作：所有操作均为异步，以提高性能
• 类型安全：所有参数均经过 Pydantic 类型验证
• 日志记录：详细的调试日志，便于故障排除