haraprasadj/gen3-mcp-server

Gen3 MCP Server

A Model Context Protocol (MCP) server for interacting with Gen3's Metadata Service. This server provides tools for managing metadata, objects, and their relationships in a Gen3 commons.

Features

• Metadata Management
  • Search and retrieve metadata
  • Create, update, and delete metadata records
  • Aggregate metadata operations
• Object Management
  • Create objects with metadata
  • Get signed download URLs
• Input Validation using Pydantic models
• Error handling and detailed responses
• Authentication support via access tokens

Configuration

The server requires the following environment variables:

GEN3_URL=https://your-gen3-commons.org
GEN3_ACCESS_TOKEN=your-access-token  # Required for authenticated operations

Create a .env file in the project root with these variables.

Installation

1. Ensure Python 3.12+ is installed
2. Install dependencies:

uv pip install -r requirements.txt

Running locally

uv run gen3.py

Docker Implementation

Building the Docker Image

docker build -t gen3-mcp-server .

Running with Docker

1. Create a .env file with your Gen3 configuration:

GEN3_URL=https://your-gen3-commons.org
GEN3_ACCESS_TOKEN=your-access-token

2. Run the container:

docker run --env-file .env gen3-mcp-server

Using in Docker-based MCP Client

When using this server with a Docker-based MCP client, update your client configuration:

{
    "mcpServers": {
        "gen3": {
            "image": "gen3-mcp-server",
            "env": {
                "GEN3_URL": "https://your-gen3-commons.org",
                "GEN3_ACCESS_TOKEN": "your-access-token"
            }
        }
    }
}

Available Tools

Metadata Operations

1. get_aggregate_metadata

   • Get aggregate metadata with filtering and pagination
   • Parameters:
     • limit: Maximum records to return (max: 2000)
     • offset: Pagination offset
     • counts: Return counts for array fields
     • flatten: Remove commons grouping
     • pagination: Include pagination info

2. search_metadata

   • Search metadata using query parameters
   • Parameters:
     • query: Dictionary of search parameters
     • params: Optional MetadataSearchParams for pagination

3. get_metadata_by_guid

   • Get metadata for a specific GUID
   • Parameters:
     • guid: The GUID to fetch metadata for

4. create_metadata

   • Create or update metadata for a GUID
   • Parameters:
     • guid: Target GUID
     • metadata: Metadata dictionary
     • overwrite: Whether to overwrite existing data

5. update_metadata

   • Update metadata for a GUID
   • Parameters:
     • guid: Target GUID
     • metadata: New metadata
     • merge: Whether to merge with existing data

6. delete_metadata

   • Delete metadata for a GUID
   • Parameters:
     • guid: GUID to delete metadata for

Object Operations

1. create_object

   • Create a new object with metadata
   • Parameters:
     • input_data: CreateObjectInput model with:
       • file_name: Name of the file
       • authz: Authorization requirements
       • aliases: Optional unique names
       • metadata: Optional additional metadata

2. get_object_download_url

   • Get a signed download URL for an object
   • Parameters:
     • guid: Object GUID

Adding to an MCP Client

Add the following configuration to your MCP client settings:

{
    "mcpServers": {
        "gen3": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/gen3-mcp-server",
                "run",
                "gen3.py"
            ],
            "env": {
                "GEN3_URL": "https://your-gen3-commons.org",
                "GEN3_ACCESS_TOKEN": "your-access-token"
            }
        }
    }
}

Example Usage

# Search metadata
result = await search_metadata(
    query={"data_type": "clinical"},
    params={"limit": 10, "offset": 0}
)

# Create metadata
metadata = {
    "data_type": "clinical",
    "file_format": "csv",
    "file_size": 1024
}
result = await create_metadata("guid-123", metadata)

# Get download URL
url = await get_object_download_url("guid-123")

Error Handling

All tools return a dictionary with an "error" key when an operation fails:

{
    "error": "Unable to fetch metadata for GUID: guid-123"
}

Development

To add new tools or modify existing ones:

1. Define any new Pydantic models needed for input validation
2. Add the tool using the @mcp.tool() decorator
3. Update the README with documentation for the new tool
4. Test the tool with various inputs and error conditions