feat(tools): add MCP lazy loading with search/call proxy tools

Introduce MCP lazy mode when >15 MCP tools are available:
- Replace all individual MCP schemas with 2 fixed proxy tools
  - `mcp_tool_search`: regex search MCP tools, returns schema text
  - `mcp_call`: execute any MCP tool by exact name + args
- Inject session hint with MCP tool index (name:description)
- Cache-safe: tool list fixed for entire session lifetime

Update marketplace index to 120 tools. Minor fixes to Mermaid error handling.

Author: JegernOUTT

refact-agent/engine/src/chat/generation.rs

@@ -33,6 +33,7 @@ use crate::chat::trajectory_ops::approx_token_count;
 
 const TOKEN_BUDGET_CADENCE: usize = 6;
 const TOKEN_BUDGET_MARKER: &str = "token_budget_info";
+const MCP_LAZY_INDEX_MARKER: &str = "mcp_lazy_index";
 
 fn maybe_inject_token_budget_instruction(
     session: &mut ChatSession,
@@ -105,6 +106,28 @@ fn maybe_inject_token_budget_instruction(
 
 
 
+fn build_mcp_index_message(index: &[(String, String)], total: usize) -> String {
+    let mut lines = vec![
+        format!(
+            "💿 MCP Tools — Lazy Mode Active ({} tools available). \
+             You MUST call `mcp_tool_search` before using any MCP tool. \
+             Example: mcp_tool_search({{\"query\": \"github.*pull|pr\"}})",
+            total
+        ),
+        String::new(),
+        "Available MCP tools (name: description):".to_string(),
+    ];
+    for (name, desc) in index {
+        let short = if desc.chars().count() > 100 {
+            format!("{}…", desc.chars().take(100).collect::<String>())
+        } else {
+            desc.clone()
+        };
+        lines.push(format!("- {}: {}", name, short));
+    }
+    lines.join("\n")
+}
+
 pub async fn prepare_session_preamble_and_knowledge(
     gcx: Arc<ARwLock<GlobalContext>>,
     session_arc: Arc<AMutex<ChatSession>>,
@@ -121,6 +144,9 @@ pub async fn prepare_session_preamble_and_knowledge(
 
     let needs_preamble = !has_system || (!has_project_context && thread.include_project_info);
 
+    // Populated inside `needs_preamble`; used after to inject the MCP index hint message.
+    let mut mcp_for_index: Option<(Vec<(String, String)>, usize)> = None;
+
     if needs_preamble {
         let caps = match crate::global_context::try_load_caps_quickly_if_not_present(gcx.clone(), 0).await {
             Ok(caps) => caps,
@@ -137,14 +163,16 @@ pub async fn prepare_session_preamble_and_knowledge(
             }
         };
 
-        let tools: Vec<crate::tools::tools_description::ToolDesc> =
+        let raw_tools =
             crate::tools::tools_list::get_tools_for_mode(gcx.clone(), &thread.mode, Some(&model_rec.base.id))
-                .await
-                .into_iter()
-                .map(|tool| tool.tool_description())
-                .collect();
+                .await;
+        let tools_for_mode =
+            crate::tools::tools_list::apply_mcp_lazy_filter(raw_tools);
+        if tools_for_mode.mcp_lazy_mode {
+            mcp_for_index = Some((tools_for_mode.mcp_tool_index.clone(), tools_for_mode.mcp_total_count));
+        }
         let tool_names: std::collections::HashSet<String> =
-            tools.iter().map(|t| t.name.clone()).collect();
+            tools_for_mode.tools.iter().map(|t| t.tool_description().name.clone()).collect();
 
         let meta = ChatMeta {
             chat_id: chat_id.clone(),
@@ -238,6 +266,33 @@ pub async fn prepare_session_preamble_and_knowledge(
         }
     }
 
+    // Inject MCP lazy-mode index hint (once per session, idempotent via marker)
+    if let Some((mcp_index, mcp_total)) = mcp_for_index {
+        let already_has_index = {
+            let session = session_arc.lock().await;
+            session.messages.iter().any(|m| {
+                m.role == "cd_instruction" && m.tool_call_id == MCP_LAZY_INDEX_MARKER
+            })
+        };
+        if !already_has_index {
+            let index_text = build_mcp_index_message(&mcp_index, mcp_total);
+            let mut session = session_arc.lock().await;
+            let insert_pos = session
+                .messages
+                .iter()
+                .position(|m| m.role == "system")
+                .map(|i| i + 1)
+                .unwrap_or(0);
+            session.insert_message(insert_pos, ChatMessage {
+                role: "cd_instruction".to_string(),
+                tool_call_id: MCP_LAZY_INDEX_MARKER.to_string(),
+                content: ChatContent::SimpleText(index_text),
+                ..Default::default()
+            });
+            info!("Injected MCP lazy index hint with {} tools", mcp_total);
+        }
+    }
+
     // Knowledge enrichment for agentic mode
     let last_is_user = {
         let session = session_arc.lock().await;
@@ -600,14 +655,18 @@ pub async fn run_llm_generation(
         .map_err(|e| e.message)?;
     let model_rec = crate::caps::resolve_chat_model(caps.clone(), &thread.model)?;
 
-    let tools: Vec<crate::tools::tools_description::ToolDesc> =
+    let raw_tools_for_gen =
         crate::tools::tools_list::get_tools_for_mode(gcx.clone(), &thread.mode, Some(&model_rec.base.id))
-            .await
-            .into_iter()
-            .map(|tool| tool.tool_description())
-            .collect();
-
-    info!("session generation: model={}, tools count = {}", model_rec.base.id, tools.len());
+            .await;
+    let tools_for_gen =
+        crate::tools::tools_list::apply_mcp_lazy_filter(raw_tools_for_gen);
+    let mcp_lazy_active = tools_for_gen.mcp_lazy_mode;
+    let tools: Vec<crate::tools::tools_description::ToolDesc> = tools_for_gen.tools
+        .into_iter()
+        .map(|tool| tool.tool_description())
+        .collect();
+
+    info!("session generation: model={}, tools count = {} (mcp_lazy={})", model_rec.base.id, tools.len(), mcp_lazy_active);
 
     let model_n_ctx = if model_rec.base.n_ctx > 0 {
         model_rec.base.n_ctx

refact-agent/engine/src/chat/tools.rs

@@ -1083,7 +1083,8 @@ async fn instantiate_tool_for_call(
     model_id: Option<&str>,
     tool_name: &str,
 ) -> Option<Box<dyn crate::tools::tools_description::Tool + Send>> {
-    let tools = crate::tools::tools_list::get_tools_for_mode(gcx, mode_id, model_id).await;
+    let raw_tools = crate::tools::tools_list::get_tools_for_mode(gcx, mode_id, model_id).await;
+    let tools = crate::tools::tools_list::apply_mcp_lazy_filter(raw_tools).tools;
     for tool in tools {
         if tool.tool_description().name == tool_name {
             return Some(tool);
@@ -1319,7 +1320,8 @@ async fn execute_tools_inner(
 ) -> (Vec<ChatMessage>, bool) {
     let max_parallel = limits().max_parallel_tools.max(1);
 
-    let available_tools = crate::tools::tools_list::get_tools_for_mode(gcx.clone(), mode_id, model_id).await;
+    let raw_available_tools = crate::tools::tools_list::get_tools_for_mode(gcx.clone(), mode_id, model_id).await;
+    let available_tools = crate::tools::tools_list::apply_mcp_lazy_filter(raw_available_tools).tools;
 
     let mut tool_allow_parallel: std::collections::HashMap<String, bool> = std::collections::HashMap::new();
     let mut serial_registry: SerialToolRegistry = std::collections::HashMap::new();

refact-agent/engine/src/tools/mod.rs

@@ -31,6 +31,8 @@ mod tool_web;
 mod tool_web_search;
 mod tool_compress_chat;
 mod tool_handoff_to_mode;
+mod tool_mcp_search;
+mod tool_mcp_call;
 
 pub mod file_edit;
 mod tool_create_knowledge;

refact-agent/engine/src/tools/tool_mcp_call.rs

@@ -0,0 +1,109 @@
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use serde_json::{json, Value};
+use tokio::sync::Mutex as AMutex;
+
+use crate::at_commands::at_commands::AtCommandsContext;
+use crate::call_validation::ContextEnum;
+use crate::tools::tools_description::{MatchConfirmDenyResult, Tool, ToolConfig, ToolDesc, ToolGroupCategory, ToolSource, ToolSourceType};
+use crate::tools::tools_list::get_integration_tools;
+
+pub struct ToolMcpCall {}
+
+#[async_trait]
+impl Tool for ToolMcpCall {
+    fn tool_description(&self) -> ToolDesc {
+        ToolDesc {
+            name: "mcp_call".to_string(),
+            experimental: false,
+            allow_parallel: true,
+            description: "Execute any MCP tool by name with the given arguments. \
+                Use `mcp_tool_search` first to discover the tool name and its input schema, \
+                then call this with the exact arguments the schema requires."
+                .to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "tool_name": {
+                        "type": "string",
+                        "description": "Exact MCP tool name as returned by mcp_tool_search"
+                    },
+                    "args": {
+                        "type": "object",
+                        "description": "Arguments object matching the tool's input schema"
+                    }
+                },
+                "required": ["tool_name", "args"]
+            }),
+            output_schema: None,
+            annotations: None,
+            display_name: "MCP Call".to_string(),
+            source: ToolSource {
+                source_type: ToolSourceType::Builtin,
+                config_path: String::new(),
+            },
+        }
+    }
+
+    fn config(&self) -> Result<ToolConfig, String> {
+        Ok(ToolConfig { enabled: true, allow_parallel: None })
+    }
+
+    async fn tool_execute(
+        &mut self,
+        ccx: Arc<AMutex<AtCommandsContext>>,
+        tool_call_id: &String,
+        args: &HashMap<String, Value>,
+    ) -> Result<(bool, Vec<ContextEnum>), String> {
+        let tool_name = args.get("tool_name")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| "mcp_call: missing required argument 'tool_name'".to_string())?
+            .to_string();
+
+        let tool_args: HashMap<String, Value> = args.get("args")
+            .and_then(|v| v.as_object())
+            .map(|obj| obj.iter().map(|(k, v)| (k.clone(), v.clone())).collect())
+            .unwrap_or_default();
+
+        let gcx = ccx.lock().await.global_context.clone();
+        let mut integration_groups = get_integration_tools(gcx).await;
+
+        // Find the named MCP tool and extract it (needs &mut self for tool_execute).
+        let mut found_tool: Option<Box<dyn Tool + Send>> = None;
+        'outer: for group in &mut integration_groups {
+            if !matches!(group.category, ToolGroupCategory::MCP) {
+                continue;
+            }
+            if let Some(pos) = group.tools.iter().position(|t| t.tool_description().name == tool_name) {
+                found_tool = Some(group.tools.remove(pos));
+                break 'outer;
+            }
+        }
+
+        let mut tool = found_tool.ok_or_else(|| {
+            format!(
+                "MCP tool '{}' not found. Use mcp_tool_search to discover available tools.",
+                tool_name
+            )
+        })?;
+
+        let confirm_result = tool.match_against_confirm_deny(ccx.clone(), &tool_args).await
+            .map_err(|e| format!("mcp_call confirmation check failed: {}", e))?;
+        if confirm_result.result == MatchConfirmDenyResult::DENY {
+            return Err(format!(
+                "MCP tool '{}' was denied by rule '{}'",
+                tool_name, confirm_result.rule
+            ));
+        }
+        if confirm_result.result == MatchConfirmDenyResult::CONFIRMATION {
+            return Err(format!(
+                "MCP tool '{}' requires user confirmation (rule '{}'). Use the tool directly instead of via mcp_call to enable the confirmation flow.",
+                tool_name, confirm_result.rule
+            ));
+        }
+
+        tool.tool_execute(ccx, tool_call_id, &tool_args).await
+    }
+}