# SingleOps MCP

**First MCP server for the SingleOps Public API** — let Claude, Cursor, or any
MCP client read operations, look up clients, and create leads in SingleOps,
the leading US green-industry field-service platform (landscaping, tree care,
irrigation, lawn care, sod farms), part of Granum (1,000+ customers).

## Why this exists

SingleOps is the operations backbone for thousands of tree-care companies,
lawn-care operators, and full-service landscaping businesses across the US
and Canada. The public REST API at `app.singleops.com/api/v1/` has been
documented since the mid-2010s, but until now no one had wrapped it for
MCP clients. The fitness/wellness MCP space is saturated (Mindbody, Glofox,
Wodify, PushPress, etc. all have multiple wrappers), but the green industry
is wide open.

The same MCP works across the SingleOps and Granum family because Granum
(acquired SingleOps) and LMN share infrastructure. Tools that help an
arborist or lawn-care owner get a lead into the system in 30 seconds from
their phone or browser are an obvious fit for AI agents.

## What you can do with it

```
You:   "What divisions does our account have?"
Claude: *calls list_operations, returns Maintenance / Install / Irrigation*

You:   "Did we already quote Jane Doe? Her email is jane@example.com."
Claude: *calls search_clients_by_email, finds client_id 42*

You:   "Create a new lead for client 42 in the Maintenance division for a backyard cleanup."
Claude: *calls create_lead_for_existing_client, returns the new lead id*

You:   "New lead from a phone call — John Smith at 555-123-4567, wants irrigation estimate."
Claude: *calls create_lead_with_new_client with the new client details*
```

## Install

```bash
pip install -e ".[dev]"
```

## Configure

SingleOps uses an `user_email` + `user_token` pair (NOT a bearer token).
Contact `support@singleops.com` to provision an API user on your account.
API access is gated to the **MAX plan** (the doc explicitly states: "API
access may not be available on all pricing tiers").

```bash
export SINGLEOPS_USER_EMAIL="api+youraccount@singleops.example.com"
export SINGLEOPS_USER_TOKEN="<secret-token-issued-by-singleops-support>"
```

## Use with Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "singleops": {
      "command": "singleops_mcp",
      "env": {
        "SINGLEOPS_USER_EMAIL": "api+youraccount@singleops.example.com",
        "SINGLEOPS_USER_TOKEN": "<your-token>"
      }
    }
  }
}
```

## Tools

| Tool | Purpose |
| --- | --- |
| `health_check` | Verify the credentials work. If this fails, all other tools will too. |
| `list_operations` | List the divisions configured in your account (e.g. Maintenance, Install, Irrigation). |
| `list_custom_inputs` | List the per-account custom fields that augment the default lead/job/client schema. |
| `search_clients_by_email` | Find clients by email (prefix match, up to 50 per page). |
| `search_clients_by_phone` | Find clients by phone (prefix match, up to 50 per page). |
| `create_lead_for_existing_client` | Create a lead attached to an existing client record. |
| `create_lead_with_new_client` | Create a new client + lead in a single call. |

## API surface

SingleOps's public REST API is at `https://app.singleops.com/api/v1/`. The
MCP wraps:

- `GET /operations` — list divisions
- `GET /custom_inputs` — list custom field definitions
- `GET /clients/search_by_field?search_field=email|phone&search_term=...&page=...` — search clients
- `POST /jobs` — create a new lead (either for an existing client or with a new client profile)

## Engineering

- 33 tests via `respx` + `hypothesis`, 0% live API calls
- `ruff` (full rule set) + `mypy --strict` + `ruff-format` all clean
- Typed exception hierarchy (`SingleopsAuthError`, `SingleopsNotFoundError`, `SingleopsRateLimitError`, `SingleopsAPIError`, `SingleopsConnectionError`)
- isError-compliance: tools `raise` (not return) on failure, so FastMCP sets `isError: true` on the wire (per the Blackwell MCP security audit)
- JSONL audit logging per tool call with secret redaction (`user_token`, `email`, `phone`, `mobile` all stripped)
- Retry with exponential backoff + full jitter, honoring `Retry-After`

## License

MIT — see `LICENSE`.