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

Setup

1. Create and activate a virtual environment:

2. Install dependencies:

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

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

Running the Server

Start the server:

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:

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:

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:

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:

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:

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