npm package: @flotac/service-mcp
Description: Flotac Service MCP Server - Model Context Protocol server for managing service orders, customers, parts, estimates, and more. Per-company scoped with granular permissions.
Author: Flotac
Latest version: 1.0.0

# @flotac/service-mcp

Model Context Protocol (MCP) server for Flotac fleet management. Provides 28 tools for managing service orders, customers, units, parts, employees, scheduling, estimates, and vendor quotes — all gated by per-company user permissions.

## Installation

```bash
npm install @flotac/service-mcp
```

## Quick Start

### As an MCP server (Claude Code / Claude Desktop)

Add to your `.mcp.json` or Claude Desktop config:

```json
{
  "mcpServers": {
    "flotac-service": {
      "command": "npx",
      "args": ["@flotac/service-mcp"]
    }
  }
}
```

### Environment Variables

Set these in your `.env` or `.env.local`:

```
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
```

The server also checks for `VITE_SUPABASE_URL` as a fallback.

## Tools (28)

### Authentication & Context
| Tool | Permission | Description |
|------|-----------|-------------|
| `authenticate_user` | none | Resolve user identity, roles, companies |
| `check_permission` | none | Check specific permission for user+company |

### Customers
| Tool | Permission |
|------|-----------|
| `list_customers` | scoped by `customers.canViewAll` |
| `create_customer` | `customers.canCreate` |
| `get_customer` | read access |

### Units
| Tool | Permission |
|------|-----------|
| `list_units` | inherits customer access |
| `create_unit` | `customers.canEdit` |

### Service Orders
| Tool | Permission |
|------|-----------|
| `list_service_orders` | scoped by `serviceOrders.canViewAll` |
| `create_service_order` | `serviceOrders.canCreate` |
| `get_service_order` | view access |
| `update_service_order` | `serviceOrders.canEdit` |
| `add_task` | `serviceOrders.canEdit` |
| `add_subtask` | `serviceOrders.canEdit` |
| `assign_technician` | `employees.canAssign` |

### Employees & Scheduling
| Tool | Permission |
|------|-----------|
| `list_employees` | `employees.canView` |
| `create_employee` | `employees.canEdit` |
| `update_employee_permissions` | `employees.canManagePermissions` |
| `create_schedule` | `employees.canAssign` |
| `list_locations` | none (read-only) |

### Parts
| Tool | Permission |
|------|-----------|
| `search_parts` | `parts.canView` |
| `add_part_to_subtask` | `parts.canOrder` |
| `update_part_status` | `parts.canOrder` / `parts.canReceive` |

### Financial
| Tool | Permission |
|------|-----------|
| `get_labor_rates` | none (read-only) |
| `update_labor_rate` | `financial.canViewFinancials` + owner role |
| `get_estimate` | view access |

### Vendor Quotes
| Tool | Permission |
|------|-----------|
| `create_quote_request` | `parts.canOrder` |
| `list_quote_requests` | `parts.canView` |

## Per-Company Scoping

Every tool requires `user_id` and `company_id`. The server resolves the user's role and permissions within that specific company — a user may have different roles across multiple companies.

## Permission System

Permissions use dot-notation paths mapped to the `EmployeePermissions` interface:

- `serviceOrders.canCreate` — Create new service orders
- `parts.canOrder` — Order parts
- `employees.canAssign` — Assign technicians to work
- `financial.canViewFinancials` — View revenue and margins
- `employees.canManagePermissions` — Change employee permissions

Built-in role templates: `company_owner`, `manager`, `service_advisor`, `technician`, `parts_specialist`, `bookkeeper`

## Programmatic Usage

```typescript
import { FlotacServiceMCPServer } from '@flotac/service-mcp';

const server = new FlotacServiceMCPServer({
  supabaseUrl: 'https://your-project.supabase.co',
  supabaseServiceRoleKey: 'your-key',
});

await server.start();
```

## License

MIT