Mutation Clinical Trial Matching MCP

A Model Context Protocol (MCP) server that enables Claude Desktop to search for matches in clincialtrials.gov based on mutations.

Status

This is currently first phase of development. It works to retreive trials based on given mutations in the claude query. However, there are still bugs and further refinements and additions to be implemented.

Overview

This project follows the Agentic Coding principles to create a system that integrates Claude Desktop with the clinicaltrials.gov API. The server allows for natural language queries about genetic mutations and returns summarized information about relevant clinical trials.

flowchart LR
    Claude[Claude Desktop] <-->|MCP Protocol| Server[MCP Server]
    
    subgraph Flow[PocketFlow]
        QueryNode[Query Node] -->|trials_data| SummarizeNode[Summarize Node]
    end
    
    Server -->|mutation| Flow
    QueryNode -->|API Request| API[Clinicaltrials.gov API]
    API -->|Trial Data| QueryNode
    Flow -->|summary| Server
    Server -->|Return| Claude

Each node in the flow follows the PocketFlow Node pattern with prep, exec, and post methods:

Project Structure

This project is organized according to the Agentic Coding paradigm:

1. Requirements (Human-led):
- Search and summarize clinical trials related to specific genetic mutations
- Provide mutation information as contextual resources
- Integrate seamlessly with Claude Desktop

2. Flow Design (Collaborative):
- User queries Claude Desktop about a genetic mutation
- Claude calls our MCP server tool
- Server queries clinicaltrials.gov API
- Server processes and summarizes the results
- Server returns formatted results to Claude

3. Utilities (Collaborative):
- clinicaltrials/query.py: Handles API calls to clinicaltrials.gov
- utils/call_llm.py: Utilities for working with Claude

4. Node Design (AI-led):
- utils/node.py: Implements base Node and BatchNode classes with prep/exec/post pattern
- clinicaltrials/nodes.py: Defines specialized nodes for querying and summarizing
- clinicaltrials_mcp_server.py: Orchestrates the flow execution

5. Implementation (AI-led):
- FastMCP SDK for handling the protocol details
- Error handling at all levels
- Resources for common mutations

Components

MCP Server (clinicaltrials_mcp_server.py)

The main server that implements the Model Context Protocol interface, using the official Python SDK. It:

- Registers and exposes tools for Claude to use
- Provides resources with information about common mutations
- Handles the communication with Claude Desktop

Query Module (clinicaltrials/query.py)

Responsible for querying the clinicaltrials.gov API with:
- Robust error handling
- Input validation
- Detailed logging

Summarizer (llm/summarize.py)

Processes and formats the clinical trials data:
- Organizes trials by phase
- Extracts key information (NCT ID, summary, conditions, etc.)
- Creates a readable markdown summary

Node Pattern Implementation

This project implements the PocketFlow Node pattern, which provides a modular, maintainable approach to building AI workflows:

Core Node Classes (utils/node.py)

- Node: Base class with prep, exec, and post methods for processing data
- BatchNode: Extension for batch processing multiple items
- Flow: Orchestrates execution of nodes in sequence

Implementation Nodes (clinicaltrials/nodes.py)

1. QueryTrialsNode:

   # Queries clinicaltrials.gov API

   def prep(self, shared): return shared["mutation"]

   def exec(self, mutation): return query_clinical_trials(mutation)

   def post(self, shared, mutation, result):

       shared["trials_data"] = result

       shared["studies"] = result.get("studies", [])

       return "summarize"

   

2. SummarizeTrialsNode:

   # Formats trial data into readable summaries

   def prep(self, shared): return shared["studies"]

   def exec(self, studies): return format_trial_summary(studies)

   def post(self, shared, studies, summary):

       shared["summary"] = summary

       return None  # End of flow

   

Flow Execution

The MCP server creates and runs the flow:

```python