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.
- coala_runtime-0.1.0/.github/workflows/release.yml +31 -0
- coala_runtime-0.1.0/.gitignore +60 -0
- coala_runtime-0.1.0/AGENTS.md +27 -0
- coala_runtime-0.1.0/MCP_CONFIG.md +178 -0
- coala_runtime-0.1.0/PKG-INFO +164 -0
- coala_runtime-0.1.0/README.md +135 -0
- coala_runtime-0.1.0/docker/Dockerfile.python +33 -0
- coala_runtime-0.1.0/docker/Dockerfile.r +44 -0
- coala_runtime-0.1.0/docker/README.md +66 -0
- coala_runtime-0.1.0/docker/build.sh +37 -0
- coala_runtime-0.1.0/pyproject.toml +57 -0
- coala_runtime-0.1.0/skills/SKILL.md +112 -0
- coala_runtime-0.1.0/src/coala_runtime/__init__.py +3 -0
- coala_runtime-0.1.0/src/coala_runtime/__main__.py +56 -0
- coala_runtime-0.1.0/src/coala_runtime/runtime/__init__.py +1 -0
- coala_runtime-0.1.0/src/coala_runtime/runtime/container_manager.py +207 -0
- coala_runtime-0.1.0/src/coala_runtime/runtime/docker_images.py +123 -0
- coala_runtime-0.1.0/src/coala_runtime/runtime/executor_base.py +612 -0
- coala_runtime-0.1.0/src/coala_runtime/runtime/file_handler.py +84 -0
- coala_runtime-0.1.0/src/coala_runtime/server.py +692 -0
- coala_runtime-0.1.0/src/coala_runtime/tools/__init__.py +1 -0
- coala_runtime-0.1.0/src/coala_runtime/tools/python_executor.py +207 -0
- coala_runtime-0.1.0/src/coala_runtime/tools/r_executor.py +185 -0
- coala_runtime-0.1.0/src/coala_runtime/utils/__init__.py +1 -0
- coala_runtime-0.1.0/src/coala_runtime/utils/output_parser.py +124 -0
- coala_runtime-0.1.0/tests/README.md +47 -0
- coala_runtime-0.1.0/tests/scripts/boxplot_script.py +42 -0
- coala_runtime-0.1.0/tests/scripts/pdf_extraction_script.py +37 -0
- coala_runtime-0.1.0/tests/scripts/venn_diagram_script.R +23 -0
- coala_runtime-0.1.0/tests/test_executor_models.py +59 -0
- coala_runtime-0.1.0/tests/test_prune_install_list.py +71 -0
- coala_runtime-0.1.0/tests/test_python_executor_install.py +90 -0
- coala_runtime-0.1.0/tests/test_r_executor_install.py +21 -0
- coala_runtime-0.1.0/tests/test_via_mcp.py +193 -0
- 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"]
|