JosefVilestadGit/colonies-mcp

MCP ColonyOS Server

An MCP (Model Context Protocol) server for interacting with ColonyOS, a distributed meta-orchestrator framework for seamless execution of computational workloads across heterogeneous platforms.

What is ColonyOS?

ColonyOS is a distributed computing framework that creates Compute Continuums across cloud, edge, HPC, IoT devices, and more. It uses a broker-based architecture where:

• Colonies are distributed runtime environments consisting of networked executors
• Executors are distributed workers that pull and execute processes
• Processes are computational workloads with states (WAITING → RUNNING → SUCCESS/FAILED)
• FunctionSpecs define what computation to run and execution conditions

Features

This MCP server provides tools to interact with ColonyOS:

Process Management

• submit_function_spec - Submit computational tasks to the colony
• get_process - Get detailed information about a process
• list_waiting_processes - List processes waiting for execution
• list_running_processes - List currently running processes
• list_successful_processes - List completed successful processes
• list_failed_processes - List failed processes
• close_process_successful - Mark a running process as successfully completed
• close_process_failed - Mark a running process as failed with an error message
• delete_process - Permanently delete a process and its history

Executor Management

• list_executors - List all registered executors
• get_executor - Get detailed executor information
• add_executor - Register a new executor
• approve_executor - Approve an executor to start processing
• list_functions_by_executor - List all functions that a specific executor can handle
• list_functions_by_colony - List all available functions across all executors in the colony

Colony Management

• get_colony - Get information about the current colony

Development Server Management

• start_colonies_dev_server - Start a local ColonyOS development environment with Docker
• stop_colonies_dev_server - Stop the development server and optionally remove volumes
• check_colonies_server_status - Check if the server is running and healthy
• get_colonies_logs - View logs from server containers

Executor Runtime Management

• start_python_executor - Start a Python executor that connects to the dev server
• stop_python_executor - Stop a running Python executor
• list_running_executors - List all executors started by this MCP server

Security & Key Management

• generate_keypair - Generate a new Ed25519 keypair (ID and private key) for colonies, executors, users, or servers

Installation

1. Clone this repository:

cd /home/ayag/git/mcp-colonies

2. Install dependencies:

pip install -e .

Or install from PyPI (when published):

pip install mcp-colonies

Configuration

The server requires ColonyOS credentials to be configured via environment variables.

1. Copy the example environment file:

cp .env.example .env

2. Edit .env with your ColonyOS credentials:

# ColonyOS Server Configuration
COLONIES_SERVER_HOST=localhost
COLONIES_SERVER_PORT=8080
COLONIES_SERVER_TLS=false

# Colony Configuration
COLONIES_COLONY_NAME=your_colony_name
COLONIES_COLONY_PRVKEY=your_colony_private_key

# Executor Configuration (optional)
COLONIES_EXECUTOR_NAME=your_executor_name
COLONIES_EXECUTOR_PRVKEY=your_executor_private_key

Quick Start: Local Development Environment

The easiest way to get started is to use the built-in dev server management tools:

1. Clone the ColonyOS repository (if not already done):

cd ~/git  # or your preferred location
git clone https://github.com/colonyos/colonies.git

2. Set up the .env file in the colonies repository:

cd ~/git/colonies
cp .env.example .env
# Edit .env if needed - the defaults work for local development

3. Start the dev server using Claude: Once the MCP server is configured in Claude Desktop (see below), you can simply ask Claude:

Start the ColonyOS development server

Claude will use the start_colonies_dev_server tool to automatically start all services (TimescaleDB, MinIO, Colonies server) using Docker Compose.

4. Check server status:

Check if the ColonyOS server is running

Alternative: Manual Setup

If you prefer manual setup or need custom configuration:

1. Start a ColonyOS server:

cd ~/git/colonies
docker-compose up -d

2. The dev environment automatically creates:

   • A colony (check .env for COLONIES_COLONY_NAME and credentials)
   • Docker executors via the reconciler

3. Use these credentials in your MCP server configuration

See the ColonyOS documentation for more details.

Usage with Claude Desktop

Add this server to your Claude Desktop configuration:

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "colonies": {
      "command": "python",
      "args": ["-m", "mcp_colonies.server"],
      "env": {
        "COLONIES_SERVER_HOST": "localhost",
        "COLONIES_SERVER_PORT": "8080",
        "COLONIES_SERVER_TLS": "false",
        "COLONIES_COLONY_NAME": "your_colony_name",
        "COLONIES_COLONY_PRVKEY": "your_colony_private_key",
        "COLONIES_EXECUTOR_NAME": "your_executor_name",
        "COLONIES_EXECUTOR_PRVKEY": "your_executor_private_key"
      }
    }
  }
}

Linux

Edit ~/.config/Claude/claude_desktop_config.json with the same configuration.

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json with the same configuration.

Example Usage

Once configured, you can use Claude to interact with your ColonyOS cluster:

Manage Development Server:

Start the ColonyOS development server
Check the status of the ColonyOS server
Show me the logs from the colonies-server
Stop the ColonyOS development server

Generate Keypairs:

Generate a keypair for a new colony
Generate a keypair for an executor

Start an Executor:

Start a Python executor
List running executors
Submit a function spec with func_name "echo" and executor_type "python-executor" with kwargs {"message": "Hello from Claude!"}
Stop the Python executor

Submit a task:

Submit a function spec with:
- func_name: "process_image"
- executor_type: "gpu-worker"
- kwargs: {"image_url": "https://example.com/image.jpg", "model": "yolo"}
- max_exec_time: 300

Check process status:

Get the status of process abc123def456

List executors:

Show me all executors in the colony

Discover available functions:

What functions are available in the colony?
What functions can the executor "mcp-executor" handle?
List all functions by colony

Monitor running tasks:

List all currently running processes

Manage process lifecycle:

Mark process abc123 as successful
Mark process def456 as failed with error message "Timeout exceeded"
Delete process xyz789

Development

Running in Development Mode

1. Install development dependencies:

pip install -e ".[dev]"

2. Run the server directly:

python -m mcp_colonies.server

Testing

pytest tests/

Code Formatting

black src/
ruff check src/

Architecture

This MCP server wraps the official pycolonies Python SDK to provide MCP tools for ColonyOS operations. It:

1. Initializes a ColonyOS client from environment variables
2. Exposes ColonyOS operations as MCP tools
3. Handles authentication using Ed25519 cryptographic signing
4. Returns formatted results to Claude

Use Cases

With this MCP server, Claude can help you:

• Monitor distributed workflows - Check status of tasks across your compute continuum
• Submit computational jobs - Deploy ML/AI workloads, data processing pipelines
• Manage executors - Register and approve new workers in your colony
• Debug failures - Investigate failed processes and their error messages
• Orchestrate complex workflows - Submit multi-step computational pipelines

Links

• ColonyOS GitHub
• pycolonies SDK
• ColonyOS Documentation
• Model Context Protocol

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.