npm package: @rashidazarang/servicefusion-mcp
Description: Model Context Protocol server for ServiceFusion API integration - enables AI agents to interact with ServiceFusion customers, jobs, and work orders
Author: Rashid Azarang
Latest version: 1.0.8

# ServiceFusion MCP Server

A Model Context Protocol (MCP) server that provides AI agents with standardized access to ServiceFusion API operations.

## Features

- **OAuth 2.0 Authentication**: Automatic token management and refresh
- **Complete CRUD Operations**: Create, read, update, and delete customers and jobs
- **Type-Safe Interface**: Full TypeScript support with validation
- **Resource Access**: MCP resources for browsing customers and jobs
- **Error Handling**: Comprehensive error handling and validation

## Available Tools

### Connection Management
- `sf_test_connection` - Test ServiceFusion API connectivity
- `sf_get_api_status` - Get current authentication status

### Customer Operations
- `sf_create_customer` - Create new customers with contacts and locations
- `sf_get_customers` - Search and retrieve customers with pagination

### Job Operations  
- `sf_create_job` - Create new work orders/jobs
- `sf_get_jobs` - Search and retrieve jobs with filtering
- `sf_update_job` - Update job status and details
- `sf_delete_job` - Delete/cancel jobs

## Available Resources

- `servicefusion://customers` - Paginated list of customers
- `servicefusion://jobs` - Paginated list of jobs
- `servicefusion://customer/{id}` - Individual customer details
- `servicefusion://job/{id}` - Individual job details
- `servicefusion://api-status` - API connection status

## Installation

1. Clone and install dependencies:
```bash
npm install
```

2. Set up environment variables:
```bash
cp .env.example .env
# Edit .env with your ServiceFusion credentials
```

3. Build the project:
```bash
npm run build
```

## Usage

### Running the MCP Server

```bash
npm start
```

### Development Mode

```bash
npm run dev
```

### Testing

```bash
npm test
```

## Configuration

Set the following environment variables:

- `SERVICEFUSION_CLIENT_ID` - Your ServiceFusion API client ID
- `SERVICEFUSION_CLIENT_SECRET` - Your ServiceFusion API client secret
- `SERVICEFUSION_BASE_URL` - (Optional) API base URL (defaults to https://api.servicefusion.com)

## Integration with Claude Desktop

Add to your Claude Desktop MCP configuration:

```json
{
  "mcpServers": {
    "servicefusion": {
      "command": "node",
      "args": ["/path/to/servicefusion-mcp/build/index.js"],
      "env": {
        "SERVICEFUSION_CLIENT_ID": "your_client_id",
        "SERVICEFUSION_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

## API Examples

### Create a Customer
```typescript
await sf_create_customer({
  customer_name: "ABC Property Management",
  contacts: [{
    fname: "John",
    lname: "Doe", 
    contact_type: "Primary",
    phone: "555-1234",
    email: "john@abc.com"
  }],
  locations: [{
    street_1: "123 Main St",
    city: "Dallas",
    state_prov: "TX",
    postal_code: "75201"
  }]
});
```

### Create a Job
```typescript
await sf_create_job({
  check_number: "WO-12345",
  customer_id: 123456,
  description: "HVAC repair needed",
  category: "Maintenance",
  priority: "High",
  street_1: "123 Main St",
  city: "Dallas",
  state_prov: "TX"
});
```

### Search Jobs
```typescript
await sf_get_jobs({
  page: 1,
  customer_name: "ABC Property",
  status: "Scheduled",
  updated_since: "2025-01-01T00:00:00Z"
});
```

## Data Models

### Customer
- `customer_name` (required)
- `parent_customer` (optional) - For hierarchical customers
- `contacts[]` - Array of contact information
- `locations[]` - Array of location information

### Job
- `check_number` (required) - Unique identifier
- `customer_id` (required) - Associated customer
- `description` (required) - Job description
- `status` - Job status (Scheduled, In Progress, Completed, etc.)
- `priority` - Job priority (Normal, High, Low)
- `custom_fields[]` - Custom field values

## Error Handling

The server includes comprehensive error handling for:
- Authentication failures (automatic token refresh)
- API rate limits and timeouts
- Invalid input validation
- Network connectivity issues

## Contributing

1. Make changes to TypeScript files in `src/`
2. Build with `npm run build`
3. Test with `npm test`
4. Submit pull requests with tests

## License

MIT