# mini-mcp-lab

[正體中文測試手冊](README.zh-TW.md)

This is a hands-on procurement scenario test. You do not need prior knowledge
of MCP, AI agents, or JSON-RPC. If you can run commands in a terminal and
compare text results, you can complete the acceptance test.

## What you are testing

You are acting as the requester. Requisition `PR-1042` is already saved:

- 20 annual cloud document-collaboration licenses;
- total value TWD 72,000;
- lines and attachments are stored;
- submission discovers one missing security approval ID.

The separate security workflow takes three days and produces
`SEC-2026-0715`. While waiting, the procurement service restarts because of a
deployment or disconnection.

The test answers one question:

> After the service restarts, can the work that was waiting for human input
> continue from where it stopped?

| Test | Plain-language analogy | Expected result after restart |
|---|---|---|
| Legacy | A phone call stays open while you look for the answer | The call drops. The draft remains, but submission and the answer must be repeated |
| Modern | You receive a claim ticket and return with it later | The first call is over. A new request carries the ticket and answer, then continues |

A surviving requisition does not prove that the pending interaction survived.
The scenario tests these two facts separately.

## Five-minute acceptance test

The examples below use Windows. Start PowerShell or Command Prompt in this
project directory. Equivalent [macOS/Linux commands](#macoslinux-commands) are
listed below.

### 1. Install

```bat
scripts\setup.bat
```

The first run may take a few minutes. This final line means installation passed:

```text
[setup] ready: ...\.venv\Scripts\python.exe
```

If it does not appear, stop and retain the error shown in the terminal.

### 2. Test the legacy flow

```bat
scripts\lab.bat --era legacy --sleep 0
```

The scenario runs automatically. For the first pass, look only at lines
beginning with `[agent]`; you may ignore `[wire]` and `[server]`.

The test passes when these events appear in order:

```text
[agent] 模擬部署／斷線：真人回答前，舊 server process 被重啟
[agent] 預期結果：等待回答期間 server 已重啟；原 tools/call 無法續接
[agent] 請購草稿仍在，但原問答已遺失；重新呼叫 submit 並再次補件
[agent] 送出流程完成：status=submitted, receipt=SUB-PR-1042
```

“Cannot resume” is the expected legacy result, not a program failure. The
original interaction must break; the script then submits and answers again.

The test fails if the expected interruption is absent, the draft disappears,
the final status is not `submitted`, or an unhandled Python error is shown.

### 3. Test the modern flow

```bat
scripts\lab.bat --era modern --sleep 0
```

Again, focus on `[agent]`. The test passes when these events appear in order:

```text
[agent] Server 已回 input_required；第 1 次 tools/call 已正常結束
[agent] /restart：要求重新啟動 server
[agent] 新 request 接續成功：status=submitted, approval=SEC-2026-0715
```

The first request ends normally after returning an opaque claim ticket. After
the service restarts, a new request brings back that ticket and the approval ID
and continues the work.

The test fails if the first request does not ask for missing input normally,
the service asks for the same information again after restart, the final
`submitted` result is absent, or an unhandled Python error is shown.

### 4. Record the result

| Check | Legacy | Modern |
|---|---|---|
| Service restarts while waiting | Must pass | Must pass |
| `PR-1042` draft remains available | Must pass | Must pass |
| Pending input work resumes directly | Expected not to | Must pass |
| Requisition is eventually submitted | Passes after repeating work | Passes after resuming |

The complete scenario passes only when both commands match this table.

### macOS/Linux commands

```sh
./scripts/setup.sh
./scripts/lab.sh --era legacy --sleep 0
./scripts/lab.sh --era modern --sleep 0
```

Use the same acceptance criteria.

## Reading the terminal

| Prefix | Meaning | Read on the first run? |
|---|---|---|
| `[human]` | The user request or supplied approval ID | Optional story context |
| `[agent]` | What the system is doing and the outcome | Yes |
| `[wire C→S]` | Raw message sent to the service | No; technical evidence |
| `[wire S→C]` | Raw response from the service | No; technical evidence |
| `[server]` | Procurement service log | Only when diagnosing failure |

Large `{...}` blocks are raw MCP messages. They prove that real protocol
messages were exchanged; business testers do not need to interpret every field.

## Optional interactive test

After the scripted scenario passes:

```bat
scripts\agent-modern.bat
```

Enter these lines one at a time after the `agent>` prompt:

```text
show
/sleep 3
scenario
/new
show
/new PR-1042
show
/quit
```

| Command | Action | Expected result |
|---|---|---|
| `show` | Display the current requisition | Finds `PR-1042` |
| `/sleep 3` | Represent a three-day wait with three seconds | Setting is accepted |
| `scenario` | Wait, restart, and return with the answer | Modern flow resumes and submits |
| `/new` | Start a new conversation without a handoff | Next `show` fails because no requisition was identified |
| `/new PR-1042` | Start a new conversation with an explicit handoff | Next `show` finds the record |
| `/quit` | Exit | Returns to the terminal |

The missing record context after `/new` does not mean the data was deleted.
The new conversation simply has not been told which requisition to use.

Interactive mode reuses `data/procurement.sqlite3`. If an earlier run already
submitted the sample, `scenario` may finish immediately without asking for
input. Use `scripts\lab.bat`, which creates fresh temporary data every time,
for the formal legacy-versus-modern comparison.

## What this test does not prove

- It does not prove that modern MCP automatically remembers a requisition.
  SQLite preserves the business data.
- `PR-1042` is a business record ID, not an MCP session ID or continuation
  ticket.
- The agent is deterministic software, not a large language model, so the wire
  and outcome are reproducible.
- The lab is stdio-only and single-machine; it does not cover HTTP, OAuth,
  multi-host deployment, subscriptions, or Tasks.
- It does not claim a complete official conformance-suite pass. See
  [Protocol and evidence](docs/protocol.md).

## Technical verification

Business acceptance does not require this section. To assert the raw wire:

```bat
scripts\verify-wire.bat
```

To run unit tests, type and format checks, and both scenarios:

```bat
scripts\test.bat
```

The project uses one official `mcp==2.0.0` Python SDK v2 environment and one
server implementation. A deterministic raw stdio agent selects
`2025-11-25` or `2026-07-28` through real opening messages; the comparison
does not use two hand-written servers pretending to be two protocol versions.

```mermaid
flowchart LR
    U["Tester"] --> A["Text-based simulated agent"]
    A -->|"Real stdio MCP messages"| S["One procurement MCP Server"]
    S --> D[("SQLite<br/>draft and continuation verification data")]
    S -->|"Legacy: keep original call waiting"| A
    S -->|"Modern: return a claim ticket and end call"| A
```

Further reading:

- [Full scenario](docs/scenario.md)
- [Engineering runbook](docs/runbook.md)
- [Protocol and evidence](docs/protocol.md)

## Contributing

Run `scripts\test.bat` or `scripts/test.sh` before submitting changes. Protocol
changes require raw-wire regression coverage, not only in-memory SDK tests.

## License

[MIT](LICENSE)