# Housecall Pro MCP Server

Complete Model Context Protocol server for Housecall Pro field service management platform.

## Features

### 🛠️ **47 Tools Across 10 Categories**

#### Job Management (10 tools)
- `list_jobs` - List jobs with filters (status, customer, dates, tags)
- `get_job` - Get detailed job information
- `create_job` - Create new jobs
- `update_job` - Update job details
- `complete_job` - Mark jobs as completed
- `cancel_job` - Cancel jobs with reason
- `list_job_line_items` - List line items for a job
- `add_job_line_item` - Add line items to jobs
- `schedule_job` - Schedule jobs
- `reschedule_job` - Reschedule existing jobs

#### Customer Management (7 tools)
- `list_customers` - List customers with filters
- `get_customer` - Get customer details
- `create_customer` - Create new customers
- `update_customer` - Update customer information
- `delete_customer` - Delete customers
- `search_customers` - Search by name, email, phone
- `list_customer_addresses` - List customer addresses

#### Estimate Management (8 tools)
- `list_estimates` - List estimates with filters
- `get_estimate` - Get estimate details
- `create_estimate` - Create new estimates
- `update_estimate` - Update estimate details
- `send_estimate` - Send estimates to customers
- `approve_estimate` - Mark estimates as approved
- `decline_estimate` - Decline estimates
- `convert_estimate_to_job` - Convert approved estimates to jobs

#### Invoice Management (6 tools)
- `list_invoices` - List invoices with filters
- `get_invoice` - Get invoice details
- `create_invoice` - Create new invoices
- `send_invoice` - Send invoices to customers
- `mark_invoice_paid` - Record invoice payments
- `list_invoice_payments` - List all payments for an invoice

#### Employee Management (6 tools)
- `list_employees` - List employees with filters
- `get_employee` - Get employee details
- `create_employee` - Create new employees
- `update_employee` - Update employee information
- `get_employee_schedule` - Get employee schedules
- `list_employee_time_entries` - List time entries

#### Dispatch & Scheduling (3 tools)
- `get_dispatch_board` - Get dispatch board view
- `assign_employee_to_job` - Assign employees to jobs
- `get_employee_availability` - Check employee availability

#### Tag Management (5 tools)
- `list_tags` - List all tags
- `create_tag` - Create new tags
- `delete_tag` - Delete tags
- `add_tag_to_job` - Tag jobs
- `add_tag_to_customer` - Tag customers

#### Notification Management (3 tools)
- `list_notifications` - List sent notifications
- `send_notification` - Send SMS/email notifications
- `mark_notification_read` - Mark notifications as read

#### Review Management (3 tools)
- `list_reviews` - List customer reviews
- `get_review` - Get review details
- `request_review` - Request reviews from customers

#### Reporting & Analytics (3 tools)
- `get_revenue_report` - Revenue analytics
- `get_job_completion_report` - Job completion metrics
- `get_employee_performance_report` - Employee performance stats

## Installation

```bash
npm install @mcpengine/housecall-pro
```

## Configuration

Set the required environment variable:

```bash
export HOUSECALL_PRO_API_KEY="your-api-key-here"
```

Optional configuration:

```bash
export HOUSECALL_PRO_BASE_URL="https://api.housecallpro.com"  # default
```

## Usage

### As MCP Server

Add to your MCP settings file:

```json
{
  "mcpServers": {
    "housecall-pro": {
      "command": "npx",
      "args": ["-y", "@mcpengine/housecall-pro"],
      "env": {
        "HOUSECALL_PRO_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Programmatic Usage

```typescript
import { HousecallProClient } from '@mcpengine/housecall-pro';

const client = new HousecallProClient({
  apiKey: process.env.HOUSECALL_PRO_API_KEY!,
});

// List jobs
const jobs = await client.listJobs({
  work_status: 'scheduled',
  start_date: '2024-01-01',
  end_date: '2024-01-31',
});

// Create a customer
const customer = await client.createCustomer({
  first_name: 'John',
  last_name: 'Doe',
  email: 'john@example.com',
  mobile_number: '+1234567890',
});

// Create an estimate
const estimate = await client.createEstimate({
  customer_id: customer.id,
  line_items: [
    {
      name: 'HVAC Repair',
      description: 'Replace thermostat',
      quantity: 1,
      unit_price: 250.00,
    },
  ],
});

// Send the estimate
await client.sendEstimate(estimate.id);
```

## API Reference

### Client Initialization

```typescript
const client = new HousecallProClient({
  apiKey: string;           // Required: Your Housecall Pro API key
  baseUrl?: string;         // Optional: API base URL (default: https://api.housecallpro.com)
});
```

### Error Handling

The client throws `APIError` objects with the following structure:

```typescript
{
  error: 'APIError' | 'NetworkError' | 'ExecutionError';
  message: string;
  status: number;
  details?: any;
}
```

Example error handling:

```typescript
try {
  const job = await client.getJob('job-123');
} catch (error: any) {
  if (error.error === 'APIError') {
    console.error(`API Error ${error.status}: ${error.message}`);
  } else {
    console.error(`Error: ${error.message}`);
  }
}
```

### Pagination

List methods support pagination:

```typescript
// Get single page
const page = await client.getPage('/jobs', {
  page: 1,
  page_size: 50,
});

// Get all pages (auto-pagination)
const allJobs = await client.listJobs({
  page_size: 100,  // Items per page
});
```

## Tool Examples

### Job Management

```typescript
// Create and schedule a job
const job = await client.createJob({
  customer_id: 'cust-123',
  description: 'Annual HVAC maintenance',
  schedule_start: '2024-02-15T09:00:00Z',
  schedule_end: '2024-02-15T11:00:00Z',
  assigned_employees: ['emp-456'],
});

// Add line items
await client.addJobLineItem(job.id, {
  name: 'Filter Replacement',
  quantity: 2,
  unit_price: 45.00,
});

// Complete the job
await client.completeJob(job.id);
```

### Customer & Address Management

```typescript
// Create customer with tags
const customer = await client.createCustomer({
  first_name: 'Jane',
  last_name: 'Smith',
  email: 'jane@example.com',
  tags: ['vip', 'commercial'],
});

// Get customer addresses
const addresses = await client.listCustomerAddresses(customer.id);
```

### Estimates & Invoices

```typescript
// Create estimate
const estimate = await client.createEstimate({
  customer_id: 'cust-123',
  line_items: [
    { name: 'Labor', quantity: 2, unit_price: 85.00 },
    { name: 'Parts', quantity: 1, unit_price: 150.00 },
  ],
  valid_until: '2024-03-01',
});

// Send and track
await client.sendEstimate(estimate.id);
await client.approveEstimate(estimate.id);
const job = await client.convertEstimateToJob(estimate.id);

// Create invoice from job
const invoice = await client.createInvoice({
  job_id: job.id,
  due_date: '2024-02-28',
});

// Record payment
await client.markInvoicePaid(invoice.id, {
  amount: 320.00,
  method: 'card',
  reference: 'ch_1234567890',
});
```

### Dispatch & Scheduling

```typescript
// Check employee availability
const availability = await client.getEmployeeAvailability('emp-123', {
  start_date: '2024-02-15',
  end_date: '2024-02-21',
});

// View dispatch board
const board = await client.getDispatchBoard({
  date: '2024-02-15',
  employee_ids: ['emp-123', 'emp-456'],
});

// Assign employee
await client.assignEmployee('job-789', 'emp-123');
```

### Reports & Analytics

```typescript
// Revenue report
const revenue = await client.getRevenueReport({
  start_date: '2024-01-01',
  end_date: '2024-01-31',
  group_by: 'day',
});

// Job completion metrics
const completion = await client.getJobCompletionReport({
  start_date: '2024-01-01',
  end_date: '2024-01-31',
});

// Employee performance
const performance = await client.getEmployeePerformanceReport({
  employee_id: 'emp-123',
  start_date: '2024-01-01',
  end_date: '2024-01-31',
});
```

## MCP Apps (UI Components)

This server includes 16 React-based MCP apps for rich UI interactions:

- **job-dashboard** - Overview of all jobs
- **job-detail** - Detailed job view
- **job-grid** - Grid view of jobs
- **customer-detail** - Customer profile view
- **customer-grid** - Customer list/grid
- **estimate-builder** - Interactive estimate creation
- **estimate-grid** - Estimate list/grid
- **invoice-dashboard** - Invoice overview
- **invoice-detail** - Detailed invoice view
- **dispatch-board** - Visual dispatch/scheduling board
- **employee-schedule** - Employee schedule calendar
- **employee-performance** - Performance metrics dashboard
- **review-dashboard** - Review management
- **revenue-dashboard** - Revenue analytics
- **tag-manager** - Tag organization
- **notification-center** - Notification management

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Development (watch mode)
npm run dev

# Run server
npm start
```

## API Documentation

For complete API documentation, visit: https://docs.housecallpro.com/

## License

MIT

## Support

For issues and feature requests, please visit: https://github.com/mcpengine/housecall-pro-mcp
