first

2025-07-11 20:22:12 +05:00
commit 8c74b0e23f
120 changed files with 206874 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,399 @@
+# 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 caching 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
+
+1. **Clone or extract the server directory**:
+
+   ```bash
+   cd laravel-healthcare-mcp-server
+   ```
+
+2. **Install dependencies**:
+
+   ```bash
+   npm install
+   ```
+
+3. **Configure environment variables**:
+
+   ```bash
+   cp .env.example .env
+   # Edit .env with your configuration
+   ```
+
+4. **Validate configuration**:
+   ```bash
+   npm run validate-config
+   ```
+
+## ⚙️ Configuration
+
+### Required Environment Variables
+
+```env
+# 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
+
+```env
+# 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_CACHE_DURATION=3600
+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
+
+```bash
+# MCP Server only (stdio protocol)
+npm start
+
+# HTTP Server (full features with MCP tools)
+npm run start:http
+
+# HTTP Server (simple version with startup banner)
+npm run start:http-simple
+
+# Both MCP and HTTP servers simultaneously
+npm run start:both
+
+# Development mode with auto-restart
+npm run dev              # MCP server only
+npm run dev:http         # HTTP server only
+npm run dev:http-simple  # Simple HTTP server only
+npm run dev:both         # Both servers
+```
+
+### 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:
+
+```json
+{
+  "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
+
+```bash
+# 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
+
+1. **Update endpoint registry** in `src/config/endpoints.js`
+2. **Add authentication configuration** if needed
+3. **Restart server** to regenerate tools
+
+Example endpoint definition:
+
+```javascript
+{
+  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:
+
+```bash
+# 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 caching** with configurable TTL
+- **Automatic token refresh** before expiration
+- **Credential validation** on startup
+- **Rate limiting** support
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+1. **Authentication Failures**
+
+   ```bash
+   # Validate credentials
+   npm run validate-config
+
+   # Check logs for auth errors
+   tail -f logs/mcp-server.log | grep auth
+   ```
+
+2. **API Connection Issues**
+
+   ```bash
+   # Test API connectivity
+   curl -v $LARAVEL_API_BASE_URL/health
+
+   # Check network configuration
+   npm run test
+   ```
+
+3. **Tool Execution Errors**
+
+   ```bash
+   # Enable debug logging
+   LOG_LEVEL=debug npm start
+
+   # Check tool validation
+   npm run validate-config
+   ```
+
+### Debug Mode
+
+Enable debug mode for detailed logging:
+
+```env
+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
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Submit a pull request
+
+## 📄 License
+
+MIT License - see LICENSE file for details
+
+## 🆘 Support
+
+For support and questions:
+
+1. Check the troubleshooting section
+2. Review logs for error details
+3. Validate configuration
+4. Test API connectivity
+
+## 🔄 Updates
+
+To update the server:
+
+1. Pull latest changes
+2. Run `npm install` for new dependencies
+3. Update configuration if needed
+4. Restart the server
+
+---
+
+**Laravel Healthcare MCP Server** - Bridging healthcare APIs with Model Context Protocol