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

This server cannot be installed

security - not tested

license - not found

quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A Model Context Protocol server implementation that provides a standardized interface for interacting with Spiral's language models, offering tools to generate text from prompts, files, or web URLs.

Related Resources

Reddit Discussion about this server

Related MCP Servers

mcp-server-code-assist
abhishekbhakat
A
security
A
license
A
quality
A Model Context Protocol server that provides tools for code modification and generation via Large Language Models, allowing users to create, modify, rewrite, and delete files using structured XML instructions.
Last updated -
12
Python
MIT License
NPM Sentinel MCP
Nekzus
A
security
A
license
A
quality
A Model Context Protocol server providing utility tools for development and testing, offering functionalities like personalized greetings, random card drawing, and datetime formatting with an extensible architecture.
Last updated -
19
464
2
TypeScript
MIT License
MCP Conversation Server
bsmi021
-
security
A
license
-
quality
A Model Context Protocol server implementation that provides a standardized interface for applications to interact with OpenRouter's language models through a unified conversation management system.
Last updated -
TypeScript
MIT License
MCP Server Basic Example
krishnaik06
-
security
-
license
-
quality
A simple implementation of a Model Context Protocol server that demonstrates core functionality including mathematical tools (add, subtract) and personalized greeting resources.
Last updated -
3
Python
GPL 3.0

View all related MCP servers

Spiral MCP Server