An intelligent clinical decision support system that leverages the Model Context Protocol (MCP) to provide structured, auditable clinical recommendations. The system ingests unstructured clinical notes and generates evidence-based treatment plans with precise medication dosing calculations.
- Clinical Note Parsing: Extracts structured patient data from unstructured text
- Condition Identification: Matches symptoms and assessments to medical conditions
- Medication Dosing: Calculates weight-based doses with safety constraints
- Treatment Planning: Generates comprehensive, evidence-based treatment plans
- Audit Trail: Provides transparent, reproducible clinical reasoning
- Pediatric Croup (Laryngotracheobronchitis)
- Adult Acute Asthma (Bronchospasm)
- COPD Exacerbation (Chronic Obstructive Pulmonary Disease)
- Community-Acquired Pneumonia (CAP)
- Pediatric Gastroenteritis (Dehydration management)
🔗 Production System:
┌──────────────-───┐ ┌─────────────────┐ ┌─────────────────┐
│ React Frontend │ │ AWS Gateway │ │ MCP Server │
│ (Vite + UI) │───▶│ (Lambda) │───▶│ (Python) │
└──────────────── ─┘ └─────────────────┘ └─────────────────┘
│
┌─────────────────┐
│ JSON Data │
│ (Conditions │
│ & Guidelines) │
└─────────────────┘
- Deterministic Results: Medical decisions require reproducible, auditable outputs
- Structured Validation: Medical data needs strict input/output validation
- Performance: Direct tool calls are faster than semantic search
- Safety: Explicit logic is safer than AI interpretation for medical calculations
- Transparency: Clear reasoning chain for clinical decisions
- Simplicity: No database setup/configuration for MVP
- Version Control: Clinical data tracked in git with code
- Performance: Fast file reads from Lambda filesystem
- Cost: No database costs for MVP
- Development Speed: Instant data updates without deployment
- Node.js 18+ (managed via .nvmrc)
- Python 3.9+ for MCP server
- AWS CLI configured (for deployment)
- NVM (Node Version Manager)
# 1. Clone repository
# 2. Install Node Version Manager (if not installed)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# 3. Use correct Node version
nvm use
# 4. Install dependencies
npm install
pip3 install -r requirements.txt
# 5. Setup environment variables
cp .env.example .env
# Edit .env with your actual values
# 6. Run the system
python3 -m backend.mcp_server.server # MCP server
npm run dev -- --port 4000 # Frontend (in separate terminal)# Run the 20-line agent demo
python3 demo_agent.pyPatient: Jack T.
DOB: 12/03/2022
Age: 3 years
Weight: 14.2 kg
Presenting complaint:
Jack presented with a 2-day history of barky cough, hoarse voice, and low-grade fever.
Symptoms worsened overnight, with increased work of breathing and stridor noted at rest this morning.
Assessment:
Jack presents with classic features of moderate croup (laryngotracheobronchitis), likely viral in origin.
{
"condition": "croup",
"severity": "moderate",
"medication_dose": {
"medication": "dexamethasone",
"final_dose": 2.13,
"unit": "mg",
"dosing_rationale": "Calculated at 0.15 mg/kg for 14.2kg patient"
},
"treatment_plan": {
"immediate_actions": ["Administer corticosteroids", "Monitor respiratory status"],
"monitoring": "Observe for symptom improvement over 2-4 hours",
"follow_up": "Return if symptoms worsen or persist >5 days"
}
}Extracts structured patient data from unstructured clinical text.
{
"clinical_note": "Patient: John Doe, Age: 5 years, Weight: 18kg..."
}Matches symptoms and assessment to medical conditions.
{
"symptoms": ["barky cough", "hoarse voice", "stridor"],
"assessment": "moderate croup",
"patient_age": 3
}Calculates weight-based medication doses with safety constraints.
{
"medication": "dexamethasone",
"condition": "croup",
"patient_weight": 14.2,
"severity": "moderate"
}Generates comprehensive, evidence-based treatment plans.
{
"condition": "croup",
"severity": "moderate",
"patient_data": {"age": 3, "weight": 14.2, "name": "Jack T."},
"calculated_doses": [...]
}All tools include comprehensive input validation:
- Patient Weight: 0.5-300 kg (with 0.1 kg precision)
- Patient Age: 0-150 years (integer)
- Severity: Enum ["mild", "moderate", "severe", "life-threatening"]
- Clinical Notes: 10-10,000 characters
- Medications: Pattern validation for known drugs
The system provides structured error responses:
{
"success": false,
"error": "Patient weight must be between 0.5 and 300 kg",
"error_code": "INVALID_PATIENT_DATA",
"details": {"provided_weight": -5.0},
"recoverable": true
}root/
├── backend/
│ ├── mcp_server/ # MCP server implementation
│ │ ├── server.py # Main MCP server
│ │ ├── tools/ # MCP tools (parser, dosing, etc.)
│ │ ├── schemas/ # Pydantic data models
│ │ └── data/ # JSON data files
│ ├── lambda/ # Lambda function handlers
│ └── tests/ # Backend tests
├── frontend/
│ ├── src/
│ │ ├── components/ # React components (shadcn/ui)
│ │ ├── pages/ # Page components
│ │ └── lib/ # Utilities and API calls
│ └── dist/ # Build output
├── infrastructure/
│ ├── sst.config.ts # SST configuration
│ └── stacks/ # AWS CDK stacks
└── docs/ # Documentation
# Run MCP server locally
python3 -m backend.mcp_server.server
# Run tests
python3 -m pytest backend/tests/
# Run edge case tests
python3 -m pytest backend/tests/test_edge_cases.py
# Deploy to AWS
npx sst deploy --stage prod# Development server (MANDATORY: port 4000)
lsof -ti:4000 && kill -9 $(lsof -ti:4000) || true
npm run dev -- --port 4000
# Build for production
npm run build
# Type checking
npm run type-check
# Linting
npm run lintThe system includes comprehensive test coverage:
- Unit Tests: All MCP tools
- Integration Tests: Complete clinical workflows
- Edge Case Tests: Boundary conditions and error scenarios
- Performance Tests: Load and stress testing
# Run all tests
python3 -m pytest backend/tests/
# Run specific test categories
python3 -m pytest backend/tests/test_edge_cases.py -v
python3 -m pytest backend/tests/test_integration.py -vThe system deploys to AWS using SST (Serverless Stack):
- API Gateway: RESTful endpoints with authentication
- Lambda Functions: Serverless compute for MCP server
- CloudFront CDN: Global content delivery
- Route 53: DNS management
- CloudWatch: Logging and monitoring
# Data Configuration
DATA_PATH=/opt/data/
CONDITIONS_FILE=conditions.json
GUIDELINES_FILE=guidelines.json
# API Configuration
API_KEY=your-secure-api-key-here
CORS_ORIGINS=https://noteparser.uk,http://localhost:3000
# Logging
LOG_LEVEL=INFO
ENVIRONMENT=production# API Configuration
VITE_API_BASE_URL=https://api.noteparser.uk
VITE_API_KEY=your-secure-api-key-here
VITE_APP_NAME=Heidi Clinical Decision Support- No PHI Storage: No Personal Health Information stored in logs
- HIPAA Compliance: Data handling follows HIPAA guidelines
- Encryption: At rest (Lambda) and in transit (HTTPS)
- Input Validation: Comprehensive sanitization
- Rate Limiting: API endpoint protection
- Authentication: API key-based access control
- Not for Clinical Use: This system is not validated for clinical decision making
- Educational Only: Intended for demonstration and educational purposes
- Professional Oversight: All clinical decisions require qualified healthcare professionals
- Liability: Users assume all responsibility for any clinical decisions
- Validation Required: Any clinical use requires proper validation and regulatory approval
- Not FDA Approved: This software is not approved by the FDA or any regulatory body
- Not Diagnostic: This system does not diagnose medical conditions
- Not Prescriptive: This system does not prescribe medications
- Professional Judgment: Healthcare professionals must use their clinical judgment
- Updated Guidelines: Always refer to current medical guidelines and protocols
We welcome contributions from healthcare professionals and developers:
- Review clinical algorithms and dosing calculations
- Suggest additional conditions and treatment protocols
- Validate against current medical guidelines
- Provide clinical feedback and edge cases
- Improve system architecture and performance
- Add new MCP tools and integrations
- Enhance error handling and validation
- Write comprehensive tests
- Fork the repository
- Create a feature branch
- Add comprehensive tests
- Ensure all tests pass
- Update documentation
- Submit a pull request
MIT License - See LICENSE file for details.
This software is provided "as is" without warranty of any kind. The authors and contributors disclaim all liability for any medical decisions made using this system. Users must obtain proper medical advice from qualified healthcare professionals.
- Documentation: See docs/ directory
- Issues: Report bugs on GitHub Issues
- Discussions: Join GitHub Discussions
- Clinical Questions: Contact qualified healthcare professionals
- Clinical Guidelines: Based on NICE, BTS, AAP, and WHO guidelines
- MCP Framework: Built on Anthropic's Model Context Protocol
- UI Components: Uses shadcn/ui design system
- Infrastructure: Deployed on AWS with SST framework
⚕️ Remember: This is a prototype system. All clinical decisions must be made by qualified healthcare professionals using established medical protocols.