# Android Tester QC MCP App

Standalone MCP server for Hugomemo Android QA. It gives an agent deterministic application truth
while Android MCP remains the only owner of emulator interaction.

The important split is:

| Responsibility | Tooling |
| --- | --- |
| Tap, type, swipe, Back, screenshot, UI tree | `android_emulator_1` / the configured Android MCP |
| Server session, queue, attempts, raw result detail, ratings, score, entitlement, usage | this `hugomemo-qa` MCP |
| Optional fixture reset/subscription/seed controls | an explicitly configured local QA control plane |
| Local SQLite queue or in-process game state | optional state sidecar/bridge; otherwise reported as not observable |

This repository intentionally does not contain an Android APK, `adb` wrapper, autonomous launcher,
AI provider, database credential, or screenshot analyzer. That keeps failures attributable and the
test surface safe to run against a disposable emulator.

## Quick start

```bash
npm ci
npm run check
npm run lint
cp .env.example .env   # keep the file local; never commit it
export HUGOMEMO_API_URL=http://127.0.0.1:3000
export HUGOMEMO_QA_ENV=development
export HUGOMEMO_QA_ACCESS_TOKEN='set-this-outside-the-repository'
npm run doctor
npm start
```

The MCP process speaks JSON-RPC on stdout. Diagnostics go to stderr only. Put the token in the
MCP client's process environment rather than in a checked-in config file.

## Recommended MCP pairing

Configure this server beside the existing serial-pinned Android MCP. Do not expose duplicate UI
actions from this server; it is an application-truth server.

The checked-in, secret-free Hugomemo profile is `config/hugomemo-profile.json`; it is the single
place for the package, serial ownership, status command, and route markers.

```json
{
  "mcpServers": {
    "hugomemo-qa": {
      "command": "node",
      "args": ["/absolute/path/to/Android_tester_qc_mcp_app/dist/index.js"],
      "env": {
        "HUGOMEMO_API_URL": "http://127.0.0.1:3000",
        "HUGOMEMO_QA_ENV": "development"
      }
    }
  }
}
```

Inject `HUGOMEMO_QA_ACCESS_TOKEN` through the MCP host/terminal. The Android MCP server is
configured separately and remains the sole owner of `emulator-5554`.

## Tool groups

Read tools include:

- `qa_health` — unauthenticated API/database health.
- `qa_get_app_snapshot` — consistent, bounded Today/Progress/entitlement/usage snapshot.
- `qa_get_current_session` — server session and validity state.
- `qa_get_current_round` — next server-selected queue round, with asset URLs omitted.
- `qa_get_game_state` — optional live game state from the sidecar/bridge.
- `qa_get_attempts` and `qa_get_round_detail` — account-export-backed server attempts.
- `qa_get_skill_ratings` and `qa_get_memory_score` — ratings/score from Progress.
- `qa_get_entitlement` and `qa_get_usage` — server-owned access and usage ledgers.
- `qa_get_sync_status` — server sync evidence plus an explicit local-queue observability result.
- `qa_validate_app_contract` — validates the live response contracts and reports each failed section.

Mutation names (`qa_reset_test_user`, `qa_set_subscription`, `qa_seed_questions`,
`qa_set_game_level`, and `qa_force_offline_queue`) are present for a future/local QA control plane.
They fail closed unless `HUGOMEMO_QA_CONTROL_URL`, a control token, a non-production environment,
and `HUGOMEMO_QA_ALLOW_MUTATIONS=1` are all present. This prevents a missing fixture service from
turning into a misleading successful test.

## Typical deterministic check

1. Use Android MCP to navigate to `today-screen` and start the visible game.
2. Call `qa_get_current_round` to retrieve the server question/configuration. Use the returned
   `test_ids` and Android MCP component bounds for UI interaction; do not guess from the image URL.
3. Use Android MCP to play the round and reach the completion route.
4. Call `qa_get_attempts` or `qa_get_round_detail` and compare the raw detail with the visible
   result. `qa_get_memory_score` can also compare a UI score supplied by the tester to the server
   score.
5. Call `qa_validate_app_contract` and record the result in the product screen ledger.

If a tool says `not_observable`, record that as a real gap. The app currently has no supported
remote JS/SQLite inspection channel, so the MCP cannot honestly claim local queue contents.

## Commands

```bash
npm test          # unit/contract tests, no network or emulator
npm run build     # strict TypeScript build
npm run lint      # ESLint
npm run check     # test + build
npm run doctor    # read-only local API health probe
```

Runtime artifacts belong outside git (the default is `.qa-runs/`). Never target production or a
real user account with fixture controls.