# EVOLV MCP services — Docker stack

Three MCP services Claude Code uses to close real loops during EVOLV work:

| Service | What it does | Tools exposed |
|---|---|---|
| `mcp-node-red-admin` | Wraps the Node-RED HTTP admin API | `getFlows`, `postFlow`, `getFlow`, `inject`, `listNodes`, `restartFlow` |
| `mcp-influxdb` | Queries the telemetry bucket | `query`, `assertSeriesExists`, `assertRecentWrite`, `listMeasurements` |
| `mcp-browser` | Headless Playwright against the FlowFuse dashboard | `loadDashboard`, `screenshot`, `consoleLogs`, `waitForChart`, `getChartData` |

## Why these

Each closes a verification loop Claude currently cannot close:

- **Node-RED admin** — today Claude pushes flows via raw `curl`; the
  MCP lets Claude deploy + fire injects + read live state in one
  conversational turn.
- **InfluxDB** — today Claude cannot verify "did the telemetry land?"
  beyond reading source. The MCP closes the loop after a deploy.
- **Browser** — today Claude cannot see the rendered dashboard. The
  MCP catches the failure mode behind the η-null crash + the
  blank-ui-chart bug + the editor pile-up bug at the only layer where
  they're visible.

## Migration plan

These run locally **now** (we're in the middle of an infra migration).
Once the central MCP server is provisioned (target Q3 2026), each
service moves to shared infra by lifting the entry from this
`docker-compose.yml` plus the matching `tools/mcp/<name>/Dockerfile`
and pointing every developer's Claude Code at the central endpoint
instead of `localhost`. **The compose file stays here as the canonical
definition.**

## Usage

```bash
# build the three images (one-off, ~3 min)
cd tools
docker compose --profile mcp build

# start them
docker compose --profile mcp up -d

# wire Claude Code to them — add to your user-level .mcp.json
{
  "mcpServers": {
    "evolv-node-red-admin": { "type": "stdio", "command": "docker", "args": ["exec", "-i", "evolv-mcp-node-red-admin", "node", "server.mjs"] },
    "evolv-influxdb":       { "type": "stdio", "command": "docker", "args": ["exec", "-i", "evolv-mcp-influxdb",       "node", "server.mjs"] },
    "evolv-browser":        { "type": "stdio", "command": "docker", "args": ["exec", "-i", "evolv-mcp-browser",        "node", "server.mjs"] }
  }
}
```

The repo-level `.mcp.json` is deliberately **not** committed (each
developer has different host endpoints / tokens). Use a user-level
config or `~/.claude.json`.

## Required environment

`tools/.env` (gitignored) with:

```dotenv
NODE_RED_HOST=http://host.docker.internal:1880
NODE_RED_TOKEN=…           # optional, only if Node-RED has admin auth on
INFLUX_URL=http://host.docker.internal:8086
INFLUX_TOKEN=…
INFLUX_ORG=wbd
INFLUX_BUCKET=telemetry
DASHBOARD_URL=http://host.docker.internal:1880/dashboard
```

## Status

| Service | Dockerfile | Server impl | Status |
|---|---|---|---|
| `mcp-node-red-admin` | placeholder | **TODO** — see `mcp/node-red-admin/ROADMAP.md` | not runnable yet |
| `mcp-influxdb` | placeholder | **TODO** | not runnable yet |
| `mcp-browser` | placeholder | **TODO** — wrap `@playwright/test` | not runnable yet |

The compose file is the **target shape**. The Dockerfile + server
implementation per service is a follow-up (each is ~200–400 LOC of MCP
protocol + the wrapped client). When a service lands, flip its row
above to `runnable` and remove the placeholder.

## When to use these — required reading

`CLAUDE.md` § "Tooling (Docker-first, local now, central later)" lists
the operating doctrine: **always prefer these tools over ad-hoc
curl/grep/manual checks**. Each tool exists because of a specific bug
class we've already paid for. Skipping them re-opens those bugs.

## Future: OPC-UA / PLC MCP

Out of scope for this round; will be revisited later. When added it
follows the same pattern: `tools/mcp/opcua/` with its own Dockerfile
and a row in this README.