FHIR Progressive Discovery MCP Server

# Claude Code MCP Installation Guide ## Quick Install (3 Steps) ### 1. Set MCP Configuration Path Claude Code needs to know where your MCP config is: ```bash export MCP_CONFIG_PATH="/Users/maxsonderby/CaseMark/FHIR MCP/mcp_config.json" ``` Add this to your shell profile to make it permanent: ```bash echo 'export MCP_CONFIG_PATH="/Users/maxsonderby/CaseMark/FHIR MCP/mcp_config.json"' >> ~/.zshrc source ~/.zshrc ``` ### 2. Verify Installation Test that the server works: ```bash cd "/Users/maxsonderby/CaseMark/FHIR MCP" python3 test_mcp_client.py ``` You should see: ✅ ALL MCP CLIENT TESTS PASSED! ### 3. Start Using in Claude Code Claude Code will automatically load the MCP server from the config. **Test it:** ``` You: List all available FHIR resource groups ``` Claude Code will use the `list_all_resource_groups` tool. --- ## Alternative: Manual Claude Code Settings If Claude Code doesn't auto-detect the config, you can configure it manually: ### Using Claude Code Settings UI 1. Open Claude Code settings 2. Navigate to MCP Servers section 3. Add a new server: - **Name**: `fhir-progressive` - **Command**: `python3` - **Args**: `["/Users/maxsonderby/CaseMark/FHIR MCP/fhir_mcp_server.py"]` ### Using settings.json Add to your Claude Code `settings.json`: ```json { "claudeCode.mcpServers": { "fhir-progressive": { "command": "python3", "args": [ "/Users/maxsonderby/CaseMark/FHIR MCP/fhir_mcp_server.py" ] } } } ``` --- ## Verify MCP Server is Running Check if the server shows up: ```bash # The server should respond to stdio echo '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' | python3 "/Users/maxsonderby/CaseMark/FHIR MCP/fhir_mcp_server.py" ``` --- ## Usage Examples in Claude Code ### Example 1: Progressive Discovery ``` You: I'm building a healthcare app for patient management. What FHIR resources are available? Claude Code will: 1. Call discover_resource_groups(intent="patient management healthcare") 2. Show relevant groups: Administrative, Clinical, Workflow 3. List specific resources in each group ``` ### Example 2: Create Patient ``` You: Create a FHIR Patient resource: - Name: Alice Johnson - Gender: Female - DOB: 1992-05-20 - Active status Claude Code will: 1. Call get_resource_schema(resource_type="Patient") to check structure 2. Call create_resource() with the data 3. Return validated FHIR JSON ``` ### Example 3: Convert PDF ``` You: Convert this medical PDF to FHIR: /path/to/lab_results.pdf Claude Code will: 1. Call convert_pdf_to_fhir(pdf_path="...", document_type="lab_report") 2. Extract text and create DocumentReference 3. Show structured FHIR resource ``` --- ## Available Tools (11 Total) Once loaded, Claude Code has access to: **Discovery (3 tools):** - `discover_resource_groups` - Intent-based discovery - `explore_resource_group` - Deep dive into groups - `list_all_resource_groups` - Complete overview **FHIR Operations (5 tools):** - `get_resource_schema` - Get resource structure - `create_resource` - Create & validate - `validate_resource` - Validate JSON - `convert_between_formats` - JSON/XML/YAML conversion - `search_resources` - Parameter validation **PDF Conversion (2 tools):** - `convert_pdf_to_fhir` - Single file conversion - `batch_convert_pdfs_to_fhir` - Batch processing **Utilities (1 tool):** - `get_fhir_version_info` - Version info --- ## Troubleshooting ### Server doesn't load **Check Python path:** ```bash which python3 # Should show: /Library/Frameworks/Python.framework/Versions/3.13/bin/python3 ``` **Check dependencies:** ```bash cd "/Users/maxsonderby/CaseMark/FHIR MCP" python3 -m pip install -r requirements.txt ``` **Test server directly:** ```bash python3 fhir_mcp_server.py # Should start the FastMCP server ``` ### Tools not appearing **Check MCP config is valid JSON:** ```bash cat "/Users/maxsonderby/CaseMark/FHIR MCP/mcp_config.json" | python3 -m json.tool ``` **Restart Claude Code:** - Completely quit and restart Claude Code - Check developer console for errors ### Import errors **Missing fhir.resources:** ```bash python3 -m pip install fhir.resources>=8.0.0 ``` **Missing FastMCP:** ```bash python3 -m pip install fastmcp>=2.0.0 ``` --- ## Testing Commands ### Quick Test ```bash cd "/Users/maxsonderby/CaseMark/FHIR MCP" python3 test_server.py ``` ### Full MCP Test ```bash python3 test_mcp_client.py ``` ### Interactive Demo ```bash python3 test_interactive.py ``` --- ## Configuration File Location The MCP config is at: ``` /Users/maxsonderby/CaseMark/FHIR MCP/mcp_config.json ``` You can also copy it to standard locations: **For Claude Desktop:** ```bash cp mcp_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` **For VS Code:** ```bash mkdir -p ~/.config/Code/User/ cp mcp_config.json ~/.config/Code/User/claude_code_mcp.json ``` --- ## What Happens When You Use It **Behind the scenes:** 1. You ask Claude Code a FHIR-related question 2. Claude Code analyzes your intent 3. Calls `discover_resource_groups(intent="your question")` 4. Gets back relevant FHIR resource groups ranked by relevance 5. Progressively loads only what's needed 6. Performs operations (create, validate, convert) **Benefits:** - 🚀 Only loads resources you need (saves context) - 🎯 Intent-driven discovery - ✅ Full FHIR validation - 📄 Native PDF processing - 🔄 Multi-format support --- ## Quick Start Checklist - [ ] Dependencies installed: `pip install -r requirements.txt` - [ ] Tests passing: `python3 test_mcp_client.py` - [ ] Config file exists: `mcp_config.json` - [ ] Environment variable set: `MCP_CONFIG_PATH` - [ ] Claude Code restarted - [ ] Test query: "List all FHIR resource groups" **You're ready to go!** 🎉