jake/mcpengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
mcpengine/servers/servicetitan/README.md

276 lines
8.4 KiB
Markdown
Raw Blame History

# ServiceTitan MCP Server
Complete Model Context Protocol (MCP) server for ServiceTitan field service management platform.
## Features
### 🔧 **55 MCP Tools** across 10 categories:
#### Jobs Management (9 tools)
- `servicetitan_list_jobs` - List jobs with filters
- `servicetitan_get_job` - Get job details
- `servicetitan_create_job` - Create new job
- `servicetitan_update_job` - Update job
- `servicetitan_cancel_job` - Cancel job
- `servicetitan_list_job_appointments` - List job appointments
- `servicetitan_create_job_appointment` - Create appointment
- `servicetitan_reschedule_appointment` - Reschedule appointment
- `servicetitan_get_job_history` - Get job history
#### Customer Management (9 tools)
- `servicetitan_list_customers` - List customers
- `servicetitan_get_customer` - Get customer details
- `servicetitan_create_customer` - Create customer
- `servicetitan_update_customer` - Update customer
- `servicetitan_search_customers` - Search customers
- `servicetitan_list_customer_contacts` - List contacts
- `servicetitan_create_customer_contact` - Create contact
- `servicetitan_list_customer_locations` - List locations
- `servicetitan_create_customer_location` - Create location
#### Invoice Management (8 tools)
- `servicetitan_list_invoices` - List invoices
- `servicetitan_get_invoice` - Get invoice details
- `servicetitan_create_invoice` - Create invoice
- `servicetitan_update_invoice` - Update invoice
- `servicetitan_list_invoice_items` - List invoice items
- `servicetitan_add_invoice_item` - Add invoice item
- `servicetitan_list_invoice_payments` - List payments
- `servicetitan_add_invoice_payment` - Add payment
#### Estimates (6 tools)
- `servicetitan_list_estimates` - List estimates
- `servicetitan_get_estimate` - Get estimate
- `servicetitan_create_estimate` - Create estimate
- `servicetitan_update_estimate` - Update estimate
- `servicetitan_convert_estimate_to_job` - Convert to job
- `servicetitan_list_estimate_items` - List items
#### Technician Management (6 tools)
- `servicetitan_list_technicians` - List technicians
- `servicetitan_get_technician` - Get technician details
- `servicetitan_create_technician` - Create technician
- `servicetitan_update_technician` - Update technician
- `servicetitan_get_technician_performance` - Get performance
- `servicetitan_list_technician_shifts` - List shifts
#### Dispatch (4 tools)
- `servicetitan_list_dispatch_zones` - List zones
- `servicetitan_get_dispatch_board` - Get dispatch board
- `servicetitan_assign_technician` - Assign technician
- `servicetitan_get_dispatch_capacity` - Get capacity
#### Equipment (5 tools)
- `servicetitan_list_equipment` - List equipment
- `servicetitan_get_equipment` - Get equipment
- `servicetitan_create_equipment` - Create equipment
- `servicetitan_update_equipment` - Update equipment
- `servicetitan_list_location_equipment` - List by location
#### Memberships (6 tools)
- `servicetitan_list_memberships` - List memberships
- `servicetitan_get_membership` - Get membership
- `servicetitan_create_membership` - Create membership
- `servicetitan_update_membership` - Update membership
- `servicetitan_cancel_membership` - Cancel membership
- `servicetitan_list_membership_types` - List types
#### Reporting (4 tools)
- `servicetitan_revenue_report` - Revenue analytics
- `servicetitan_technician_performance_report` - Performance metrics
- `servicetitan_job_costing_report` - Job costing
- `servicetitan_call_tracking_report` - Call tracking
#### Marketing (4 tools)
- `servicetitan_list_campaigns` - List campaigns
- `servicetitan_get_campaign` - Get campaign
- `servicetitan_list_leads` - List leads
- `servicetitan_get_lead_source_analytics` - Lead source ROI
### 📊 **20 MCP Apps** (React-based UI)
- **Job Dashboard** - Overview of all jobs
- **Job Detail** - Detailed job information
- **Job Grid** - Searchable job grid
- **Customer Detail** - Complete customer profile
- **Customer Grid** - Customer database
- **Invoice Dashboard** - Revenue overview
- **Invoice Detail** - Invoice line items
- **Estimate Builder** - Create estimates
- **Dispatch Board** - Visual scheduling
- **Technician Dashboard** - Performance overview
- **Technician Detail** - Individual tech stats
- **Equipment Tracker** - Equipment by location
- **Membership Manager** - Recurring memberships
- **Revenue Dashboard** - Revenue trends
- **Performance Metrics** - KPIs
- **Call Tracking** - Inbound call analytics
- **Lead Source Analytics** - Marketing ROI
- **Schedule Calendar** - Calendar view
- **Appointment Manager** - Appointment management
- **Marketing Dashboard** - Campaign performance
## Installation
```bash
npm install
```
## Configuration
Create a `.env` file in the server root:
```env
# Required
SERVICETITAN_CLIENT_ID=your_client_id
SERVICETITAN_CLIENT_SECRET=your_client_secret
SERVICETITAN_TENANT_ID=your_tenant_id
SERVICETITAN_APP_KEY=your_app_key
# Optional
SERVICETITAN_BASE_URL=https://api.servicetitan.io
PORT=3000
MODE=stdio # or "http"
```
### Getting ServiceTitan API Credentials
1. **Register Developer Account**
- Visit https://developer.servicetitan.io
- Sign up for developer access
2. **Create Application**
- Create a new application in the developer portal
- Note your `client_id`, `client_secret`, and `app_key`
3. **Get Tenant ID**
- Your tenant ID is provided by ServiceTitan
- Usually visible in your ServiceTitan admin dashboard
## Usage
### Stdio Mode (MCP Protocol)
For use with Claude Desktop or other MCP clients:
```bash
npm run build
npm start
```
Add to your MCP client configuration (e.g., `claude_desktop_config.json`):
```json
{
"mcpServers": {
"servicetitan": {
"command": "node",
"args": ["/path/to/servicetitan/dist/main.js"],
"env": {
"SERVICETITAN_CLIENT_ID": "your_client_id",
"SERVICETITAN_CLIENT_SECRET": "your_client_secret",
"SERVICETITAN_TENANT_ID": "your_tenant_id",
"SERVICETITAN_APP_KEY": "your_app_key"
}
}
}
}
```
### HTTP Mode (Web Apps)
For browser-based UI apps:
```bash
MODE=http PORT=3000 npm start
```
Visit http://localhost:3000/apps to access the React apps.
## API Architecture
### Authentication
- OAuth2 client_credentials flow
- Automatic token refresh
- 5-minute token expiry buffer
### Pagination
- Automatic pagination handling
- Configurable page size (default: 50, max: 500)
- `getPaginated()` for automatic multi-page fetching
### Error Handling
- Comprehensive error messages
- Rate limit detection
- Network error recovery
- 401/403 authentication errors
- 429 rate limit errors
- 500+ server errors
### API Endpoints
Base URL: `https://api.servicetitan.io`
- Jobs: `/jpm/v2/tenant/{tenant}/`
- Customers: `/crm/v2/tenant/{tenant}/`
- Invoices: `/accounting/v2/tenant/{tenant}/`
- Estimates: `/sales/v2/tenant/{tenant}/`
- Technicians: `/settings/v2/tenant/{tenant}/`
- Dispatch: `/dispatch/v2/tenant/{tenant}/`
- Equipment: `/equipment/v2/tenant/{tenant}/`
- Memberships: `/memberships/v2/tenant/{tenant}/`
- Reporting: `/reporting/v2/tenant/{tenant}/`
- Marketing: `/marketing/v2/tenant/{tenant}/`
## Development
```bash
# Build
npm run build
# Watch mode
npm run dev
# Start server
npm start
```
## Project Structure
```
servicetitan/
├── src/
│ ├── clients/
│ │ └── servicetitan.ts # API client with OAuth2
│ ├── tools/
│ │ ├── jobs-tools.ts # Job management tools
│ │ ├── customers-tools.ts # Customer tools
│ │ ├── invoices-tools.ts # Invoice tools
│ │ ├── estimates-tools.ts # Estimate tools
│ │ ├── technicians-tools.ts # Technician tools
│ │ ├── dispatch-tools.ts # Dispatch tools
│ │ ├── equipment-tools.ts # Equipment tools
│ │ ├── memberships-tools.ts # Membership tools
│ │ ├── reporting-tools.ts # Reporting tools
│ │ └── marketing-tools.ts # Marketing tools
│ ├── types/
│ │ └── index.ts # TypeScript types
│ ├── ui/
│ │ └── react-app/ # 20 React MCP apps
│ ├── server.ts # MCP server
│ └── main.ts # Entry point
├── package.json
├── tsconfig.json
└── README.md
```
## License
MIT
## Support
- ServiceTitan API Documentation: https://developer.servicetitan.io/docs
- ServiceTitan Developer Portal: https://developer.servicetitan.io
- MCP Protocol: https://modelcontextprotocol.io
Reference in New Issue View Git Blame Copy Permalink