Metadata-Version: 2.5
Name: coala-runtime
Version: 0.1.5
Summary: MCP server for executing Python and R scripts in containerized environments
Project-URL: Homepage, https://github.com/coala-info/coala-runtime
Project-URL: Repository, https://github.com/coala-info/coala-runtime
Project-URL: Issues, https://github.com/coala-info/coala-runtime/issues
Author: Qiang
License-Expression: MIT
Keywords: apptainer,containers,docker,mcp,podman,python,r,singularity
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.11
Requires-Dist: docker>=7.1.0
Requires-Dist: mcp<2,>=1.12.0
Requires-Dist: pydantic>=2.10.0
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Provides-Extra: xcrunner
Requires-Dist: xcrunner>=0.1.3; extra == 'xcrunner'
Description-Content-Type: text/markdown

# 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](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
- **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](MCP_CONFIG.md))
- Python 3.11 or higher
- Executor images available locally or pullable (Docker/Podman: see [Building Docker Images](#building-docker-images); Singularity/Apptainer: pulled on first run)

## Installation

```bash
# 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.

```bash
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):

```bash
./docker/build.sh
```

## Usage

### As MCP Server

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

```bash
coala-runtime
```

Or with the module runner:

```bash
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](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)

**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)

**Output:** Same as `coala_python_executor`

## Development

```bash
# 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
