# Practice Fusion MCP Server

A comprehensive Model Context Protocol (MCP) server that provides healthcare tools, resources, and prompts for interacting with Practice Fusion EHR using any MCP client. Supports both **STDIO** (traditional) and **HTTP** (remote-capable) transports.

## 🚀 Quick Start

### Prerequisites
- **Node.js 18+** and npm
- **Practice Fusion API credentials** (optional at startup - see [Getting Practice Fusion Credentials](#getting-practice-fusion-credentials))

### Installation & Build
```bash
git clone <repository-url>
cd practice-fusion-mcp-server
npm install
npm run build
```

### Basic Usage (STDIO Mode)
```bash
# Start server in STDIO mode (default) - no credentials needed at startup
node build/index.js

# OAuth will trigger when tools/resources are accessed
# Configure credentials in .env for Practice Fusion integration
```

### HTTP Mode (Remote Access)
```bash
# Set environment for HTTP transport
export TRANSPORT_TYPE=http
export HTTP_PORT=3000

# Start HTTP server - no credentials needed at startup
node build/index.js

# Server available at:
# Health: http://127.0.0.1:3000/health  ← Works immediately
# Status: http://127.0.0.1:3000/status   ← Works immediately  
# MCP: http://127.0.0.1:3000/mcp         ← Works immediately
```

## 🏥 Features

### Complete Practice Fusion Integration
- **19 Practice Fusion Tools**: Patient search, scheduling, demographics, insurance management
- **MCP Resources System**: Structured data access (facilities, patient profiles, schedules)
- **MCP Prompts System**: 9 workflow templates for common healthcare tasks
- **OAuth2 Authentication**: Secure Practice Fusion API access with automatic token refresh

### Dual Transport Support
- **STDIO Transport**: Traditional MCP transport for local clients (Claude Desktop)
- **HTTP Transport**: Remote-capable HTTP transport with SSE streaming (NEW!)

### Enterprise Features
- **Session Management**: Secure session handling with configurable timeout
- **Security Middleware**: CORS, Origin validation, Rate limiting
- **Health Monitoring**: Health check and status endpoints
- **Comprehensive Logging**: Structured logging with debug modes

## 🛠️ Available Tools (19 Total)

### Patient Management
- `search_patients` - Search patients by name, DOB, demographics, or identifiers
- `get_patient_v4` - Get complete patient details with profile, contact, demographics
- `create_patient_v4` - Register new patients with validation
- `update_patient_v4` - Update patient information (demographics, contact, insurance)
- `get_patient_insurance_plans` - Retrieve patient insurance coverage details
- `create_patient_insurance_plan` - Add new insurance plans for patients

### Scheduling & Calendar
- `query_events` - Query appointments and calendar events with filtering
- `get_event` - Get detailed appointment information by event ID
- `create_event` - Schedule new appointments with validation
- `update_event` - Modify existing appointments (time, status, details)
- `get_event_types` - List available appointment types and categories
- `get_event_confirmation` - Retrieve appointment confirmation details
- `update_event_confirmation` - Update appointment confirmation status

### Practice Administration
- `get_users` - List all practice users and providers with profiles
- `get_facilities` - Get practice facilities with locations and contact information
- `find_payers` - Search insurance payers and coverage plans

### Document Management
- `get_document_types` - List available document types for practice
- `get_document` - Retrieve specific documents by ID
- `create_document` - Upload and create new documents

## 📋 MCP Resources (Structured Data Access)

### Practice Resources
- `practice://facilities` - All practice facilities with locations and details
- `practice://users` - Complete users and providers directory
- `practice://event-types` - Available appointment types and categories

### Patient Resources (Dynamic)
- `patient://profile/{patientGuid}` - Patient demographics and contact information
- `patient://insurance/{patientGuid}` - Patient insurance plans and coverage

### Calendar Resources (Dynamic)
- `calendar://schedule/{facilityGuid}/{date}` - Daily facility schedule (YYYY-MM-DD)
- `calendar://availability/{ehrUserGuid}/{startDate}/{endDate}` - Provider availability

### Payer Resources
- `payers://directory` - Insurance payers directory with available plans

## 📝 MCP Prompts (Workflow Templates)

### Scheduling Workflows
- `schedule-appointment` - Interactive appointment scheduling with validation
- `reschedule-appointment` - Appointment rescheduling with conflict checking
- `check-availability` - Provider availability analysis and optimization

### Patient Management Workflows
- `patient-intake` - New patient registration workflow with insurance setup
- `update-patient-info` - Guided patient information updates
- `insurance-verification` - Step-by-step insurance verification and setup

### Administrative Workflows
- `daily-schedule-review` - Comprehensive daily schedule analysis
- `patient-search-optimization` - Search strategy guidance and best practices
- `appointment-status-update` - Appointment status management workflow

## ⚙️ Configuration

### Getting Practice Fusion Credentials

To use this MCP server, you need Practice Fusion API credentials:

1. **Contact Practice Fusion Developer Support**
   - Email: `developer-support@practicefusion.com`
   - Request API access for your practice/organization

2. **Request Required Information**
   - Client ID and Client Secret
   - API URL (typically `https://api.practicefusion.com` for production)
   - Required OAuth scopes for your use case

3. **Scopes You'll Need**
   ```
   calendar:a_confirmation_v1 calendar:a_events_v1 calendar:a_events_v2
   calendar:a_notes_v1 calendar:a_status_v1 calendar:d_events_v1
   calendar:r_events_v1 calendar:r_events_v2 calendar:r_eventtypes_v1
   patient:a_contact_v4 patient:a_demographics_v1 patient:a_insurance_plan_v1
   patient:r_profile_v4 patient:r_contact_v4 patient:r_search_v2
   practice:r_facilities_v2 user:r_login_v2 user:r_profile_v2
   payer:r_insurance_v1 document:r_document_v2
   ```

### Environment Configuration

Create a `.env` file in the project root:

```bash
# ========================================
# PRACTICE FUSION API CREDENTIALS
# ========================================
# REQUIRED: Get these from Practice Fusion Developer Support
PF_CLIENT_ID=your_client_id_here
PF_CLIENT_SECRET=your_client_secret_here

# ========================================
# PRACTICE FUSION API CONFIGURATION
# ========================================
# API Base URL (default: QA environment)
PF_API_URL=https://qa-api.practicefusion.com

# OAuth Endpoints (usually don't need to change)
PF_TOKEN_PATH=/ehr/oauth2/token
PF_AUTHORIZE_PATH=/ehr/oauth2/auth

# OAuth Callback (for local development)
PF_CALLBACK_URL=http://localhost:3456/oauth/callback
PF_CALLBACK_PORT=3456

# API Scopes (copy the scopes provided by Practice Fusion)
PF_SCOPES="calendar:a_confirmation_v1 calendar:a_events_v1 calendar:a_events_v2 calendar:a_notes_v1 calendar:a_status_v1 calendar:d_events_v1 calendar:r_events_v1 calendar:r_events_v2 calendar:r_eventtypes_v1 calendar:r_notes_v1 chart:a_superbill_v2 chart:a_vxu_v2 document:a_document_v2 document:r_document_types_v2 document:r_document_v2 document:z_document_v2 encounter:a_diagnosis_v1 encounter:a_notes_v1 encounter:r_metadata_v1 encounter:r_summary_v1 me:r_erx_v2 me:r_login_v2 me:r_profile_v2 patient:a_contact_v4 patient:a_demographics_v1 patient:a_guarantor_v1 patient:a_insurance_plan_v1 patient:a_preferredPharmacy_v1 patient:a_relatedPerson_v1 patient:r_ccda_allergies_v2 patient:r_ccda_assessmentAndPlan_v2 patient:r_ccda_clinicalNotes_v2 patient:r_ccda_demographics_v2 patient:r_ccda_encounters_v2 patient:r_ccda_functionalStatus_v2 patient:r_ccda_goals_v2 patient:r_ccda_healthConcerns_v2 patient:r_ccda_immunizations_v2 patient:r_ccda_medicalEquipment_v2 patient:r_ccda_medications_v2 patient:r_ccda_mentalStatus_v2 patient:r_ccda_problems_v2 patient:r_ccda_procedures_v2 patient:r_ccda_reasonForReferral_v2 patient:r_ccda_results_v2 patient:r_ccda_socialHistory_v2 patient:r_ccda_vitalSigns_v2 patient:r_contact_v4 patient:r_demographics_v2 patient:r_diagnosis_v1 patient:r_guarantor_v1 patient:r_insurance_v3 patient:r_insurance_plan_v1 patient:r_preferredPharmacy_v1 patient:r_profile_v4 patient:r_relatedPerson_v1 patient:r_search_v2 payer:r_insurance_v1 payer:r_insurance_plan_v1 practice:r_facilities_v2 user:r_login_v2 user:r_profile_v2"

# ========================================
# TRANSPORT CONFIGURATION
# ========================================
# Transport Type: 'stdio' (default) or 'http'
TRANSPORT_TYPE=stdio

# HTTP Transport Settings (only used when TRANSPORT_TYPE=http)
HTTP_PORT=3000
HTTP_HOST=127.0.0.1
HTTP_ALLOWED_ORIGINS=http://localhost:*,https://localhost:*
HTTP_REQUIRE_ORIGIN_VALIDATION=true
HTTP_ENABLE_CORS=true
HTTP_SESSION_TIMEOUT_MS=1800000
```

### Security Notes
- **Never commit credentials** to version control
- **.env file is gitignored** for security
- **Use environment variables** in production deployments
- **Restrict HTTP_HOST** to localhost (127.0.0.1) unless external access needed

## 🖥️ Transport Modes

### STDIO Transport (Default)
For local MCP clients like Claude Desktop:

```bash
# Default mode - no configuration needed
node build/index.js
```

### HTTP Transport (Remote Access)
For web applications and remote integrations:

```bash
# Enable HTTP transport
export TRANSPORT_TYPE=http
export HTTP_PORT=3000
export HTTP_HOST=127.0.0.1

# Start HTTP server
node build/index.js

# Available endpoints:
# http://127.0.0.1:3000/health   - Health check
# http://127.0.0.1:3000/status   - Server status
# http://127.0.0.1:3000/mcp      - MCP endpoint
```

### Quick HTTP Test
```bash
# Use provided test script
./start-http-test.sh

# Manual health check
curl http://127.0.0.1:3000/health
```

### HTTP Transport Testing

#### Build Command
```bash
npm run build
```

#### Test HTTP Transport Functionality
```bash
# Automated test suite
./test-http-only.sh

# Manual server start for testing
./start-http-test.sh
```

#### Manual HTTP Testing
```bash
# 1. Start server in HTTP mode
export TRANSPORT_TYPE=http
export HTTP_PORT=3000
export PF_CLIENT_ID=test
export PF_CLIENT_SECRET=test
node build/index.js

# 2. Test health endpoint
curl http://127.0.0.1:3000/health

# 3. Test initialization
curl -X POST http://127.0.0.1:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {"name": "Test Client", "version": "1.0.0"}
    }
  }'
```

## 🔗 Integration Examples

### Claude Desktop (STDIO Mode)

Add to Claude Desktop configuration:
```json
{
  "mcpServers": {
    "practice-fusion": {
      "command": "node",
      "args": ["/path/to/practice-fusion-mcp-server/build/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

**Important**: Credentials are read from `.env` file, not Claude Desktop config for security.

### HTTP Client Integration (JavaScript)

```javascript
// Initialize MCP session
const initResponse = await fetch('http://127.0.0.1:3000/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'MCP-Protocol-Version': '2025-06-18'
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'initialize',
    params: {
      protocolVersion: '2025-06-18',
      capabilities: {},
      clientInfo: { name: 'My App', version: '1.0.0' }
    }
  })
});

const sessionId = initResponse.headers.get('Mcp-Session-Id');

// Use tools with session
const searchResponse = await fetch('http://127.0.0.1:3000/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'MCP-Protocol-Version': '2025-06-18',
    'Mcp-Session-Id': sessionId
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 2,
    method: 'tools/call',
    params: {
      name: 'search_patients',
      arguments: { FirstName: 'John', LastName: 'Smith' }
    }
  })
});
```

### Server-Sent Events (SSE) Example

```javascript
// Open SSE connection for real-time updates
const eventSource = new EventSource(
  `http://127.0.0.1:3000/mcp?Mcp-Session-Id=${sessionId}`
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

eventSource.addEventListener('response', (event) => {
  const response = JSON.parse(event.data);
  // Handle JSON-RPC response
});
```

## 🧪 Development & Testing

### Development Commands
```bash
npm run build          # TypeScript compilation
npm run watch          # Watch mode for development
npm run inspector      # Launch MCP Inspector
```

### MCP Inspector (Development Tool)
```bash
# Install globally
npm install -g @modelcontextprotocol/inspector

# Launch inspector
npx @modelcontextprotocol/inspector build/index.js

# Access at http://localhost:5173
```

### Testing Scripts
```bash
# Test HTTP transport functionality
./test-http-only.sh

# Start HTTP server for manual testing
./start-http-test.sh

# Test specific Practice Fusion APIs (requires real credentials)
npm run build && node build/test-pf-apis.js
```

### Environment Variables for Testing
```bash
# HTTP Transport Testing
export TRANSPORT_TYPE=http
export HTTP_PORT=3000
export HTTP_HOST=127.0.0.1
export HTTP_REQUIRE_ORIGIN_VALIDATION=false  # Disable for testing
export HTTP_ENABLE_CORS=true

# Use dummy credentials for HTTP transport testing
export PF_CLIENT_ID=test-client-id
export PF_CLIENT_SECRET=test-client-secret
```

## 🔧 Troubleshooting

### Common Issues

#### Build Errors
```bash
# Clear build cache
rm -rf build/
npm run build
```

#### Port Conflicts
```bash
# Check if port is in use
lsof -i :3000
lsof -i :3456  # OAuth callback port

# Kill process using port
kill -9 $(lsof -t -i:3000)
```

#### HTTP Transport Issues
```bash
# Check configuration
echo $TRANSPORT_TYPE $HTTP_PORT $HTTP_HOST

# Test health endpoint
curl http://127.0.0.1:3000/health

# Check server logs
TRANSPORT_TYPE=http node build/index.js
```

#### Practice Fusion Authentication
```bash
# Verify credentials are set
echo $PF_CLIENT_ID $PF_CLIENT_SECRET

# Check .env file exists and is loaded
cat .env | grep PF_

# Test with debug logging
DEBUG=* node build/index.js
```

#### Session Issues (HTTP Mode)
```bash
# Check session status
curl http://127.0.0.1:3000/status

# Clear sessions (restart server)
# Sessions are in-memory and cleared on restart
```

### Debug Mode
```bash
# Enable detailed logging
DEBUG=* node build/index.js

# HTTP transport with debug logs
DEBUG=* TRANSPORT_TYPE=http node build/index.js
```

## 🚀 Production Deployment

### Environment Setup
```bash
# Production environment variables
TRANSPORT_TYPE=http
HTTP_HOST=0.0.0.0                    # Bind to all interfaces
HTTP_PORT=3000
HTTP_REQUIRE_ORIGIN_VALIDATION=true  # Enable security
HTTP_ALLOWED_ORIGINS=https://yourdomain.com
HTTP_SESSION_TIMEOUT_MS=3600000      # 1 hour
```

### Docker Example
```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY build/ ./build/
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost:3000/health || exit 1
CMD ["node", "build/index.js"]
```

### Security Recommendations
- **Use HTTPS** in production with proper SSL certificates
- **Configure firewall** to restrict access
- **Set up monitoring** for health endpoints
- **Use reverse proxy** (nginx, Apache) for advanced features
- **Implement log aggregation** for monitoring

## 📄 License

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

## 🤝 Contributing

1. Fork the repository
2. Create feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m 'Add amazing feature'`)
4. Push to branch (`git push origin feature/amazing-feature`)
5. Open Pull Request

### Development Guidelines
- Follow TypeScript best practices
- Add tests for new features
- Update documentation
- Test both STDIO and HTTP transports
- Ensure no credentials in code

## 📞 Support

For support and questions:
1. Check this README and [CLAUDE.md](./CLAUDE.md) documentation
2. Review error logs for specific issues
3. Test with health endpoints to isolate problems
4. Verify Practice Fusion credentials and permissions
5. Check MCP client compatibility

## 📚 Additional Documentation

- **[CLAUDE.md](./CLAUDE.md)** - Comprehensive technical documentation
- **[HTTP Transport Details](./CLAUDE.md#http-transport-details)** - In-depth HTTP implementation guide
- **[Security Considerations](./CLAUDE.md#security-considerations)** - Security best practices
- **[Integration Examples](./CLAUDE.md#integration-examples)** - More detailed integration examples

---

**⚠️ Security Notice**: This server handles healthcare data. Ensure compliance with HIPAA and other healthcare regulations in your deployment. Never commit credentials to version control.