mcpengine/servers/fieldedge/README.md

# FieldEdge MCP Server

Complete Model Context Protocol (MCP) server for FieldEdge field service management platform. Provides comprehensive access to jobs, customers, invoices, estimates, technicians, dispatch, equipment, inventory, service agreements, and reporting.

## Features

### 45+ Tools Across 10 Categories

#### Jobs Management (9 tools)
- `fieldedge_jobs_list` - List and filter jobs
- `fieldedge_jobs_get` - Get job details
- `fieldedge_jobs_create` - Create new job
- `fieldedge_jobs_update` - Update job
- `fieldedge_jobs_complete` - Mark job complete
- `fieldedge_jobs_cancel` - Cancel job
- `fieldedge_jobs_line_items_list` - List job line items
- `fieldedge_jobs_line_items_add` - Add line item to job
- `fieldedge_jobs_equipment_list` - List equipment on job

#### Customer Management (8 tools)
- `fieldedge_customers_list` - List and filter customers
- `fieldedge_customers_get` - Get customer details
- `fieldedge_customers_create` - Create new customer
- `fieldedge_customers_update` - Update customer
- `fieldedge_customers_delete` - Delete/deactivate customer
- `fieldedge_customers_search` - Search customers
- `fieldedge_customers_locations_list` - List customer locations
- `fieldedge_customers_equipment_list` - List customer equipment

#### Invoice Management (6 tools)
- `fieldedge_invoices_list` - List and filter invoices
- `fieldedge_invoices_get` - Get invoice details
- `fieldedge_invoices_create` - Create invoice
- `fieldedge_invoices_update` - Update invoice
- `fieldedge_invoices_payments_list` - List payments
- `fieldedge_invoices_payments_add` - Add payment

#### Estimate Management (6 tools)
- `fieldedge_estimates_list` - List estimates
- `fieldedge_estimates_get` - Get estimate details
- `fieldedge_estimates_create` - Create estimate
- `fieldedge_estimates_update` - Update estimate
- `fieldedge_estimates_send` - Send estimate to customer
- `fieldedge_estimates_approve` - Approve and convert to job

#### Technician Management (6 tools)
- `fieldedge_technicians_list` - List technicians
- `fieldedge_technicians_get` - Get technician details
- `fieldedge_technicians_create` - Create technician
- `fieldedge_technicians_update` - Update technician
- `fieldedge_technicians_performance_get` - Get performance metrics
- `fieldedge_technicians_time_entries_list` - List time entries

#### Dispatch Management (5 tools)
- `fieldedge_dispatch_board_get` - Get dispatch board
- `fieldedge_dispatch_assign_tech` - Assign technician to job
- `fieldedge_dispatch_technician_availability_get` - Get technician availability
- `fieldedge_dispatch_zones_list` - List dispatch zones
- `fieldedge_dispatch_optimize` - Auto-optimize dispatch schedule

#### Equipment Management (5 tools)
- `fieldedge_equipment_list` - List equipment
- `fieldedge_equipment_get` - Get equipment details
- `fieldedge_equipment_create` - Create equipment record
- `fieldedge_equipment_update` - Update equipment
- `fieldedge_equipment_service_history_list` - List service history

#### Inventory Management (6 tools)
- `fieldedge_inventory_parts_list` - List inventory parts
- `fieldedge_inventory_parts_get` - Get part details
- `fieldedge_inventory_stock_update` - Update stock levels
- `fieldedge_inventory_purchase_orders_list` - List purchase orders
- `fieldedge_inventory_purchase_orders_get` - Get PO details
- `fieldedge_inventory_reorder_report` - Get reorder report

#### Service Agreements (6 tools)
- `fieldedge_agreements_list` - List service agreements
- `fieldedge_agreements_get` - Get agreement details
- `fieldedge_agreements_create` - Create agreement
- `fieldedge_agreements_update` - Update agreement
- `fieldedge_agreements_cancel` - Cancel agreement
- `fieldedge_agreements_renew` - Renew agreement

#### Reporting & Analytics (6 tools)
- `fieldedge_reports_revenue` - Revenue report
- `fieldedge_reports_job_profitability` - Job profitability analysis
- `fieldedge_reports_technician_performance` - Tech performance metrics
- `fieldedge_reports_aging` - A/R aging report
- `fieldedge_reports_service_agreement_revenue` - Agreement revenue
- `fieldedge_reports_equipment_service_due` - Equipment service due

### 16 Interactive MCP Apps

- **job-dashboard** - Interactive jobs overview with filtering
- **job-detail** - Detailed job view with all information
- **job-grid** - Spreadsheet-style bulk job management
- **customer-detail** - Complete customer profile
- **customer-grid** - Customer data grid view
- **invoice-dashboard** - Invoice and payment tracking
- **estimate-builder** - Interactive estimate creation
- **dispatch-board** - Visual dispatch board
- **schedule-calendar** - Job scheduling calendar
- **technician-dashboard** - Tech performance dashboard
- **equipment-tracker** - Equipment and maintenance tracking
- **inventory-manager** - Inventory and stock management
- **agreement-manager** - Service agreement management
- **revenue-dashboard** - Revenue analytics
- **performance-metrics** - Performance analytics
- **aging-report** - A/R aging visualization

## Installation

```bash
npm install
npm run build
```

## Configuration

Set the following environment variables:

```bash
export FIELDEDGE_API_KEY="your_api_key_here"
export FIELDEDGE_BASE_URL="https://api.fieldedge.com/v2"  # Optional, defaults to production
```

## Usage

### With Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "fieldedge": {
      "command": "node",
      "args": ["/path/to/fieldedge/dist/main.js"],
      "env": {
        "FIELDEDGE_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Standalone

```bash
FIELDEDGE_API_KEY=your_key npm start
```

## Example Queries

**Jobs:**
- "Show me all emergency jobs scheduled for today"
- "Create a new HVAC maintenance job for customer C123"
- "What jobs are assigned to technician T456?"
- "Mark job J789 as complete"

**Customers:**
- "Find all commercial customers in Chicago"
- "Show me customer details for account C123"
- "List all equipment for customer C456"

**Invoices:**
- "Show me all overdue invoices"
- "Create an invoice for job J789"
- "Add a $500 payment to invoice INV-123"

**Dispatch:**
- "Show me today's dispatch board"
- "Assign technician T123 to job J456"
- "What's the technician availability for tomorrow?"
- "Optimize the dispatch schedule for tomorrow"

**Reports:**
- "Show me revenue for the last 30 days"
- "What's the profitability of job J123?"
- "Generate an aging report"
- "Show technician performance metrics for this month"

## Architecture

```
src/
├── client.ts              # API client with auth, pagination, error handling
├── types.ts              # TypeScript type definitions
├── tools/                # Tool implementations
│   ├── jobs-tools.ts
│   ├── customers-tools.ts
│   ├── invoices-tools.ts
│   ├── estimates-tools.ts
│   ├── technicians-tools.ts
│   ├── dispatch-tools.ts
│   ├── equipment-tools.ts
│   ├── inventory-tools.ts
│   ├── agreements-tools.ts
│   └── reporting-tools.ts
├── apps/                 # MCP app implementations
│   └── index.ts
├── server.ts            # MCP server setup
└── main.ts              # Entry point
```

## API Client Features

- **Bearer Token Authentication** - Automatic authorization header injection
- **Pagination Support** - Built-in pagination handling with `getPaginated()` and `getAllPages()`
- **Error Handling** - Comprehensive error handling with detailed error messages
- **Request Methods** - Full REST support (GET, POST, PUT, PATCH, DELETE)
- **Type Safety** - Full TypeScript typing for all API responses

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Development with watch mode
npm run build -- --watch

# Run tests (if implemented)
npm test
```

## License

MIT

## Support

For issues or questions:
- FieldEdge API documentation: https://developer.fieldedge.com
- MCP Protocol: https://modelcontextprotocol.io