Spiral MCP Server

by jxnl

Integrations

  • Supports loading environment variables from .env files for configuration management

  • Provides type validation and safety for all parameters using Pydantic models

  • Implemented in Python, allowing for development and extension in the Python ecosystem

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

  1. Create and activate a virtual environment:
python3 -m venv venv source venv/bin/activate # On Windows, use `venv\Scripts\activate`
  1. Install dependencies:
uv pip install -r requirements.txt
  1. 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
-
security - not tested
F
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.

  1. Installation
    1. Setup
      1. Running the Server
        1. Testing the Tools
          1. MCP Tools
            1. list_models
            2. generate
            3. generate_from_file
            4. generate_from_url
          2. Error Handling
            1. Environment Variables
              1. Features

                Related MCP Servers

                • 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
                  • Linux
                  • Apple
                • 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
                  123
                  2
                  TypeScript
                  MIT License
                  • Apple
                  • Linux
                • -
                  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
                • -
                  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

                ID: ekws8l4sjy