cli: align Rust MCP read catalog (#519)

[willwashburn]

Summary

• Adds burn__summary, burn__hotspots, burn__overhead, burn__overheadTrim, and burn__compare to the Rust burn mcp-server catalog.
• Mirrors the npm MCP schemas and validation semantics, including findings mode, fidelity controls, u32 numeric bounds, and registered-session scoping for summary and hotspots only.
• Keeps every tool as a thin LedgerHandle wrapper and returns SDK JSON unchanged as MCP text and structured content.
• Adds populated fixture-ledger, empty-ledger, malformed-input, recovery, catalog, and real stdio process coverage.
• Documents the full Rust MCP catalog and its session-scoping behavior in the root README.

Deliberate Rust schema difference

The npm overhead tools describe project as a path or key, while Rust OverheadOptions and OverheadTrimOptions accept PathBuf and scan that filesystem root. The Rust MCP schemas therefore describe a project filesystem path only. A ledger project key does not resolve as a key on this surface; it is interpreted as a relative filesystem path and will normally produce an empty scan.

Verification

• cargo test --workspace
• cargo fmt --all -- --check
• cargo clippy -p relayburn-cli --all-targets -- -D warnings
• git diff --check

Fixes#519

🤖 Generated with Claude Code.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2b9d6ffe-be33-43b4-928b-3d7f6a2d40dc

📥 Commits

Reviewing files that changed from the base of the PR and between dfcc041 and c40c92d.

📒 Files selected for processing (2)

• CHANGELOG.md
• README.md

🚧 Files skipped from review as they are similar to previous changes (2)

• README.md
• CHANGELOG.md

Included review availability: Your plan includes up to 1 review per rolling hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The Rust MCP server expands from two to seven read-only tools. It adds validated schemas, shared dispatch and result framing, SDK-backed analytical handlers, session defaults, documentation, and unit, integration, and stdio protocol tests.

Changes

MCP read tool catalog

Layer / File(s)	Summary
Tool catalog and documented scope crates/relayburn-cli/src/commands/mcp_server.rs, crates/relayburn-cli/src/cli.rs, README.md, CHANGELOG.md	The server advertises seven read-only tools with input constraints. CLI documentation describes session defaults and supported tool scopes. The changelog records the expanded catalog.
Dispatch, validation, and result framing crates/relayburn-cli/src/commands/mcp_server.rs	Shared validation and result framing support summary, hotspots, overhead, overhead trimming, and model comparison. Unknown tools return JSON-RPC errors. SDK failures return tool errors.
Analytical tool and edge-case coverage crates/relayburn-cli/src/commands/mcp_server.rs	Tests cover valid results, filtering, default sessions, invalid arguments, numeric normalization, recovery, and empty ledgers.
Stdio protocol integration crates/relayburn-cli/tests/mcp_server.rs	The integration test verifies discovery, malformed calls, unknown-tool errors, one response per request, and continued operation.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk:⚪ Minimal · up to c40c9

The PR adds the Rust MCP read catalog with documented schema and session-scoping behavior, and no actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
participant MCPClient
participant burn_mcp_server
participant relayburn_sdk
participant Ledger
MCPClient->>burn_mcp_server: tools/call with validated tool arguments
burn_mcp_server->>relayburn_sdk: execute summary, hotspots, overhead, trim, or compare query
relayburn_sdk->>Ledger: read ledger data
Ledger-->>relayburn_sdk: query data
relayburn_sdk-->>burn_mcp_server: structured result or error
burn_mcp_server-->>MCPClient: MCP tool result or JSON-RPC error

Loading

Poem

A rabbit reviewed each tool in the run,
Seven read-only paths now hop in the sun.
Schemas check bounds, and errors stay clear,
Ledgers yield answers for every query here.
“Keep sending requests!” says the rabbit with cheer.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the Rust CLI MCP catalog alignment, which is the primary change in the pull request.
Description check	✅ Passed	The description directly explains the added MCP tools, schema parity, tests, documentation, and verification steps.
Linked Issues check	✅ Passed	The changes satisfy issue #519 by expanding the Rust MCP catalog, adding SDK-backed handlers, mirroring validation, and updating module documentation.
Out of Scope Changes check	✅ Passed	The changelog, README, CLI documentation, implementation, and tests all support the linked issue objectives without unrelated changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-519-rust-mcp-parity

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:6c3bb38e51

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cubic-dev-ai]

All reported issues were addressed

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[coderabbitai]

🧹 Nitpick comments (2)

crates/relayburn-cli/src/commands/mcp_server.rs (1)

1017-1085: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider adding a happy-path case for tags and groupByTag.

The fixture test covers session, groupBy, patterns, kind, top, includeDiff, and models. It does not cover a successful tags object or groupByTag. optional_string_record is only exercised by its failure case at Line 1095. A single success assertion would pin the Enrichment mapping.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@crates/relayburn-cli/src/commands/mcp_server.rs` around lines 1017 - 1085,
Extend new_tools_invoke_sdk_verbs_against_fixture_ledger with a successful
hotspots invocation using a valid tags object and groupByTag option, then assert
the response succeeds and reports the expected tag grouping. Ensure this
exercises optional_string_record’s success path and verifies the Enrichment
mapping without changing existing coverage.

crates/relayburn-cli/tests/mcp_server.rs (1)

70-81: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Do not assert JSON object key order.

property_names relies on serde_json::Map iteration order, which changes if serde_json loses the preserve_order feature. Since the MCP tool schema allows any order for these properties, compare the key set instead.

♻️ Proposed order-independent assertion

- let property_names = |tool: &Value| {- tool["inputSchema"]["properties"]- .as_object()- .expect("schema properties")- .keys()- .cloned()- .collect::<Vec<_>>()- };- assert_eq!(- property_names(&tools[2]),- ["session", "project", "since", "tags", "groupByTag"]- );+ let property_names = |tool: &Value| {+ let mut keys = tool["inputSchema"]["properties"]+ .as_object()+ .expect("schema properties")+ .keys()+ .cloned()+ .collect::<Vec<_>>();+ keys.sort();+ keys+ };+ assert_eq!(+ property_names(&tools[2]),+ ["groupByTag", "project", "session", "since", "tags"]+ );

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@crates/relayburn-cli/tests/mcp_server.rs` around lines 70 - 81, Update the
property_names assertion in the MCP server test to compare the returned property
keys as an order-independent set rather than a Vec sequence. Preserve validation
of the exact expected keys while removing reliance on serde_json::Map iteration
order.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@crates/relayburn-cli/src/commands/mcp_server.rs`:
- Around line 1017-1085: Extend
new_tools_invoke_sdk_verbs_against_fixture_ledger with a successful hotspots
invocation using a valid tags object and groupByTag option, then assert the
response succeeds and reports the expected tag grouping. Ensure this exercises
optional_string_record’s success path and verifies the Enrichment mapping
without changing existing coverage.
In `@crates/relayburn-cli/tests/mcp_server.rs`:
- Around line 70-81: Update the property_names assertion in the MCP server test
to compare the returned property keys as an order-independent set rather than a
Vec sequence. Preserve validation of the exact expected keys while removing
reliance on serde_json::Map iteration order.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f7e7c326-9b70-42dc-b9a0-6c1659e7307c

📥 Commits

Reviewing files that changed from the base of the PR and between 5b531d0 and dfcc041.

📒 Files selected for processing (5)

• CHANGELOG.md
• README.md
• crates/relayburn-cli/src/cli.rs
• crates/relayburn-cli/src/commands/mcp_server.rs
• crates/relayburn-cli/tests/mcp_server.rs