diff --git a/.env.example b/.env.example index 334c27d..4113a7b 100644 --- a/.env.example +++ b/.env.example @@ -1,2 +1,4 @@ # FieldEdge API Credentials +# Obtain from FieldEdge Settings → API Access FIELDEDGE_API_KEY=your-api-key-here +FIELDEDGE_SUBSCRIPTION_KEY=your-subscription-key-here diff --git a/README.md b/README.md index 6562211..002fa97 100644 --- a/README.md +++ b/README.md @@ -8,28 +8,38 @@ ## 💡 What This Unlocks -**This MCP server gives AI direct access to your entire FieldEdge workspace.** Instead of clicking through interfaces, you just *tell* it what you need. +**This MCP server gives AI direct access to your entire FieldEdge workspace.** Instead of clicking through interfaces, you just *tell* it what you need — and AI handles field service operations, work order management, and customer data at scale. -### 🎯 FieldEdge-Native Power Moves +### ⚡ Field Service Power Moves -The AI can directly control your FieldEdge account with natural language: +Real automation that HVAC, plumbing, and electrical contractors actually use: -- **Smart automation** — Complex workflows in plain English -- **Data intelligence** — Query, analyze, and export your FieldEdge data -- **Rapid operations** — Bulk actions that would take hours manually -- **Cross-platform integration** — Combine FieldEdge with other tools seamlessly +1. **Smart Dispatch** — *"Show me all open work orders for tomorrow, find available techs, and assign HVAC jobs to certified technicians"* +2. **Customer Intelligence** — *"Pull all customers with equipment due for maintenance this month and create preventive service work orders"* +3. **Revenue Analysis** — *"List invoices from Q1, break down by service type, and show which equipment categories generate the most revenue"* +4. **Rapid Quoting** — *"Get all work orders marked as 'estimate needed,' pull equipment specs from customer locations, and draft service proposals"* +5. **Equipment Tracking** — *"Show all HVAC units installed in 2020-2021 that haven't had service in 12+ months and create follow-up tasks"* ### 🔗 The Real Power: Combining Tools AI can chain multiple FieldEdge operations together: -- Query data → Filter results → Generate reports -- Search records → Update fields → Notify team -- Analyze metrics → Create tasks → Schedule follow-ups +- Query work orders → Filter by technician availability → Auto-schedule → Notify customer +- Search equipment records → Check warranty status → Generate service recommendations +- Analyze customer history → Identify upsell opportunities → Create follow-up jobs +- Pull invoice data → Export to accounting → Generate financial reports ## 📦 What's Inside -**96 API tools** covering the entire FieldEdge platform (Field Service). +**7 Field Service API Tools** covering work order management, dispatching, invoicing, and customer data: + +- `list_work_orders` — Query work orders by status, customer, technician, date range +- `get_work_order` — Get full work order details (line items, equipment, schedule) +- `create_work_order` — Create new service jobs with priority, scheduling, and tech assignment +- `list_customers` — Search and retrieve customer records +- `list_technicians` — Get technician/employee roster with availability and departments +- `list_invoices` — Pull invoicing data by status, customer, and date range +- `list_equipment` — Track HVAC units, appliances, and equipment at customer sites All with proper error handling, automatic authentication, and TypeScript types. @@ -45,7 +55,13 @@ All with proper error handling, automatic authentication, and TypeScript types. npm run build ``` -2. **Get your FieldEdge API credentials** (see Authentication section below) +2. **Get your FieldEdge API credentials:** + + - Log in to your FieldEdge account + - Navigate to Settings → API Keys + - Generate a new API key with appropriate permissions + - You'll receive an API key and subscription key (Azure API Management) + - See [FieldEdge API Documentation](https://api.fieldedge.com/docs) for details 3. **Configure Claude Desktop:** @@ -58,9 +74,10 @@ All with proper error handling, automatic authentication, and TypeScript types. "mcpServers": { "fieldedge": { "command": "node", - "args": ["/ABSOLUTE/PATH/TO/fieldedge-mcp/dist/index.js"], + "args": ["/ABSOLUTE/PATH/TO/fieldedge-mcp-2026-complete/dist/index.js"], "env": { - "FIELDEDGE_API_KEY": "your-api-key-here" + "FIELDEDGE_API_KEY": "your-api-key-here", + "FIELDEDGE_SUBSCRIPTION_KEY": "your-subscription-key-here" } } } @@ -83,24 +100,54 @@ All with proper error handling, automatic authentication, and TypeScript types. docker build -t fieldedge-mcp . docker run -p 3000:3000 \ -e FIELDEDGE_API_KEY=your-key \ + -e FIELDEDGE_SUBSCRIPTION_KEY=your-subscription-key \ fieldedge-mcp ``` ## 🔐 Authentication -See the official [FieldEdge API documentation](https://docs.fieldedge.com) for authentication details. +FieldEdge uses **API Key authentication** via Azure API Management. -The MCP server handles token refresh automatically. +**API Base URL:** `https://api.fieldedge.com/v1` -## 🎯 Example Prompts +**Required Headers:** +- `Authorization: Bearer YOUR_API_KEY` +- `Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_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 FieldEdge"* -- *"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 FieldEdge +2. Settings → API Access +3. Generate API Key + Subscription Key +4. Set appropriate permissions (read/write for work orders, customers, etc.) + +See the official [FieldEdge API documentation](https://api.fieldedge.com/docs) for detailed authentication steps. + +## 🎯 Example Prompts for Field Service Pros + +Once connected to Claude, use natural language for HVAC, plumbing, electrical, and field service workflows: + +**Dispatching & Scheduling:** +- *"Show me all open work orders scheduled for next week"* +- *"List available technicians for tomorrow and show their current job assignments"* +- *"Create an emergency HVAC repair work order for customer ID 12345 at their main location"* + +**Customer Management:** +- *"Find customers in zip code 75001 who have HVAC equipment older than 10 years"* +- *"Search for 'Johnson' in customer records and show their service history"* + +**Equipment & Maintenance:** +- *"List all equipment at customer location X and show last service dates"* +- *"Find HVAC units due for seasonal maintenance and create work orders"* + +**Invoicing & Revenue:** +- *"Pull all paid invoices from last month and calculate total revenue"* +- *"Show invoices over $5,000 that are still pending payment"* + +**Bulk Operations:** +- *"For all customers with 'annual maintenance' contracts, check equipment records and schedule Q2 service visits"* +- *"Export work order data for completed jobs last quarter and summarize by service type"* ## 🛠️ Development @@ -132,18 +179,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 both API key and subscription key are correct +- Check that your keys haven't been revoked in FieldEdge settings +- Ensure you have the necessary permissions for the operations you're attempting +- Test credentials directly via [FieldEdge API docs](https://api.fieldedge.com/docs) ### "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) + +### "Rate limit exceeded" +- FieldEdge enforces API rate limits +- Implement pagination for large queries +- Use date filters to reduce result sets ## 📖 Resources -- [FieldEdge API Documentation](https://docs.fieldedge.com) +- [FieldEdge API Documentation](https://api.fieldedge.com/docs) +- [FieldEdge Developer Portal](https://developer.fieldedge.com) - [MCP Protocol Specification](https://modelcontextprotocol.io/) - [Claude Desktop Documentation](https://claude.ai/desktop) @@ -163,10 +218,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 Housecall Pro, 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 242c419..5cc6dcc 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for FieldEdge API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",