AWS HealthOmics Model Context Protocol Server SDK

Warnings

• breaking As a pre-1.0 (0.0.x series) library, API interfaces and behaviors may change frequently without strict adherence to semantic versioning. Always review release notes or the GitHub repository when upgrading.
  Fix: Pin specific patch versions (`==0.0.X`) in your `requirements.txt` and thoroughly test when upgrading. Consult the GitHub repository's `CHANGELOG.md` or commit history for breaking changes.
• gotcha The server implementation may interact with AWS HealthOmics or other AWS services (e.g., S3, EC2). Ensure that the IAM role or credentials used by the server have the necessary permissions for these interactions, including `omics:GetRun` or similar actions depending on your model context.
  Fix: Define a fine-grained IAM policy for your server's execution role, granting only the least privilege required. Test permissions thoroughly during development.
• gotcha This library explicitly requires Pydantic V2 (`pydantic>=2.0`). If your project also uses other FastAPI-based libraries or a legacy FastAPI setup, ensure compatibility. Pydantic V2 introduced significant breaking changes from V1.
  Fix: Verify all dependencies are compatible with Pydantic V2. If integrating with existing code, be aware of Pydantic V1 to V2 migration steps (e.g., `Field` vs `FieldInfo`, `BaseModel` changes).

Install

• pip install awslabs-aws-healthomics-mcp-server Install core library
• pip install awslabs-aws-healthomics-mcp-server[uvicorn] Install with Uvicorn (recommended for local development)

Imports

• HealthOmicsMCPServer

  from healthomics_mcp_server.server import HealthOmicsMCPServer

  Base class for implementing the custom MCP server logic.
• create_app

  from healthomics_mcp_server.app import create_app

  Function to initialize the FastAPI application with a custom MCP server instance.
• ModelContext

  from healthomics_mcp_server.model import ModelContext

  Data model for representing a HealthOmics model context.
• ModelContextType

  from healthomics_mcp_server.model import ModelContextType

  Enum for defining the type of model context.

Quickstart

This quickstart demonstrates how to implement a basic AWS HealthOmics Model Context Protocol (MCP) server using the SDK. It defines a custom server class inheriting from `HealthOmicsMCPServer`, implements the `get_model_context` method to return model-specific information, and sets up a FastAPI application instance using `create_app`. The resulting `app` can be run with Uvicorn. It includes comments on how to run and test the server locally, along with considerations for AWS authentication.

import os
from typing import Dict, Any
from healthomics_mcp_server.server import HealthOmicsMCPServer
from healthomics_mcp_server.model import ModelContext, ModelContextType
from healthomics_mcp_server.app import create_app

# Configure AWS credentials for boto3 if not using environment variables or instance profiles
# os.environ['AWS_ACCESS_KEY_ID'] = os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_ACCESS_KEY_ID')
# os.environ['AWS_SECRET_ACCESS_KEY'] = os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_SECRET_ACCESS_KEY')
# os.environ['AWS_REGION'] = os.environ.get('AWS_REGION', 'us-east-1')

class MyCustomMCPServer(HealthOmicsMCPServer):
    async def get_model_context(self, model_id: str) -> ModelContext:
        """Implement logic to retrieve a model's context based on its ID."""
        print(f"[MCP Server] Request received for model context: {model_id}")
        
        # In a real application, you would fetch this from a database, S3, or another service.
        # For this example, we return a predefined context based on an environment variable.
        if model_id == os.environ.get('EXAMPLE_MODEL_ID', 'example-model-123'):
            return ModelContext(
                id=model_id,
                type=ModelContextType.DEFAULT,
                properties={
                    "workflow_id": "wf-abc123def456",
                    "reference_genome": "hg38",
                    "sample_type": "blood"
                }
            )
        
        # For any other model_id, return a generic or empty context
        return ModelContext(
            id=model_id,
            type=ModelContextType.DEFAULT, # Or another specific type like ModelContextType.EMPTY
            properties={}
        )

    async def get_health(self) -> Dict[str, Any]:
        """Provide health status of the server."""
        print("[MCP Server] Health check requested.")
        return {"status": "ok", "server_id": "my-omics-server-v1"}

# Instantiate your custom server implementation
server_instance = MyCustomMCPServer()

# Create the FastAPI application instance by passing your server_instance
app = create_app(server_instance)

# --- To run this application: ---
# 1. Save the code above as `main.py`.
# 2. Make sure uvicorn is installed: `pip install awslabs-aws-healthomics-mcp-server[uvicorn]`
# 3. Run from your terminal: `uvicorn main:app --host 0.0.0.0 --port 8000 --reload`
# 4. Access the health endpoint: `http://localhost:8000/health`
# 5. Get model context (replace `example-model-123` with your desired ID):
#    `http://localhost:8000/model-context/example-model-123`
#    Set EXAMPLE_MODEL_ID in your environment for a specific test: `export EXAMPLE_MODEL_ID=my-custom-model`