Spiral MCP Server

This is a Model Context Protocol (MCP) server implementation for the Spiral API using Python. It provides a standardized interface for interacting with Spiral's language models.

Installation

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

Setup

Create and activate a virtual environment:

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

Install dependencies:

uv pip install -r requirements.txt

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

SPIRAL_API_KEY=your_api_key_here

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

Running the Server

Start the server:

python src/server.py

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

Testing the Tools

To test the MCP tools directly:

python src/test_tools.py

This will run tests for all available tools to verify their functionality.

MCP Tools

The server implements four powerful MCP tools:

list_models

Lists all available Spiral models 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

Generates text using a specified Spiral model.

Parameters:

model: The ID or slug of the Spiral model to use
prompt: The input text to generate from

Example:

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

generate_from_file

Generates text using a Spiral model with input from a file. This is useful for processing larger documents or maintaining consistent formatting.

Parameters:

model: The ID or slug of the Spiral model to use
file_path: Path to the file to use as input

Example:

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

generate_from_url

Generates text using a Spiral model with input from a URL. This tool can automatically extract article content from web pages.

Parameters:

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

Example:

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

Error Handling

The server handles various error cases including:

Invalid API key
Model not found
Input too long
Rate limit exceeded
URL fetch failures
File read errors
Server errors
Request timeouts

Each error returns a clear error message to help diagnose the issue.

Environment Variables

SPIRAL_API_KEY: Your Spiral API key (required)
PORT: Server port (optional, defaults to 3000)
TIMEOUT: Request timeout in seconds (optional, defaults to 30)

Features

Robust Error Handling: Comprehensive error handling and logging for all operations
Article Extraction: Smart extraction of article content from web pages
Flexible Input Sources: Support for text, files, and URLs as input
Async Operations: All operations are asynchronous for better performance
Type Safety: Full Pydantic type validation for all parameters
Logging: Detailed debug logging for troubleshooting