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
- Create and activate a virtual environment:
- Install dependencies:
- Create a
.envfile 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
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
- Create and activate a virtual environment:
- Install dependencies:
- Create a
.envfile 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