Coala Runtime

An MCP (Model Context Protocol) server for executing Python and R scripts in containerized environments with support for dynamic package installation and file mounting.

Features

• Containerized Execution: Run Python and R scripts in isolated Docker containers
• Dynamic Package Installation:
  • Python: Uses uv for fast package installation
  • R: Uses r2u and BiocManager for CRAN and Bioconductor packages
• File Mounting: Bind-mount local files and directories into containers
• Pre-installed packages: Python image includes numpy, pandas, matplotlib; R image includes tidyverse
• MCP Integration: Exposes coala_python_executor and coala_r_executor tools for LLM interaction

Prerequisites

• Docker installed and running
• Python 3.11 or higher
• Built Docker images (see Building Docker Images)

Installation

# Install dependencies
uv pip install -e .

# Or using pip
pip install -e .

Docker Images

By default, the server pulls the executor images from Docker Hub if they are not present locally:

• hubentu/coala-runtime-python:latest → tagged as coala-runtime-python:latest
• hubentu/coala-runtime-r:latest → tagged as coala-runtime-r:latest

To build the images locally instead (e.g. for development or custom Dockerfiles), run with --build or build manually:

coala-runtime --build
# or
python -m coala_runtime --build

Manual build (same as --build):

./docker/build.sh

This creates:

• coala-runtime-python:latest - Python executor image
• coala-runtime-r:latest - R executor image

Usage

As MCP Server

The server can be run as an MCP server for LLM integration:

coala-runtime

Or with the module runner:

python -m coala_runtime

Use coala-runtime --build (or python -m coala_runtime --build) to build Docker images locally before starting.

Configuration

See MCP_CONFIG.md for detailed configuration instructions for various MCP clients (Cursor, Claude Desktop, etc.).

Tool Schemas

coala_python_executor

Executes Python scripts in a containerized environment with uv package management.

Input:

• script or script_file (one required): Inline Python code or host path to a .py file
• packages (optional): Additional packages to install via uv. The image already includes numpy, pandas, matplotlib. Can include version specifiers (e.g., 'requests>=2.31.0')
• conda_packages (optional, Python only): Conda specs installed before pip/uv (requires conda/mamba in the image)
• docker_image (optional): Docker image to run instead of the default Coala Python image (e.g. python:3.12-slim, quay.io/biocontainers/...)
• skip_package_install (optional): If true, skip install step (typical when docker_image already has all dependencies)
• input_files (optional): Map of container paths to host paths for bind-mounting (e.g., {'/input/data.csv': '/host/path/data.csv'})
• timeout (optional): Execution timeout in seconds (default: 300, 0 = no timeout, max: 3600)

Output:

• success: Whether execution succeeded
• exit_code: Process exit code (0 = success)
• stdout: Standard output from script
• stderr: Standard error output
• output_files: List of output file paths (for files/images generated by the script)
• output_data: Echoed output for strings/numbers (captured via print statements)
• container_logs: Full container execution logs including package installation
• execution_time: Execution time in seconds

coala_r_executor

Executes R scripts in a containerized environment with r2u and BiocManager.

Input:

• script or script_file (one required): Inline R code or host path to an .R file
• packages (optional): Additional R packages to install. Use 'bioc::package_name' format for Bioconductor packages. The image already includes tidyverse. Examples: ['ggplot2', 'dplyr', 'bioc::Biobase']
• docker_image (optional): Docker image to run instead of the default Coala R image (must provide Rscript on PATH)
• skip_package_install (optional): If true, skip install step (typical when docker_image already has all dependencies)
• input_files (optional): Map of container paths to host paths for bind-mounting (e.g., {'/input/data.csv': '/host/path/data.csv'})
• timeout (optional): Execution timeout in seconds (default: 300, 0 = no timeout, max: 3600)

Output: Same as coala_python_executor

Development

# Install with dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src tests

# Lint code
ruff check src tests

License

MIT