Spiral Writer

🚀 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 類型驗證
• 日誌記錄：詳細的調試日誌，便於故障排除