FHIR Progressive Discovery MCP Server

# Claude Desktop Integration Guide ## Quick Setup Add this to your Claude Desktop MCP configuration file: **Location:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ```json { "mcpServers": { "fhir-progressive": { "command": "python3", "args": [ "/Users/maxsonderby/CaseMark/FHIR MCP/fhir_mcp_server.py" ], "env": {} } } } ``` ## Restart Claude Desktop After saving the config, restart Claude Desktop to load the MCP server. ## Verify Connection In Claude Desktop, you should see the FHIR server tools available. Try: > "List all FHIR resource groups available" Claude will use the `list_all_resource_groups` tool. ## Example Workflows in Claude Desktop ### 1. Progressive Discovery ``` You: I need to work with patient vitals and observations Claude will: 1. Call discover_resource_groups(intent="patient vitals observations") 2. Show you relevant groups (Clinical, Administrative) 3. Call explore_resource_group(group_id="clinical") 4. Present Observation resource details ``` ### 2. Create a Patient ``` You: Create a FHIR patient resource for John Doe, born 1990-01-01, male Claude will: 1. Call get_resource_schema(resource_type="Patient") 2. Call create_resource() with the data 3. Return validated FHIR JSON ``` ### 3. Convert PDF Medical Record ``` You: Convert this PDF lab report to FHIR format: /path/to/report.pdf Claude will: 1. Call convert_pdf_to_fhir(pdf_path="/path/to/report.pdf", document_type="lab_report") 2. Extract text and metadata 3. Return DocumentReference resource ``` ## Available Tools in Claude Desktop Once connected, Claude can use these 11 tools: **Discovery:** - `discover_resource_groups` - Find relevant FHIR groups by intent - `explore_resource_group` - Deep dive into specific group - `list_all_resource_groups` - Complete overview **Resource Operations:** - `get_resource_schema` - Get structure of any FHIR resource - `create_resource` - Create & validate resources - `validate_resource` - Validate FHIR JSON - `convert_between_formats` - JSON ↔ XML ↔ YAML - `search_resources` - Validate search parameters **PDF Conversion:** - `convert_pdf_to_fhir` - Single PDF to FHIR - `batch_convert_pdfs_to_fhir` - Batch process directory **Utilities:** - `get_fhir_version_info` - Version information ## Testing the Integration After setup, test with: ``` You: What FHIR resource groups are available for billing and claims? Expected: Claude will discover_resource_groups with intent "billing claims" and show you the Financial resource group with Coverage, Claim, Invoice, etc. ``` ## Troubleshooting **Server doesn't appear:** - Check the config file path is correct - Verify Python 3 is in your PATH: `which python3` - Check absolute path to fhir_mcp_server.py is correct - Restart Claude Desktop completely **Tools fail to execute:** - Ensure dependencies are installed: `cd "/Users/maxsonderby/CaseMark/FHIR MCP" && python3 -m pip install -r requirements.txt` - Check server logs (they appear in Claude Desktop developer console) **PDF conversion fails:** - Install PyPDF2: `pip3 install PyPDF2` - Verify PDF file path is absolute and exists ## Advanced Configuration ### Environment Variables Add environment variables to the config if needed: ```json { "mcpServers": { "fhir-progressive": { "command": "python3", "args": [ "/Users/maxsonderby/CaseMark/FHIR MCP/fhir_mcp_server.py" ], "env": { "FHIR_VERSION": "R5", "DEBUG": "false" } } } } ``` ### Using Virtual Environment If you want to use a virtual environment: ```json { "mcpServers": { "fhir-progressive": { "command": "/Users/maxsonderby/CaseMark/FHIR MCP/venv/bin/python", "args": [ "/Users/maxsonderby/CaseMark/FHIR MCP/fhir_mcp_server.py" ] } } } ``` ## Benefits of This Integration 1. **Context Efficiency**: Progressive discovery means Claude doesn't load 100+ resources at once 2. **Intent-Based**: Claude discovers resources based on what you actually need 3. **Validation**: All FHIR resources are validated before creation 4. **Format Flexibility**: Convert between JSON, XML, YAML seamlessly 5. **PDF Processing**: Extract medical data from PDFs natively ## Example Session ``` You: I'm building a patient management system. Show me what's available. Claude: Let me discover the relevant FHIR resources for patient management... [Calls discover_resource_groups(intent="patient management")] I found these relevant resource groups: - Administrative Resources (9 resources): Patient, Practitioner, Organization... - Clinical Resources (10 resources): Condition, Observation, Procedure... - Workflow Resources (10 resources): Encounter, Appointment, Task... Would you like to explore any of these groups in detail? You: Yes, show me the administrative resources Claude: [Calls explore_resource_group(group_id="administrative")] The Administrative Resources group contains: - Patient, Practitioner, PractitionerRole, Organization, Location, HealthcareService, Endpoint, Person, Group, RelatedPerson I can help you: - Get the schema for any resource (e.g., Patient) - Create new resources with validation - Search for resources - Convert between formats What would you like to do? You: Create a patient record for Sarah Johnson, female, born 1988-03-15 Claude: [Calls create_resource with Patient data] ✅ Created FHIR Patient resource successfully: { "resourceType": "Patient", "id": "not-assigned", "name": [{ "family": "Johnson", "given": ["Sarah"] }], "gender": "female", "birthDate": "1988-03-15" } This resource is valid FHIR R5. You can now send it to your FHIR server! ``` --- **Ready to go!** 🚀