smart-mcp-server

DigitalSQR/smart-mcp-server

3.2

If you are the rightful owner of smart-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

This MCP server provides tools to interact with FHIR R4 PlanDefinition resources, enabling AI assistants to list and apply PlanDefinitions.

Tools
2
Resources
0
Prompts
0

FHIR MCP 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

Configuration

Environment variables:

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

License

MIT License