# Ask FieldRoutes (fieldroutes-mcp)

Read-only MCP server so pest and lawn owners can ask FieldRoutes questions in plain English — in Claude, ChatGPT, or Cursor.

Sister product to [Ask Fieldwork](https://github.com/daisydaines/fieldwork-mcp). Same Relay pattern: owner-shaped tools with an `answer` string, `/connect` vault (no Terminal-first setup), lookup only.

## Why this exists

Most FieldRoutes MCPs are thin API wrappers: `search_tickets`, env vars in JSON, pip + Terminal. Owners bounce.

Ask FieldRoutes leads with questions owners actually ask:

| Ask… | Tool |
| --- | --- |
| How many customers do I have? | `how_many_customers` |
| Find customer Smith | `find_customer` |
| Who owes me money? | `who_owes_me_money` |
| What’s on the schedule? | `whats_on_the_schedule` |
| Who are my technicians? | `who_are_my_technicians` |
| How are my routes doing? | `how_are_my_routes_doing` |

Lower-level `search_*` / `get_*` tools stay available as a fallback. Writes (create/update/cancel) are refused.

## Auth

FieldRoutes uses **API key + token** (Settings → API), sent in the JSON body as `authenticationKey` / `authenticationToken`.

Optional company subdomain → `https://{subdomain}.pestroutes.com/api`.

## Quick start (local stdio)

```bash
cd fieldroutes-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
# fill FIELDROUTES_AUTHENTICATION_KEY and FIELDROUTES_AUTHENTICATION_TOKEN
```

Point Cursor / Claude at `scripts/run_mcp.sh` (see `mcp.json.example`).

## Hosted connect (no Terminal)

```bash
./scripts/run_mcp_http.sh
# open http://127.0.0.1:8000/connect
```

Paste key + token → encrypted SQLite vault → bearer token for Streamable HTTP MCP at `/mcp`.

| URL | Role |
| --- | --- |
| `/` | Relay landing |
| `/fieldroutes` | Ask FieldRoutes product page |
| `/connect` | Paste credentials → token |
| `/mcp` | Streamable HTTP MCP |
| `/healthz` | Health |

## Deploy

- **Vercel** (`vercel.json`): static `landing/` only (marketing).
- **Docker**: full MCP + `/connect` + vault. Set `FIELDROUTES_VAULT_SECRET` and optionally `FIELDROUTES_PUBLIC_BASE_URL`.

## Safety

- Client allowlists only `search` and `get`.
- Tool annotations mark everything read-only.
- Vault stores encrypted credentials; connect tokens are hashed at rest.

## Vs thin wrappers

| | Typical FieldRoutes MCP | Ask FieldRoutes |
| --- | --- | --- |
| Tools | API-shaped (`search_tickets`) | Owner-shaped + `answer` |
| Setup | pip + env + JSON | `/connect` vault |
| Writes | Often on by default | Off |
| Technicians | Often missing | `who_are_my_technicians` |
| Audience | Developers | Owners |

## License

MIT