From 1f69e79315155f26d8e81c5ea6c5524f7790192e Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Mon, 2 Feb 2026 07:02:08 -0500 Subject: [PATCH] =?UTF-8?q?Rebrand=20MCPEngine=20=E2=86=92=20MCPEngage=20+?= =?UTF-8?q?=20deep=20customization=20for=20Jobber=20field=20service?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix all MCPEngine → MCPEngage, mcpengine → mcpengage - Add 5 field service Power Moves (job pipeline, quote acceleration, revenue forecasting) - Document 8 GraphQL tools with accurate descriptions from source - Add real API URLs (api.getjobber.com/api/graphql) and OAuth auth details - Platform-specific prompts for landscaping, cleaning, HVAC, electrical - Update .env.example with JOBBER_ACCESS_TOKEN (OAuth) - Fix package.json author --- .env.example | 5 +- README.md | 146 ++++++++++++++++++++++++++++++++++++++------------- package.json | 2 +- 3 files changed, 113 insertions(+), 40 deletions(-) diff --git a/.env.example b/.env.example index fe383c2..6446e7a 100644 --- a/.env.example +++ b/.env.example @@ -1,2 +1,3 @@ -# Jobber API Credentials -JOBBER_API_KEY=your-api-key-here +# Jobber OAuth Access Token +# Obtain via OAuth 2.0 flow at https://developer.getjobber.com +JOBBER_ACCESS_TOKEN=your-oauth-access-token-here diff --git a/README.md b/README.md index 2cd68c3..374cbed 100644 --- a/README.md +++ b/README.md @@ -8,30 +8,41 @@ ## 💡 What This Unlocks -**This MCP server gives AI direct access to your entire Jobber workspace.** Instead of clicking through interfaces, you just *tell* it what you need. +**This MCP server gives AI direct access to your entire Jobber workspace.** Instead of clicking through interfaces, you just *tell* it what you need — and AI handles job management, quoting, invoicing, and client operations at scale via GraphQL. -### 🎯 Jobber-Native Power Moves +### ⚡ Field Service Power Moves -The AI can directly control your Jobber account with natural language: +Real automation that landscaping, cleaning, HVAC, and field service pros actually use: -- **Smart automation** — Complex workflows in plain English -- **Data intelligence** — Query, analyze, and export your Jobber data -- **Rapid operations** — Bulk actions that would take hours manually -- **Cross-platform integration** — Combine Jobber with other tools seamlessly +1. **Smart Job Pipeline** — *"Show all jobs scheduled for this week, identify conflicts where techs are double-booked, and suggest rescheduling options"* +2. **Quote to Job Acceleration** — *"Pull all quotes sent last month, filter for those awaiting client approval, and create reminder tasks for follow-ups"* +3. **Revenue Forecasting** — *"List all invoices by status, calculate outstanding AR, project cash flow for next 30 days based on payment patterns"* +4. **Client Intelligence** — *"Search clients in Chicago area who haven't booked in 90+ days, pull their service history, and generate re-engagement quotes"* +5. **Workflow Automation** — *"For every new job created today with 'lawn care' tag, auto-generate a quote with standard line items and send to client"* ### 🔗 The Real Power: Combining Tools -AI can chain multiple Jobber operations together: +AI can chain multiple Jobber operations together via GraphQL: -- Query data → Filter results → Generate reports -- Search records → Update fields → Notify team -- Analyze metrics → Create tasks → Schedule follow-ups +- Query jobs → Filter by status → Analyze completion times → Optimize scheduling +- Search clients → Identify service patterns → Create targeted quotes → Track conversions +- List invoices → Identify late payments → Generate AR aging reports → Prioritize collections +- Pull job data → Analyze profitability by service type → Adjust pricing strategies ## 📦 What's Inside -**103 API tools** covering the entire Jobber platform (Field Service). +**8 Field Service GraphQL Tools** covering job management, quoting, invoicing, and client data: -All with proper error handling, automatic authentication, and TypeScript types. +- `list_jobs` — Query jobs with pagination, filter by status and client +- `get_job` — Get complete job details (line items, schedule, client info, property address) +- `create_job` — Create new jobs with title, client, dates, and line items +- `list_quotes` — Query quotes by status with pagination +- `create_quote` — Build quotes with line items and send to clients +- `list_invoices` — Pull invoice data with amounts, status, and payment tracking +- `list_clients` — Search clients with optional filters and pagination +- `create_client` — Add new clients with contact info and addresses + +All with proper error handling, automatic authentication, and TypeScript types. Powered by **Jobber's GraphQL API** for flexible, efficient queries. ## 🚀 Quick Start @@ -45,7 +56,13 @@ All with proper error handling, automatic authentication, and TypeScript types. npm run build ``` -2. **Get your Jobber API credentials** (see Authentication section below) +2. **Get your Jobber API credentials via OAuth:** + + Jobber uses **OAuth 2.0** for authentication. You'll need to: + - Register your app at [Jobber Developer Portal](https://developer.getjobber.com) + - Complete OAuth flow to obtain an access token + - Tokens are scoped to specific permissions (jobs:read, jobs:write, clients:read, etc.) + - See [Jobber OAuth Documentation](https://developer.getjobber.com/docs/authentication) for step-by-step guide 3. **Configure Claude Desktop:** @@ -58,9 +75,9 @@ All with proper error handling, automatic authentication, and TypeScript types. "mcpServers": { "jobber": { "command": "node", - "args": ["/ABSOLUTE/PATH/TO/jobber-mcp/dist/index.js"], + "args": ["/ABSOLUTE/PATH/TO/jobber-mcp-2026-complete/dist/index.js"], "env": { - "JOBBER_API_KEY": "your-api-key-here" + "JOBBER_ACCESS_TOKEN": "your-oauth-access-token-here" } } } @@ -74,7 +91,7 @@ All with proper error handling, automatic authentication, and TypeScript types. [![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/jobber-mcp) 1. Click the button above -2. Set your Jobber API credentials in Railway dashboard +2. Set your Jobber OAuth access token in Railway dashboard 3. Use the Railway URL as your MCP server endpoint ### Option 3: Docker @@ -82,32 +99,71 @@ All with proper error handling, automatic authentication, and TypeScript types. ```bash docker build -t jobber-mcp . docker run -p 3000:3000 \ - -e JOBBER_API_KEY=your-key \ + -e JOBBER_ACCESS_TOKEN=your-token \ jobber-mcp ``` ## 🔐 Authentication -See the official [Jobber API documentation](https://docs.jobber.com) for authentication details. +Jobber uses **OAuth 2.0** authentication with a **GraphQL API**. -The MCP server handles token refresh automatically. +**GraphQL Endpoint:** `https://api.getjobber.com/api/graphql` -## 🎯 Example Prompts +**Required Headers:** +- `Authorization: Bearer YOUR_ACCESS_TOKEN` +- `X-JOBBER-GRAPHQL-VERSION: 2024-12-16` (API version) -Once connected to Claude, you can use natural language. Examples: +The MCP server handles authentication automatically once you provide your OAuth access token in environment variables. -- *"Show me recent activity in Jobber"* -- *"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 (OAuth flow):** +1. Register your application at [Jobber Developer Portal](https://developer.getjobber.com) +2. Configure OAuth redirect URIs +3. Initiate OAuth flow to get authorization code +4. Exchange code for access token +5. Use token to authenticate API requests + +**Note:** Access tokens may expire; implement token refresh logic for production use. + +See the official [Jobber API documentation](https://developer.getjobber.com/docs) and [GraphQL schema reference](https://developer.getjobber.com/docs/api) for details. + +## 🎯 Example Prompts for Field Service Pros + +Once connected to Claude, use natural language for landscaping, cleaning, HVAC, electrical, and field service workflows: + +**Job Management:** +- *"Show me all jobs scheduled for next week with their client names and addresses"* +- *"Create a new lawn care job for client ID abc123, scheduled for tomorrow 9am-11am with standard mowing line items"* +- *"Get full details for job #12345 including line items and total cost"* + +**Quoting & Sales:** +- *"List all quotes sent in the past 2 weeks that are still pending client approval"* +- *"Create a quote for spring cleanup service with 3 line items: debris removal, mulching, trimming"* +- *"Show quotes that were approved and check if jobs were created from them"* + +**Client Management:** +- *"Search for clients in Seattle area and show their contact info"* +- *"Find clients who had jobs completed last summer but no activity since"* +- *"Create a new client record for 'Green Thumb Apartments' with email and billing address"* + +**Invoicing & Revenue:** +- *"List all invoices due this month and show payment status"* +- *"Calculate total outstanding invoice balance across all clients"* +- *"Show invoices with partial payments and identify remaining balances"* + +**Business Intelligence:** +- *"For all jobs completed last quarter, calculate average job value by service type"* +- *"Identify top 10 clients by total invoice amount and show their service history"* + +**Bulk Operations:** +- *"For all lawn care clients, create seasonal spring quotes with standard packages"* +- *"Export job data from Q4, group by property type (residential vs commercial), analyze profitability"* ## 🛠️ Development ### Prerequisites - Node.js 18+ - npm or yarn -- Jobber account with API access +- Jobber account with API access (OAuth app registered) ### Setup @@ -116,7 +172,7 @@ git clone https://github.com/BusyBee3333/Jobber-MCP-2026-Complete.git cd jobber-mcp-2026-complete npm install cp .env.example .env -# Edit .env with your Jobber credentials +# Edit .env with your Jobber OAuth access token npm run build npm start ``` @@ -132,18 +188,34 @@ 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 OAuth access token is valid and not expired +- Check that your app has the necessary scopes (jobs:read, jobs:write, etc.) +- Ensure your OAuth app is approved in Jobber Developer Portal +- Test your token directly via [Jobber GraphQL Explorer](https://developer.getjobber.com/explorer) ### "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) + +### "GraphQL errors" +- Review error messages for schema validation issues +- Check that field names match Jobber's current GraphQL schema +- Verify API version header (`X-JOBBER-GRAPHQL-VERSION`) matches your schema +- Consult [Jobber GraphQL docs](https://developer.getjobber.com/docs/api) for schema changes + +### "Rate limiting" +- Jobber enforces API rate limits per OAuth app +- Use pagination (`first` parameter) to fetch data in smaller chunks +- Implement exponential backoff for retries ## 📖 Resources -- [Jobber API Documentation](https://docs.jobber.com) +- [Jobber API Documentation](https://developer.getjobber.com/docs) +- [Jobber GraphQL Schema Reference](https://developer.getjobber.com/docs/api) +- [Jobber OAuth Guide](https://developer.getjobber.com/docs/authentication) +- [GraphQL Explorer (test queries)](https://developer.getjobber.com/explorer) - [MCP Protocol Specification](https://modelcontextprotocol.io/) - [Claude Desktop Documentation](https://claude.ai/desktop) @@ -163,10 +235,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 field service and business 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, Housecall Pro, 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 1fb2bc1..de3f023 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for Jobber API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",