feat: add tool annotations, deferred loading, and pagination to MCP server

[pureugong]

Summary

When running in Full mode with -s all, the MCP server can expose hundreds of tools, overwhelming MCP clients' context windows. This proposal adds three features to address this, following patterns from the MCP spec 2024-11-05.

Changes (implemented)

1. Tool Annotations

Adds readOnlyHint, destructiveHint, idempotentHint annotations to all MCP tools based on HTTP method:

• GET → read-only
• DELETE → destructive mutation
• POST/PUT/PATCH → non-destructive mutation

This helps MCP clients (Claude, ChatGPT, etc.) decide approval behavior automatically.

2. tool_search Meta-tool

A new always-exposed tool that searches the full cached tool catalog by keyword or service name, returning up to 20 matches with full schemas. Enables deferred tool discovery — clients can find and call tools without them being listed in tools/list.

3. --tool-filter / -f CLI Flag

Value	Behavior
"" (default)	All tools exposed (current behavior)
deferred	Only tool_search + gws_discover exposed; full catalog searchable via tool_search
drive,gmail	Only tools from these services + tool_search

4. --page-size Cursor-based Pagination

Slices tools/list responses with base64-encoded cursors. Default 0 = no pagination (backwards compatible).

5. listChanged: true in Initialize

Advertises tool list change capability per MCP spec.

Implementation

All changes are in src/mcp_server.rs with 25 new tests. Full implementation is available on my fork:

Branch: pureugong/cli:feat/mcp-tool-annotations-deferred
PR (on fork): pureugong#1

• cargo clippy -- -D warnings passes clean
• cargo test — all 465 tests pass (39 new)
• cargo fmt --all applied
• Changeset included

I wasn't able to open a PR directly due to collaborator restrictions. Happy to submit a PR if given access, or feel free to cherry-pick from the branch above.