fix(mcp): split invoke_tool into read/write/destructive dispatchers

[pcfreak30]

Replaces the single invoke_tool meta-tool with three typed invokers — invoke_read_tool, invoke_write_tool, invoke_destructive_tool — each admitting exactly one safety class and carrying matching tool annotations (read-only; mutating/open-world; destructive/open-world).

search_tools and describe_tool are unchanged, and describe_tool now names the dispatcher for each tool (invokeTool field); server instructions and guides direct agents to route by it. Each dispatcher enforces its safety class server-side and refuses out-of-class tools with a pointer to the right one.

The split satisfies directory rules that reject one dispatcher mixing safe and unsafe operations and require annotations to match real capabilities.

---

Summary

This PR replaces the single invoke_tool MCP meta-tool with three typed invoke dispatchers split by safety class: invoke_read_tool, invoke_write_tool, and invoke_destructive_tool.

Key changes

Typed invoke dispatchers

• Replaced invoke_tool with three safety-class-specific tools:
  • invoke_read_tool — for read-only operations (marks readOnlyHint=true)
  • invoke_write_tool — for state-mutating operations (marks openWorldHint=true)
  • invoke_destructive_tool — for destructive/irreversible operations (marks destructiveHint=true, openWorldHint=true)
• Each dispatcher rejects out-of-class tools with an error message pointing to the correct dispatcher, ensuring no single MCP tool straddles the safe/unsafe boundary that platform directory validators reject.

Routing improvements

• describe_tool now returns an invokeTool field in ToolDetail naming the correct dispatcher for each tool, so agents never guess which dispatcher to call.
• Added classifyEntry() to map a catalog entry's platform hints (destructive/readOnly/openWorld) to a safety class. Entries that are read-only but also declare openWorld are conservatively routed to the write dispatcher since the read contract would be contradictory.

Documentation & test updates

• Updated all documentation (README, AGENTS.md, architecture docs, adapter instructions) to reference the new typed dispatchers.
• Updated E2E test helpers to resolve the correct dispatcher via describe_tool's invokeTool field, with a cache to avoid repeated lookups.
• Added TestOfficialInvokeClassGate to lock the split: each dispatcher admits only its own class and refuses the rest.
• Updated server card metadata, MCP instructions, and wire annotation tests to reflect the new tool names and truthfully split safety hints.

This change makes the MCP tool surface's safety annotations truthful for platform directory validation while preserving the progressive-disclosure discovery workflow.

[github-actions]

Code Coverage Report

Total Coverage: 50.1%

Generated from commit: 1fc557e
Repository: LumeWeb/pinner-cli

[kody-ai]

Kody Review Complete

Great news! 🎉
No issues were found that match your current review configurations.

Keep up the excellent work! 🚀

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

• Validate Business Logic: Ask Kody to validate your code against business rules by adding a comment with the @kody -v business-logic command.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

​