# sudo-meow-mcp

MCP server + autonomous QA agent for [sudo meow](https://github.com/alicefarron/sudo-meow)'s state machine (a Tauri desktop app) — the agent explores the app's actual running state machine over MCP and decides for itself what to test.

## Why this exists

Most test suites encode test cases someone already thought of. This instead gives an LLM agent a small set of tools (read current state, list what transitions are valid from here, fire an event, read history/logs) and a systematic-exploration instruction, and lets it drive the app's real state machine — through a live debug bridge, not mocks — deciding what to probe next based on what it just observed. Coverage of "every state got visited" is enforced by the harness independently of the agent, so the result is trustworthy even when the agent (especially a small local model) doesn't behave perfectly.

## Architecture

```
sudo meow (Tauri app, dev mode)
  Vite dev server ── vite-debug-plugin.ts ── HTTP /__debug/* (localhost:1420)
                                                     │
                                                     ▼
                                    sudo-meow-mcp (this repo)
                                    src/httpClient.ts + src/index.ts
                                    MCP server, stdio transport
                                                     │
                                                     ▼
                                    agent/run-qa.ts (MCP client)
                                    tool-calling loop  ◄──►  Ollama (local LLM)
                                                     │
                                                     ▼
                                              test-report.md
```

- **App → debug bridge**: [sudo-meow](https://github.com/alicefarron/sudo-meow)'s Vite dev server exposes the cat's state machine and Pomodoro timer over a dev-only HTTP API (`/__debug/state`, `/state/transitions`, `/state/trigger`, `/state/history`, `/logs`) — see [`docs/DEBUG_SERVER.md`](docs/DEBUG_SERVER.md) and [`docs/STATE_MACHINE.md`](docs/STATE_MACHINE.md), copied here from that repo since this one directly depends on that contract.
- **Debug bridge → MCP server**: `src/` wraps those 5 endpoints as 5 MCP tools (`get_current_state`, `get_available_transitions`, `trigger_event`, `get_state_history`, `read_console_logs`), served over stdio — the standard transport for a locally-spawned MCP server.
- **MCP server → agent**: `agent/run-qa.ts` is itself an MCP client (spawns the server over stdio, same as Claude Desktop would) and a tool-calling loop against Ollama. Not using any cloud API's remote-MCP connector (e.g. Anthropic's `mcp_servers`) — those only reach servers on a public URL, and this one is deliberately stdio-only/local (see `docs/DEBUG_SERVER.md`).
- **Coverage guarantee, independent of the agent**: the system prompt instructs BFS exploration, but after the agent's own loop ends, a deterministic pass in `agent/bookkeeping.ts` + `run-qa.ts` force-visits any state the agent didn't reach, using the same tool calls. Two mechanical anomaly checks (does a forced transition land where requested; did a new warning/error log line appear) are computed from the raw tool-call transcript, not from asking the agent to self-report.

## Run it

```bash
# 1. In the sudo-meow app repo (separate clone):
npm install && npm run tauri dev     # leave running

# 2. Ollama, once:
brew install ollama                   # or see https://ollama.com
ollama pull llama3.1                  # ~4.7 GB; any tool-calling-capable model works

# 3. This repo:
npm install
npm run build
npm run qa
```

Writes `test-report.md` to this repo's root. Configurable via `.env` (copy `.env.example`) or env vars: `QA_MAX_STEPS` (default 200), `QA_OLLAMA_MODEL` (default `llama3.1`), `OLLAMA_BASE_URL`, `SUDO_MEOW_DEBUG_URL`.

On CPU-only local inference, each tool-call round trip can take from a few
seconds to close to a minute depending on the model and prompt length — the
default budget of 200 can take a while. `QA_MAX_STEPS=40` or so is enough to
see the agent actually explore before the harness's completion pass takes
over; the checked-in `test-report.md` was generated that way.

## Example finding

From a real run ([`test-report.md`](test-report.md), `qwen2.5`, 40 tool calls): the coverage table's `idle` row lists `idle` itself among its own declared organic edges — impossible per the app's own state graph, which has no self-transitions. Root cause: `GET /state/transitions` reports transitions for whatever the live state is *at that instant* but never says which state that was, so the harness infers it from the last snapshot it saw. Real latency between a forced transition and the next tool call is enough for the cat's own clock to have already moved on — the response then gets attributed to the wrong state. Not an app bug; a gap in the debug API's response shape, caught only because the agent was slow enough for the race to matter.

## Stack

TypeScript · [Tauri 2.x](https://v2.tauri.app/) (the app under test) · [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) · [Ollama](https://ollama.com) (local LLM runtime, native tool-calling)

## Reference

### MCP tools

| Tool | Parameters | Wraps |
|---|---|---|
| `get_current_state` | — | `GET /__debug/state` |
| `get_available_transitions` | — | `GET /__debug/state/transitions` |
| `trigger_event` | `eventName: string`, `payload?: object` | `POST /__debug/state/trigger` |
| `get_state_history` | `limit?: number` | `GET /__debug/state/history` |
| `read_console_logs` | `limit?: number` | `GET /__debug/logs` |

`limit` on the last two is applied client-side — the underlying endpoints
always return everything they have, capped at 50 (history) / 200 (logs)
server-side.

Valid `eventName`s for `trigger_event` (call `get_available_transitions`
first to see what's actually valid from the *current* state):

- `cat.forceTransition` — payload `{ "state": CatState }`
- `pomodoro.start` — payload `{ "minutes"?: number }`
- `pomodoro.tick` — payload `{ "dtSeconds"?: number }`
- `pomodoro.resume` — no payload
- `pomodoro.cancel` — no payload

### Using the MCP server outside this agent

It's a normal stdio MCP server — connect it to Claude Desktop or Claude Code
directly, independent of `agent/run-qa.ts`.

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`
on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "sudo-meow-debug": {
      "command": "node",
      "args": ["/absolute/path/to/sudo-meow-mcp/dist/index.js"]
    }
  }
}
```

**Claude Code**:

```bash
claude mcp add sudo-meow-debug -- node /absolute/path/to/sudo-meow-mcp/dist/index.js
```

Use an absolute path in both cases — these tools don't run from this
package's directory. Requires `npm run build` first.

### Manual testing without any LLM

```bash
npm run smoke-test
```

Spawns the built server over stdio, does the MCP `initialize` handshake,
lists tools, and calls each of the 5 tools once (including an intentionally
invalid `trigger_event`, to confirm error handling) — see
[`scripts/smoke-test.mjs`](scripts/smoke-test.mjs). Or, interactively:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

Stopping `npm run tauri dev` and re-running either should make every call
return `isError: true` with a message pointing at the missing dev server,
not a crash or a hang.

## Limitations

- Everything here depends on the sudo-meow app running in dev mode — the
  debug HTTP surface doesn't exist in a built app, by design (see
  `docs/DEBUG_SERVER.md`).
- Day/night variants of the cat's transition graph aren't exercised — no
  tool exposes control over the system clock or the app's time-of-day
  config.
- The QA agent's mechanical anomaly detection is intentionally narrow (2
  checks) to avoid false positives from the state machine's inherent
  randomness; see `test-report.md`'s own "Limitations" section for the
  specifics of any given run.