lollms-client 0.19.9__py3-none-any.whl → 0.20.0__py3-none-any.whl

examples/external_mcp.py

@@ -0,0 +1,267 @@
+# File: run_lollms_client_with_mcp_example.py
+
+import sys
+import os
+import shutil
+from pathlib import Path
+import json
+import subprocess
+from dotenv import load_dotenv # Import the function
+
+# --- Load environment variables from .env file ---
+# Load from .env in the current script's directory, or from project root if specified
+# You can specify a path: load_dotenv(dotenv_path=Path('.') / '.env')
+# By default, it looks for .env in the current working directory or parent directories.
+# For simplicity, let's assume .env is next to this script or in a discoverable location.
+load_dotenv()
+
+# --- Python Path Adjustment (same as before) ---
+current_script_dir = Path(__file__).resolve().parent
+project_root_for_lollms_client = current_script_dir.parent
+if str(project_root_for_lollms_client) not in sys.path:
+    sys.path.insert(0, str(project_root_for_lollms_client))
+    print(f"Added to sys.path: {project_root_for_lollms_client}")
+
+# --- Pipmaster and LollmsClient Core Imports (same as before) ---
+try:
+    import pipmaster as pm
+except ImportError:
+    print("ERROR: pipmaster is not installed or not in PYTHONPATH.")
+    sys.exit(1)
+
+try:
+    from lollms_client import LollmsClient
+    from lollms_client.lollms_llm_binding import LollmsLLMBinding
+    from ascii_colors import ASCIIColors, trace_exception
+    from lollms_client.lollms_types import MSG_TYPE
+except ImportError as e:
+    print(f"ERROR: Could not import LollmsClient components: {e}")
+    trace_exception(e)
+    sys.exit(1)
+
+
+# --- Dummy Server Scripts (Time and Calculator - same as before) ---
+TIME_SERVER_PY = """
+import asyncio
+from datetime import datetime
+from mcp.server.fastmcp import FastMCP
+
+mcp_server = FastMCP("TimeMCP", description="A server that provides the current time.")
+
+@mcp_server.tool(description="Returns the current server time and echoes received parameters.")
+def get_current_time(user_id: str = "unknown_user") -> dict:
+    return {"time": datetime.now().isoformat(), "params_received": {"user_id": user_id}, "server_name": "TimeServer"}
+
+if __name__ == "__main__":
+    mcp_server.run(transport="stdio")
+"""
+
+CALCULATOR_SERVER_PY = """
+import asyncio
+from typing import List, Union
+from mcp.server.fastmcp import FastMCP
+
+mcp_server = FastMCP("CalculatorMCP", description="A server that performs addition.")
+
+@mcp_server.tool(description="Adds a list of numbers provided in the 'numbers' parameter.")
+def add_numbers(numbers: List[Union[int, float]]) -> dict:
+    if not isinstance(numbers, list) or not all(isinstance(x, (int, float)) for x in numbers):
+        return {"error": "'numbers' must be a list of numbers."}
+    return {"sum": sum(numbers), "server_name": "CalculatorServer"}
+
+if __name__ == "__main__":
+    mcp_server.run(transport="stdio")
+"""
+
+# --- Main Function ---
+def main():
+    ASCIIColors.red("--- Example: Using LollmsClient with StandardMCPBinding (including external ElevenLabs MCP) ---")
+
+    # --- 1. Setup Temporary Directory for Dummy MCP Servers ---
+    example_base_dir = Path(__file__).parent / "temp_mcp_example_servers"
+    if example_base_dir.exists():
+        shutil.rmtree(example_base_dir)
+    example_base_dir.mkdir(exist_ok=True)
+
+    time_server_script_path = example_base_dir / "time_server.py"
+    with open(time_server_script_path, "w") as f: f.write(TIME_SERVER_PY)
+
+    calculator_server_script_path = example_base_dir / "calculator_server.py"
+    with open(calculator_server_script_path, "w") as f: f.write(CALCULATOR_SERVER_PY)
+
+    # --- 2. MCP Configuration ---
+    initial_mcp_servers = {
+        "time_machine": {
+            "command": [sys.executable, str(time_server_script_path.resolve())],
+        },
+        "calc_unit": {
+            "command": [sys.executable, str(calculator_server_script_path.resolve())]
+        }
+    }
+
+    # --- Configuration for ElevenLabs MCP Server (Optional) ---
+    # Variables are now loaded from .env by load_dotenv() at the start of the script
+    elevenlabs_api_key = os.getenv("ELEVENLABS_API_KEY")
+    elevenlabs_voice_id_from_env = os.getenv("ELEVENLABS_VOICE_ID", "Rachel") # Default if not in .env
+    elevenlabs_model_id_from_env = os.getenv("ELEVENLABS_MODEL_ID", "eleven_multilingual_v2") # Default
+
+    uvx_available = False
+    try:
+        subprocess.run(["uvx", "--version"], capture_output=True, check=True, text=True, timeout=5)
+        uvx_available = True
+        ASCIIColors.green("uvx command is available.")
+    except (FileNotFoundError, subprocess.CalledProcessError, subprocess.TimeoutExpired):
+        ASCIIColors.yellow("uvx command not found, not working, or timed out. ElevenLabs MCP server (via uvx) will not be configured.")
+
+    if elevenlabs_api_key and uvx_available:
+        ASCIIColors.green("ELEVENLABS_API_KEY found (from .env) and uvx available. Configuring ElevenLabs MCP server.")
+        initial_mcp_servers["elevenlabs"] = {
+            "command": ["uvx"],
+            "args": ["elevenlabs-mcp-server"],
+            "env": {
+                "ELEVENLABS_API_KEY": elevenlabs_api_key,
+                "ELEVENLABS_VOICE_ID": elevenlabs_voice_id_from_env,
+                "ELEVENLABS_MODEL_ID": elevenlabs_model_id_from_env,
+                "ELEVENLABS_OUTPUT_DIR": str(example_base_dir / "elevenlabs_output")
+                # Add other ELEVENLABS_ env vars from os.getenv() if needed
+            }
+        }
+        (example_base_dir / "elevenlabs_output").mkdir(exist_ok=True)
+    elif not elevenlabs_api_key:
+        ASCIIColors.yellow("ELEVENLABS_API_KEY not found in .env file or environment variables. Skipping ElevenLabs MCP server configuration.")
+    
+    mcp_config = {"initial_servers": initial_mcp_servers}
+
+    # --- 3. Initialize LollmsClient ---
+    ASCIIColors.magenta("\n1. Initializing LollmsClient...")
+    try:
+        client = LollmsClient(
+            binding_name="ollama",
+            model_name="mistral-nemo:latest",
+            mcp_binding_name="standard_mcp",
+            mcp_binding_config=mcp_config,
+        )
+    except Exception as e:
+        ASCIIColors.error(f"Failed to initialize LollmsClient: {e}")
+        trace_exception(e)
+        shutil.rmtree(example_base_dir, ignore_errors=True)
+        sys.exit(1)
+
+    if not client.binding:
+        ASCIIColors.error("LollmsClient's LLM binding (ollama) failed to load.")
+        shutil.rmtree(example_base_dir, ignore_errors=True)
+        sys.exit(1)
+    if not client.mcp:
+        ASCIIColors.error("LollmsClient's MCP binding (standard_mcp) failed to load.")
+        if hasattr(client, 'close'): client.close()
+        shutil.rmtree(example_base_dir, ignore_errors=True)
+        sys.exit(1)
+    ASCIIColors.green("LollmsClient initialized successfully.")
+
+
+    # --- 4. Define Streaming Callback (same as before) ---
+    def mcp_streaming_callback(chunk: str, msg_type: MSG_TYPE, metadata: dict = None, history: list = None) -> bool:
+        if metadata:
+            type_info = metadata.get('type', 'unknown_type')
+            if msg_type == MSG_TYPE.MSG_TYPE_STEP_START: ASCIIColors.cyan(f"MCP Step Start ({type_info}): {chunk}")
+            elif msg_type == MSG_TYPE.MSG_TYPE_STEP_END: ASCIIColors.cyan(f"MCP Step End ({type_info}): {chunk}")
+            elif msg_type == MSG_TYPE.MSG_TYPE_INFO: ASCIIColors.yellow(f"MCP Info ({type_info}): {chunk}")
+            elif msg_type == MSG_TYPE.MSG_TYPE_CHUNK: ASCIIColors.green(chunk, end="")
+            else: ASCIIColors.green(f"MCP Output ({str(msg_type)}, {type_info}): {chunk}")
+        else:
+             if msg_type == MSG_TYPE.MSG_TYPE_CHUNK: ASCIIColors.green(chunk, end="")
+             else: ASCIIColors.green(f"MCP Output ({str(msg_type)}): {chunk}")
+        sys.stdout.flush()
+        return True
+
+    # --- 5. Use generate_with_mcp with local dummy servers ---
+    ASCIIColors.magenta("\n2. Calling generate_with_mcp to get current time (local dummy server)...")
+    time_prompt = "Hey assistant, what time is it right now?"
+    time_response = client.generate_with_mcp(
+        prompt=time_prompt,
+        streaming_callback=mcp_streaming_callback
+    )
+    print() 
+    ASCIIColors.blue(f"Final response for time prompt: {json.dumps(time_response, indent=2)}")
+    assert time_response.get("error") is None, f"Time prompt error: {time_response.get('error')}"
+    assert time_response.get("final_answer"), "Time prompt no final answer."
+    assert len(time_response.get("tool_calls", [])) > 0, "Time prompt should call tool."
+    if time_response.get("tool_calls"):
+        assert time_response["tool_calls"][0]["name"] == "time_machine::get_current_time", "Incorrect tool for time."
+        assert "time" in time_response["tool_calls"][0].get("result", {}).get("output", {}), "Time tool result missing time."
+
+    ASCIIColors.magenta("\n3. Calling generate_with_mcp for calculation (local dummy server)...")
+    calc_prompt = "Can you sum 50, 25, and 7.5 for me?"
+    calc_response = client.generate_with_mcp(
+        prompt=calc_prompt,
+        streaming_callback=mcp_streaming_callback
+    )
+    print()
+    ASCIIColors.blue(f"Final response for calc prompt: {json.dumps(calc_response, indent=2)}")
+    assert calc_response.get("error") is None, f"Calc prompt error: {calc_response.get('error')}"
+    assert calc_response.get("final_answer"), "Calc prompt no final answer."
+    assert len(calc_response.get("tool_calls", [])) > 0, "Calc prompt should call tool."
+    if calc_response.get("tool_calls"):
+        assert calc_response["tool_calls"][0]["name"] == "calc_unit::add_numbers", "Incorrect tool for calc."
+        assert "sum" in calc_response["tool_calls"][0].get("result", {}).get("output", {}), "Calculator tool result missing sum."
+
+
+    # --- 6. Interact with ElevenLabs MCP Server (if configured) ---
+    if "elevenlabs" in client.mcp.get_binding_config().get("initial_servers", {}):
+        ASCIIColors.magenta("\n4. Interacting with ElevenLabs MCP server...")
+
+        ASCIIColors.info("Discovering all available tools (including ElevenLabs)...")
+        all_mcp_tools = client.mcp.discover_tools(force_refresh=True, timeout_per_server=45) # Longer timeout for external server
+        ASCIIColors.green(f"Discovered {len(all_mcp_tools)} tools in total:")
+        for tool in all_mcp_tools:
+            # Try to get properties keys from input_schema for a more informative print
+            props_keys = "N/A"
+            if isinstance(tool.get('input_schema'), dict) and isinstance(tool['input_schema'].get('properties'), dict):
+                props_keys = list(tool['input_schema']['properties'].keys())
+            print(f"  - Name: {tool.get('name')}, Desc: {tool.get('description')}, Schema Props: {props_keys}")
+
+
+        elevenlabs_list_voices_tool_name = "elevenlabs::list_voices"
+        if any(t['name'] == elevenlabs_list_voices_tool_name for t in all_mcp_tools):
+            ASCIIColors.magenta(f"\n4a. Calling '{elevenlabs_list_voices_tool_name}' via LLM prompt...")
+            
+            list_voices_prompt = "Please list all the available voices from the elevenlabs tool."
+            voices_response = client.generate_with_mcp(
+                prompt=list_voices_prompt,
+                streaming_callback=mcp_streaming_callback,
+                max_tool_calls=1 
+            )
+            print()
+            ASCIIColors.blue(f"Final response for ElevenLabs list_voices prompt: {json.dumps(voices_response, indent=2)}")
+
+            assert voices_response.get("error") is None, f"ElevenLabs list_voices error: {voices_response.get('error')}"
+            assert voices_response.get("final_answer"), "ElevenLabs list_voices no final answer."
+            tool_calls = voices_response.get("tool_calls", [])
+            assert len(tool_calls) > 0, "ElevenLabs list_voices should call tool."
+            if tool_calls:
+                assert tool_calls[0]["name"] == elevenlabs_list_voices_tool_name, "Incorrect tool for ElevenLabs list_voices."
+                tool_output = tool_calls[0].get("result", {}).get("output")
+                assert isinstance(tool_output, list), f"ElevenLabs list_voices output not a list, got: {type(tool_output)}"
+                if tool_output:
+                     ASCIIColors.green(f"First voice from ElevenLabs: {tool_output[0].get('name')} (ID: {tool_output[0].get('voice_id')})")
+        else:
+            ASCIIColors.yellow(f"Tool '{elevenlabs_list_voices_tool_name}' not found. Skipping ElevenLabs tool execution test.")
+    else:
+        ASCIIColors.yellow("ElevenLabs MCP server not configured in this run (check .env for API key and uvx availability). Skipping ElevenLabs tests.")
+
+    # --- 7. Cleanup ---
+    ASCIIColors.magenta("\n5. Closing LollmsClient and cleaning up...")
+    if client and hasattr(client, 'close'):
+        try:
+            client.close()
+        except Exception as e:
+            ASCIIColors.error(f"Error closing LollmsClient: {e}")
+            trace_exception(e)
+
+    ASCIIColors.info("Cleaning up temporary server scripts directory...")
+    shutil.rmtree(example_base_dir, ignore_errors=True)
+
+    ASCIIColors.red("\n--- LollmsClient with MCP Example (including external) Finished ---")
+
+if __name__ == "__main__":
+    main()

examples/run_standard_mcp_example.py

@@ -0,0 +1,204 @@
+# File: run_lollms_client_with_mcp_example.py
+
+import sys
+import os
+import shutil
+from pathlib import Path
+import json
+from lollms_client import LollmsClient
+# --- Dynamically adjust Python path to find lollms_client ---
+# This assumes the example script is in a directory, and 'lollms_client' is
+# in a sibling directory or a known relative path. Adjust as needed.
+# For example, if script is in 'lollms_client/examples/' and lollms_client code is in 'lollms_client/'
+# then the parent of the script's parent is the project root.
+
+# Get the directory of the current script
+current_script_dir = Path(__file__).resolve().parent
+
+# Option 1: If lollms_client is in the parent directory of this script's directory
+# (e.g. script is in 'project_root/examples' and lollms_client is in 'project_root/lollms_client')
+# project_root = current_script_dir.parent
+# lollms_client_path = project_root / "lollms_client" # Assuming this is where lollms_client.py and bindings are
+
+# Option 2: If lollms_client package is directly one level up
+# (e.g. script is in 'lollms_client/examples' and lollms_client package is 'lollms_client')
+project_root_for_lollms_client = current_script_dir.parent
+if str(project_root_for_lollms_client) not in sys.path:
+    sys.path.insert(0, str(project_root_for_lollms_client))
+    print(f"Added to sys.path: {project_root_for_lollms_client}")
+
+
+# --- Ensure pipmaster is available (core LoLLMs dependency) ---
+try:
+    import pipmaster as pm
+except ImportError:
+    print("ERROR: pipmaster is not installed or not in PYTHONPATH.")
+    sys.exit(1)
+
+# --- Import LollmsClient and supporting components ---
+try:
+
+    from lollms_client.lollms_llm_binding import LollmsLLMBinding # Base for LLM
+    from ascii_colors import ASCIIColors, trace_exception
+    from lollms_client.lollms_types import MSG_TYPE # Assuming MSG_TYPE is here
+except ImportError as e:
+    print(f"ERROR: Could not import LollmsClient components: {e}")
+    print("Ensure 'lollms_client' package structure is correct and accessible via PYTHONPATH.")
+    print(f"Current sys.path: {sys.path}")
+    trace_exception(e)
+    sys.exit(1)
+
+
+# --- Dummy Server Scripts using FastMCP (as per previous successful iteration) ---
+TIME_SERVER_PY = """
+import asyncio
+from datetime import datetime
+from mcp.server.fastmcp import FastMCP
+
+mcp_server = FastMCP("TimeMCP", description="A server that provides the current time.")
+
+@mcp_server.tool(description="Returns the current server time and echoes received parameters.")
+def get_current_time(user_id: str = "unknown_user") -> dict:
+    return {"time": datetime.now().isoformat(), "params_received": {"user_id": user_id}, "server_name": "TimeServer"}
+
+if __name__ == "__main__":
+    mcp_server.run(transport="stdio")
+"""
+
+CALCULATOR_SERVER_PY = """
+import asyncio
+from typing import List, Union
+from mcp.server.fastmcp import FastMCP
+
+mcp_server = FastMCP("CalculatorMCP", description="A server that performs addition.")
+
+@mcp_server.tool(description="Adds a list of numbers provided in the 'numbers' parameter.")
+def add_numbers(numbers: List[Union[int, float]]) -> dict:
+    if not isinstance(numbers, list) or not all(isinstance(x, (int, float)) for x in numbers):
+        return {"error": "'numbers' must be a list of numbers."}
+    return {"sum": sum(numbers), "server_name": "CalculatorServer"}
+
+if __name__ == "__main__":
+    mcp_server.run(transport="stdio")
+"""
+
+
+def main():
+    ASCIIColors.red("--- Example: Using LollmsClient with StandardMCPBinding ---")
+
+    # --- 1. Setup Temporary Directory for Dummy MCP Servers ---
+    example_base_dir = Path(__file__).parent / "temp_mcp_example_servers"
+    if example_base_dir.exists():
+        shutil.rmtree(example_base_dir)
+    example_base_dir.mkdir(exist_ok=True)
+
+    time_server_script_path = example_base_dir / "time_server.py"
+    with open(time_server_script_path, "w") as f: f.write(TIME_SERVER_PY)
+
+    calculator_server_script_path = example_base_dir / "calculator_server.py"
+    with open(calculator_server_script_path, "w") as f: f.write(CALCULATOR_SERVER_PY)
+
+    # MCP Binding Configuration (for StandardMCPBinding)
+    mcp_config = {
+        "initial_servers": {
+            "time_machine": {
+                "command": [sys.executable, str(time_server_script_path.resolve())],
+            },
+            "calc_unit": {
+                "command": [sys.executable, str(calculator_server_script_path.resolve())]
+            }
+        }
+    }
+    ASCIIColors.magenta("\n1. Initializing LollmsClient...")
+    try:
+        client = LollmsClient(
+            binding_name="ollama", # Use the dummy LLM binding
+            model_name="mistral-nemo:latest",
+            mcp_binding_name="standard_mcp",
+            mcp_binding_config=mcp_config,
+        )
+    except Exception as e:
+        ASCIIColors.error(f"Failed to initialize LollmsClient: {e}")
+        trace_exception(e)
+        shutil.rmtree(example_base_dir)
+        sys.exit(1)
+
+    if not client.binding:
+        ASCIIColors.error("LollmsClient's LLM binding (dummy_llm) failed to load.")
+        shutil.rmtree(example_base_dir)
+        sys.exit(1)
+    if not client.mcp:
+        ASCIIColors.error("LollmsClient's MCP binding (standard_mcp) failed to load.")
+        client.close() # Close LLM binding if it loaded
+        shutil.rmtree(example_base_dir)
+        sys.exit(1)
+
+    ASCIIColors.green("LollmsClient initialized successfully with DummyLLM and StandardMCP bindings.")
+
+    # --- 3. Define a streaming callback for generate_with_mcp ---
+    def mcp_streaming_callback(chunk: str, msg_type: MSG_TYPE, metadata: dict = None, history: list = None) -> bool:
+        if metadata:
+            type_info = metadata.get('type', 'unknown_type')
+            if msg_type == MSG_TYPE.MSG_TYPE_STEP_START:
+                ASCIIColors.cyan(f"MCP Step Start ({type_info}): {chunk}")
+            elif msg_type == MSG_TYPE.MSG_TYPE_STEP_END:
+                ASCIIColors.cyan(f"MCP Step End ({type_info}): {chunk}")
+            elif msg_type == MSG_TYPE.MSG_TYPE_INFO:
+                ASCIIColors.yellow(f"MCP Info ({type_info}): {chunk}")
+            elif msg_type == MSG_TYPE.MSG_TYPE_CHUNK: # Part of final answer typically
+                ASCIIColors.green(chunk, end="") # type: ignore
+            else: # FULL, default, etc.
+                ASCIIColors.green(f"MCP Output ({str(msg_type)}, {type_info}): {chunk}")
+        else:
+             if msg_type == MSG_TYPE.MSG_TYPE_CHUNK:
+                ASCIIColors.green(chunk, end="") # type: ignore
+             else:
+                ASCIIColors.green(f"MCP Output ({str(msg_type)}): {chunk}")
+        sys.stdout.flush()
+        return True # Continue streaming
+
+    # --- 4. Use generate_with_mcp ---
+    ASCIIColors.magenta("\n2. Calling generate_with_mcp to get current time...")
+    time_prompt = "Hey assistant, what time is it right now?"
+    time_response = client.generate_with_mcp(
+        prompt=time_prompt,
+        streaming_callback=mcp_streaming_callback,
+        interactive_tool_execution=False # Set to True to test interactive mode
+    )
+    print() # Newline after streaming
+    ASCIIColors.blue(f"Final response for time prompt: {json.dumps(time_response, indent=2)}")
+
+    assert time_response.get("error") is None, f"Time prompt resulted in an error: {time_response.get('error')}"
+    assert time_response.get("final_answer"), "Time prompt did not produce a final answer."
+    assert len(time_response.get("tool_calls", [])) > 0, "Time prompt should have called a tool."
+    assert time_response["tool_calls"][0]["name"] == "time_machine::get_current_time", "Incorrect tool called for time."
+    assert "time" in time_response["tool_calls"][0].get("result", {}).get("output", {}), "Time tool result missing time."
+
+
+    ASCIIColors.magenta("\n3. Calling generate_with_mcp for calculation...")
+    calc_prompt = "Can you please calculate the sum of 50, 25, and 7.5 for me?"
+    calc_response = client.generate_with_mcp(
+        prompt=calc_prompt,
+        streaming_callback=mcp_streaming_callback
+    )
+    print() # Newline
+    ASCIIColors.blue(f"Final response for calc prompt: {json.dumps(calc_response, indent=2)}")
+
+    assert calc_response.get("error") is None, f"Calc prompt resulted in an error: {calc_response.get('error')}"
+    assert calc_response.get("final_answer"), "Calc prompt did not produce a final answer."
+    assert len(calc_response.get("tool_calls", [])) > 0, "Calc prompt should have called a tool."
+    assert calc_response["tool_calls"][0]["name"] == "calc_unit::add_numbers", "Incorrect tool called for calculation."
+    # The dummy LLM uses hardcoded params [1,2,3] for calc, so result will be 6.
+    # A real LLM would extract 50, 25, 7.5.
+    # For this dummy test, we check against the dummy's behavior.
+    assert calc_response["tool_calls"][0].get("result", {}).get("output", {}).get("sum") == 82.5, "Calculator tool result mismatch for dummy params."
+
+
+    # --- 5. Cleanup ---
+    ASCIIColors.info("Cleaning up temporary server scripts and dummy binding directory...")
+    shutil.rmtree(example_base_dir, ignore_errors=True)
+
+    ASCIIColors.red("\n--- LollmsClient with StandardMCPBinding Example Finished Successfully! ---")
+
+if __name__ == "__main__":
+    main()

lollms_client/__init__.py

@@ -7,7 +7,7 @@ from lollms_client.lollms_utilities import PromptReshaper # Keep general utiliti
 from lollms_client.lollms_mcp_binding import LollmsMCPBinding, LollmsMCPBindingManager
 
 
-__version__ = "0.19.9" # Updated version
+__version__ = "0.20.0" # Updated version
 
 # Optionally, you could define __all__ if you want to be explicit about exports
 __all__ = [

lollms_client/lollms_core.py

@@ -922,7 +922,6 @@ Respond with a JSON object containing ONE of the following structures:
         for hop_count in range(max_rag_hops + 1):
             if streaming_callback:
                 streaming_callback(f"Starting RAG Hop {hop_count + 1}", MSG_TYPE.MSG_TYPE_STEP, {"type": "rag_hop_start", "hop": hop_count + 1}, turn_rag_history_for_callback)
-
             txt_previous_queries = f"Previous queries:\n"+'\n'.join(previous_queries)+"\n\n" if len(previous_queries)>0 else ""
             txt_informations = f"Information:\n"+'\n'.join([f"(from {chunk['document']}):{chunk['content']}" for _, chunk in all_unique_retrieved_chunks_map.items()]) if len(all_unique_retrieved_chunks_map)>0 else "This is the first request. No data received yet. Build a new query."
             txt_sp = "Your objective is to analyze the provided chunks of information, then decise if they are sufficient to reach the objective. If you need more information, formulate a new query to extract more data."
@@ -930,7 +929,7 @@ Respond with a JSON object containing ONE of the following structures:
 ```json
 {
     "decision": A boolean depicting your decision (true: more data is needed, false: there is enough data to reach objective),
-    "query": (optional, only if decision is true). A new query to recover more information from the data source (do not use previous queries as they have already been used)
+    "query": (str, optional, only if decision is true). A new query to recover more information from the data source (do not use previous queries as they have already been used)
 }
 ```
 """
@@ -942,7 +941,7 @@ Respond with a JSON object containing ONE of the following structures:
                 if not decision:
                     break
                 else:
-                    current_query_for_rag = answer["query"]
+                    current_query_for_rag = str(answer["query"])
             except Exception as ex:
                 trace_exception(ex)
 

lollms_client/mcp_bindings/standard_mcp/__init__.py

@@ -0,0 +1,519 @@
+# File: lollms_client/mcp_bindings/standard_mcp/__init__.py
+
+import pipmaster as pm
+
+# Ensure critical dependencies for this binding are present.
+# If pipmaster itself is missing, lollms_client is not correctly installed.
+pm.ensure_packages(["mcp", "ascii-colors"])
+
+import asyncio
+import json
+import threading
+import sys
+from contextlib import AsyncExitStack
+from pathlib import Path
+from typing import Optional, List, Dict, Any, Tuple
+
+# These imports should now succeed if pipmaster did its job.
+from lollms_client.lollms_mcp_binding import LollmsMCPBinding # Assuming this base class exists
+from ascii_colors import ASCIIColors, trace_exception
+
+# Attempt to import MCP library components.
+try:
+    from mcp import ClientSession, StdioServerParameters
+    from mcp.client.stdio import stdio_client
+    from mcp import types # Use mcp.types for data structures
+    MCP_LIBRARY_AVAILABLE = True
+    ASCIIColors.green("Successfully imported MCP library components for StandardMCPBinding.")
+except ImportError as e:
+    ASCIIColors.error(f"StandardMCPBinding: Critical MCP library components could not be imported even after pipmaster attempt: {e}")
+    ASCIIColors.error("Please check your Python environment, internet connection, and pip installation.")
+    ASCIIColors.error("StandardMCPBinding will be non-functional.")
+    ClientSession = None
+    StdioServerParameters = None
+    stdio_client = None
+    types = None # MCP types module unavailable
+    MCP_LIBRARY_AVAILABLE = False
+
+# This variable is used by LollmsMCPBindingManager to identify the binding class.
+BindingName = "StandardMCPBinding" # Must match the class name below
+TOOL_NAME_SEPARATOR = "::"
+
+class StandardMCPBinding(LollmsMCPBinding):
+    """
+    A LollmsMCPBinding to connect to multiple standard Model Context Protocol (MCP) servers.
+    This binding acts as an MCP client to these servers.
+    Each server is launched via a command, communicates over stdio, and is identified by a unique alias.
+    Tool names are prefixed with 'server_alias::' for disambiguation.
+    """
+
+    def __init__(self,
+                 initial_servers: Optional[Dict[str, Dict[str, Any]]] = None,
+                 **other_config_params: Any):
+        super().__init__(binding_name="standard_mcp")
+
+        self.config = {"initial_servers": initial_servers if initial_servers else {}}
+        self.config.update(other_config_params)
+
+        self._server_configs: Dict[str, Dict[str, Any]] = {}
+        # Type hint with ClientSession, actual obj if MCP_LIBRARY_AVAILABLE
+        self._mcp_sessions: Dict[str, ClientSession] = {} # type: ignore
+        self._exit_stacks: Dict[str, AsyncExitStack] = {}
+        self._discovered_tools_cache: Dict[str, List[Dict[str, Any]]] = {}
+        self._server_locks: Dict[str, threading.Lock] = {}
+        self._initialization_status: Dict[str, bool] = {}
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._thread: Optional[threading.Thread] = None
+
+        if not MCP_LIBRARY_AVAILABLE:
+            ASCIIColors.error(f"{self.binding_name}: Cannot initialize; MCP library components are missing.")
+            return # Binding remains in a non-functional state
+
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(target=self._start_event_loop, daemon=True,
+                                        name=f"{self.binding_name}EventLoopThread")
+        self._thread.start()
+        ASCIIColors.info(f"{self.binding_name}: Event loop thread started.")
+
+        if initial_servers:
+            for alias, config_data in initial_servers.items():
+                if isinstance(config_data, dict):
+                    # Ensure command is a list
+                    command = config_data.get("command")
+                    if isinstance(command, str): # if command is a single string, convert to list
+                        command = command.split()
+
+                    self.add_server(
+                        alias=alias,
+                        command=command, # type: ignore
+                        cwd=config_data.get("cwd"),
+                        env=config_data.get("env")
+                    )
+                else:
+                    ASCIIColors.warning(f"{self.binding_name}: Invalid configuration for server alias '{alias}' in 'initial_servers'. Expected a dictionary.")
+
+    def _start_event_loop(self):
+        if not self._loop: return
+        asyncio.set_event_loop(self._loop)
+        try:
+            self._loop.run_forever()
+        finally:
+            # Cleanup tasks before closing the loop
+            if hasattr(asyncio, 'all_tasks'): # Python 3.7+
+                pending = asyncio.all_tasks(self._loop)
+            else: # Python 3.6
+                pending = asyncio.Task.all_tasks(self._loop) # type: ignore
+
+            if pending:
+                self._loop.run_until_complete(asyncio.gather(*pending, return_exceptions=True))
+
+            if self._loop.is_running():
+                self._loop.stop()
+
+            if not self._loop.is_closed():
+                if sys.platform == "win32" and isinstance(self._loop, asyncio.ProactorEventLoop): # type: ignore
+                    self._loop.call_soon(self._loop.stop)
+                    try:
+                        # This run_until_complete might be problematic if called from non-loop thread after stop
+                        # but often necessary for proactor loop cleanup on Windows
+                        self._loop.run_until_complete(asyncio.sleep(0.1))
+                    except RuntimeError as e:
+                        if "cannot be called from a different thread" not in str(e):
+                            ASCIIColors.warning(f"{self.binding_name}: Minor issue during proactor loop sleep: {e}")
+                self._loop.close()
+            ASCIIColors.info(f"{self.binding_name}: Asyncio event loop has stopped and closed.")
+
+
+    def _run_async_task(self, coro, timeout: Optional[float] = None) -> Any:
+        if not MCP_LIBRARY_AVAILABLE or not self._loop or not self._loop.is_running() or not self._thread or not self._thread.is_alive():
+            raise RuntimeError(f"{self.binding_name}'s event loop is not operational or MCP library is missing.")
+        future = asyncio.run_coroutine_threadsafe(coro, self._loop)
+        try:
+            return future.result(timeout=timeout)
+        except TimeoutError:
+            future.cancel() # Attempt to cancel the coroutine
+            raise
+        except Exception:
+            raise
+
+    def add_server(self, alias: str, command: List[str], cwd: Optional[str] = None, env: Optional[Dict[str, str]] = None) -> bool:
+        if not MCP_LIBRARY_AVAILABLE:
+            ASCIIColors.error(f"{self.binding_name}: Cannot add server '{alias}', MCP library is not available.")
+            return False
+
+        if not alias or not isinstance(alias, str):
+            ASCIIColors.error(f"{self.binding_name}: Server alias must be a non-empty string.")
+            return False
+        if not command or not isinstance(command, list) or not all(isinstance(c, str) for c in command) or not command[0]:
+            ASCIIColors.error(f"{self.binding_name}: Server command for '{alias}' must be a non-empty list of strings (e.g., ['python', 'server.py']).")
+            return False
+
+        if alias in self._server_configs:
+            ASCIIColors.warning(f"{self.binding_name}: Reconfiguring server '{alias}'. Existing connection (if any) will be closed.")
+            self.remove_server(alias, silent=True)
+
+        self._server_configs[alias] = {"command": command, "cwd": cwd, "env": env}
+        self._server_locks[alias] = threading.Lock()
+        self._initialization_status[alias] = False
+        self._discovered_tools_cache[alias] = [] # Initialize cache for the new server
+        ASCIIColors.info(f"{self.binding_name}: Server '{alias}' configured with command: {command}")
+
+        if "initial_servers" not in self.config:
+            self.config["initial_servers"] = {}
+        if isinstance(self.config["initial_servers"], dict): # Ensure it's a dict
+            self.config["initial_servers"][alias] = self._server_configs[alias]
+        return True
+
+    async def _close_server_connection_async(self, alias: str):
+        exit_stack_to_close = self._exit_stacks.pop(alias, None)
+        # Pop session and status immediately to reflect desired state
+        self._mcp_sessions.pop(alias, None)
+        self._initialization_status[alias] = False
+
+        if exit_stack_to_close:
+            ASCIIColors.info(f"{self.binding_name}: Attempting to close MCP connection for server '{alias}'...")
+            try:
+                await exit_stack_to_close.aclose()
+                ASCIIColors.info(f"{self.binding_name}: MCP connection for '{alias}' resources released via aclose.")
+            except RuntimeError as e:
+                if "Attempted to exit cancel scope in a different task" in str(e):
+                    ASCIIColors.warning(f"{self.binding_name}: Known anyio task ownership issue during close for '{alias}': {e}.")
+                    ASCIIColors.warning(f"{self.binding_name}: Underlying MCP client resources for '{alias}' may not have been fully cleaned up due to this anyio constraint.")
+                    # At this point, the stdio process might still be running.
+                    # Further action (like trying to kill the process) is outside the scope of AsyncExitStack.
+                else:
+                    # Reraise other RuntimeErrors or handle them
+                    trace_exception(e)
+                    ASCIIColors.error(f"{self.binding_name}: Unexpected RuntimeError closing MCP connection for '{alias}': {e}")
+            except Exception as e:
+                trace_exception(e)
+                ASCIIColors.error(f"{self.binding_name}: General error closing MCP connection for '{alias}': {e}")
+        # else:
+            # ASCIIColors.debug(f"{self.binding_name}: No active exit stack found for server '{alias}' to close (already closed or never fully initialized).")
+
+    def remove_server(self, alias: str, silent: bool = False):
+        if not MCP_LIBRARY_AVAILABLE:
+            if not silent: ASCIIColors.error(f"{self.binding_name}: Cannot remove server '{alias}', MCP library issues persist."); return
+
+        if alias not in self._server_configs:
+            if not silent: ASCIIColors.warning(f"{self.binding_name}: Server '{alias}' not found for removal.")
+            return
+
+        if not silent: ASCIIColors.info(f"{self.binding_name}: Removing server '{alias}'.")
+
+        if self._initialization_status.get(alias) or alias in self._exit_stacks or alias in self._mcp_sessions:
+             try:
+                self._run_async_task(self._close_server_connection_async(alias), timeout=10.0)
+             except RuntimeError as e:
+                if not silent: ASCIIColors.warning(f"{self.binding_name}: Could not run async close for '{alias}' (event loop issue?): {e}")
+             except Exception as e:
+                if not silent: ASCIIColors.error(f"{self.binding_name}: Exception during async close for '{alias}': {e}")
+
+        self._server_configs.pop(alias, None)
+        self._server_locks.pop(alias, None)
+        self._initialization_status.pop(alias, None)
+        self._discovered_tools_cache.pop(alias, None)
+        if "initial_servers" in self.config and isinstance(self.config["initial_servers"], dict) and alias in self.config["initial_servers"]:
+            self.config["initial_servers"].pop(alias)
+        if not silent: ASCIIColors.info(f"{self.binding_name}: Server '{alias}' removed.")
+
+    async def _initialize_connection_async(self, alias: str) -> bool:
+        if not MCP_LIBRARY_AVAILABLE or not types or not ClientSession or not StdioServerParameters or not stdio_client:
+            ASCIIColors.error(f"{self.binding_name}: MCP library components (types, ClientSession, etc.) not available. Cannot initialize '{alias}'.")
+            return False
+        if self._initialization_status.get(alias): return True
+        if alias not in self._server_configs:
+            ASCIIColors.error(f"{self.binding_name}: No configuration for server alias '{alias}'. Cannot initialize.")
+            return False
+
+        config = self._server_configs[alias]
+        ASCIIColors.info(f"{self.binding_name}: Initializing MCP connection for server '{alias}'...")
+        try:
+            if alias in self._exit_stacks: # Should ideally be cleaned up if a previous attempt failed
+                old_stack = self._exit_stacks.pop(alias)
+                await old_stack.aclose()
+
+            exit_stack = AsyncExitStack()
+            self._exit_stacks[alias] = exit_stack
+
+            server_params = StdioServerParameters(
+                command=config["command"][0],
+                args=config["command"][1:],
+                cwd=Path(config["cwd"]) if config["cwd"] else None,
+                env=config["env"]
+            )
+            read_stream, write_stream = await exit_stack.enter_async_context(stdio_client(server_params))
+
+            # CORRECTED: Removed client_name from ClientSession constructor
+            session = await exit_stack.enter_async_context(ClientSession(read_stream, write_stream))
+
+            await session.initialize() # This is where client capabilities/info might be exchanged
+            self._mcp_sessions[alias] = session
+            self._initialization_status[alias] = True
+            ASCIIColors.green(f"{self.binding_name}: Successfully initialized MCP session for server '{alias}'.")
+            await self._refresh_tools_cache_async(alias)
+            return True
+        except Exception as e:
+            trace_exception(e)
+            ASCIIColors.error(f"{self.binding_name}: Failed to initialize MCP connection for '{alias}': {e}")
+            if alias in self._exit_stacks:
+                current_stack = self._exit_stacks.pop(alias)
+                try:
+                    await current_stack.aclose()
+                except Exception as e_close:
+                    ASCIIColors.error(f"{self.binding_name}: Error during cleanup after failed init for '{alias}': {e_close}")
+            self._initialization_status[alias] = False
+            self._mcp_sessions.pop(alias, None)
+            return False
+
+    def _ensure_server_initialized_sync(self, alias: str, timeout: float = 30.0):
+        if not MCP_LIBRARY_AVAILABLE or not self._loop or not types:
+             raise ConnectionError(f"{self.binding_name}: MCP library/event loop/types module not available. Cannot initialize server '{alias}'.")
+
+        if alias not in self._server_configs:
+            raise ValueError(f"{self.binding_name}: Server alias '{alias}' is not configured.")
+
+        lock = self._server_locks.get(alias)
+        if not lock:
+            ASCIIColors.error(f"{self.binding_name}: Internal error - No lock for server '{alias}'. Creating one now.")
+            self._server_locks[alias] = threading.Lock()
+            lock = self._server_locks[alias]
+
+
+        with lock:
+            if not self._initialization_status.get(alias):
+                ASCIIColors.info(f"{self.binding_name}: Connection for '{alias}' not initialized. Attempting initialization...")
+                try:
+                    success = self._run_async_task(self._initialize_connection_async(alias), timeout=timeout)
+                    if not success:
+                        raise ConnectionError(f"Failed to initialize MCP connection for server '{alias}'. Check previous logs for details.")
+                except TimeoutError:
+                    raise ConnectionError(f"MCP initialization for server '{alias}' timed out after {timeout} seconds.")
+                except Exception as e:
+                    raise ConnectionError(f"MCP initialization for server '{alias}' failed: {str(e)}")
+
+        if not self._initialization_status.get(alias) or alias not in self._mcp_sessions:
+            raise ConnectionError(f"MCP Session for server '{alias}' is not valid after initialization attempt.")
+
+    async def _refresh_tools_cache_async(self, alias: str):
+        if not MCP_LIBRARY_AVAILABLE or not types:
+            ASCIIColors.error(f"{self.binding_name}: MCP library or types module not available. Cannot refresh tools for '{alias}'.")
+            return
+        if not self._initialization_status.get(alias) or alias not in self._mcp_sessions:
+            ASCIIColors.warning(f"{self.binding_name}: Server '{alias}' not initialized or no session. Cannot refresh tools.")
+            return
+
+        session = self._mcp_sessions[alias]
+        ASCIIColors.info(f"{self.binding_name}: Refreshing tools cache for server '{alias}'...")
+        try:
+            list_tools_result = await session.list_tools() # Expected to be types.ListToolsResult
+            current_server_tools = []
+            if list_tools_result and list_tools_result.tools:
+                for tool_obj in list_tools_result.tools: # tool_obj is expected to be types.Tool
+                    # --- DEBUGGING ---
+                    # print(f"DEBUG: tool_obj type: {type(tool_obj)}")
+                    # print(f"DEBUG: tool_obj dir: {dir(tool_obj)}")
+                    # if hasattr(tool_obj, 'model_fields'): print(f"DEBUG: tool_obj fields: {tool_obj.model_fields.keys()}") # Pydantic v2
+                    # elif hasattr(tool_obj, '__fields__'): print(f"DEBUG: tool_obj fields: {tool_obj.__fields__.keys()}") # Pydantic v1
+                    # if hasattr(tool_obj, 'model_dump_json'): print(f"DEBUG: tool_obj JSON: {tool_obj.model_dump_json(indent=2)}")
+                    # elif hasattr(tool_obj, 'json'): print(f"DEBUG: tool_obj JSON: {tool_obj.json(indent=2)}")
+                    # --- END DEBUGGING ---
+
+                    input_schema_dict = {}
+                    # Try accessing with 'inputSchema' (camelCase) or check other potential names based on debug output
+                    tool_input_schema = None
+                    if hasattr(tool_obj, 'inputSchema'): # Common JSON convention
+                        tool_input_schema = tool_obj.inputSchema
+                    elif hasattr(tool_obj, 'input_schema'): # Python convention
+                        tool_input_schema = tool_obj.input_schema
+                    # Add more elif for other possibilities if revealed by debugging
+
+                    if tool_input_schema: # Check if the schema object itself exists and is not None
+                        # tool_input_schema is expected to be types.InputSchema | None
+                        # or a Pydantic model that has model_dump
+                        if hasattr(tool_input_schema, 'model_dump'):
+                             input_schema_dict = tool_input_schema.model_dump(mode='json', exclude_none=True)
+                        else:
+                            # If it's not a Pydantic model but some other dict-like structure
+                            # This part might need adjustment based on what tool_input_schema actually is
+                            ASCIIColors.warning(f"{self.binding_name}: input schema for tool '{tool_obj.name}' on '{alias}' is not a Pydantic model with model_dump. Type: {type(tool_input_schema)}")
+                            if isinstance(tool_input_schema, dict):
+                                input_schema_dict = tool_input_schema
+                            # else: leave it as empty dict
+
+                    tool_dict = {
+                        "name": tool_obj.name,
+                        "description": tool_obj.description or "",
+                        "input_schema": input_schema_dict
+                    }
+                    current_server_tools.append(tool_dict)
+            self._discovered_tools_cache[alias] = current_server_tools
+            ASCIIColors.green(f"{self.binding_name}: Tools cache for '{alias}' refreshed. Found {len(current_server_tools)} tools.")
+        except Exception as e:
+            trace_exception(e)
+            ASCIIColors.error(f"{self.binding_name}: Error refreshing tools cache for '{alias}': {e}")
+            self._discovered_tools_cache[alias] = [] # Clear cache on error
+
+    def discover_tools(self, specific_tool_names: Optional[List[str]]=None, force_refresh: bool=False, timeout_per_server: float=10.0, **kwargs) -> List[Dict[str, Any]]:
+        if not MCP_LIBRARY_AVAILABLE or not self._loop or not types:
+             ASCIIColors.warning(f"{self.binding_name}: Cannot discover tools, MCP library, event loop, or types module not available.")
+             return []
+
+        stn = kwargs.get('specific_tool_names', specific_tool_names)
+        fr = kwargs.get('force_refresh', force_refresh)
+        tps = kwargs.get('timeout_per_server', timeout_per_server)
+
+        all_tools: List[Dict[str, Any]] = []
+        active_aliases = list(self._server_configs.keys())
+
+        for alias in active_aliases:
+            try:
+                self._ensure_server_initialized_sync(alias, timeout=tps)
+
+                if fr or (self._initialization_status.get(alias) and not self._discovered_tools_cache.get(alias)):
+                    ASCIIColors.info(f"{self.binding_name}: Force refreshing tools for '{alias}' or cache is empty.")
+                    self._run_async_task(self._refresh_tools_cache_async(alias), timeout=tps)
+
+                for tool_data in self._discovered_tools_cache.get(alias, []):
+                    prefixed_tool_data = tool_data.copy()
+                    prefixed_tool_data["name"] = f"{alias}{TOOL_NAME_SEPARATOR}{tool_data['name']}"
+                    all_tools.append(prefixed_tool_data)
+            except ConnectionError as e:
+                ASCIIColors.error(f"{self.binding_name}: Connection problem with server '{alias}' during tool discovery: {e}")
+            except Exception as e:
+                trace_exception(e)
+                ASCIIColors.error(f"{self.binding_name}: Unexpected problem with server '{alias}' during tool discovery: {e}")
+
+        if stn:
+            return [t for t in all_tools if t.get("name") in stn]
+        return all_tools
+
+    def _parse_tool_name(self, prefixed_tool_name: str) -> Optional[Tuple[str, str]]:
+        parts = prefixed_tool_name.split(TOOL_NAME_SEPARATOR, 1)
+        if len(parts) == 2:
+            return parts[0], parts[1]
+        ASCIIColors.warning(f"{self.binding_name}: Tool name '{prefixed_tool_name}' is not in the expected 'alias{TOOL_NAME_SEPARATOR}tool' format.")
+        return None
+
+    async def _execute_tool_async(self, server_alias: str, actual_tool_name: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        if not MCP_LIBRARY_AVAILABLE or not types:
+            error_msg = f"{self.binding_name}: MCP library or types module not available. Cannot execute tool '{actual_tool_name}' on '{server_alias}'."
+            ASCIIColors.error(error_msg)
+            return {"error": error_msg, "status_code": 503}
+
+        if not self._initialization_status.get(server_alias) or server_alias not in self._mcp_sessions:
+            error_msg = f"Server '{server_alias}' not initialized or session lost. Cannot execute tool '{actual_tool_name}'."
+            ASCIIColors.error(f"{self.binding_name}: {error_msg}")
+            return {"error": error_msg, "status_code": 503}
+
+        session = self._mcp_sessions[server_alias]
+        # Use a more careful way to log params if they can be very large or sensitive
+        params_log = {k: (v[:100] + '...' if isinstance(v, str) and len(v) > 100 else v) for k,v in params.items()}
+        ASCIIColors.info(f"{self.binding_name}: Executing MCP tool '{actual_tool_name}' on server '{server_alias}' with params: {json.dumps(params_log)}")
+        try:
+            # call_tool returns types.CallToolResult
+            mcp_call_result = await session.call_tool(name=actual_tool_name, arguments=params)
+
+            output_parts = []
+            if mcp_call_result and mcp_call_result.content: # content is List[types.ContentPart]
+                for content_part in mcp_call_result.content:
+                    if isinstance(content_part, types.TextContent) and hasattr(content_part, 'text') and content_part.text is not None:
+                        output_parts.append(content_part.text)
+
+            if not output_parts:
+                ASCIIColors.info(f"{self.binding_name}: Tool '{actual_tool_name}' on '{server_alias}' executed but returned no textual content.")
+                return {"output": {"message": "Tool executed successfully but returned no textual content."}, "status_code": 200}
+
+            combined_output_str = "\n".join(output_parts)
+            ASCIIColors.success(f"{self.binding_name}: Tool '{actual_tool_name}' on '{server_alias}' executed. Raw output (first 200 chars): '{combined_output_str[:200]}'")
+
+            try:
+                parsed_output = json.loads(combined_output_str)
+                return {"output": parsed_output, "status_code": 200}
+            except json.JSONDecodeError:
+                return {"output": combined_output_str, "status_code": 200}
+
+        except Exception as e:
+            trace_exception(e)
+            error_msg = f"Error executing tool '{actual_tool_name}' on server '{server_alias}': {str(e)}"
+            ASCIIColors.error(f"{self.binding_name}: {error_msg}")
+            return {"error": error_msg, "status_code": 500}
+
+    def execute_tool(self, tool_name: str, params: Dict[str, Any], **kwargs) -> Dict[str, Any]:
+        if not MCP_LIBRARY_AVAILABLE or not self._loop or not types:
+             error_msg = f"{self.binding_name}: MCP support (library, event loop, or types module) not available. Cannot execute tool '{tool_name}'."
+             ASCIIColors.warning(error_msg)
+             return {"error": error_msg, "status_code": 503}
+
+        timeout = float(kwargs.get('timeout', 60.0))
+
+        parsed_name = self._parse_tool_name(tool_name)
+        if not parsed_name:
+            return {"error": f"Invalid tool name format for {self.binding_name}: '{tool_name}'. Expected 'alias{TOOL_NAME_SEPARATOR}toolname'.", "status_code": 400}
+
+        server_alias, actual_tool_name = parsed_name
+
+        if server_alias not in self._server_configs:
+            return {"error": f"Server alias '{server_alias}' (from tool name '{tool_name}') is not configured.", "status_code": 404}
+
+        try:
+            init_timeout = min(timeout, 30.0)
+            self._ensure_server_initialized_sync(server_alias, timeout=init_timeout)
+        except ConnectionError as e:
+            return {"error": f"{self.binding_name}: Connection or configuration issue for server '{server_alias}': {e}", "status_code": 503}
+        except Exception as e:
+            trace_exception(e)
+            return {"error": f"{self.binding_name}: Failed to ensure server '{server_alias}' is initialized: {e}", "status_code": 500}
+
+        try:
+            return self._run_async_task(self._execute_tool_async(server_alias, actual_tool_name, params), timeout=timeout)
+        except TimeoutError:
+            return {"error": f"{self.binding_name}: Tool '{actual_tool_name}' on server '{server_alias}' timed out after {timeout} seconds.", "status_code": 504}
+        except RuntimeError as e:
+             return {"error": f"{self.binding_name}: Runtime error executing tool '{actual_tool_name}' on '{server_alias}': {e}", "status_code": 500}
+        except Exception as e:
+            trace_exception(e)
+            return {"error": f"{self.binding_name}: An unexpected error occurred while running MCP tool '{actual_tool_name}' on server '{server_alias}': {e}", "status_code": 500}
+
+    def close(self):
+        ASCIIColors.info(f"{self.binding_name}: Initiating shutdown process...")
+
+        if hasattr(self, '_server_configs') and self._server_configs:
+            active_aliases = list(self._server_configs.keys())
+            if active_aliases:
+                ASCIIColors.info(f"{self.binding_name}: Closing connections for servers: {active_aliases}")
+                for alias in active_aliases:
+                    self.remove_server(alias, silent=True)
+
+        if hasattr(self, '_loop') and self._loop:
+            if self._loop.is_running():
+                ASCIIColors.info(f"{self.binding_name}: Requesting event loop to stop.")
+                self._loop.call_soon_threadsafe(self._loop.stop)
+
+        if hasattr(self, '_thread') and self._thread and self._thread.is_alive():
+            ASCIIColors.info(f"{self.binding_name}: Waiting for event loop thread to join...")
+            self._thread.join(timeout=10.0)
+            if self._thread.is_alive():
+                ASCIIColors.warning(f"{self.binding_name}: Event loop thread did not terminate cleanly after 10 seconds.")
+            else:
+                ASCIIColors.info(f"{self.binding_name}: Event loop thread joined successfully.")
+
+        ASCIIColors.info(f"{self.binding_name}: Binding closed.")
+
+    def __del__(self):
+        # Check if attributes relevant to closing exist to prevent errors if __init__ failed early
+        needs_close = False
+        if hasattr(self, '_loop') and self._loop and (self._loop.is_running() or not self._loop.is_closed()):
+            needs_close = True
+        if hasattr(self, '_thread') and self._thread and self._thread.is_alive():
+            needs_close = True
+        if hasattr(self, '_server_configs') and self._server_configs: # Check if there are any servers to close
+             needs_close = True
+
+        if needs_close:
+            ASCIIColors.warning(f"{self.binding_name}: __del__ called; attempting to close resources. Explicit .close() is recommended for reliability.")
+            try:
+                self.close()
+            except Exception as e:
+                # __del__ should not raise exceptions
+                ASCIIColors.error(f"{self.binding_name}: Error during __del__ cleanup: {e}")

{lollms_client-0.19.9.dist-info → lollms_client-0.20.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lollms_client
-Version: 0.19.9
+Version: 0.20.0
 Summary: A client library for LoLLMs generate endpoint
 Author-email: ParisNeo <parisneoai@gmail.com>
 License: Apache Software License

{lollms_client-0.19.9.dist-info → lollms_client-0.20.0.dist-info}/RECORD

@@ -1,8 +1,10 @@
+examples/external_mcp.py,sha256=swx1KCOz6jk8jGTAycq-xu7GXPAhRMDe1x--SKocugE,13371
 examples/function_calling_with_local_custom_mcp.py,sha256=g6wOFRB8-p9Cv7hKmQaGzPvtMX3H77gas01QVNEOduM,12407
 examples/generate_a_benchmark_for_safe_store.py,sha256=bkSt0mrpNsN0krZAUShm0jgVM1ukrPpjI7VwSgcNdSA,3974
 examples/generate_text_with_multihop_rag_example.py,sha256=riEyVYo97r6ZYdySL-NJkRhE4MnpwbZku1sN8RNvbvs,11519
 examples/internet_search_with_rag.py,sha256=cbUoGgY3rxZpQ5INoaA0Nhm0cutii-2AQ9WCz71Ch3o,12369
 examples/local_mcp.py,sha256=w40dgayvHYe01yvekEE0LjcbkpwKjWwJ-9v4_wGYsUk,9113
+examples/run_standard_mcp_example.py,sha256=GSZpaACPf3mDPsjA8esBQVUsIi7owI39ca5avsmvCxA,9419
 examples/simple_text_gen_test.py,sha256=RoX9ZKJjGMujeep60wh5WT_GoBn0O9YKJY6WOy-ZmOc,8710
 examples/simple_text_gen_with_image_test.py,sha256=rR1O5Prcb52UHtJ3c6bv7VuTd1cvbkr5aNZU-v-Rs3Y,9263
 examples/text_2_audio.py,sha256=MfL4AH_NNwl6m0I0ywl4BXRZJ0b9Y_9fRqDIe6O-Sbw,3523
@@ -20,9 +22,9 @@ examples/personality_test/chat_test.py,sha256=o2jlpoddFc-T592iqAiA29xk3x27KsdK5D
 examples/personality_test/chat_with_aristotle.py,sha256=4X_fwubMpd0Eq2rCReS2bgVlUoAqJprjkLXk2Jz6pXU,1774
 examples/personality_test/tesks_test.py,sha256=7LIiwrEbva9WWZOLi34fsmCBN__RZbPpxoUOKA_AtYk,1924
 examples/test_local_models/local_chat.py,sha256=slakja2zaHOEAUsn2tn_VmI4kLx6luLBrPqAeaNsix8,456
-lollms_client/__init__.py,sha256=ZuMTyKsGxnpozXbTiKEBlP7iMSdWHqlU2mAw_Jp1NY8,910
+lollms_client/__init__.py,sha256=6mEOGmlBcMfm69OMeheDvrv_uQhGXf8s6A-u45k0KEs,910
 lollms_client/lollms_config.py,sha256=goEseDwDxYJf3WkYJ4IrLXwg3Tfw73CXV2Avg45M_hE,21876
-lollms_client/lollms_core.py,sha256=3SxNX4cUgP3zN8x0TYv-G5XeS8WhoSiyss69qmjweRE,112862
+lollms_client/lollms_core.py,sha256=w-wy0YO6Yojido4p2f-0zykpLEzLRI2XGUAYlfVsUCA,112870
 lollms_client/lollms_discussion.py,sha256=EV90dIgw8a-f-82vB2GspR60RniYz7WnBmAWSIg5mW0,2158
 lollms_client/lollms_js_analyzer.py,sha256=01zUvuO2F_lnUe_0NLxe1MF5aHE1hO8RZi48mNPv-aw,8361
 lollms_client/lollms_llm_binding.py,sha256=bdElz_IBx0zZ-85YTT1fyY_mSoHo46tKIMiHYJlKCkM,9809
@@ -50,6 +52,7 @@ lollms_client/mcp_bindings/local_mcp/default_tools/file_writer/file_writer.py,sh
 lollms_client/mcp_bindings/local_mcp/default_tools/generate_image_from_prompt/generate_image_from_prompt.py,sha256=THtZsMxNnXZiBdkwoBlfbWY2C5hhDdmPtnM-8cSKN6s,9488
 lollms_client/mcp_bindings/local_mcp/default_tools/internet_search/internet_search.py,sha256=PLC31-D04QKTOTb1uuCHnrAlpysQjsk89yIJngK0VGc,4586
 lollms_client/mcp_bindings/local_mcp/default_tools/python_interpreter/python_interpreter.py,sha256=McDCBVoVrMDYgU7EYtyOY7mCk1uEeTea0PSD69QqDsQ,6228
+lollms_client/mcp_bindings/standard_mcp/__init__.py,sha256=xhXlBFHA7njNKnshrGF-WTw0DbxNKDchYt43-I56-2U,30230
 lollms_client/stt_bindings/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 lollms_client/stt_bindings/lollms/__init__.py,sha256=jBz3285atdPRqQe9ZRrb-AvjqKRB4f8tjLXjma0DLfE,6082
 lollms_client/stt_bindings/whisper/__init__.py,sha256=vrua7fLwDId9_WiH4y2gXOE0hy3Gr2Ig-z5ScIT2bHI,15447
@@ -70,8 +73,8 @@ lollms_client/tts_bindings/piper_tts/__init__.py,sha256=0IEWG4zH3_sOkSb9WbZzkeV5
 lollms_client/tts_bindings/xtts/__init__.py,sha256=FgcdUH06X6ZR806WQe5ixaYx0QoxtAcOgYo87a2qxYc,18266
 lollms_client/ttv_bindings/__init__.py,sha256=UZ8o2izQOJLQgtZ1D1cXoNST7rzqW22rL2Vufc7ddRc,3141
 lollms_client/ttv_bindings/lollms/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-lollms_client-0.19.9.dist-info/licenses/LICENSE,sha256=HrhfyXIkWY2tGFK11kg7vPCqhgh5DcxleloqdhrpyMY,11558
-lollms_client-0.19.9.dist-info/METADATA,sha256=ODlUMX37ZeZ1tJEPgJyc2yk40Dac-iivpGAM5IjPxSI,13374
-lollms_client-0.19.9.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-lollms_client-0.19.9.dist-info/top_level.txt,sha256=NI_W8S4OYZvJjb0QWMZMSIpOrYzpqwPGYaklhyWKH2w,23
-lollms_client-0.19.9.dist-info/RECORD,,
+lollms_client-0.20.0.dist-info/licenses/LICENSE,sha256=HrhfyXIkWY2tGFK11kg7vPCqhgh5DcxleloqdhrpyMY,11558
+lollms_client-0.20.0.dist-info/METADATA,sha256=GB6TGuMpSqhgobl3ig9zTdSoyc_OzVk29cit_wht0HA,13374
+lollms_client-0.20.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+lollms_client-0.20.0.dist-info/top_level.txt,sha256=NI_W8S4OYZvJjb0QWMZMSIpOrYzpqwPGYaklhyWKH2w,23
+lollms_client-0.20.0.dist-info/RECORD,,