Skip to content

refactor(mcp): consolidate position params and centralize tool annotations - #319

Merged
bug-ops merged 2 commits into
mainfrom
mcp-tool-dispatch-dedup
Aug 5, 2026
Merged

refactor(mcp): consolidate position params and centralize tool annotations#319
bug-ops merged 2 commits into
mainfrom
mcp-tool-dispatch-dedup

Conversation

@bug-ops

@bug-ops bug-ops commented Aug 5, 2026

Copy link
Copy Markdown
Owner

Summary

  • Collapse six byte-identical position-only param wrapper structs (HoverParams, DefinitionParams, SignatureHelpParams, GoToImplementationParams, GoToTypeDefinitionParams, CallHierarchyPrepareParams) in mcp/tools.rs into direct use of PositionParams. rmcp's schema validation already strips the top-level title/description these wrappers carried before it reaches an MCP client, so the six contributed nothing beyond PositionParams itself.
  • Replace the identical annotations(...) block repeated on all 20 #[tool(...)] handlers in mcp/server.rs with a single central pass in McplsServer::tool_router(), and collapse the redundant let result = { ... }; to_tool_result(result) pattern in 19 of 20 handlers to a single expression.
  • A golden-snapshot test (tool_surface.json, captured from unmodified code) proves the client-visible tool surface (names, descriptions, titles, annotations for all 20 tools) is byte-identical before and after this refactor.

Closes #301, closes #302.

Design note

An earlier draft of this refactor proposed a macro_rules!-generated #[tool_router] block to also dedup the per-tool destructure/call/wrap boilerplate. That approach was withdrawn after adversarial review found a simpler mechanism (a ~10-line central annotations pass over the already-pub ToolRouter::map) achieves the same deduplication without introducing project-specific macro machinery, an unformattable hand-aligned table, or macro-hygiene footguns — consistent with this project's MVP/no-premature-abstraction convention. Note that neither approach closes #301's stated line/character argument-swap risk; that would require newtypes on the Translator::handle_* signatures, tracked as a separate follow-up.

Breaking change

mcpls_core::mcp::{HoverParams, DefinitionParams, CallHierarchyPrepareParams} are removed. Use mcpls_core::mcp::PositionParams directly. No deprecation shim, per this project's pre-1.0 policy.

Test plan

  • cargo +nightly fmt --all -- --check
  • cargo clippy --all-targets --all-features --workspace -- -D warnings
  • cargo nextest run --workspace --all-features --lib --bins (643 passed, 1 intentionally skipped)
  • RUSTFLAGS="-D warnings" RUSTDOCFLAGS="--deny rustdoc::broken_intra_doc_links" cargo doc --no-deps --all-features
  • Golden-snapshot test (test_tool_surface_matches_golden_snapshot) confirms zero client-visible change to the 20-tool MCP surface
  • Independently re-verified against vendored rmcp-3.0.0/rmcp-macros-3.0.0 source (not just developer self-report) during review

@github-actions github-actions Bot added documentation Improvements or additions to documentation rust Rust code changes mcpls-core mcpls-core crate changes labels Aug 5, 2026
@bug-ops
bug-ops enabled auto-merge (squash) August 5, 2026 01:34
bug-ops added 2 commits August 5, 2026 03:37
…ations

Collapse six byte-identical position-only param wrapper structs
(HoverParams, DefinitionParams, SignatureHelpParams,
GoToImplementationParams, GoToTypeDefinitionParams,
CallHierarchyPrepareParams) in mcp/tools.rs into direct use of
PositionParams. rmcp's schema validation already strips the top-level
title/description these wrappers carried before it reaches an MCP
client, so the six were structurally identical to PositionParams and
contributed nothing.

Replace the identical annotations(...) block repeated on all 20
#[tool(...)] handlers in mcp/server.rs with a single central pass:
retag the impl block #[tool_router(router = declared_tool_router)]
and fill in any route missing annotations via
McplsServer::tool_router(). Also collapse the redundant
`let result = { ... }; to_tool_result(result)` pattern in 19 of the
20 handlers down to a single to_tool_result(...) expression.

A golden-snapshot test (tool_surface.json, captured from
unmodified code) proves the client-visible tool surface -
names, descriptions, titles, and annotations for all 20 tools -
is byte-identical before and after this refactor.

BREAKING CHANGE: mcpls_core::mcp::{HoverParams, DefinitionParams,
CallHierarchyPrepareParams} are removed. Use
mcpls_core::mcp::PositionParams directly. No deprecation shim,
per pre-1.0 policy.

Closes #301, #302
@bug-ops
bug-ops force-pushed the mcp-tool-dispatch-dedup branch from a38c068 to 766dba3 Compare August 5, 2026 01:37
@bug-ops
bug-ops merged commit 4448537 into main Aug 5, 2026
28 checks passed
@bug-ops
bug-ops deleted the mcp-tool-dispatch-dedup branch August 5, 2026 01:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation mcpls-core mcpls-core crate changes rust Rust code changes

Projects

None yet

1 participant