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
Metadata
Release files for iflow-mcp_jxnl-spiral-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_jxnl_spiral_mcp-0.1.0.tar.gz | 7.4 kB | Without provenance | Details for iflow_mcp_jxnl_spiral_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_jxnl_spiral_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_jxnl_spiral_mcp-0.1.0-py3-none-any.whl |
Total release size: 13.9 kB
Release files / iflow_mcp_jxnl_spiral_mcp-0.1.0.tar.gz
| Download URL | iflow_mcp_jxnl_spiral_mcp-0.1.0.tar.gz |
|---|---|
| Size | 7.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
09a64dad9feaa1f990dc889c4cc5cbc6390e7396019d5a44474fdcbed30c94db
|
|
BLAKE2b-256 checksum How to use checksums |
a2b439fa58c82d65dcc1e4b1ca98123df89c4d5dcabdced538b571bb13833780
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_jxnl_spiral_mcp-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_jxnl_spiral_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 6.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6de6bd485581634734600d78ba49e03a7666f6604eabf0dc719f0ed9ad923553
|
|
BLAKE2b-256 checksum How to use checksums |
874e9232163b35a578f8693118f21d53b9ef2b6e5d9b8f31db6201acd6e78b14
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_jxnl-spiral-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.