windbg-mcp: Instructions file for Codex

Repository Guidelines

Project Structure & Module Organization

windbg-mcp is a Rust MCP server for WinDbg/DbgEng. Core code lives in src/: main.rs selects the process role (supervisor or engine worker) and wires tokio and stdio transport, server.rs defines the MCP tool surface, engine.rs is the supervisor (session registry, worker processes, routing), worker.rs is the child process that owns serialized DbgEng access on a dedicated thread, proto.rs is the protocol between them, and ttd.rs handles Time Travel Debugging discovery and launch logic. Operational documentation is in docs/, agent playbooks are in skills/windbg-debugging/, and PowerShell examples live in examples/. Helper tooling such as IOCTL harness scripts is under tools/. Build output in target/ is generated and should not be committed.

Build, Test, and Development Commands

• cargo fmt --all --check: verify Rust formatting as CI does.
• cargo clippy --all-targets -- -D warnings: run lint checks for library, binary, and tests, as CI does — a warning fails the build there.
• cargo test: run the unit tests, including parser and tool-schema coverage in src/server.rs and src/ttd.rs.
• cargo build --release: build the Windows release binary at target/release/windbg-mcp.exe.

For local iteration while an MCP client may have the release executable locked, prefer cargo test or debug builds. See .claude/CLAUDE.md before replacing a running release binary.

Coding Style & Naming Conventions

Use Rust 2024 idioms and rustfmt defaults. Keep DbgEng access inside the worker process and on its engine thread; do not add ad hoc cross-thread or cross-process calls. The supervisor must never touch a DebugEngine.

The rule's constraint is one debuggee session per process, every call on the thread that made it, and no engine in the process that serves MCP — and there is now a third process that meets all three without being a worker. --sk-inspect --symbols (src/sksym.rs, FOLLOWUPS.md item 103 gate S2) opens securekernel.exe as an image target to read its symbols: one target, and that target is a file, with no process behind it to resume, detach or kill. That role speaks no MCP, holds no session registry, has no clients, and returns from main before a tokio runtime exists, so there is no server for a wedged engine to take down and no other session to protect — which is what the worker boundary buys. Review raised this as a P1 on #399 against the prose above, correctly: the sentence said worker or nothing and this is neither. Two files may construct a DebugEngine and sksym::tests::only_the_worker_and_this_module_build_an_engine fails if a third does, so the next one is a decision taken deliberately rather than a review finding. Mentioning the type is not constructing it: the worker's analysis modules take &DebugEngine throughout and always have.