Epic Ehr

A comprehensive Electronic Health Record (EHR) system implementing EPIC-style workflows with WebSocket support, JWT authentication, and complete healthcare data management.

License: MIT Python 3.11+

🏥 Overview

This is a production-ready Model Context Protocol (MCP) server that simulates a complete EHR system similar to EPIC. It provides 20+ healthcare tools for managing patient data, appointments, medications, lab results, and more.

Perfect for:

• Healthcare AI agent development
• EHR integration testing
• Clinical workflow simulation
• Medical AI training
• FHIR/HL7 prototyping
• Healthcare app development

✨ Features

Complete EHR Functionality

• Patient Management - Demographics, search, insurance
• Clinical Documentation - Medical history, allergies, SOAP notes, care plans
• Medication Management - Prescriptions, refills, current medications
• Lab & Diagnostics - Lab results, orders, imaging reports
• Vital Signs - Recording and history
• Appointments - Scheduling, cancellation, status tracking
• Immunizations - Vaccine records
• Provider Directory - Search by specialty
• Billing & Insurance - Claims, charges

Security Features

• JWT Token-based Authentication (industry standard)
• Access tokens (24-hour expiry) and refresh tokens (30-day expiry)
• Token revocation (logout functionality)
• Role-based access control (Doctor, Nurse, Patient, Admin)
• Permission validation for sensitive operations
• Secure token signing with HS256 algorithm

Technical Features

• WebSocket + stdio transport
• 20+ MCP tools
• Comprehensive mock data
• Session-based authentication
• EPIC-style operations
• Production-ready architecture

🚀 Quick Start

Installation

# Clone repository
git clone https://github.com/YOUR_USERNAME/epic-ehr-mcp-server.git
cd epic-ehr-mcp-server

# Install dependencies
pip install -r requirements.txt

Run Server

# WebSocket mode (for remote connections)
python ehr_server.py --websocket

# Stdio mode (for local MCP clients like Kiro)
python ehr_server.py

Test

# Run test client
python test_client.py

📚 Documentation

• QUICKSTART.md - 5-minute setup guide
• AUTHENTICATION.md - Complete JWT authentication guide
• DEPLOYMENT.md - Cloud deployment options (AWS, Azure, Railway)
• SIMPLE_DEPLOYMENT.md - VPS deployment without Docker
• JWT_FEATURES.md - JWT implementation details

🔐 Authentication

Test Users

Username	Password	Role	Description
dr_smith	doctor123	doctor	Dr. Sarah Smith (Internal Medicine)
nurse_jones	nurse123	nurse	Nurse John Jones
patient_doe	patient123	patient	John Doe (Patient MRN001)
admin_user	admin123	admin	System Administrator

Example Usage

import asyncio
import websockets
import json

async def example():
    async with websockets.connect('ws://localhost:8766') as ws:
        # Authenticate
        auth_msg = {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": "authenticate",
                "arguments": {
                    "username": "dr_smith",
                    "password": "doctor123"
                }
            }
        }
        await ws.send(json.dumps(auth_msg))
        response = await ws.recv()
        auth_data = json.loads(response)
        
        # Extract access token
        access_token = auth_data['result']['content'][0]['text']['access_token']
        
        # Get patient data
        patient_msg = {
            "jsonrpc": "2.0",
            "id": 2,
            "method": "tools/call",
            "params": {
                "name": "get_patient",
                "arguments": {
                    "access_token": access_token,
                    "mrn": "MRN001"
                }
            }
        }
        await ws.send(json.dumps(patient_msg))
        response = await ws.recv()
        print(response)

asyncio.run(example())

🛠️ Available Tools

Authentication

• authenticate - Login and get JWT tokens
• refresh_token - Refresh expired access token
• logout - Revoke access token

Patient Management

• get_patient - Get patient demographics
• search_patients - Search for patients

Medical Records

• get_medical_history - Get conditions and diagnoses
• get_allergies - Get patient allergies
• get_medications - Get current medications
• prescribe_medication - Prescribe new medication

Lab & Diagnostics

• get_lab_results - Get lab test results
• order_lab_test - Order new lab test
• get_imaging_reports - Get imaging reports

Vital Signs

• get_vital_signs - Get vital signs history
• record_vital_signs - Record new vitals

Appointments

• get_appointments - Get patient appointments
• schedule_appointment - Schedule new appointment
• cancel_appointment - Cancel appointment

Clinical Documentation

• get_clinical_notes - Get clinical notes
• create_clinical_note - Create new note

Other

• get_immunizations - Get immunization history
• get_care_plan - Get patient care plan
• search_providers - Search healthcare providers
• get_billing_info - Get billing information

🏗️ Architecture

Client (AI Agent, Web App, Mobile)
    ↓
WebSocket/Stdio Transport (JSON-RPC 2.0)
    ↓
JWT Authentication & Authorization
    ↓
MCP Server Core (Tool Registry)
    ↓
Business Logic Layer (20+ Tools)
    ↓
Data Layer (Mock Data / Database)

📦 Project Structure

epic-ehr-server/
├── ehr_server.py              # Main MCP server
├── auth.py                    # JWT authentication
├── ehr_tools.py              # Tool implementations
├── mock_data.py              # Healthcare mock data
├── test_client.py            # Test client
├── requirements.txt          # Dependencies
├── README.md                 # This file
├── AUTHENTICATION.md         # Auth guide
├── DEPLOYMENT.md            # Deployment guide
├── SIMPLE_DEPLOYMENT.md     # VPS deployment
├── QUICKSTART.md            # Quick start
└── JWT_FEATURES.md          # JWT details

🚀 Deployment

Quick Deploy (Railway)

1. Push to GitHub
2. Connect Railway to GitHub
3. Railway auto-deploys
4. Get public URL

VPS Deployment

See SIMPLE_DEPLOYMENT.md for step-by-step guide.

Cloud Deployment

See DEPLOYMENT.md for AWS, Azure, Google Cloud options.

🔒 Security

• JWT token-based authentication
• Role-based access control (RBAC)
• Token expiration and refresh
• Secure password hashing (SHA-256)
• HTTPS/WSS support
• Input validation
• Permission checks

🧪 Testing

# Run complete workflow test
python test_client.py

# Run appointment booking test
python appointment_booking_example.py

# Run persistence test
python test_persistence.py

📊 Mock Data

The server includes comprehensive mock data:

• 2 patients with complete medical records
• Medical history, allergies, medications
• Lab results, vital signs, immunizations
• Appointments, clinical notes, care plans
• 2 providers (doctors)
• Billing records

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with MCP (Model Context Protocol)
• Inspired by EPIC EHR workflows
• JWT implementation using PyJWT

📞 Support

For issues, questions, or contributions:

• Open an issue on GitHub
• Check documentation in the repo
• Review example files

🗺️ Roadmap

• Database persistence (PostgreSQL)
• FHIR R4 compliance
• HL7 v2 message support
• SMART on FHIR authentication
• Real-time notifications
• Audit logging
• Multi-tenancy support
• GraphQL API

---

Built with ❤️ for healthcare AI development