feat(mcp): add config-gated lazy MCP schema loading

[Interstellar-code]

Refs #6839

Summary

This PR adds a narrow, config-gated Phase 1 implementation of lazy MCP schema loading to reduce per-turn tool-schema token overhead for MCP-heavy installs.

Scope in this PR:

• replace full MCP tool schemas with lightweight stubs at request time
• add a meta-tool to promote selected MCP tools to full schemas on demand
• keep promoted-tool state per session
• keep the feature off by default

This PR is intentionally limited to the core lazy-loading loop. It does not include later expansion ideas like server-level discovery, eager server promotion, or broader telemetry/reporting.

Problem

Large MCP installations inject hundreds of full tool schemas into every API call, even when the conversation does not need them. This creates large fixed prompt overhead and can block lower-TPM providers entirely.

Approach

When mcp.lazy_loading is enabled:

• MCP tools are exposed to the model as request-time stubs
• the model can call load_mcp_tools to request full schemas for selected tools
• promoted tools remain full for the rest of the session
• builtin/non-MCP tools remain unchanged

The hook is plugin-based and fail-open:

• transform_tools rewrites the outgoing tool list just before API dispatch
• on any internal failure, the original full tool list is used unchanged

Backward compatibility

• off by default
• no behavior change unless explicitly enabled

Included config keys

• mcp.lazy_loading
• mcp.lazy_stub_max_desc

Not included in this PR

• server discovery / server stub mode
• eager server promotion thresholds
• telemetry/reporting extras
• semantic/RAG preselection

Tests

Ran the narrowed Phase 1 suite:

• tests/plugins/mcp_lazy/test_stubs.py
• tests/plugins/mcp_lazy/test_pool.py
• tests/plugins/mcp_lazy/test_promote_and_hook.py
• tests/hermes_cli/test_config_validation.py

Command:

scripts/run_tests.sh tests/plugins/mcp_lazy/test_stubs.py tests/plugins/mcp_lazy/test_pool.py tests/plugins/mcp_lazy/test_promote_and_hook.py tests/hermes_cli/test_config_validation.py

[teknium1]

Thanks for the focused MCP-heavy-install proposal. This is an automated hermes-sweeper review; current main already ships the requested progressive-disclosure behavior.

• 369075dc95bb998fdf493ef0f97dfa2d19c43d82 added Tool Search before this PR was opened, and it is contained in v2026.6.5.
• model_tools.py:537 conditionally replaces MCP/plugin schemas with tool_search, tool_describe, and tool_call at the configured threshold.
• tools/tool_search.py:632 returns a selected tool's full schema on demand; model_tools.py:1071 dispatches the selected underlying tool with session toolset scope enforcement.
• The linked Feature: Lazy Tool Schema Loading — Two-Pass Tool Injection to Reduce Token Overhead #6839 discussion also records the maintained Tool Search direction.

Closing as implemented on main.