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

API キーは、https://app.spiral.computer/api から取得できます。

▶️ サーバーの起動

サーバーを起動します：

python src/server.py

サーバーはデフォルトで 3000 ポートで動作します。PORT 環境変数を設定することでポートを変更できます。

🧪 テストツール

MCP ツールを直接テストするには：

python src/test_tools.py

これにより、すべての利用可能なツールがテストされ、機能が検証されます。

💻 MCP ツール

サーバーは 4 つの強力な 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 モデルからテキストを生成します。このツールは、Web ページの記事内容を自動的に抽出できます。

パラメータ：

• model: 使用する Spiral モデルの ID またはエイリアス
• url: 内容を取得する URL
• extract_article: 記事内容を抽出するか、完全な HTML を使用するか（デフォルト: true）

例：

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

❌ エラー処理

サーバーは、以下を含むさまざまなエラー状況を処理します：

• 無効な API キー
• モデルが見つからない
• 入力が長すぎる
• リクエストレート制限超過
• URL 取得失敗
• ファイル読み取りエラー
• サーバーエラー
• リクエストタイムアウト

各エラーは、問題の診断を支援するために明確なエラーメッセージを返します。

🌐 環境変数

• SPIRAL_API_KEY: あなたの Spiral API キー（必須）
• PORT: サーバーのポート（オプション、デフォルトは 3000）
• TIMEOUT: リクエストのタイムアウト時間（秒単位、デフォルトは 30）

✨ 主な機能

• 強力なエラー処理：すべての操作に対する包括的なエラー処理とログ記録
• 記事抽出：Web ページからの記事内容のスマートな抽出
• 柔軟な入力ソース：テキスト、ファイル、URL を入力ソースとしてサポート
• 非同期操作：すべての操作が非同期で行われ、パフォーマンスが向上します
• 型安全：すべてのパラメータが Pydantic で型検証されます
• ログ記録：詳細なデバッグログが記録され、トラブルシューティングが容易になります