Files

nasir@endelospay.com 47e3c98b65 fix

2025-07-22 02:31:27 +05:00

10 KiB

Raw Blame History

Laravel Healthcare MCP Server

A comprehensive Model Context Protocol (MCP) server that acts as a proxy/router for a Laravel healthcare API with Sanctum authentication. This server provides seamless integration between MCP clients and the Laravel healthcare application, supporting all 8 user roles and 400+ API endpoints.

🚀 Features

Complete API Coverage: 400+ endpoints from Laravel healthcare application
9 Authentication Types: Admin, Agent, Patient, Practitioner, Affiliate, Partner, Network, Doctor, Provider
Automatic Token Management: Sanctum token storage and refresh
HIPAA Compliance: Sensitive data masking and secure logging
Comprehensive Error Handling: Healthcare-specific error responses
Real-time Monitoring: Health checks and performance metrics
Retry Logic: Exponential backoff for failed requests
Validation: Joi schemas for all endpoint parameters

📋 Prerequisites

Node.js 18.0.0 or higher
Access to Laravel healthcare API
Valid authentication credentials for desired user roles

🛠️ Installation

Clone or extract the server directory:
Install dependencies:
```
npm install
```

Configure environment variables:

cp .env.example .env
# Edit .env with your configuration

Validate configuration:
```
npm run validate-config
```

⚙️ Configuration

Required Environment Variables

# Laravel API Configuration
LARAVEL_API_BASE_URL=https://your-healthcare-api.com

# At least one authentication type must be configured
ADMIN_USERNAME=admin@healthcare.com
ADMIN_PASSWORD=your_admin_password

# Additional auth types as needed...

Authentication Types

The server supports 9 authentication types. Configure credentials for the roles you need:

Role	Username Variable	Password Variable	Default Endpoint
Admin	`ADMIN_USERNAME`	`ADMIN_PASSWORD`	`/api/admin/login`
Agent	`AGENT_USERNAME`	`AGENT_PASSWORD`	`/agent/login/post`
Patient	`PATIENT_USERNAME`	`PATIENT_PASSWORD`	`/api/frontend/login`
Practitioner	`PRACTITIONER_USERNAME`	`PRACTITIONER_PASSWORD`	`/api/practitioner/login`
Affiliate	`AFFILIATE_USERNAME`	`AFFILIATE_PASSWORD`	`/api/affiliate/login`
Partner	`PARTNER_USERNAME`	`PARTNER_PASSWORD`	`/api/partner/login`
Network	`NETWORK_USERNAME`	`NETWORK_PASSWORD`	`/api/network/login`
Doctor	`DOCTOR_USERNAME`	`DOCTOR_PASSWORD`	`/api/doctor/login`
Provider	`PROVIDER_USERNAME`	`PROVIDER_PASSWORD`	`/api/provider/login`

Optional Configuration

# Server Configuration
MCP_SERVER_NAME=laravel-healthcare-mcp-server
MCP_SERVER_VERSION=1.0.0
MCP_SERVER_PORT=3000
MCP_SERVER_HOST=0.0.0.0

# API Client Settings
LARAVEL_API_TIMEOUT=30000
LARAVEL_API_RETRY_ATTEMPTS=3
LARAVEL_API_RETRY_DELAY=1000

# Token Management
TOKEN_REFRESH_BUFFER=300

# Logging
LOG_LEVEL=info
ENABLE_REQUEST_LOGGING=true
MASK_SENSITIVE_DATA=true

# Security
HIPAA_COMPLIANCE_MODE=true
ENABLE_DETAILED_ERRORS=false

🚀 Usage

Starting the Server

# MCP Server only (stdio protocol)
npm start

# HTTP Server (full features with MCP tools)
npm run start


# Both MCP and HTTP servers simultaneously
npm run start

Server URLs

When running the HTTP server, you can access:

Health Check: http://localhost:3000/health
Tools List: http://localhost:3000/tools
Server Stats: http://localhost:3000/stats
Tool Execution: POST http://localhost:3000/tools/{toolName}/execute
Auth Status: http://localhost:3000/auth/status

Using with MCP Clients

The server implements the Model Context Protocol and can be used with any MCP-compatible client:

{
  "mcpServers": {
    "laravel-healthcare": {
      "command": "node",
      "args": ["path/to/laravel-healthcare-mcp-server/server.js"]
    }
  }
}

Available Tools

The server automatically generates MCP tools for all API endpoints. Tool names follow the pattern:

Public endpoints: public_{action}_{resource}
Authenticated endpoints: {role}_{action}_{resource}

Examples:

public_create_patient - Register new patient (public)
admin_get_patient_list - Get patient list (admin only)
agent_create_appointment - Create appointment (agent only)
provider_create_getAvailableSlotsData - Get available appointment slots by practitioner ID, month and timezone (provider only)

Tool Categories

Tools are organized into categories:

Patient Management (150+ tools)
Appointment Scheduling (50+ tools)
Medical Records (40+ tools)
Prescription Management (30+ tools)
Document Management (25+ tools)
Messaging (20+ tools)
Billing & Orders (30+ tools)
Analytics & Reports (25+ tools)
User Management (20+ tools)
Forms & Questionnaires (15+ tools)

🔧 Development

Project Structure

laravel-healthcare-mcp-server/
├── src/
│   ├── auth/           # Authentication management
│   ├── config/         # Configuration and endpoints
│   ├── proxy/          # API client and HTTP handling
│   ├── server/         # MCP server implementation
│   ├── tools/          # Tool generation and execution
│   └── utils/          # Utilities (logging, errors)
├── config/             # Configuration files
├── logs/               # Log files
├── docs/               # Documentation
├── test/               # Test scripts
├── server.js           # Main entry point
├── package.json        # Dependencies and scripts
└── README.md           # This file

Scripts

# Start server
npm start

# Development mode
npm run dev

# Run tests
npm test

# Validate configuration
npm run validate-config

# Generate documentation
npm run docs

# Lint code
npm run lint

Adding New Endpoints

Update endpoint registry in src/config/endpoints.js
Add authentication configuration if needed
Restart server to regenerate tools

Example endpoint definition:

{
  path: '/api/new-endpoint/{id}',
  method: 'POST',
  controller: 'Controller@method',
  category: ENDPOINT_CATEGORIES.PATIENT_MANAGEMENT,
  description: 'Description of the endpoint',
  parameters: {
    id: { type: 'string', required: true, description: 'Resource ID' },
    data: { type: 'object', required: true, description: 'Request data' }
  }
}

🔍 Monitoring

Health Checks

The server provides health check endpoints and logging:

# Check server health (if health endpoint enabled)
curl http://localhost:3000/health

Logging

Logs are written to:

Console (formatted for development)
Files (JSON format for production)
Separate error logs for critical issues

Log levels: error, warn, info, debug

Performance Monitoring

The server tracks:

Tool execution times
API response times
Authentication token refresh cycles
Error rates by endpoint

🔒 Security

HIPAA Compliance

Sensitive data masking in logs
Secure token storage with automatic expiration
Audit logging for all operations
Error message sanitization to prevent data leaks

Authentication Security

Token storage with automatic expiration
Automatic token refresh before expiration
Credential validation on startup
Rate limiting support

🐛 Troubleshooting

Common Issues

Authentication Failures

# Validate credentials
npm run validate-config

# Check logs for auth errors
tail -f logs/mcp-server.log | grep auth

API Connection Issues

# Test API connectivity
curl -v $LARAVEL_API_BASE_URL/health

# Check network configuration
npm run test

Tool Execution Errors

# Enable debug logging
LOG_LEVEL=debug npm start

# Check tool validation
npm run validate-config

Debug Mode

Enable debug mode for detailed logging:

DEBUG_MODE=true
LOG_LEVEL=debug
ENABLE_DETAILED_ERRORS=true

📚 API Documentation

Generated Tools

The server automatically generates tools for all endpoints. Each tool includes:

Name: Descriptive tool name
Description: Endpoint purpose and details
Parameters: JSON schema with validation
Authentication: Required auth type

Endpoint Categories

Category	Description	Tool Count
Patient Management	Patient registration, profiles, medical history	150+
Appointment Scheduling	Booking, availability, calendar integration	50+
Medical Records	SOAP notes, vitals, clinical documentation	40+
Prescription Management	Medications, dosages, pharmacy integration	30+
Document Management	File uploads, signed documents, sharing	25+
Messaging	Secure messaging, notifications, communication	20+
Billing & Orders	Payments, subscriptions, lab orders	30+
Analytics & Reports	Statistics, exports, business intelligence	25+
User Management	Authentication, profiles, permissions	20+
Forms & Questionnaires	Dynamic forms, intake questionnaires	15+

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Submit a pull request

📄 License

MIT License - see LICENSE file for details

🆘 Support

For support and questions:

Check the troubleshooting section
Review logs for error details
Validate configuration
Test API connectivity

🔄 Updates

To update the server:

Pull latest changes
Run npm install for new dependencies
Update configuration if needed
Restart the server

Laravel Healthcare MCP Server - Bridging healthcare APIs with Model Context Protocol

10 KiB Raw Blame History