FHIR Progressive Discovery MCP Server

# 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](https://github.com/Klavis-AI/klavis) 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: ``` User Intent → Discover Groups → Explore Group → Use Specific Resources ``` **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 | Group | Resources | Priority | |-------|-----------|----------| | **Clinical** | Condition, Observation, Procedure, Medication, Immunization, AllergyIntolerance, DiagnosticReport | 1 | | **Administrative** | Patient, Practitioner, Organization, Location, HealthcareService | 1 | | **Workflow** | Encounter, Appointment, EpisodeOfCare, Task, ServiceRequest, CarePlan | 2 | | **Financial** | Coverage, Claim, Invoice, PaymentNotice, Account, ExplanationOfBenefit | 3 | | **Diagnostics** | ImagingStudy, Media, BodyStructure, MolecularSequence | 2 | | **Medications** | Medication, MedicationAdministration, MedicationDispense, MedicationRequest | 2 | | **Documents** | DocumentReference, DocumentManifest, Composition | 2 | | **Clinical Reasoning** | PlanDefinition, ActivityDefinition, Questionnaire, RiskAssessment | 3 | | **Research** | ResearchStudy, ResearchSubject, Evidence, Citation | 4 | | **Terminology** | CodeSystem, ValueSet, ConceptMap, NamingSystem | 4 | | **Security** | AuditEvent, Provenance, Consent, Permission | 3 | ## 🚀 Installation ```bash # Clone or download the repository cd "FHIR MCP" # Install dependencies pip install -r requirements.txt # Or use the project config pip install -e . ``` ## 📖 Usage ### Starting the Server ```bash python fhir_mcp_server.py ``` ### 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 ```python # Example intents: "patient care" # → Clinical, Administrative groups "billing" # → Financial, Administrative groups "scheduling" # → Workflow, Administrative groups "research study" # → Research, Clinical groups ``` **`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 ```python # 1. Discover what's available for patient management discover_resource_groups(intent="patient management") # → Returns: Administrative, Clinical groups # 2. Explore the administrative group explore_resource_group(group_id="administrative") # → Shows: Patient, Practitioner, Organization... # 3. Get Patient schema get_resource_schema(resource_type="Patient") # → Returns: Full Patient schema with required fields # 4. Create a patient create_resource( resource_type="Patient", resource_data={ "resourceType": "Patient", "active": True, "name": [{ "use": "official", "family": "Doe", "given": ["John"] }], "gender": "male", "birthDate": "1990-01-01" } ) # → Returns: Validated Patient FHIR resource ``` ### Workflow 2: Convert Lab Report PDF to FHIR ```python # Convert a single lab report convert_pdf_to_fhir( pdf_path="/path/to/lab_report.pdf", document_type="lab_report", patient_reference="Patient/12345" ) # → Returns: DocumentReference resource with extracted text # Batch convert all PDFs in a folder batch_convert_pdfs_to_fhir( pdf_directory="/path/to/medical_records/", document_type="clinical_note", patient_reference="Patient/12345" ) # → Processes all PDFs and returns results ``` ### Workflow 3: Create and Convert Observation ```python # 1. Discover clinical resources discover_resource_groups(intent="patient vitals") # → Returns: Clinical group # 2. Create an Observation create_resource( resource_type="Observation", resource_data={ "resourceType": "Observation", "status": "final", "code": { "coding": [{ "system": "http://loinc.org", "code": "85354-9", "display": "Blood pressure" }] }, "subject": {"reference": "Patient/123"}, "valueQuantity": { "value": 120, "unit": "mmHg" } } ) # → Returns: Validated Observation in JSON # 3. Convert to XML convert_between_formats( resource_data='{"resourceType": "Observation", ...}', input_format="json", output_format="xml" ) # → Returns: XML representation ``` ## 🧠 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](https://github.com/nazrulworld/fhir.resources) - Python FHIR resources library - [Klavis AI](https://github.com/Klavis-AI/klavis) - Progressive discovery inspiration - [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework - [FHIR Specification](https://hl7.org/fhir/) - Official FHIR documentation --- **Built with surgical precision for the gods of programming** ⚡️