ai4gh 1.0.0

Comprehensive Python SDK, MCP server, and compliance test suite for GA4GH specifications

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

Spec	Plugin	Phase	Status
Beacon v2	ai4gh[beacon]	Tier 1	Done
DRS v1.4	ai4gh[drs]	Tier 1	Done
htsget v1.3	ai4gh[htsget]	Tier 1	Done
refget v2	ai4gh[refget]	Tier 1	Done
Phenopackets v2	ai4gh[phenopackets]	Tier 1	Done
VRS v2.0	ai4gh[vrs]	Tier 1	Done
WES v1.1	ai4gh[wes]	Tier 2	Done
TES v1.1	ai4gh[tes]	Tier 2	Done
TRS v2.0.1	ai4gh[trs]	Tier 2	Done
Data Connect v1	ai4gh[data-connect]	Tier 2	Done
Passports v1	ai4gh[passports]	Tier 3	Done
DUO	ai4gh[duo]	Tier 3	Done
Crypt4GH v1	ai4gh[crypt4gh]	Tier 3	Done
Pedigree v1	ai4gh[pedigree]	Tier 3	Done
Cat-VRS v1	(in vrs)	Tier 3	Done
VA-Spec v1	(in vrs)	Tier 3	Done

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