Spiral

Provides an MCP interface to list Spiral models and generate text from local Python-based services.

python

16

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "jxnl-spiral-mcp": {
      "command": "python",
      "args": [
        "src/server.py"
      ],
      "env": {
        "PORT": "3000",
        "TIMEOUT": "30",
        "SPIRAL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

You run an MCP server that provides a structured, asynchronous interface to Spiral’s language models. It lets you list available models and generate text using specific models, with input coming from text, files, or URLs, all through a consistent MCP workflow. This enables you to build tools that query, compose, and extract model outputs in a scalable way.

How to use

To use this MCP server, start the server locally and connect your MCP client to its runtime. Your client can list available models, generate text with a chosen model, or feed input from a file or URL. All operations are designed to be asynchronous and type-safe, with clear error messages if something goes wrong.

Typical usage patterns include discovering the models you can work with, then generating text based on a given prompt. You can route content from documents you already have, or fetch and extract article content from the web for downstream processing.

How to install

# 1) Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows, use `venv\Scripts\activate`

# 2) Install dependencies
uv pip install -r requirements.txt

# 3) Create a .env file and set your Spiral API key
# Replace YOUR_API_KEY with your real key
SPIRAL_API_KEY=YOUR_API_KEY

Start the MCP server locally

python src/server.py

Notes and tips

The server runs on port 3000 by default. Change the port by setting the PORT environment variable if needed.

# Example to start on a different port (adjust as needed)
PORT=4000 python src/server.py

Additional configuration and usage notes

Environment variables you will use include the Spiral API key (SPIRAL_API_KEY), the server port (PORT), and an optional request timeout (TIMEOUT). Ensure your environment is secure and your API key is not exposed in logs or verbose output.

Testing the tools locally helps confirm everything is wired correctly. You can run the test suite dedicated to the MCP tools to verify that model listing and generation endpoints behave as expected.

Troubleshooting tips

Invalid API key: Verify that SPIRAL_API_KEY is set correctly and has the necessary permissions.
Model not found or input too long: Ensure you request a valid model ID and that your input content complies with model limits.
Port or connection errors: If the port is occupied or you cannot reach the server, check your firewall rules and ensure PORT is set correctly when starting the server.

Tools and capabilities overview

This server exposes a set of MCP tools to interact with Spiral models. You can list available models and perform text generation with a chosen model, either from plain text, a file, or content fetched from a URL.

Available tools

list_models

Lists all available Spiral models with their capabilities and metadata.

generate

Generates text using a specified Spiral model given a model identifier and a prompt.

generate_from_file

Generates text using a Spiral model with input sourced from a file.

generate_from_url

Generates text using a Spiral model with input sourced from a URL, with optional article extraction.