mcp-tool/N8N-SETUP-GUIDE.md

# 🔧 n8n MCP Client Setup Guide

This guide shows you how to connect n8n to the Laravel Healthcare MCP Server via HTTP.

## 📋 Prerequisites

1. **MCP Server Running**: Ensure your Laravel Healthcare MCP Server is running
2. **n8n Installed**: Have n8n installed and accessible
3. **Network Access**: n8n can reach the MCP server (usually `http://localhost:3000`)

## 🚀 Quick Start

### 1. Start the MCP Server

```bash
cd laravel-healthcare-mcp-server
npm start
```

The server will start in dual mode (stdio + HTTP) and be available at:
- **HTTP Endpoint**: `http://localhost:3000/mcp`
- **n8n Info**: `http://localhost:3000/n8n/info`

### 2. Test Server Connectivity

```bash
# Test server health
curl http://localhost:3000/health

# Get n8n-specific information
curl http://localhost:3000/n8n/info
```

## 🔌 n8n Integration Methods

### Method 1: HTTP Request Node (Recommended)

**Step 1: Add HTTP Request Node**
- Add an "HTTP Request" node to your n8n workflow
- Set the following parameters:

**Basic Configuration:**
- **Method**: `POST`
- **URL**: `http://localhost:3000/mcp`
- **Headers**:
  ```json
  {
    "Content-Type": "application/json",
    "Accept": "application/json"
  }
  ```

**Step 2: Initialize MCP Connection**
```json
{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "clientInfo": {
      "name": "n8n",
      "version": "1.0.0"
    }
  },
  "id": 1
}
```

**Step 3: List Available Tools**
```json
{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "params": {},
  "id": 2
}
```

**Step 4: Execute Healthcare Tools**
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "public_manage_login",
    "arguments": {
      "email": "provider@example.com",
      "password": "your_password"
    }
  },
  "id": 3
}
```

### Method 2: Custom n8n Node (Advanced)

For advanced users, you can create a custom n8n node specifically for MCP:

1. **Create Node Structure**:
   ```
   nodes/
   ├── McpClient/
   │   ├── McpClient.node.ts
   │   └── mcp-client.svg
   ```

2. **Node Configuration**:
   - Server URL: `http://localhost:3000/mcp`
   - Protocol: JSON-RPC 2.0
   - Methods: initialize, tools/list, tools/call, ping

## 📊 Available Healthcare Tools

The MCP server provides 470+ healthcare API tools organized by category:

### Authentication Tools
- `public_manage_login` - Provider login
- `patient_login` - Patient portal login
- `partner_login` - Partner authentication

### Clinical Tools (Provider Auth Required)
- `provider_get_patients` - Get patient list
- `provider_create_patient` - Create new patient
- `provider_update_patient` - Update patient data
- `provider_get_appointments` - Get appointments

### Patient Portal Tools
- `patient_get_profile` - Get patient profile
- `patient_get_appointments` - Get patient appointments
- `patient_book_appointment` - Book new appointment

### Business Tools
- `partner_get_analytics` - Get business analytics
- `affiliate_get_commissions` - Get affiliate data
- `network_get_providers` - Get network providers

## 🔐 Authentication Flow

### 1. Login First
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "public_manage_login",
    "arguments": {
      "email": "your-email@example.com",
      "password": "your-password"
    }
  },
  "id": 1
}
```

### 2. Token Auto-Storage
The server automatically extracts and stores authentication tokens from login responses.

### 3. Use Protected Tools
After login, you can use provider-authenticated tools without additional auth.

## 🧪 Testing Examples

### Example 1: Get Patient List
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "provider_get_patients",
    "arguments": {
      "page": 1,
      "limit": 10
    }
  },
  "id": 4
}
```

### Example 2: Create Patient
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "provider_create_patient",
    "arguments": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "dateOfBirth": "1990-01-01",
      "phone": "+1234567890"
    }
  },
  "id": 5
}
```

## 🔧 Troubleshooting

### Common Issues

1. **Connection Refused**
   - Ensure MCP server is running: `npm start`
   - Check server URL: `http://localhost:3000/mcp`
   - Verify port 3000 is not blocked

2. **Authentication Errors**
   - Login first using `public_manage_login`
   - Check credentials are correct
   - Verify token storage in server logs

3. **Tool Not Found**
   - List available tools: `tools/list`
   - Check tool name spelling
   - Verify tool exists in current server version

### Debug Commands

```bash
# Check server status
curl http://localhost:3000/health

# Get server info for n8n
curl http://localhost:3000/n8n/info

# List all tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
```

## 📚 Additional Resources

- **Server Documentation**: `README.md`
- **API Reference**: `MCP-TOOLS-REFERENCE.md`
- **Example Workflow**: `n8n-workflow-template.json`
- **Configuration**: `n8n-mcp-config.json`

## 🆘 Support

If you encounter issues:
1. Check server logs for errors
2. Verify n8n can reach the server URL
3. Test with curl commands first
4. Check authentication flow