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
.envfile 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 useprompt: 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 usefile_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 useurl: URL to fetch content fromextract_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