npm package: @servihero/n8n-nodes-housecall-pro
Description: HouseCall Pro MCP server for appointment scheduling and customer management
Author: Garrett Elmore
Latest version: 0.2.2

# HouseCall Pro MCP Server

This MCP server provides integration with the HouseCall Pro API, allowing chat agents to manage customer information, and simulate scheduling functionality.

## Features

The server exposes the following tools:

1. **get_estimates** - Get a list of estimates from HouseCall Pro
2. **get_jobs** - Get a list of jobs from HouseCall Pro
3. **get_booking_windows** - Get available booking windows
4. **get_schedule_windows** - Get the company's schedule windows (business hours)
5. **search_customers** - Search for existing customers by phone or email
6. **create_customer** - Create a new customer record
7. **get_available_slots** - Retrieve available appointment slots
8. **check_specific_availability** - Check specific time slot availability
9. **create_appointment** - Create a new appointment

## Installation

The MCP server is installed and configured for Claude. The configuration is stored in:
- `~/Library/Application Support/Claude/claude_desktop_config.json`
- `~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`

## Usage

To use these tools from Claude, you need to provide an agent_id when invoking the tools. The agent_id is used to retrieve the corresponding HouseCall Pro API key from the database. For example:

```
// Example usage in Claude
use_mcp_tool(
  "housecall-pro-server",
  "get_available_slots",
  {
    "agent_id": "your_agent_id",
    "start_date": "2025-03-27",
    "end_date": "2025-04-02"
  }
)
```

## Security Improvements

The server now uses `agent_id` instead of directly passing API keys:
1. API keys are stored securely in the database
2. The server retrieves the API key based on the agent_id
3. This prevents API keys from being exposed in chat logs
4. Allows for better tracking and management of API usage

## Appointment Creation Workflow

When creating an appointment with the `create_appointment` tool, the server follows this workflow:

1. **Check availability** - Verifies if the requested time slot is available
2. **Customer management** - Two-step process:
   - **Find existing customer** - Searches for customer by phone or email
   - **Create new customer if needed** - If no existing customer is found, creates a new one with:
     - Properly formatted address (street, city, state, zip)
     - Lead source set to "Chat"
3. **Create booking** - Creates the appointment with the customer ID

This approach ensures that returning customers are properly linked to their existing records, while new customers are created with all required information.

## Current API Status

After extensive testing with the HouseCall Pro API, we've discovered:

1. ✅ **Customer API Works**: We can successfully list and create customers
2. ❌ **Availability/Booking APIs Unavailable**: The availability and booking endpoints mentioned in the documentation return 404 errors

Our implementation adapts to these limitations by:
- Using the customer API for actual customer management
- Simulating availability and booking functionality based on customer data

## Test Scripts

Several test scripts are included to verify the server's functionality:

- `test-housecall-pro-server.js`: Tests the MCP server protocol
- `api-test.js`: Tests API connectivity with multiple base URLs
- `test-create-customer.js`: Tests customer creation via the HouseCall Pro API
- `test-agent-id.js`: Tests the new agent_id functionality

Example:
```bash
node test-agent-id.js <agent_id>
```

## Implementation Notes

- Customer creation works with the actual HouseCall Pro API
- Availability checks are simulated based on customer data
- Booking functionality uses a hybrid approach of customer API and simulated scheduling
- API keys are securely managed through the Supabase database

## Deployment to Railway

To deploy this MCP server to Railway, follow these steps:

1. **Sign up for Railway**: If you haven't already, create an account at [Railway.app](https://railway.app).

2. **Install Railway CLI** (optional, for local development):
   ```bash
   npm i -g @railway/cli
   railway login
   ```

3. **Deploy using Railway Dashboard**:
   - Fork or clone this repository to your GitHub account
   - In Railway dashboard, click "New Project" → "Deploy from GitHub repo"
   - Select your repository
   - Railway will automatically detect the Node.js project and build settings

4. **Configure Environment Variables**:
   - In the Railway dashboard, go to your project
   - Navigate to the "Variables" tab
   - Add the environment variables listed in `.env.example`:
     - `SUPABASE_URL`
     - `SUPABASE_SERVICE_ROLE_KEY`
     - `HOUSECALL_PRO_API_KEY` (if not using Supabase for key storage)

5. **Deploy and Monitor**:
   - Railway will automatically build and deploy your application
   - You can monitor logs in the "Deployments" tab
   - The URL of your deployed application will be available in the "Settings" tab

6. **Update MCP Configuration**:
   - Update your Claude MCP configuration to point to your new Railway-hosted server URL

### Maintaining the Deployment

- Railway will automatically rebuild and redeploy when you push changes to your GitHub repository
- To update environment variables, use the Railway dashboard or CLI
- Monitor usage in the Railway dashboard to stay within free tier limits or upgrade as needed