diff options
Diffstat (limited to 'debug/risc-v-gsp-rm-vm/docs/20-MCP-SERVER.md')
| -rw-r--r-- | debug/risc-v-gsp-rm-vm/docs/20-MCP-SERVER.md | 20 |
1 files changed, 16 insertions, 4 deletions
diff --git a/debug/risc-v-gsp-rm-vm/docs/20-MCP-SERVER.md b/debug/risc-v-gsp-rm-vm/docs/20-MCP-SERVER.md index 46e28a4..0e5fede 100644 --- a/debug/risc-v-gsp-rm-vm/docs/20-MCP-SERVER.md +++ b/debug/risc-v-gsp-rm-vm/docs/20-MCP-SERVER.md @@ -127,7 +127,7 @@ the audit trail). | `initialize` | returns `protocolVersion` (echoes `2024-11-05`, `2025-03-26` or `2025-06-18`; otherwise the server default), `serverInfo`, `capabilities.tools` | | `notifications/initialized` | accepted silently (notifications never get a response) | | `ping` | `{}` | -| `tools/list` | the 24-tool catalogue with JSON input schemas | +| `tools/list` | the 31-tool catalogue with JSON input schemas | | `tools/call` | `{"name": ..., "arguments": {...}}` → `{"content":[{"type":"text","text":"<json>"}]}`, or `isError: true` for tool errors | JSON-RPC errors: `-32700` parse error, `-32600` invalid request, `-32601` @@ -144,6 +144,8 @@ them deterministically. | Tool | Arguments | Class | Notes | |---|---|---|---| | `session_info` | — | read | backend, PC, symbols, recording, breakpoints/watches, enabled capabilities | +| `backends_list` | — | read | QEMU/native availability and features; `active` backend; `launchable` (standalone only) | +| `session_launch` | `backend=native\|qemu`, `kernel`, `record=true`, `name`, `trace=false` | session | protocol-level backend selection; replaces the served session; **standalone mode only**; `trace` is native-only; allowed without `--allow-write` (it replaces the local served session and writes only its own recording; it never touches target memory) | | `symbols_resolve` | `target` | read | symbol, `symbol+0xNN` or hex address | | `bp_set` | `target`, `kind=sw\|hw` | observe | hits recorded as `bp_hit` | | `bp_clear` | `target` | observe | removes every breakpoint at that address | @@ -157,8 +159,13 @@ them deterministically. | `snapshot` | `addr`, `size` (max 16 MiB), `label=mcp` | read | zlib + sha256 into the session | | `call_function` | `target`, `args=[]`, `timeout=5.0` | **write** | requires `--allow-write`; Frida-like remote call | | `inject_service` | `service`, `slot=6`, `load_addr`, `cmd=1`, `arg0`, `arg1`, `path=remote\|firmware\|both`, `settle=0.25` | **inject** | requires `--allow-inject`; service ELF built with `make sdk` | +| `service_list` | — | read | services loaded into this session (injection registry) + the demo handler slots | | `trace_start` | `exec=true`, `start`, `end`, `max_events` | trace | native backend + recording session only | | `trace_stop` | — | trace | flushes `blobs/trace.jsonl`, returns counts | +| `sim_cycles` | — | read | native only: `insns`, modeled `cycles`, cycle-model table, fidelity label | +| `sim_device_state` | `limit=16` | read | native only: unknown-MMIO policy/log, device-map size, optional `sim/devices` model state | +| `sim_profile` | — | read | native only: firmware, bias, stop/profile metadata, trace config, model identity, session meta | +| `sim_regions` | `limit=16` | read | native only: RAM/UART windows, loaded firmware segments, device-map entries, observed unmodelled MMIO pages | | `analyze_current` | `max_rows=40` | read | `render_summary` for the active recording | | `compare_sessions` | `a`, `b`, `symbols=true`, `max_rows=40` | read | A/B recorded sessions | | `export_hits` | `session`, `out` | read | Ghidra `greeneye_hits.tsv` | @@ -231,7 +238,10 @@ recorded, and the session can be compared like any other run. 3. **Read-only by default.** `--allow-write` enables `write_mem` and `call_function`; `--allow-inject` enables `inject_service`. The agent's client config decides which manifest class it gets; a read/observe agent is - configured without those flags. + configured without those flags. Session-class tools (`session_info`, + `session_launch`) stay available without the flags: launching selects or + replaces the local served session (standalone mode) and never mutates + target memory. 4. **Sessions are the audit trail.** Writes, calls, injections and snapshots land in `events.jsonl`; run with `--record` (the trace tools require it). A finding without a session is not a finding. @@ -259,14 +269,16 @@ The tool list is stable regardless of what is present. ## 9. Testing ```bash -python3 -m unittest tests.test_mcp -v # 34 tests, no external deps +python3 -m unittest tests.test_mcp -v # 55 tests, no external deps ``` The suite drives `initialize`/`tools/list`/`tools/call` over in-memory streams (including unknown method/tool, parse errors, write/inject gating, no-stdout-pollution and structured `not_available`), plus a standalone subprocess test on the native backend that skips cleanly when the native -simulator is absent. +simulator is absent. Native-backend tools have additional end-to-end tests on +the bundled demo firmware (skipped when it is not built): `step`/`run` budgets, +`sim_cycles` accounting, `sim_regions` metadata and native backend detection. ## 10. Roadmap |