Metadata-Version: 2.4
Name: coala-runtime
Version: 0.1.0
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: containers,docker,mcp,python,r
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: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: docker>=7.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
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 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](#building-docker-images))

## Installation

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

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

Manual build (same as `--build`):

```bash
./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:

```bash
coala-runtime
```

Or with the module runner:

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

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