Metadata-Version: 2.4
Name: galaxy-mcp
Version: 1.7.0
Summary: Model Context Protocol server for Galaxy bioinformatics platform
Author-email: Dannon Baker <dannon.baker@gmail.com>
Maintainer-email: Dannon Baker <dannon.baker@gmail.com>, Galaxy Project <contact@galaxyproject.org>
License-Expression: MIT
Project-URL: Homepage, https://github.com/galaxyproject/galaxy-mcp
Project-URL: Repository, https://github.com/galaxyproject/galaxy-mcp
Project-URL: Issues, https://github.com/galaxyproject/galaxy-mcp/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anyio<5,>=4.0.0
Requires-Dist: bioblend<2,>=1.9.0
Requires-Dist: cryptography<49,>=41.0.0
Requires-Dist: fastmcp<4,>=3.1.0
Requires-Dist: requests<3,>=2.32.3
Requires-Dist: python-dotenv<2,>=1.0.0
Requires-Dist: rank-bm25<1,>=0.2.2
Requires-Dist: typing-extensions<5,>=4.0.0
Provides-Extra: code-mode
Requires-Dist: fastmcp[code-mode]<4,>=3.1.0; extra == "code-mode"
Provides-Extra: dev
Requires-Dist: ruff>=0.11.2; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: types-requests>=2.31.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.25.0; extra == "dev"
Requires-Dist: pytest-watch>=4.2.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
Requires-Dist: responses>=0.25.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Requires-Dist: pre-commit>=3.6.0; extra == "dev"
Requires-Dist: tox>=4.11.0; extra == "dev"
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# Galaxy MCP Server - Python Implementation

<!-- mcp-name: io.github.galaxyproject/galaxy-mcp -->

This is the Python implementation of the Galaxy MCP server, providing a Model Context Protocol server for interacting with Galaxy instances.

## Features

- Complete Galaxy API integration through BioBlend
- Optional OAuth login flow for HTTP deployments
- Interactive Workflow Composer (IWC) integration
- FastMCP2 server with remote deployment support
- Type-annotated Python codebase

## Requirements

- Python 3.10+
- FastMCP 2.3.0+

## Installation

### From PyPI (Recommended)

```bash
# Install from PyPI
pip install galaxy-mcp

# Or using uv (recommended)
uvx galaxy-mcp
```

### From Source

```bash
# Clone the repository
git clone https://github.com/galaxyproject/galaxy-mcp.git
cd galaxy-mcp/mcp-server-galaxy-py

# Install with uv (recommended)
uv sync --all-extras
```

## Configuration

At minimum the server needs to know which Galaxy instance to target:

```bash
export GALAXY_URL="https://usegalaxy.org.au/"
```

How you authenticate depends on your transport:

- **Stdio / long-lived sessions** – provide an API key:

  ```bash
  export GALAXY_API_KEY="your-api-key"
  ```

- **HTTP / OAuth** – configure the public URL that users reach and a signing secret for session
  tokens. The server mints short-lived Galaxy API keys on behalf of each user.

  ```bash
  export GALAXY_MCP_PUBLIC_URL="https://mcp.example.com"
  export GALAXY_MCP_SESSION_SECRET="$(openssl rand -hex 32)"
  ```

  Optionally set `GALAXY_MCP_CLIENT_REGISTRY` to control where OAuth client registrations are stored.

  For non-OAuth HTTP clients, `connect(url=..., api_key=...)` stores Galaxy credentials per MCP
  session rather than globally. Clients normally preserve MCP sessions by default, which allows
  multiple users to share the same MCP server while keeping their Galaxy credentials isolated.

You can also steer the transport with `GALAXY_MCP_TRANSPORT` (`stdio`, `streamable-http`, or `sse`).
All variables can be placed in a `.env` file for convenience.

## Usage

### Quick Start with `uvx`

```bash
# Local stdio transport (no network listener)
uvx galaxy-mcp

# Remote/browser clients with HTTP + OAuth
export GALAXY_URL="https://usegalaxy.org.au/"
export GALAXY_MCP_PUBLIC_URL="https://mcp.example.com"
export GALAXY_MCP_SESSION_SECRET="$(openssl rand -hex 32)"
uvx galaxy-mcp --transport streamable-http --host 0.0.0.0 --port 8000
```

### Installed CLI

```bash
pip install galaxy-mcp
galaxy-mcp --transport streamable-http --host 0.0.0.0 --port 8000
```

If `--transport` is omitted the server defaults to stdio and reads/writes MCP messages via stdin/stdout.

### Working from a checkout

```bash
uv sync
uv run galaxy-mcp --transport streamable-http --host 0.0.0.0 --port 8000
```

See [USAGE_EXAMPLES.md](USAGE_EXAMPLES.md) for detailed tool usage patterns.

### Tool discovery mode (experimental)

Galaxy MCP exposes 30+ `@mcp.tool` registrations, which costs tokens on every turn for agents that only ever use a handful. `--discovery-mode code` (also honored via `GALAXY_MCP_DISCOVERY_MODE=code`) collapses the whole catalog into three meta-tools:

- `search` -- BM25 search over tool names and descriptions
- `get_schema` -- fetch the full schema for specific tools
- `run_galaxy_tool` -- execute any tool by name

```bash
pip install 'galaxy-mcp[code-mode]'   # pulls in pydantic-monty sandbox
galaxy-mcp --discovery-mode code
```

The `code-mode` extra installs `pydantic-monty`, the sandboxed Python interpreter that backs `run_galaxy_tool`. Without it the server still starts in `full` mode but raises a clear error if `--discovery-mode code` is requested.

Default is `full`, which keeps the existing catalog unchanged. CodeMode is useful when you want to keep the agent's context lean and are willing to trade a few extra turns (search -> schema -> execute) per tool call. It's built on FastMCP's experimental `CodeMode` transform, so the API may shift before it stabilizes.

The server also ships agent-facing usage guidance via the MCP `instructions` field (returned during the initial handshake). It explains the typical workflow, the difference between MCP tools and Galaxy tools (e.g. FastQC isn't an MCP tool -- find it via `search_tools_by_name`), and -- when code mode is active -- how to use `run_galaxy_tool` and `call_tool`. Agents that respect the `instructions` field will read this without you having to prompt them.

## Available MCP Tools

The Python implementation provides the following MCP tools:

- `connect`: Establish connection to a Galaxy instance
- `search_tools_by_name`: Find Galaxy tools by name
- `get_tool_details`: Retrieve detailed tool information
- `run_tool`: Execute a Galaxy tool with parameters
- `get_tool_panel`: Retrieve the Galaxy tool panel structure
- `get_tool_run_examples`: Retrieve XML-defined test lessons that show how to run a tool
- `get_tool_input_template`: Returns a ready-to-fill `inputs` skeleton (with placeholders) plus the parameter schema for a tool, to build correct `run_tool` inputs
- `get_user`: Get current user information
- `get_histories`: List available Galaxy histories
- `list_history_ids`: Get simplified list of history IDs and names
- `get_history_details`: Get detailed information about a specific history
- `upload_file`: Upload local files to Galaxy
- `upload_file_from_url`: Upload files from URLs to Galaxy
- `list_workflows`: List available workflows in Galaxy instance
- `get_workflow_details`: Get detailed information about a specific workflow
- `invoke_workflow`: Execute/run a workflow with specified inputs
- `cancel_workflow_invocation`: Cancel a running workflow invocation
- `get_invocations`: View workflow executions
- `get_iwc_workflows`: Access Interactive Workflow Composer workflows
- `search_iwc_workflows`: Search IWC workflows by keywords
- `import_workflow_from_iwc`: Import an IWC workflow to Galaxy

## Testing

The project includes a comprehensive test suite using pytest with mock-based testing.

### Running Tests

```bash
# Install test dependencies
uv pip install -r requirements-test.txt

# Run all tests
uv run pytest

# Run with coverage report
uv run pytest --cov=main --cov-report=html

# Run specific test file
uv run pytest tests/test_history_operations.py

# Run tests with verbose output
uv run pytest -v
```

### Test Structure

Tests are organized by functionality:

- `test_connection.py` - Galaxy connection and authentication
- `test_history_operations.py` - History-related operations
- `test_dataset_operations.py` - Dataset upload/download
- `test_tool_operations.py` - Tool search and execution
- `test_workflow_operations.py` - Workflow import and invocation
- `test_integration.py` - End-to-end scenarios

See [tests/README.md](tests/README.md) for more details on the testing strategy.

## Development

### Code Style Guidelines

- Use Python 3.10+ features
- Employ type hints where appropriate
- Follow PEP 8 style guidelines
- Use ruff for code formatting and linting
- All code should pass type checking with mypy

### Development Setup

```bash
# Install development dependencies
make install-dev

# Set up pre-commit hooks (required for contributing)
uv run pre-commit install
```

Pre-commit hooks will automatically format your code and run linting checks when you commit. All contributors should install these hooks to maintain consistent code quality.

### Development Commands

We use a Makefile for consistent development commands:

```bash
# Show all available commands
make help

# Install dependencies
make install       # Install all dependencies

# Code quality
make lint          # Format code and run all checks

# Testing
make test          # Run tests with coverage

# Building
make clean         # Clean build artifacts
make build         # Build distribution packages

# Running
make run           # Run the MCP server
make dev           # Run FastMCP2 dev server
```

### Using uv directly

All commands can also be run directly with uv:

```bash
# Install dependencies
uv sync --all-extras

# Format and lint code
uv run pre-commit run --all-files

# Run tests with coverage
uv run pytest --cov=galaxy_mcp --cov-report=html

# Update dependencies
uv lock --upgrade
```

### Cross-version Testing

Test across multiple Python versions using tox:

```bash
# Test on all supported Python versions
tox

# Test on specific version
tox -e py312

# Run only linting
tox -e lint

# Run type checking
tox -e type
```

### Pre-commit Hooks

The project uses pre-commit hooks for automatic code quality checks:

```bash
# Install pre-commit hooks (one-time setup)
uv run pre-commit install

# Run pre-commit manually on all files
uv run pre-commit run --all-files

# Skip pre-commit for a single commit (not recommended)
git commit --no-verify
```

Pre-commit runs automatically on `git commit` and includes:

- Code formatting with ruff
- Linting with ruff
- Trailing whitespace removal
- File cleanup (EOF, YAML/JSON/TOML validation)
- Large file detection
- Merge conflict detection

## License

[MIT](../LICENSE)
