From 87944facc0a91f662544af6ccbd1e452647ce60c Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Mon, 2 Feb 2026 07:02:02 -0500 Subject: [PATCH] =?UTF-8?q?Rebrand=20MCPEngine=20=E2=86=92=20MCPEngage=20+?= =?UTF-8?q?=20deep=20customization=20for=20Housecall=20Pro=20home=20servic?= =?UTF-8?q?e?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix all MCPEngine → MCPEngage, mcpengine → mcpengage - Add 5 home service Power Moves (scheduling, estimate pipeline, revenue tracking) - Document 8 tools with accurate descriptions from source - Add real API URLs (api.housecallpro.com/v1) and auth details - Platform-specific prompts for plumbing, HVAC, electrical, landscaping - Update package.json author --- README.md | 117 ++++++++++++++++++++++++++++++++++++++------------- package.json | 2 +- 2 files changed, 88 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index baf610d..e1e1e40 100644 --- a/README.md +++ b/README.md @@ -8,28 +8,39 @@ ## 💡 What This Unlocks -**This MCP server gives AI direct access to your entire Housecall Pro workspace.** Instead of clicking through interfaces, you just *tell* it what you need. +**This MCP server gives AI direct access to your entire Housecall Pro workspace.** Instead of clicking through interfaces, you just *tell* it what you need — and AI handles job scheduling, estimates, invoicing, and customer management at scale. -### 🎯 Housecall Pro-Native Power Moves +### ⚡ Home Service Power Moves -The AI can directly control your Housecall Pro account with natural language: +Real automation that plumbing, HVAC, electrical, and home service pros actually use: -- **Smart automation** — Complex workflows in plain English -- **Data intelligence** — Query, analyze, and export your Housecall Pro data -- **Rapid operations** — Bulk actions that would take hours manually -- **Cross-platform integration** — Combine Housecall Pro with other tools seamlessly +1. **Smart Scheduling** — *"Show me all unscheduled jobs, find available pros today, and book same-day HVAC repairs with customer notifications"* +2. **Estimate to Job Pipeline** — *"Pull all approved estimates from last week, convert them to jobs, assign techs based on specialty, and schedule for this week"* +3. **Revenue Intelligence** — *"List all invoices marked partial payment, calculate outstanding balances by customer, and flag accounts over 30 days"* +4. **Customer Lifecycle** — *"Find customers who booked plumbing jobs 6+ months ago but haven't returned, create follow-up estimates for drain cleaning or water heater checks"* +5. **Employee Optimization** — *"Show all employees with fewer than 5 jobs this week, list unassigned work, and suggest optimal job assignments by location and skill"* ### 🔗 The Real Power: Combining Tools AI can chain multiple Housecall Pro operations together: -- Query data → Filter results → Generate reports -- Search records → Update fields → Notify team -- Analyze metrics → Create tasks → Schedule follow-ups +- Query jobs → Filter by urgency → Auto-assign pros → Send customer updates +- Search estimates → Identify approval patterns → Create follow-up jobs → Schedule dispatch +- Analyze customer data → Identify repeat business → Generate targeted service offers +- Pull invoice history → Export to QuickBooks → Generate cash flow reports ## 📦 What's Inside -**88 API tools** covering the entire Housecall Pro platform (Field Service). +**8 Home Service API Tools** covering job management, estimates, invoicing, and customer data: + +- `list_jobs` — Query jobs by status, customer, date range with pagination +- `get_job` — Get full job details (line items, schedule, assigned pros, customer info) +- `create_job` — Create new service jobs with scheduling, assignments, and tags +- `list_estimates` — Query estimates by status and customer +- `create_estimate` — Build multi-option estimates with line items and pricing +- `list_customers` — Search customers by name, email, phone +- `list_invoices` — Pull invoicing data by status and customer +- `list_employees` — Get employee/pro roster with active status All with proper error handling, automatic authentication, and TypeScript types. @@ -45,7 +56,12 @@ All with proper error handling, automatic authentication, and TypeScript types. npm run build ``` -2. **Get your Housecall Pro API credentials** (see Authentication section below) +2. **Get your Housecall Pro API credentials:** + + - Log in to your Housecall Pro account + - Navigate to Settings → Integrations → API + - Generate a new API key with appropriate permissions + - See [Housecall Pro API Documentation](https://docs.housecallpro.com/reference) for details 3. **Configure Claude Desktop:** @@ -58,7 +74,7 @@ All with proper error handling, automatic authentication, and TypeScript types. "mcpServers": { "housecallpro": { "command": "node", - "args": ["/ABSOLUTE/PATH/TO/housecallpro-mcp/dist/index.js"], + "args": ["/ABSOLUTE/PATH/TO/housecall-pro-mcp-2026-complete/dist/index.js"], "env": { "HOUSECALL_PRO_API_KEY": "your-api-key-here" } @@ -88,19 +104,52 @@ docker run -p 3000:3000 \ ## 🔐 Authentication -See the official [Housecall Pro API documentation](https://docs.housecallpro.com) for authentication details. +Housecall Pro uses **API Key authentication** via bearer token. -The MCP server handles token refresh automatically. +**API Base URL:** `https://api.housecallpro.com/v1` -## 🎯 Example Prompts +**Required Header:** +- `Authorization: Bearer YOUR_API_KEY` -Once connected to Claude, you can use natural language. Examples: +The MCP server handles authentication automatically once you provide credentials in your environment variables. -- *"Show me recent activity in Housecall Pro"* -- *"Create a new record with these details..."* -- *"Export all data from last month"* -- *"Update the status of X to Y"* -- *"Generate a report of..."* +**Getting credentials:** +1. Log in to Housecall Pro +2. Settings → Integrations → API Access +3. Generate API Key +4. Set appropriate scopes (jobs:read, jobs:write, customers:read, etc.) + +See the official [Housecall Pro API documentation](https://docs.housecallpro.com/reference) for detailed authentication steps. + +## 🎯 Example Prompts for Home Service Pros + +Once connected to Claude, use natural language for plumbing, HVAC, electrical, landscaping, and home service workflows: + +**Job Management:** +- *"Show me all jobs scheduled for today with status 'in_progress'"* +- *"Create an emergency plumbing job for customer ID abc123 at their primary address, schedule for 2 hours from now"* +- *"List unscheduled jobs from the past week and show customer contact info"* + +**Estimates & Sales:** +- *"Pull all estimates sent in the last 30 days that are still pending customer approval"* +- *"Create a two-option estimate for HVAC replacement: basic unit at $4,500 and premium at $6,800"* +- *"Show approved estimates that haven't been converted to jobs yet"* + +**Customer Intelligence:** +- *"Search for customers in Austin with 'HVAC' in their service history"* +- *"Find customers who had jobs completed over 6 months ago but no recent activity"* + +**Invoicing & Revenue:** +- *"List all unpaid invoices and calculate total outstanding revenue"* +- *"Show invoices marked 'partial' payment and identify customers with balances over $500"* + +**Team Management:** +- *"List active employees and show who's available (no jobs assigned today)"* +- *"Show all jobs assigned to employee ID xyz789 this week"* + +**Bulk Operations:** +- *"For all customers with completed HVAC jobs last fall, create maintenance reminder estimates for spring tune-ups"* +- *"Export job data for Q1, group by service type, and calculate average job value"* ## 🛠️ Development @@ -132,18 +181,26 @@ npm run test:coverage # Coverage report ## 🐛 Troubleshooting ### "Authentication failed" -- Verify your API credentials are correct -- Check that your API key hasn't been revoked -- Ensure you have the necessary permissions +- Verify your API key is correct +- Check that your key hasn't been revoked in Housecall Pro settings +- Ensure you have the necessary scopes for the operations you're attempting +- Test credentials directly via [Housecall Pro API docs](https://docs.housecallpro.com/reference) ### "Tools not appearing in Claude" - Restart Claude Desktop after updating config -- Check that the path in `claude_desktop_config.json` is absolute +- Check that the path in `claude_desktop_config.json` is **absolute** (not relative) - Verify the build completed successfully (`dist/index.js` exists) +- Check Claude Desktop logs (Help → View Logs) + +### "Pagination issues" +- Housecall Pro uses cursor-based pagination +- Use `per_page` parameter to control result size (max 100) +- Capture `page` or pagination cursors from responses for subsequent calls ## 📖 Resources -- [Housecall Pro API Documentation](https://docs.housecallpro.com) +- [Housecall Pro API Documentation](https://docs.housecallpro.com/reference) +- [Housecall Pro Developer Portal](https://developer.housecallpro.com) - [MCP Protocol Specification](https://modelcontextprotocol.io/) - [Claude Desktop Documentation](https://claude.ai/desktop) @@ -163,10 +220,10 @@ MIT License - see [LICENSE](LICENSE) for details ## 🙏 Credits -Built by [MCPEngine](https://mcpengage.com) — AI infrastructure for business software. +Built by [MCPEngage](https://mcpengage.com) — AI infrastructure for home service and field service software. -Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms. +Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms including FieldEdge, Jobber, ServiceTitan, and more. --- -**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengine). +**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengage). diff --git a/package.json b/package.json index 40e5894..7449e3f 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for Housecall Pro API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",