mcp-tool/README.md

# 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