https://github.com/jxnl/spiral-mcp
https://github.com/jxnl/spiral-mcp
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/jxnl/spiral-mcp
- Owner: jxnl
- Created: 2025-03-19T20:47:15.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-03-19T20:48:57.000Z (3 months ago)
- Last Synced: 2025-03-19T21:40:09.922Z (3 months ago)
- Language: Python
- Size: 0 Bytes
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- mcp-index - Spiral Writing Tool - Interact with Spiral's language models to generate text from various input sources while offering functionality for model listing, text generation, and article extraction to support enhanced writing tasks. (Content Creation)
README
# 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
```bash
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:
```bash
python3 -m venv venv
source venv/bin/activate # On Windows, use `venv\Scripts\activate`
```
2. Install dependencies:
```bash
uv pip install -r requirements.txt
```
3. Create a `.env` file in the root directory and add your Spiral API key:
```bash
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:
```bash
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:
```bash
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:
```python
{
"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:
```python
{
"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:
```python
{
"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:
```python
{
"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