Spiral Writer

🚀 Spiral MCP Server

This is a Model Context Protocol (MCP) server implemented for the Spiral API, written in Python. It provides a standardized interface to interact with Spiral's language models.

🚀 Quick Start

📦 Installation

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

⚙️ Setup

1. Create and activate a virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Windows, use `venv\Scripts\activate`

2. Install dependencies:

uv pip install -r requirements.txt

3. Create a .env file in the root directory and add your Spiral API key:

SPIRAL_API_KEY=your_api_key_here

You can obtain your API key from https://app.spiral.computer/api.

▶️ Run the Server

Start the server:

python src/server.py

The server will run on port 3000 by default. You can change the port by setting the PORT environment variable.

🧪 Testing Tools

To test the MCP tools directly:

python src/test_tools.py

This will test all available tools to verify their functionality.

💻 Usage Examples

🛠️ MCP Tools

The server implements four powerful MCP tools:

list_models

List all available Spiral models along with their capabilities and metadata.

Example response:

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

generate

Generate text using a specified Spiral model.

Parameters:

• model: The ID or alias of the Spiral model to use
• prompt: The input text

Example:

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

generate_from_file

Generate text from a Spiral model using the content of a file. This is useful for handling large documents or maintaining consistent formatting.

Parameters:

• model: The ID or alias of the Spiral model to use
• file_path: The path to the input file

Example:

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

generate_from_url

Generate text from a Spiral model using the content from a URL. This tool can automatically extract the article content from a web page.

Parameters:

• model: The ID or alias of the Spiral model to use
• url: The URL to fetch the content from
• extract_article: Whether to extract the article content or use the full HTML (default: true)

Example:

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

🔧 Technical Details

❌ Error Handling

The server handles various error conditions, including:

• Invalid API key
• Model not found
• Input too long
• Request rate limit exceeded
• URL fetch failure
• File read error
• Server error
• Request timeout

Each error returns a clear error message to aid in diagnosing the problem.

🌐 Environment Variables

• SPIRAL_API_KEY: Your Spiral API key (required)
• PORT: The server port (optional, default is 3000)
• TIMEOUT: The request timeout in seconds (default is 30)

✨ Features

• Powerful Error Handling: Comprehensive error handling and logging covering all operations
• Article Extraction: Intelligent extraction of article content from web pages
• Flexible Input Sources: Supports text, files, and URLs as inputs
• Asynchronous Operations: All operations are asynchronous for improved performance
• Type Safety: All parameters are type-validated by Pydantic
• Logging: Detailed debug logs for easy troubleshooting