feat(mcp): add RTT transport for flashed devices and fix stale docs

[tarotene]

Summary

• Add --transport rtt to telepath-mcp-server so it can connect to a flashed nRF52840-DK and expose real firmware commands as MCP tools
• Feature-gate loopback scaffold and RTT implementation behind loopback / rtt Cargo features (both enabled by default)
• Inherit auto-reset-on-RTT-attach-failure and 10 s read-deadline from telepath-shell
• Fix stale Limitations entries and add RTT registration instructions for Claude Code

Background

telepath-mcp-server previously only supported --transport loopback, which ran an in-process TelepathServer using the binary's own linkme registry. CDP frames genuinely crossed the mpsc pair, but the "device" was always the host binary — never flashed firmware. This is structurally identical to the pre-#51 telepath-shell bug where commands were hardcoded rather than queried from the device.

Changes

File	Change
tools/telepath-mcp-server/Cargo.toml	Add loopback / rtt features; telepath-server and probe-rs become optional
tools/telepath-mcp-server/src/rtt_transport.rs	New — verbatim copy of tools/telepath-shell/src/rtt_transport.rs with TODO(#63) noting the temporary duplication
tools/telepath-mcp-server/src/lib.rs	Expose rtt_transport behind #[cfg(feature = "rtt")]
tools/telepath-mcp-server/src/main.rs	Transport enum (clap ValueEnum); RTT args (--chip, --rtt-control-block-addr, --no-reset); loopback scaffold moved into #[cfg(feature = "loopback")] mod loopback; RTT branch
Justfile	Add mcp-run-rtt recipe
AGENTS.md	Add RTT run command
tools/telepath-mcp-server/README.md	Add RTT claude mcp add example with flag table; replace cargo build with cargo build --release; remove stale loopback-only Limitations
docs/mcp-integration.md	Remove RTT and named-arg mapping from Known limitations (both implemented); keep serialport as remaining item
tools/telepath-shell/README.md	Remove stale "Only ping is implemented" Limitations; update REPL example to reflect discovery-driven help output

RTT mode notes

• drain_debug_logs writes to stderr only — stdout is reserved for MCP JSON-RPC
• set_read_deadline(10s) is set before build() and not cleared: RPC calls also time out after 10 s so the MCP client cannot hang indefinitely
• --no-reset disables the auto-reset-and-retry that fires when the RTT control block is not found on first attach

Build matrix verified

cargo build                                      # default features (loopback + rtt)
cargo build --no-default-features --features rtt
cargo build --no-default-features --features loopback
cargo test                                       # all tests pass
just ci                                          # full workspace CI

Test plan

• just ci passes (CI will verify)
• cargo run -- --transport loopback answers MCP tools/list with ping (loopback regression)
• (manual, requires hardware) just firmware-flash → just mcp-run-rtt → drive MCP via stdin: tools/list returns discovered commands, tools/call ping returns 0xDEADBEEF
• (manual) With no probe connected: binary exits with No debug probes found.
• (manual) With probe but firmware not running: RttTransport::new retries once then exits with error on stderr, stdout remains clean MCP JSON

Related

• Closes feat(mcp): add RTT transport branch for flashed devices #64
• Follow-up unification plan: design: unify telepath-shell and telepath-mcp-server into one binary with subcommands #63

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds an RTT-based transport option to telepath-mcp-server so it can attach to a flashed nRF52840-DK via probe-rs, run discovery against real firmware, and expose the discovered Telepath commands as MCP tools (while keeping loopback available and feature-gated).

Changes:

• Introduces --transport rtt (plus RTT-specific CLI flags) and routes MCP server startup through an RTT-backed TelepathClient.
• Feature-gates transport backends (loopback / rtt) and makes telepath-server / probe-rs optional deps accordingly.
• Adds a Just recipe and updates AGENTS.md with the RTT run command.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tools/telepath-mcp-server/Cargo.toml	Adds loopback/rtt features; makes telepath-server and probe-rs optional; enables clap env.
tools/telepath-mcp-server/src/rtt_transport.rs	Adds RTT transport implementation (copied from telepath-shell) implementing Read+Write with deadlines and log drain.
tools/telepath-mcp-server/src/lib.rs	Exposes rtt_transport module behind the rtt feature.
tools/telepath-mcp-server/src/main.rs	Adds Transport enum + RTT CLI args, feature-gated loopback module, and RTT startup branch using probe-rs.
Justfile	Adds mcp-run-rtt helper recipe.
AGENTS.md	Documents running the MCP server in RTT mode.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.