Used for high-performance asynchronous HTTP operations, enabling non-blocking I/O for FHIR server communications
Manages environment variables for configuration, particularly for storing the OpenAI API key and FHIR server credentials
Provides architecture diagram visualization capabilities for representing the FHIR system components and relationships
Enables AI-powered clinical text analysis, code mapping, and patient matching features for enhanced healthcare data processing
Core runtime environment for the FHIR server implementation and tools library
Provides enhanced terminal output formatting for the FHIR Timeline Agent's interactive CLI interface
FHIR Careplan - Universal FHIR Server and Tools
A comprehensive FHIR (Fast Healthcare Interoperability Resources) server and toolkit designed for healthcare data integration, patient care planning, and clinical decision support. This project provides a universal interface to multiple FHIR servers with advanced AI-powered clinical analysis capabilities.
🏥 Overview
The FHIR Careplan project consists of two main components:
- Universal FHIR MCP Server (
fhir_server.py
) - A Model Context Protocol (MCP) server that provides standardized access to multiple FHIR servers - FHIR Tools Library (
fhir_tools.py
) - A comprehensive Python library for FHIR data manipulation, analysis, and AI-powered clinical insights
✨ Key Features
🔗 Multi-Server FHIR Integration
- Universal FHIR Interface: Connect to multiple FHIR servers (Epic, Cerner, HAPI, Firely, etc.)
- Vendor-Agnostic: Standardized API regardless of underlying FHIR server implementation
- Real-time Connectivity Testing: Automatic server health checks and diagnostics
- Intelligent Failover: Automatic switching between servers for optimal performance
🤖 AI-Powered Clinical Analysis
- OpenAI Integration: Extract clinical keywords and concepts from free text
- Semantic Mapping: Map clinical terms to standardized FHIR codes
- Similar Patient Matching: Find patients with similar clinical profiles
- Predictive Analytics: Generate care recommendations based on historical data
📊 Comprehensive Patient Data Access
- Complete Patient Records: Demographics, conditions, medications, procedures, encounters
- Vital Signs & Lab Results: Categorized observations with time-series data
- Care Plans & Teams: Treatment plans and healthcare provider information
- Allergies & Procedures: Complete medical history tracking
🚀 Performance Optimization
- Async Operations: Non-blocking I/O for high-performance data access
- Intelligent Caching: Condition codes and frequently accessed data caching
- Batch Processing: Efficient handling of multiple patient records
- Connection Pooling: Optimized HTTP connections for multiple servers
🛠 Installation
Prerequisites
- Python 3.11 or higher
- OpenAI API key (for AI features)
- Access to FHIR servers (local or remote)
Setting Up MCP Server
- Clone the Repository
- Install Dependencies
- Configure Environment Variables
- Run the FHIR MCP Server
Setting Up Firely Test Database Locally
- Obtain a Firely Server License Key
- Visit Firely Server Trial Page
- Fill out the form to receive a license key via email
- You'll receive the license key and download files (license valid for 7 days)
- Save the license file as
firelyserver-license.json
- Set Up Using Docker
- Load Test Data
- Use Postman to load test data bundles
- Create a new PUT request in Postman
- Set request type to raw JSON
- Copy content from test data bundles
- Send requests to base URL (http://localhost:9090)
- Repeat for each data bundle
After completing these steps, you'll have a working test database accessible at http://localhost:9090.
Setting Up MCP Chatbot Client
You can set up the MCP chatbot client either by forking the repository or using Docker. The chatbot will serve as the frontend interface for interacting with the FHIR server.
- Get the Chatbot setup
- Install PNPM (if not installed)
- Choose Setup Method:
Docker Compose Setup 🐳
Local Setup 🚀
- Configure Environment Variables
Create/edit
.env
file with required API keys: - Connect MCP Server to Chatbot
- Access the chatbot at http://localhost:3000
- Create an account and login
- Go to MCP configuration
- Click "Add Server"
- Copy-paste your
.chatbot-config.json
configuration
- Configure System Prompt
- Navigate to
src/app/prompts.ts
in the chatbot repository - Replace the default system prompt with your custom prompt from
system_prompt.txt
- Example system prompt structure:
- Customize the prompt sections based on your needs:
<communication>
: Define how the AI should interact<tool_calling>
: Specify rules for using tools<making_code_changes>
: Set guidelines for code modifications
- Save the changes and restart the development server
- Navigate to
After completing these steps, your chatbot will be connected to the MCP server and ready to interact with the FHIR database.
🏗 Architecture
Core Components
Server Registry
The system maintains a comprehensive registry of FHIR servers:
- Firely Local (
http://localhost:9090
) - Local development server - HAPI R4 (
http://hapi.fhir.org/baseR4
) - Public test server - Epic, Cerner, Azure - Enterprise healthcare systems (configurable)
📖 Usage Guide
Basic FHIR Operations
1. Server Management
2. Patient Search
3. Patient Data Retrieval
AI-Powered Clinical Analysis
1. Clinical Text Extraction
2. FHIR Code Mapping
3. Similar Patient Matching
MCP Server Integration
The FHIR server can be used as an MCP server for integration with AI assistants:
🔧 Configuration
Server Configuration
The system supports multiple FHIR servers configured in fhir_tools.py
:
Environment Variables
🔍 Available Tools
Core FHIR Operations
switch_server(server_name)
- Switch between FHIR serverstest_server_connectivity(server_name)
- Test server connectivityfind_patient(search_criteria)
- Search for patientsget_comprehensive_patient_info(patient_id)
- Get complete patient data
Clinical Data Access
get_patient_observations(patient_id)
- Get patient observationsget_patient_conditions(patient_id)
- Get patient conditionsget_patient_medications(patient_id)
- Get patient medicationsget_vital_signs(patient_id)
- Get vital signsget_lab_results(patient_id)
- Get laboratory resultsget_patient_encounters(patient_id)
- Get patient encountersget_patient_allergies(patient_id)
- Get patient allergiesget_patient_procedures(patient_id)
- Get patient procedures
AI-Powered Analysis
extract_clinical_keywords(text)
- Extract clinical information from textmap_to_fhir_codes_fast(clinical_data)
- Map terms to FHIR codesfind_similar_patients_simple(criteria)
- Find similar patientsextract_condition_codes_from_fhir()
- Extract all condition codes
System Management
list_available_servers()
- List all configured serversget_server_registry()
- Get complete server registrydiagnose_fhir_server(server_name)
- Diagnose server capabilitiesclear_condition_cache()
- Clear condition codes cacheget_condition_cache_stats()
- Get cache performance statistics
🧪 Testing Tools
MCP Inspector
The MCP (Model Context Protocol) Inspector is a powerful development and testing tool that helps debug and validate FHIR server interactions. It provides real-time inspection of server behavior and API responses.
Using MCP Inspector
Features
- Real-time Monitoring: Watch FHIR server interactions as they happen
- Request/Response Logging: Detailed logs of all API calls and responses
- Error Detection: Immediate feedback on API errors or misconfigurations
- Performance Metrics: Track response times and server performance
- Debug Mode: Enhanced logging for development troubleshooting
Log File Location
The inspector writes detailed logs to:
Best Practices
- Use MCP Inspector during development to validate server behavior
- Monitor the log file for unexpected errors or performance issues
- Run the inspector when implementing new FHIR endpoints
- Use it to debug connection issues with external FHIR servers
🏥 Business Applications
Hospital Engagement Platform
This toolkit can power automated hospital engagement platforms:
- Patient Care Coordination
- Automated care plan generation
- Treatment timeline management
- Multi-disciplinary team coordination
- Clinical Decision Support
- Evidence-based treatment recommendations
- Risk assessment and early warnings
- Outcome prediction based on similar cases
- Resource Optimization
- Predictive analytics for resource allocation
- Automated scheduling and capacity management
- Cost optimization through data-driven insights
- Quality Improvement
- Automated quality metrics tracking
- Compliance monitoring and reporting
- Performance analytics and benchmarking
🔐 Security & Compliance
- HIPAA Compliance: Designed with healthcare data privacy in mind
- Secure Communication: HTTPS/TLS encryption for all server communications
- Authentication Support: Multiple authentication methods (OAuth, API keys, etc.)
- Audit Logging: Comprehensive logging for compliance and debugging
📊 Performance Features
- Async Operations: Non-blocking I/O for high throughput
- Connection Pooling: Efficient HTTP connection management
- Intelligent Caching: Condition codes and metadata caching
- Batch Processing: Efficient handling of multiple records
- Error Handling: Robust error handling and retry mechanisms
🧪 Testing
Running Tests
Server Diagnostics
📝 Logging
The system provides comprehensive logging:
🤝 Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Submit a pull request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🆘 Support
For support and questions:
- Create an issue in the GitHub repository
- Check the logs directory for detailed error information
- Use the diagnostic tools for server troubleshooting
🔄 Version History
- v0.1.0 - Initial release with core FHIR functionality
- v0.2.0 - Added AI-powered clinical analysis
- v0.3.0 - Enhanced multi-server support and caching
🎯 Roadmap
- Advanced analytics dashboard
- Real-time data streaming
- Machine learning model integration
- Enhanced security features
- Mobile application support
- Cloud deployment templates
🕒 FHIR Timeline Agent
The FHIR Timeline Agent (fhir_timeline_agent.py
) is a specialized agent designed to generate detailed clinical treatment timelines from patient queries using real FHIR data. It's specifically configured to work with the Firely Local FHIR server.
Features
- Natural Language Processing: Converts free-text patient queries into structured clinical data
- Real Patient Data Analysis: Uses actual FHIR patient records for timeline generation
- AI-Powered Timeline Generation: Leverages OpenAI GPT-4 for accurate clinical timelines
- Interactive CLI Interface: User-friendly command-line interface with rich formatting
- Comprehensive Patient Matching: Finds similar patients based on age, gender, and conditions
Usage
Example Queries
Timeline Generation Process
- Query Processing
- Extracts clinical keywords from natural language
- Identifies age, gender, conditions, stage, and biomarkers
- FHIR Code Mapping
- Maps clinical terms to standardized FHIR codes
- Uses Firely Local server's code systems
- Similar Patient Search
- Finds matching patients in the FHIR database
- Scores matches based on age, gender, and conditions
- Data Aggregation
- Collects comprehensive medical history
- Includes procedures, medications, encounters
- Timeline Generation
- Creates detailed treatment timeline using AI
- Organizes events chronologically with clinical context
Output Format
The agent generates rich, formatted output including:
- Patient Profile: Demographics, diagnosis, stage, biomarkers
- Treatment Timeline: Step-by-step clinical events with dates
- Clinical Outcomes: Treatment response, survival status, toxicity
- Data Sources: Server information and analysis metrics
Configuration
The agent is hardcoded to use:
- Firely Local FHIR server (
http://localhost:9090
) - OpenAI GPT-4 for timeline generation
- Rich console output for formatted display
Requirements
- OpenAI API key (set in
.env
file) - Running Firely Local FHIR server
- Python packages:
Best Practices
- Provide complete patient information in queries
- Include age, gender, and primary diagnosis
- Add stage and biomarker information when available
- Use specific clinical terms for better matching
Error Handling
The agent includes robust error handling for:
- Missing patient information
- FHIR server connectivity issues
- AI generation failures
- Data parsing errors
Each error is displayed with helpful suggestions for resolution.
Built with ❤️ for healthcare interoperability and patient care improvement
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A comprehensive Model Context Protocol server that provides universal access to multiple FHIR servers with AI-powered clinical analysis capabilities for healthcare data integration and patient care planning.
Related MCP Servers
- -securityFlicense-qualityA Model Context Protocol server providing AI assistants with access to healthcare data tools, including FDA drug information, PubMed research, health topics, clinical trials, and medical terminology lookup.Last updated -10Python
- -securityFlicense-qualityA Model Context Protocol server that connects AI tools to Electronic Health Records using SMART on FHIR, allowing secure searching, querying, and analysis of patient data from compatible EHRs.Last updated -38TypeScript
- -securityAlicense-qualityA server that implements the Model Context Protocol, providing a standardized way to connect AI models to different data sources and tools.Last updated -35TypeScriptMIT License
- AsecurityAlicenseAqualityA Model Context Protocol server that enables standardized interaction with Azure Health Data Services FHIR servers, allowing healthcare data operations through MCP tools.Last updated -17PythonMIT License