# Loki MCP — Diagnostics (Droplet)

Read-only MCP server over **Loki / Thor**, scoped to 1mg's **diagnostics** (phlebo
sample-collection) logistics — **not** the pharmacy delivery surface. Every
order/batch tool targets the `diagno` endpoints. Diagnostics hubs are **PACs**
(Phlebo Activity Centers, `business_client="droplet"`, `type="PAC"`) and riders
are **phlebos**.

It talks to the same gateway the Thor admin UI uses (`https://thor.1mg.com/1mg_api`),
so no VPN or host setup is needed beyond a valid login token.

## Tools

| Tool | Surface | What it does |
| --- | --- | --- |
| `loki_reference_data` | enums | Valid `order_statuses` / `task_statuses` / `rider_statuses` / `rider_types` |
| `loki_search_hubs` | hubs | Find a PAC hub id from name/code (defaults to `droplet`) |
| `loki_get_hub` | hubs | Full hub detail by id |
| `loki_search_orders` | orders | Diagnostics orders for a PAC on a day — **hub_id + day_query required** |
| `loki_count_orders_by_status` | orders | Order counts by status (all/placed/completed/…) for a PAC+day |
| `loki_get_order` | orders | Full order detail by numeric id (tests, slot, status) |
| `loki_get_order_timelines` | orders | Date-keyed status history of an order |
| `loki_search_batches` | batches | Diagnostics batches (consignments) for a day |
| `loki_get_batch_metrics` | batches | Aggregate batch/assignment metrics for a day |
| `loki_get_batch` | batches | Full batch detail (orders + assigned_in_batch) |
| `loki_search_riders` | riders | Search riders/phlebos (shared infra) |
| `loki_get_rider` | riders | Full rider detail by numeric id |
| `loki_get_hub_riders` | riders | Phlebos attached to a PAC (optionally by type) |
| `loki_get_phlebo_day_metrics` | day tracking | Daily KPI summary (assigned/completed/distance/breach) |
| `loki_get_phlebo_day_tasks` | day tracking | Chronological day timeline (shift, login, task sequence) |
| `loki_get_phlebo_planned_route` | day tracking | Planned route waypoints + locations |
| `loki_get_phlebo_actual_route` | day tracking | Actual GPS pings (speed, battery, coolbox temp) |
| `loki_search_phlebo_daily_metrics` | day tracking | "Track Phlebos" board for a PAC+date |
| `loki_get_hub_attendance_metrics` | attendance | total_present / total_absent for hub(s) on a date |
| `loki_get_rider_monthly_attendance` | attendance | Day-by-day attendance + hours for a rider/month |

All tools are read-only (`readOnlyHint: true`).

### Date-format gotchas (they differ by surface)
- **Orders** (`loki_search_orders`, `loki_count_orders_by_status`): `day_query` is **`DD/MM/YYYY`**.
- **Batches** (`loki_search_batches`, `loki_get_batch_metrics`): `date` is **`YYYY-MM-DD`**.
- **Phlebo day-tracking/attendance**: `date` is **`YYYY-MM-DD`**; `phlebo_id`/`rider_id` is the numeric rider id.
- **Order detail/timeline**: take the order's **numeric `id`** (from search rows), not the `NNN-NNN` display `order_id`.

## Auth

Thor authenticates with the `authTokenThor` JWT cookie. It is short-lived, so the
server reads it **fresh on every call** — refreshing never needs a restart.

1. Open https://thor.1mg.com while logged in.
2. DevTools → Application → Cookies → copy the `authTokenThor` value.
3. Paste it into the token file:

   ```bash
   echo 'PASTE_TOKEN_HERE' > ~/.loki_token
   ```

When calls start returning 401/403, just overwrite `~/.loki_token` with a fresh value.

| Env var | Default | Purpose |
| --- | --- | --- |
| `LOKI_TOKEN_FILE` | `~/.loki_token` | Path to token file |
| `LOKI_TOKEN` | — | Token fallback if no file |
| `LOKI_BASE_URL` | `https://thor.1mg.com/1mg_api` | Gateway base |

## Setup

```bash
cd loki-mcp
uv sync
echo 'PASTE_TOKEN_HERE' > ~/.loki_token
uv run python server.py   # smoke test (Ctrl-C to stop)
```

## Register in Claude Code

```bash
claude mcp add loki -- /Users/abhishekjain/1mg-claude-code/toy-ptojects/loki-mcp/.venv/bin/python \
  /Users/abhishekjain/1mg-claude-code/toy-ptojects/loki-mcp/server.py
```

## Notes

- `hub_id` is mandatory for order/batch/phlebo lookups. Resolve PAC names → ids with `loki_search_hubs`.
- See the date-format gotchas above — orders use `DD/MM/YYYY`, batches/phlebo use `YYYY-MM-DD`.
- Intentionally **read-only**; no write/action tools (assign, auto_assign, etc.) are exposed.