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 containers (Docker, Podman, or Singularity/Apptainer — see COALA_CONTAINER_ENGINE in MCP_CONFIG.md)
• Dynamic Package Installation:
  • Python: Uses uv for fast package installation
  • R: Based on bioconductor/bioconductor_docker (BiocManager for CRAN and Bioconductor packages)
• File Mounting: Bind-mount local files and directories into containers
• GPU Passthrough: Opt-in NVIDIA GPU access per call (gpu: true) or globally (COALA_GPU=1) — see MCP_CONFIG.md
• Pre-installed packages: Python image includes numpy, pandas, scipy, matplotlib, scikit-learn, seaborn; R image includes tidyverse
• MCP Integration: Exposes coala_python_executor and coala_r_executor tools for LLM interaction

Prerequisites

• Docker (default), Podman, or Singularity/Apptainer — set COALA_CONTAINER_ENGINE if not using Docker (see MCP_CONFIG.md)
• Python 3.11 or higher
• Executor images available locally or pullable (Docker/Podman: see Building Docker Images; Singularity/Apptainer: pulled on first run)

Installation

# Install dependencies
uv pip install -e .

# Or using pip
pip install -e .

Docker Images

Executor images (used by the MCP tools):

• coala-runtime-python:latest
• coala-runtime-r:latest

On MCP server start (Docker/Podman): if either image is missing locally, coala-runtime builds them from this repo (docker/build.sh). Set MCP cwd to the clone so the Dockerfiles are found.

coala-runtime          # build missing images, then start MCP server
coala-runtime --pull   # pull hubentu/* from Docker Hub, retag as coala-runtime-*:latest
coala-runtime --build  # force rebuild, then start
coala-runtime build    # build only (no MCP server)

Manual build (same tags as above):

./docker/build.sh

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 to build images without starting the server; use --pull on start to fetch from Docker Hub instead of building.

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, scipy, matplotlib, scikit-learn, seaborn. 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)
• gpu (optional): If true, expose the host's NVIDIA GPUs to the container (--gpus all on Docker/Podman, --nv on Singularity/Apptainer). Omit to follow COALA_GPU (default off). The default images have no CUDA libraries; add e.g. torch via packages or use a CUDA docker_image

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 Bioconductor Docker (BiocManager for extra packages).

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)
• gpu (optional): If true, expose the host's NVIDIA GPUs to the container (--gpus all on Docker/Podman, --nv on Singularity/Apptainer). Omit to follow COALA_GPU (default off). The default images have no CUDA libraries; add e.g. torch via packages or use a CUDA docker_image

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