FHIR Progressive Discovery MCP Server

A sophisticated FastMCP-based server that provides progressive discovery of FHIR (Fast Healthcare Interoperability Resources) operations, inspired by Klavis AI architecture patterns.

🎯 Key Features

• Progressive Discovery: Resources are discovered based on user intent, not loaded all at once

• 11 Resource Groups: Clinical, Administrative, Workflow, Financial, and more

• Native PDF Conversion: Convert medical PDFs directly to FHIR DocumentReference resources

• Format Conversion: Transform between JSON, XML, and YAML formats

• Built on FastMCP: Modern, type-safe Python MCP server framework

• Pydantic v2 Validation: Robust FHIR resource validation using fhir.resources

🏗️ Architecture

Progressive Discovery Model

Instead of exposing 100+ FHIR resources at once, this server organizes resources into logical groups and progressively discovers them based on context:

Discovery Flow:

1. discover_resource_groups(intent="patient care") → Returns relevant groups

2. explore_resource_group(group_id="clinical") → Shows resources in that group

3. get_resource_schema(resource_type="Patient") → Get specific resource structure

4. create_resource(...) → Work with the resource

Resource Groups

🚀 Installation

📖 Usage

Starting the Server

MCP Tools Available

1. Discovery Tools

discover_resource_groups(intent: str)

• Entry point for progressive discovery

• Returns resource groups ranked by relevance to your intent

explore_resource_group(group_id: str)

• Deep dive into a specific group

• Shows all resources and available operations

list_all_resource_groups()

• Complete overview of all groups

2. Resource Operations

get_resource_schema(resource_type: str)

• Get Pydantic schema for any FHIR resource

• Shows required fields, types, and structure

create_resource(resource_type: str, resource_data: dict)

• Create and validate FHIR resources

• Returns validated FHIR JSON

validate_resource(resource_json: str)

• Validate existing FHIR JSON against schema

convert_between_formats(resource_data: str, input_format: str, output_format: str)

• Convert between JSON, XML, YAML formats

• Formats: "json", "xml", "yaml"

search_resources(resource_type: str, search_params: dict)

• Validate search parameters against schema

• Prepares queries for FHIR server execution

3. PDF Conversion Tools

convert_pdf_to_fhir(pdf_path: str, document_type: str, patient_reference: str)

• Convert medical PDFs to FHIR DocumentReference

• Extract text and metadata

• Basic clinical data extraction

Document Types:

• clinical_note - Outpatient notes

• lab_report - Laboratory results

• discharge_summary - Hospital discharge docs

• prescription - Medication prescriptions

batch_convert_pdfs_to_fhir(pdf_directory: str, document_type: str, patient_reference: str)

• Batch process entire directories of PDFs

4. Utility Tools

get_fhir_version_info()

• Check supported FHIR versions and features

💡 Example Workflows

Workflow 1: Create a Patient Resource

Workflow 2: Convert Lab Report PDF to FHIR

Workflow 3: Create and Convert Observation

🧠 Progressive Discovery Benefits

1. Reduced Context Window Usage: Load only what you need, when you need it

2. Intent-Based Discovery: Find resources based on your use case, not alphabetically

3. Scalable: Works with 100+ FHIR resources without overwhelming the agent

4. Grouped Operations: Related resources are discovered together

5. Lazy Loading: Resources are only instantiated when accessed

🔧 Technical Details

FHIR Versions Supported

• R5 (default) - FHIR version 5.0.0

• R4B - FHIR version 4.3.0

• STU3 - FHIR version 3.0.2

Dependencies

• FastMCP: Modern MCP server framework

• fhir.resources: Official Python FHIR resources with Pydantic v2

• PyPDF2: PDF text extraction

• Pydantic: Data validation and serialization

Resource Validation

All resources are validated using:

• Pydantic v2 models from fhir.resources

• FHIR specification compliance

• Required field checking

• Type validation

• Cardinality constraints

📚 FHIR Resources

This server supports all standard FHIR R5 resources including:

Clinical: AllergyIntolerance, CarePlan, CareTeam, ClinicalImpression, Condition, DetectedIssue, DiagnosticReport, FamilyMemberHistory, Goal, Immunization, MedicationAdministration, MedicationDispense, MedicationRequest, MedicationStatement, Observation, Procedure, RiskAssessment, Specimen

Administrative: Patient, Practitioner, PractitionerRole, Organization, Location, HealthcareService, Endpoint, Person, Group, RelatedPerson

Workflow: Appointment, AppointmentResponse, Schedule, Slot, Encounter, EpisodeOfCare, Flag, ServiceRequest, Task, Communication, CommunicationRequest

Financial: Account, ChargeItem, Claim, ClaimResponse, Coverage, CoverageEligibilityRequest, CoverageEligibilityResponse, EnrollmentRequest, ExplanationOfBenefit, Invoice, PaymentNotice, PaymentReconciliation

And many more...

🎨 Design Philosophy

This server follows the Klavis progressive discovery pattern:

• Intent-driven: Start with user intent, not resource lists

• Layered discovery: Groups → Resources → Operations

• Context-aware: Relevance scoring based on use case

• Scalable architecture: Handles large resource sets efficiently

🤝 Contributing

Contributions welcome! Areas for enhancement:

• Advanced NLP for PDF extraction

• FHIR server connectivity (HAPI, Azure FHIR)

• HL7 v2 message conversion

• CDA document parsing

• SMART on FHIR integration

📄 License

MIT License

🔗 References

• fhir.resources - Python FHIR resources library

• Klavis AI - Progressive discovery inspiration

• FastMCP - MCP server framework

• FHIR Specification - Official FHIR documentation

Built with surgical precision for the gods of programming ⚡️