Smart Server

A Model Context Protocol (MCP) server that provides comprehensive FHIR R4 operations including PlanDefinition $apply, resource management, terminology services, and Questionnaire/StructureMap transformation via Matchbox.

Purpose

This MCP server provides a secure interface for AI assistants to interact with FHIR R4 servers, enabling clinical decision support workflows through PlanDefinitions, resource creation/management, terminology lookups, and structured data capture via Questionnaires.

Features

ImplementationGuide Context Management

• fhir_set_implementation_guide_context - Set the IG context for resource validation
• fhir_get_current_implementation_guide_context - Get the currently set IG context
• fhir_get_implementation_guide - Retrieve full IG details by ID or URL
• fhir_list_implementation_guides - List available IGs on the server

PlanDefinition Operations

• fhir_list_plan_definitions - List available PlanDefinitions with filters
• fhir_get_plan_definition - Get full PlanDefinition details including actions
• fhir_apply_plan_definition - Execute $apply to generate a CarePlan

Generic Resource Operations

• fhir_get_resource - Retrieve any FHIR resource by type and ID
• fhir_search_resources - Search resources with FHIR search parameters
• fhir_create_resource - Create any FHIR resource using raw JSON
• fhir_update_resource - Update an existing resource
• fhir_delete_resource - Delete a resource

Terminology Services

• fhir_list_valuesets - List available ValueSets
• fhir_expand_valueset - Expand a ValueSet to get all codes
• fhir_list_codesystems - List available CodeSystems
• fhir_lookup_code - Look up a code's display and properties

Questionnaire Operations

• fhir_get_questionnaire - Retrieve a Questionnaire for data capture
• fhir_list_questionnaires - List available Questionnaires
• fhir_transform_questionnaire_response - Transform via StructureMap on Matchbox

Server Information

• fhir_get_server_capability - Get the server's CapabilityStatement

Prerequisites

• Docker Desktop with MCP Toolkit enabled
• Docker MCP CLI plugin (docker mcp command)
• FHIR R4 server running (default: http://localhost:8080/fhir)
• Matchbox server for StructureMap transforms (default: http://localhost:8081/matchboxv3/fhir)

Configuration

Environment variables:

• FHIR_SERVER_URL - Base URL of the FHIR server (default: http://localhost:8080/fhir)
• MATCHBOX_SERVER_URL - Base URL of Matchbox server (default: http://localhost:8081/matchboxv3/fhir)

Installation

See the step-by-step instructions provided with the files.

Usage Examples

In Claude Desktop, you can ask:

ImplementationGuide Context

• "Set the implementation guide context to the WHO SMART Guidelines IG"
• "What implementation guide are we currently using?"
• "List all available implementation guides"

PlanDefinition Workflows

• "List all active plan definitions"
• "Show me the details of the diabetes screening plan definition"
• "Apply the immunization plan definition to Patient/123"
• "What actions are defined in PlanDefinition/anc-contact?"

Resource Management

• "Create a new Patient resource with name John Smith, born 1980-01-15"
• "Search for all Observations for Patient/123"
• "Get the Condition with ID abc123"
• "Delete the Observation with ID temp-obs-1"

Terminology

• "List ValueSets related to pregnancy"
• "Expand the administrative gender ValueSet"
• "Look up LOINC code 8867-4"
• "What codes are in the observation category CodeSystem?"

Questionnaire Workflow

• "Get the ANC registration questionnaire"
• "List all active questionnaires"
• "Transform this QuestionnaireResponse using the ANC StructureMap"

Architecture

Claude Desktop → MCP Gateway → FHIR MCP Server → FHIR Server (localhost:8080)
                                       ↓
                               Matchbox Server (localhost:8081)
                               (for StructureMap transforms)

Workflow: Using Questionnaires to Create Resources

1. Get the Questionnaire: Use fhir_get_questionnaire to retrieve the questionnaire structure
2. Ask Questions: The agent asks the user each question based on the Questionnaire items
3. Build QuestionnaireResponse: The agent constructs the QuestionnaireResponse JSON
4. Transform: Use fhir_transform_questionnaire_response to convert to FHIR resources via Matchbox
5. Create Resources: The transformed Bundle can be processed to create individual resources

Workflow: Applying PlanDefinitions

1. Set Context: Use fhir_set_implementation_guide_context to set the IG
2. Find PlanDefinition: Use fhir_list_plan_definitions to find available plans
3. Review Requirements: Use fhir_get_plan_definition to see what data is needed
4. Prepare Data: Create required resources (Patient, Observations, etc.)
5. Apply: Use fhir_apply_plan_definition to generate the CarePlan
6. Process: The agent processes the returned CarePlan activities

Development

Local Testing

# Set environment variables for testing
export FHIR_SERVER_URL="http://localhost:8080/fhir"
export MATCHBOX_SERVER_URL="http://localhost:8081/matchboxv3/fhir"

# Run directly
python fhir_server.py

# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python fhir_server.py

Adding New Tools

1. Add the function to fhir_server.py
2. Decorate with @mcp.tool()
3. Use SINGLE-LINE docstrings only
4. Use empty string defaults for parameters
5. Update the catalog entry with the new tool name
6. Rebuild the Docker image

Troubleshooting

Tools Not Appearing

• Verify Docker image built successfully
• Check catalog and registry files
• Ensure Claude Desktop config includes custom catalog
• Restart Claude Desktop

FHIR Server Connection Errors

• Verify FHIR server is running and accessible
• Check the FHIR_SERVER_URL environment variable
• Test with: curl http://localhost:8080/fhir/metadata

Matchbox Transform Errors

• Verify Matchbox server is running
• Check that the StructureMap exists and is valid
• Ensure QuestionnaireResponse references the correct Questionnaire

Validation Errors

• Set the ImplementationGuide context before creating resources
• Check that resources conform to the expected profiles
• Review the OperationOutcome details in error messages

Security Considerations

• No authentication configured by default (suitable for local development)
• For production, configure FHIR server authentication
• Running as non-root user in Docker
• Sensitive data never logged

FHIR Resources

• FHIR R4 Specification: https://hl7.org/fhir/R4/
• PlanDefinition: https://hl7.org/fhir/R4/plandefinition.html
• $apply Operation: https://hl7.org/fhir/R4/plandefinition-operation-apply.html
• Questionnaire: https://hl7.org/fhir/R4/questionnaire.html
• StructureMap: https://hl7.org/fhir/R4/structuremap.html

License

MIT License