ai4gh

ai4gh

Comprehensive Python SDK, MCP server, and compliance test suite for GA4GH (Global Alliance for Genomics and Health) specifications.

Features

• Unified SDK: Single Python package covering 14 GA4GH specifications
• MCP Server: Full Model Context Protocol surface with 13 tools, 14 resources, 5 prompts
• Compliance Testing: Per-spec test suites with JSON/HTML/JUnit reporting
• Plugin Architecture: Install only the specs you need via pip extras
• Async-First: All network operations are async (httpx + tenacity)
• CLI: ai4gh command for compliance testing, MCP serving, and configuration

Quick Run (no install)

# Run directly with uvx — no install needed
uvx ai4gh --help
uvx ai4gh mcp serve
uvx ai4gh test beacon https://beacon.example.org

Installation

# Core only
pip install ai4gh

# With specific specs
pip install "ai4gh[beacon,drs]"

# Everything
pip install "ai4gh[all]"

# Development
uv sync --extra dev

Quick Start

Python SDK

from ai4gh.specs.drs.client import DRSClient

async with DRSClient(base_url="https://drs.example.org") as client:
    obj = await client.get_object("drs://example/abc123")
    print(obj.name, obj.size)

Beacon Query

from ai4gh.specs.beacon.client import BeaconClient

async with BeaconClient(base_url="https://beacon.example.org") as client:
    result = await client.query("BRCA1")
    print(result)

MCP Server

# Start MCP server on stdio
ai4gh mcp serve

Compliance Testing

# Run compliance tests
ai4gh test beacon https://beacon.example.org

# JSON report
ai4gh test drs https://drs.example.org --format json -o report.json

# HTML report
ai4gh test beacon https://beacon.example.org --format html -o report.html

# List available test suites
ai4gh list-specs

Configuration

# Show current config
ai4gh config show

# Initialize config file
ai4gh config init

GA4GH Specifications Covered

MCP Server

The MCP server exposes GA4GH operations as tools for AI agents (Claude Code, Cursor, etc.).

Tools (13)

• drs_get_object - Get a DRS object by ID
• beacon_query - Query a Beacon v2 server
• htsget_reads - Get read data from htsget
• refget_sequence - Get reference sequence by checksum
• vrs_compute_id - Compute VRS identifier
• phenopacket_validate - Validate a Phenopacket
• wes_submit_run - Submit workflow to WES
• tes_create_task - Create TES task
• trs_search_tools - Search TRS registry
• data_connect_search - Query via Data Connect
• passport_decode - Decode GA4GH Passport JWT
• duo_match - Check DUO compatibility
• pedigree_validate - Validate pedigree structure

Resources (15)

• ga4gh://specs - Specification index
• ga4gh://specs/{spec_id} - Individual spec metadata (14 specs)

Prompts (5)

• find_variants - Search for genetic variants across beacons
• patient_summary - Generate clinical summary from Phenopacket
• rare_disease_search - Search federated rare disease data
• workflow_submit - Submit bioinformatics workflow
• compliance_report - Generate compliance report

Claude Code / MCP Integration

Add to your Claude Code MCP config (.claude/settings.json):

{
  "mcpServers": {
    "ai4gh": {
      "command": "uvx",
      "args": ["ai4gh", "mcp", "serve"]
    }
  }
}

All 13 tools become available to Claude as MCP tools. No install required.

Architecture

ai4gh/
  core/           # Config, auth, transport, plugin system
  specs/           # Per-spec plugins (client + models)
    beacon/        # Beacon v2
    drs/           # Data Repository Service
    htsget/        # Streaming reads/variants
    refget/        # Reference sequences
    phenopackets/  # Clinical phenotype exchange
    vrs/           # Variant representation
    wes/           # Workflow execution
    tes/           # Task execution
    trs/           # Tool registry
    data_connect/  # SQL-like data queries
    passports/     # Federated auth (JWT)
    duo/           # Data use ontology
    crypt4gh/      # File encryption
    pedigree/      # Family relationships
    cat_vrs/       # Categorical variants
    va_spec/       # Variant annotation
  mcp/             # MCP server (tools, resources, prompts)
  compliance/      # Compliance test suites + report generation
  cli/             # Typer CLI

Development

# Install with dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=ai4gh --cov-report=term-missing

# Lint
uv run ruff check .

# Type check
uv run mypy src/

# Build
uv run hatch build

License

Apache-2.0