coala-runtime 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. coala_runtime-0.1.0/.github/workflows/release.yml +31 -0
  2. coala_runtime-0.1.0/.gitignore +60 -0
  3. coala_runtime-0.1.0/AGENTS.md +27 -0
  4. coala_runtime-0.1.0/MCP_CONFIG.md +178 -0
  5. coala_runtime-0.1.0/PKG-INFO +164 -0
  6. coala_runtime-0.1.0/README.md +135 -0
  7. coala_runtime-0.1.0/docker/Dockerfile.python +33 -0
  8. coala_runtime-0.1.0/docker/Dockerfile.r +44 -0
  9. coala_runtime-0.1.0/docker/README.md +66 -0
  10. coala_runtime-0.1.0/docker/build.sh +37 -0
  11. coala_runtime-0.1.0/pyproject.toml +57 -0
  12. coala_runtime-0.1.0/skills/SKILL.md +112 -0
  13. coala_runtime-0.1.0/src/coala_runtime/__init__.py +3 -0
  14. coala_runtime-0.1.0/src/coala_runtime/__main__.py +56 -0
  15. coala_runtime-0.1.0/src/coala_runtime/runtime/__init__.py +1 -0
  16. coala_runtime-0.1.0/src/coala_runtime/runtime/container_manager.py +207 -0
  17. coala_runtime-0.1.0/src/coala_runtime/runtime/docker_images.py +123 -0
  18. coala_runtime-0.1.0/src/coala_runtime/runtime/executor_base.py +612 -0
  19. coala_runtime-0.1.0/src/coala_runtime/runtime/file_handler.py +84 -0
  20. coala_runtime-0.1.0/src/coala_runtime/server.py +692 -0
  21. coala_runtime-0.1.0/src/coala_runtime/tools/__init__.py +1 -0
  22. coala_runtime-0.1.0/src/coala_runtime/tools/python_executor.py +207 -0
  23. coala_runtime-0.1.0/src/coala_runtime/tools/r_executor.py +185 -0
  24. coala_runtime-0.1.0/src/coala_runtime/utils/__init__.py +1 -0
  25. coala_runtime-0.1.0/src/coala_runtime/utils/output_parser.py +124 -0
  26. coala_runtime-0.1.0/tests/README.md +47 -0
  27. coala_runtime-0.1.0/tests/scripts/boxplot_script.py +42 -0
  28. coala_runtime-0.1.0/tests/scripts/pdf_extraction_script.py +37 -0
  29. coala_runtime-0.1.0/tests/scripts/venn_diagram_script.R +23 -0
  30. coala_runtime-0.1.0/tests/test_executor_models.py +59 -0
  31. coala_runtime-0.1.0/tests/test_prune_install_list.py +71 -0
  32. coala_runtime-0.1.0/tests/test_python_executor_install.py +90 -0
  33. coala_runtime-0.1.0/tests/test_r_executor_install.py +21 -0
  34. coala_runtime-0.1.0/tests/test_via_mcp.py +193 -0
  35. coala_runtime-0.1.0/uv.lock +974 -0
@@ -0,0 +1,31 @@
1
+ name: Build and publish to PyPI
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+ workflow_dispatch:
7
+
8
+ permissions:
9
+ contents: read
10
+ id-token: write
11
+
12
+ jobs:
13
+ build-and-publish:
14
+ name: Build and publish to PyPI
15
+ runs-on: ubuntu-latest
16
+ environment: pypi
17
+
18
+ steps:
19
+ - name: Checkout
20
+ uses: actions/checkout@v4
21
+
22
+ - name: Install uv
23
+ uses: astral-sh/setup-uv@v8.1.0
24
+ with:
25
+ python-version: "3.11"
26
+
27
+ - name: Build package
28
+ run: uv build
29
+
30
+ - name: Publish to PyPI
31
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,60 @@
1
+ # Python
2
+ .pypirc
3
+ __pycache__/
4
+ *.py[cod]
5
+ *$py.class
6
+ *.so
7
+ .Python
8
+ build/
9
+ develop-eggs/
10
+ dist/
11
+ downloads/
12
+ eggs/
13
+ .eggs/
14
+ lib/
15
+ lib64/
16
+ parts/
17
+ sdist/
18
+ var/
19
+ wheels/
20
+ *.egg-info/
21
+ .installed.cfg
22
+ *.egg
23
+ MANIFEST
24
+
25
+ # Virtual environments
26
+ venv/
27
+ env/
28
+ ENV/
29
+ .venv
30
+
31
+ # IDE
32
+ .vscode/
33
+ .idea/
34
+ *.swp
35
+ *.swo
36
+ *~
37
+ .DS_Store
38
+
39
+ # Testing
40
+ .pytest_cache/
41
+ .coverage
42
+ htmlcov/
43
+ .tox/
44
+
45
+ # Mypy
46
+ .mypy_cache/
47
+ .dmypy.json
48
+ dmypy.json
49
+
50
+ # Output directories
51
+ coala_output_*/
52
+
53
+ # Temporary files
54
+ *.tmp
55
+ *.log
56
+
57
+ # Docker
58
+ .dockerignore
59
+
60
+ .cursor
@@ -0,0 +1,27 @@
1
+ # Available Skills
2
+
3
+ This file is auto-generated by `/sync-cursor-framework`. Do not edit manually.
4
+
5
+ | Skill | Description | Location |
6
+ |-------|-------------|----------|
7
+ | **algorithmic-art** | Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations. | `.cursor/skills/algorithmic-art/SKILL.md` |
8
+ | **brand-guidelines** | Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | `.cursor/skills/brand-guidelines/SKILL.md` |
9
+ | **canvas-design** | Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | `.cursor/skills/canvas-design/SKILL.md` |
10
+ | **doc-coauthoring** | Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | `.cursor/skills/doc-coauthoring/SKILL.md` |
11
+ | **docx** | "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks" | `.cursor/skills/docx/SKILL.md` |
12
+ | **frontend-design** | Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics. | `.cursor/skills/frontend-design/SKILL.md` |
13
+ | **internal-comms** | A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.). | `.cursor/skills/internal-comms/SKILL.md` |
14
+ | **mcp-builder** | Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | `.cursor/skills/mcp-builder/SKILL.md` |
15
+ | **pdf** | Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form or programmatically process, generate, or analyze PDF documents at scale. | `.cursor/skills/pdf/SKILL.md` |
16
+ | **pptx** | "Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying or editing content, (3) Working with layouts, (4) Adding comments or speaker notes, or any other presentation tasks" | `.cursor/skills/pptx/SKILL.md` |
17
+ | **skill-creator** | Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations. | `.cursor/skills/skill-creator/SKILL.md` |
18
+ | **slack-gif-creator** | Knowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | `.cursor/skills/slack-gif-creator/SKILL.md` |
19
+ | **template-skill** | Replace with description of the skill and when Claude should use it. | `.cursor/skills/template/SKILL.md` |
20
+ | **theme-factory** | Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly. | `.cursor/skills/theme-factory/SKILL.md` |
21
+ | **webapp-testing** | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. | `.cursor/skills/webapp-testing/SKILL.md` |
22
+ | **web-artifacts-builder** | Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts. | `.cursor/skills/web-artifacts-builder/SKILL.md` |
23
+ | **xlsx** | "Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. When Claude needs to work with spreadsheets (.xlsx, .xlsm, .csv, .tsv, etc) for: (1) Creating new spreadsheets with formulas and formatting, (2) Reading or analyzing data, (3) Modify existing spreadsheets while preserving formulas, (4) Data analysis and visualization in spreadsheets, or (5) Recalculating formulas" | `.cursor/skills/xlsx/SKILL.md` |
24
+
25
+ ## Usage
26
+
27
+ Load a skill: `Load the **[skill-name]** skill.`
@@ -0,0 +1,178 @@
1
+ # MCP Server Configuration
2
+
3
+ This document explains how to configure the Coala Runtime MCP server in various MCP client applications.
4
+
5
+ ## Prerequisites
6
+
7
+ 1. Build the Docker images:
8
+ ```bash
9
+ ./docker/build.sh
10
+ ```
11
+
12
+ 2. Install the Python package:
13
+ ```bash
14
+ uv pip install -e .
15
+ # or
16
+ pip install -e .
17
+ ```
18
+
19
+ ## Configuration Examples
20
+
21
+ ### Cursor IDE
22
+
23
+ Add the following to your Cursor settings (usually in `~/.cursor/mcp.json` or via Settings → MCP).
24
+
25
+ With the package installed, you can run the `coala-runtime` command:
26
+
27
+ ```json
28
+ {
29
+ "mcpServers": {
30
+ "coala-runtime": {
31
+ "command": "coala-runtime",
32
+ "args": [],
33
+ "cwd": "/path/to/coala-runtime"
34
+ }
35
+ }
36
+ }
37
+ ```
38
+
39
+ Or with `uv run` from the project directory:
40
+
41
+ ```json
42
+ {
43
+ "mcpServers": {
44
+ "coala-runtime": {
45
+ "command": "uv",
46
+ "args": [
47
+ "run",
48
+ "--directory",
49
+ "/path/to/coala-runtime",
50
+ "coala-runtime"
51
+ ]
52
+ }
53
+ }
54
+ }
55
+ ```
56
+
57
+ Or with `python -m`:
58
+
59
+ ```json
60
+ {
61
+ "mcpServers": {
62
+ "coala-runtime": {
63
+ "command": "python",
64
+ "args": ["-m", "coala_runtime"],
65
+ "cwd": "/path/to/coala-runtime"
66
+ }
67
+ }
68
+ }
69
+ ```
70
+
71
+ ### Claude Desktop
72
+
73
+ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/.config/Claude/claude_desktop_config.json` (Linux):
74
+
75
+ ```json
76
+ {
77
+ "mcpServers": {
78
+ "coala-runtime": {
79
+ "command": "coala-runtime",
80
+ "args": []
81
+ }
82
+ }
83
+ }
84
+ ```
85
+
86
+ ### Generic MCP Client (via stdio)
87
+
88
+ The server uses stdio transport, so it can be configured in any MCP client that supports stdio servers:
89
+
90
+ ```json
91
+ {
92
+ "mcpServers": {
93
+ "coala-runtime": {
94
+ "command": "coala-runtime",
95
+ "args": []
96
+ }
97
+ }
98
+ }
99
+ ```
100
+
101
+ ## Using with uv
102
+
103
+ If you're using `uv` for Python management, you can use:
104
+
105
+ ```json
106
+ {
107
+ "mcpServers": {
108
+ "coala-runtime": {
109
+ "command": "uv",
110
+ "args": [
111
+ "run",
112
+ "--directory",
113
+ "/path/to/coala-runtime",
114
+ "coala-runtime"
115
+ ]
116
+ }
117
+ }
118
+ }
119
+ ```
120
+
121
+ ## Environment Variables
122
+
123
+ You can optionally set environment variables for the server:
124
+
125
+ ```json
126
+ {
127
+ "mcpServers": {
128
+ "coala-runtime": {
129
+ "command": "coala-runtime",
130
+ "args": [],
131
+ "env": {
132
+ "DOCKER_HOST": "unix:///var/run/docker.sock",
133
+ "LOG_LEVEL": "INFO"
134
+ }
135
+ }
136
+ }
137
+ }
138
+ ```
139
+
140
+ ## Verification
141
+
142
+ After configuring, restart your MCP client. The server should appear in the available tools list. You can verify by:
143
+
144
+ 1. Checking the MCP server logs in your client
145
+ 2. Listing available tools - you should see:
146
+ - `coala_python_executor`
147
+ - `coala_r_executor`
148
+
149
+ ## Troubleshooting
150
+
151
+ ### Docker not found
152
+ Ensure Docker is running and accessible:
153
+ ```bash
154
+ docker ps
155
+ ```
156
+
157
+ ### Module not found
158
+ Make sure the package is installed:
159
+ ```bash
160
+ cd /path/to/coala-runtime
161
+ uv pip install -e .
162
+ ```
163
+
164
+ ### Permission issues
165
+ Ensure the user running the MCP client has permission to:
166
+ - Access Docker socket
167
+ - Read/write to the workspace directory
168
+
169
+ ## Testing the Server
170
+
171
+ You can test the server directly:
172
+
173
+ ```bash
174
+ cd /path/to/coala-runtime
175
+ coala-runtime
176
+ ```
177
+
178
+ The server will communicate via stdio, so you won't see output unless you send MCP protocol messages.
@@ -0,0 +1,164 @@
1
+ Metadata-Version: 2.4
2
+ Name: coala-runtime
3
+ Version: 0.1.0
4
+ Summary: MCP server for executing Python and R scripts in containerized environments
5
+ Project-URL: Homepage, https://github.com/coala-info/coala-runtime
6
+ Project-URL: Repository, https://github.com/coala-info/coala-runtime
7
+ Project-URL: Issues, https://github.com/coala-info/coala-runtime/issues
8
+ Author: Qiang
9
+ License-Expression: MIT
10
+ Keywords: containers,docker,mcp,python,r
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Typing :: Typed
19
+ Requires-Python: >=3.11
20
+ Requires-Dist: docker>=7.0.0
21
+ Requires-Dist: mcp>=1.0.0
22
+ Requires-Dist: pydantic>=2.0.0
23
+ Provides-Extra: dev
24
+ Requires-Dist: black>=23.0.0; extra == 'dev'
25
+ Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
26
+ Requires-Dist: pytest>=7.0.0; extra == 'dev'
27
+ Requires-Dist: ruff>=0.1.0; extra == 'dev'
28
+ Description-Content-Type: text/markdown
29
+
30
+ # Coala Runtime
31
+
32
+ An MCP (Model Context Protocol) server for executing Python and R scripts in containerized environments with support for dynamic package installation and file mounting.
33
+
34
+ ## Features
35
+
36
+ - **Containerized Execution**: Run Python and R scripts in isolated Docker containers
37
+ - **Dynamic Package Installation**:
38
+ - Python: Uses `uv` for fast package installation
39
+ - R: Uses `r2u` and `BiocManager` for CRAN and Bioconductor packages
40
+ - **File Mounting**: Bind-mount local files and directories into containers
41
+ - **Pre-installed packages**: Python image includes numpy, pandas, matplotlib; R image includes tidyverse
42
+ - **MCP Integration**: Exposes `coala_python_executor` and `coala_r_executor` tools for LLM interaction
43
+
44
+ ## Prerequisites
45
+
46
+ - Docker installed and running
47
+ - Python 3.11 or higher
48
+ - Built Docker images (see [Building Docker Images](#building-docker-images))
49
+
50
+ ## Installation
51
+
52
+ ```bash
53
+ # Install dependencies
54
+ uv pip install -e .
55
+
56
+ # Or using pip
57
+ pip install -e .
58
+ ```
59
+
60
+ ## Docker Images
61
+
62
+ By default, the server **pulls** the executor images from Docker Hub if they are not present locally:
63
+
64
+ - `hubentu/coala-runtime-python:latest` → tagged as `coala-runtime-python:latest`
65
+ - `hubentu/coala-runtime-r:latest` → tagged as `coala-runtime-r:latest`
66
+
67
+ To **build** the images locally instead (e.g. for development or custom Dockerfiles), run with `--build` or build manually:
68
+
69
+ ```bash
70
+ coala-runtime --build
71
+ # or
72
+ python -m coala_runtime --build
73
+ ```
74
+
75
+ Manual build (same as `--build`):
76
+
77
+ ```bash
78
+ ./docker/build.sh
79
+ ```
80
+
81
+ This creates:
82
+ - `coala-runtime-python:latest` - Python executor image
83
+ - `coala-runtime-r:latest` - R executor image
84
+
85
+ ## Usage
86
+
87
+ ### As MCP Server
88
+
89
+ The server can be run as an MCP server for LLM integration:
90
+
91
+ ```bash
92
+ coala-runtime
93
+ ```
94
+
95
+ Or with the module runner:
96
+
97
+ ```bash
98
+ python -m coala_runtime
99
+ ```
100
+
101
+ Use `coala-runtime --build` (or `python -m coala_runtime --build`) to build Docker images locally before starting.
102
+
103
+ ### Configuration
104
+
105
+ See [MCP_CONFIG.md](MCP_CONFIG.md) for detailed configuration instructions for various MCP clients (Cursor, Claude Desktop, etc.).
106
+
107
+ ### Tool Schemas
108
+
109
+ #### `coala_python_executor`
110
+
111
+ Executes Python scripts in a containerized environment with uv package management.
112
+
113
+ **Input:**
114
+ - `script` or `script_file` (one required): Inline Python code or host path to a `.py` file
115
+ - `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')
116
+ - `conda_packages` (optional, Python only): Conda specs installed before pip/uv (requires conda/mamba in the image)
117
+ - `docker_image` (optional): Docker image to run instead of the default Coala Python image (e.g. `python:3.12-slim`, `quay.io/biocontainers/...`)
118
+ - `skip_package_install` (optional): If `true`, skip install step (typical when `docker_image` already has all dependencies)
119
+ - `input_files` (optional): Map of container paths to host paths for bind-mounting (e.g., {'/input/data.csv': '/host/path/data.csv'})
120
+ - `timeout` (optional): Execution timeout in seconds (default: 300, 0 = no timeout, max: 3600)
121
+
122
+ **Output:**
123
+ - `success`: Whether execution succeeded
124
+ - `exit_code`: Process exit code (0 = success)
125
+ - `stdout`: Standard output from script
126
+ - `stderr`: Standard error output
127
+ - `output_files`: List of output file paths (for files/images generated by the script)
128
+ - `output_data`: Echoed output for strings/numbers (captured via print statements)
129
+ - `container_logs`: Full container execution logs including package installation
130
+ - `execution_time`: Execution time in seconds
131
+
132
+ #### `coala_r_executor`
133
+
134
+ Executes R scripts in a containerized environment with r2u and BiocManager.
135
+
136
+ **Input:**
137
+ - `script` or `script_file` (one required): Inline R code or host path to an `.R` file
138
+ - `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']
139
+ - `docker_image` (optional): Docker image to run instead of the default Coala R image (must provide `Rscript` on `PATH`)
140
+ - `skip_package_install` (optional): If `true`, skip install step (typical when `docker_image` already has all dependencies)
141
+ - `input_files` (optional): Map of container paths to host paths for bind-mounting (e.g., {'/input/data.csv': '/host/path/data.csv'})
142
+ - `timeout` (optional): Execution timeout in seconds (default: 300, 0 = no timeout, max: 3600)
143
+
144
+ **Output:** Same as `coala_python_executor`
145
+
146
+ ## Development
147
+
148
+ ```bash
149
+ # Install with dev dependencies
150
+ uv pip install -e ".[dev]"
151
+
152
+ # Run tests
153
+ pytest
154
+
155
+ # Format code
156
+ black src tests
157
+
158
+ # Lint code
159
+ ruff check src tests
160
+ ```
161
+
162
+ ## License
163
+
164
+ MIT
@@ -0,0 +1,135 @@
1
+ # Coala Runtime
2
+
3
+ An MCP (Model Context Protocol) server for executing Python and R scripts in containerized environments with support for dynamic package installation and file mounting.
4
+
5
+ ## Features
6
+
7
+ - **Containerized Execution**: Run Python and R scripts in isolated Docker containers
8
+ - **Dynamic Package Installation**:
9
+ - Python: Uses `uv` for fast package installation
10
+ - R: Uses `r2u` and `BiocManager` for CRAN and Bioconductor packages
11
+ - **File Mounting**: Bind-mount local files and directories into containers
12
+ - **Pre-installed packages**: Python image includes numpy, pandas, matplotlib; R image includes tidyverse
13
+ - **MCP Integration**: Exposes `coala_python_executor` and `coala_r_executor` tools for LLM interaction
14
+
15
+ ## Prerequisites
16
+
17
+ - Docker installed and running
18
+ - Python 3.11 or higher
19
+ - Built Docker images (see [Building Docker Images](#building-docker-images))
20
+
21
+ ## Installation
22
+
23
+ ```bash
24
+ # Install dependencies
25
+ uv pip install -e .
26
+
27
+ # Or using pip
28
+ pip install -e .
29
+ ```
30
+
31
+ ## Docker Images
32
+
33
+ By default, the server **pulls** the executor images from Docker Hub if they are not present locally:
34
+
35
+ - `hubentu/coala-runtime-python:latest` → tagged as `coala-runtime-python:latest`
36
+ - `hubentu/coala-runtime-r:latest` → tagged as `coala-runtime-r:latest`
37
+
38
+ To **build** the images locally instead (e.g. for development or custom Dockerfiles), run with `--build` or build manually:
39
+
40
+ ```bash
41
+ coala-runtime --build
42
+ # or
43
+ python -m coala_runtime --build
44
+ ```
45
+
46
+ Manual build (same as `--build`):
47
+
48
+ ```bash
49
+ ./docker/build.sh
50
+ ```
51
+
52
+ This creates:
53
+ - `coala-runtime-python:latest` - Python executor image
54
+ - `coala-runtime-r:latest` - R executor image
55
+
56
+ ## Usage
57
+
58
+ ### As MCP Server
59
+
60
+ The server can be run as an MCP server for LLM integration:
61
+
62
+ ```bash
63
+ coala-runtime
64
+ ```
65
+
66
+ Or with the module runner:
67
+
68
+ ```bash
69
+ python -m coala_runtime
70
+ ```
71
+
72
+ Use `coala-runtime --build` (or `python -m coala_runtime --build`) to build Docker images locally before starting.
73
+
74
+ ### Configuration
75
+
76
+ See [MCP_CONFIG.md](MCP_CONFIG.md) for detailed configuration instructions for various MCP clients (Cursor, Claude Desktop, etc.).
77
+
78
+ ### Tool Schemas
79
+
80
+ #### `coala_python_executor`
81
+
82
+ Executes Python scripts in a containerized environment with uv package management.
83
+
84
+ **Input:**
85
+ - `script` or `script_file` (one required): Inline Python code or host path to a `.py` file
86
+ - `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')
87
+ - `conda_packages` (optional, Python only): Conda specs installed before pip/uv (requires conda/mamba in the image)
88
+ - `docker_image` (optional): Docker image to run instead of the default Coala Python image (e.g. `python:3.12-slim`, `quay.io/biocontainers/...`)
89
+ - `skip_package_install` (optional): If `true`, skip install step (typical when `docker_image` already has all dependencies)
90
+ - `input_files` (optional): Map of container paths to host paths for bind-mounting (e.g., {'/input/data.csv': '/host/path/data.csv'})
91
+ - `timeout` (optional): Execution timeout in seconds (default: 300, 0 = no timeout, max: 3600)
92
+
93
+ **Output:**
94
+ - `success`: Whether execution succeeded
95
+ - `exit_code`: Process exit code (0 = success)
96
+ - `stdout`: Standard output from script
97
+ - `stderr`: Standard error output
98
+ - `output_files`: List of output file paths (for files/images generated by the script)
99
+ - `output_data`: Echoed output for strings/numbers (captured via print statements)
100
+ - `container_logs`: Full container execution logs including package installation
101
+ - `execution_time`: Execution time in seconds
102
+
103
+ #### `coala_r_executor`
104
+
105
+ Executes R scripts in a containerized environment with r2u and BiocManager.
106
+
107
+ **Input:**
108
+ - `script` or `script_file` (one required): Inline R code or host path to an `.R` file
109
+ - `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']
110
+ - `docker_image` (optional): Docker image to run instead of the default Coala R image (must provide `Rscript` on `PATH`)
111
+ - `skip_package_install` (optional): If `true`, skip install step (typical when `docker_image` already has all dependencies)
112
+ - `input_files` (optional): Map of container paths to host paths for bind-mounting (e.g., {'/input/data.csv': '/host/path/data.csv'})
113
+ - `timeout` (optional): Execution timeout in seconds (default: 300, 0 = no timeout, max: 3600)
114
+
115
+ **Output:** Same as `coala_python_executor`
116
+
117
+ ## Development
118
+
119
+ ```bash
120
+ # Install with dev dependencies
121
+ uv pip install -e ".[dev]"
122
+
123
+ # Run tests
124
+ pytest
125
+
126
+ # Format code
127
+ black src tests
128
+
129
+ # Lint code
130
+ ruff check src tests
131
+ ```
132
+
133
+ ## License
134
+
135
+ MIT
@@ -0,0 +1,33 @@
1
+ # Python executor image with uv and default packages
2
+ FROM python:3.12-slim
3
+
4
+ # Set environment variables
5
+ ENV PYTHONDONTWRITEBYTECODE=1 \
6
+ PYTHONUNBUFFERED=1 \
7
+ DEBIAN_FRONTEND=noninteractive
8
+
9
+ # Install system dependencies and uv
10
+ RUN apt-get update && \
11
+ apt-get install -y --no-install-recommends \
12
+ curl \
13
+ build-essential \
14
+ && curl -LsSf https://astral.sh/uv/install.sh | sh \
15
+ && mv /root/.local/bin/uv /usr/local/bin/uv \
16
+ && mv /root/.local/bin/uvx /usr/local/bin/uvx || true \
17
+ && chmod +x /usr/local/bin/uv \
18
+ && apt-get remove -y curl \
19
+ && apt-get autoremove -y \
20
+ && apt-get clean \
21
+ && rm -rf /var/lib/apt/lists/*
22
+
23
+ # Create workspace directories
24
+ RUN mkdir -p /workspace /input /output
25
+
26
+ # Set working directory
27
+ WORKDIR /workspace
28
+
29
+ # Install default Python packages using uv
30
+ RUN uv pip install --system numpy pandas matplotlib
31
+
32
+ # Default command (can be overridden)
33
+ CMD ["python"]
@@ -0,0 +1,44 @@
1
+ # R executor image with r2u, bioc2u, and tidyverse
2
+ FROM rocker/r2u:latest
3
+
4
+ # Set environment variables
5
+ ENV DEBIAN_FRONTEND=noninteractive \
6
+ R_HOME=/usr/lib/R
7
+
8
+ # Install BiocManager (needed for Bioconductor package installation)
9
+ RUN apt-get update && \
10
+ apt-get install -y --no-install-recommends \
11
+ r-cran-biocmanager \
12
+ && apt-get clean \
13
+ && rm -rf /var/lib/apt/lists/*
14
+
15
+ # Configure BiocManager to use the latest stable version
16
+ # This will be used when installing Bioconductor packages at runtime
17
+ RUN Rscript -e "BiocManager::install(version = '3.22', ask = FALSE, update = FALSE)" || true
18
+
19
+ # Note: bioc2u repository setup
20
+ # bioc2u provides Bioconductor packages as Ubuntu binaries
21
+ # If available, it can be added as a repository, but BiocManager::install()
22
+ # will work for installing Bioconductor packages at runtime
23
+ # The rocker/r2u base image already has bspm configured for CRAN packages
24
+
25
+ # Install default R package (tidyverse) via apt (r2u provides binaries)
26
+ RUN apt-get update && \
27
+ apt-get install -y --no-install-recommends \
28
+ r-cran-tidyverse \
29
+ && apt-get clean \
30
+ && rm -rf /var/lib/apt/lists/*
31
+
32
+ # Create workspace directories
33
+ RUN mkdir -p /workspace /input /output
34
+
35
+ # Set working directory
36
+ WORKDIR /workspace
37
+
38
+ # Configure R to use bspm for automatic apt integration
39
+ # This ensures install.packages() uses apt when available
40
+ RUN echo "suppressMessages(bspm::enable())" >> ${R_HOME}/etc/Rprofile.site && \
41
+ echo "options(bspm.version.check=FALSE)" >> ${R_HOME}/etc/Rprofile.site
42
+
43
+ # Default command (can be overridden)
44
+ CMD ["Rscript"]