instrument-ionwake-server

name	instrument-ionwake-server
description	Instrument the running Ionwake game server over its MCP control surface (server id `ionwake`, `mcp__ionwake__*` tools served at `/mcp` on the game port, default `127.0.0.1:8080`, behind HTTP Basic auth).

The Ionwake Rust server (crates/server) hosts an in-process MCP server so an agent can instrument it from outside, without restarts or source patches. It is served at /mcp on the game port (default 127.0.0.1:8080), guarded by HTTP Basic auth (IONWAKE_ADMIN_USER / IONWAKE_ADMIN_PASSWORD, default admin/admin). It is registered for Claude Code by the project-scoped .mcp.json at the repo root (server id ionwake, HTTP transport, http://127.0.0.1:8080/mcp, with the matching Authorization header), so the tools surface as mcp__ionwake__<tool>.

This is the agent half of one shared command set; the human half is the ionwake repl console (below), which speaks to the same admin MCP.

Tools (network-condition simulation)

Tool	Params	Effect
mcp__ionwake__net-get	map?	Read a map's current conditions.
mcp__ionwake__net-set	latency_ms?, jitter_ms?, loss?, map?	Set conditions; omitted fields stay unchanged.
mcp__ionwake__net-reset	map?	Restore perfect: no latency, jitter, or loss.

• latency_ms / jitter_ms: non-negative integer milliseconds. loss: per-message drop probability in 0.0..=1.0 (clamped). map: the map id, defaults to 0 (the default map).
• A change is per-world and live: it applies symmetrically to both legs and to every current and future player on the map. Already-buffered packets keep their release times (no retroactive reschedule), so only traffic offered after the change uses the new conditions.
• Each tool returns structured content { map, latency_ms, jitter_ms, loss } (what you read) plus a one-line human summary.
• The set is schema-driven and will grow. Don't hardcode it — read the live tools/list so new tools appear automatically.

Prerequisites: the server must be running

The admin MCP exists only while the server runs. Per AGENTS.md, assume the server is already running and restarts on changes (via mise dev:server's watcher), so do not start or restart it in the background. If the mcp__ionwake__* tools are unavailable (or tools/list is empty), the server is down; ask the user to start it with mise dev:server.

Run (agent path): call the MCP tools

Typical feel-testing loop while validating the netcode under adverse conditions:

1. mcp__ionwake__net-get — read the current state (the server boots perfect).
2. mcp__ionwake__net-set with e.g. { "latency_ms": 120, "jitter_ms": 20, "loss": 0.1 } — dial in adverse conditions. Partial: send only the knobs you want to change.
3. Observe behavior (e.g., via the instrument-ionwake-browser skill on /play).
4. mcp__ionwake__net-reset — restore perfect when done.

Target a non-default map by adding "map": <id>; an unknown map returns MCP error -32602.

Run (human path): the ionwake repl console

The same binary has a repl subcommand: an interactive MCP client over the same /mcp endpoint, exposing the identical commands as tool key=value lines. Ask the user to run it themselves (e.g., type ! ionwake repl, or in a terminal cargo run -p server -- repl). With no argument it connects to 127.0.0.1:<IONWAKE_PORT>/mcp (default :8080); pass a URL to target a remote server (ionwake repl http://host:port/mcp). Either way it authenticates with the same IONWAKE_ADMIN_USER / IONWAKE_ADMIN_PASSWORD credentials.

Example session:

> net-get
map 0: latency 0 ms, jitter 0 ms, loss 0.000
> net-set latency_ms=120 loss=0.1
map 0: latency 120 ms, jitter 20 ms, loss 0.100
> help            # list commands;  help net-set  shows a tool's parameters
> quit            # or Ctrl-D

References

• docs/session.md → "Attach and Detach" (WorldRequest::Control, the actor-model plumbing).
• crates/server/src/control.rs — the canonical command registry (#[tool] methods).
• crates/server/src/repl.rs — the console client.