dao-ai 0.1.5__py3-none-any.whl → 0.1.6__py3-none-any.whl

dao_ai/cli.py

@@ -7,7 +7,7 @@ import sys
 import traceback
 from argparse import ArgumentParser, Namespace
 from pathlib import Path
-from typing import Optional, Sequence
+from typing import Any, Optional, Sequence
 
 from dotenv import find_dotenv, load_dotenv
 from loguru import logger
@@ -114,6 +114,7 @@ Examples:
   dao-ai validate -c config/model_config.yaml            # Validate a specific configuration file
   dao-ai graph -o architecture.png -c my_config.yaml -v  # Generate visual graph with verbose output
   dao-ai chat -c config/retail.yaml --custom-input store_num=87887  # Start interactive chat session
+  dao-ai list-mcp-tools -c config/mcp_config.yaml --apply-filters  # List filtered MCP tools only
   dao-ai validate                                        # Validate with detailed logging
   dao-ai bundle --deploy                                 # Deploy the DAO AI asset bundle
         """,
@@ -309,6 +310,53 @@ Examples:
         help="Path to the model configuration file to validate",
     )
 
+    # List MCP tools command
+    list_mcp_parser: ArgumentParser = subparsers.add_parser(
+        "list-mcp-tools",
+        help="List available MCP tools from configuration",
+        description="""
+List all available MCP tools from the configured MCP servers.
+This command shows:
+- All MCP servers/functions in the configuration
+- Available tools from each server
+- Full descriptions for each tool (no truncation)
+- Tool parameters in readable format (type, required/optional, descriptions)
+- Which tools are included/excluded based on filters
+- Filter patterns (include_tools, exclude_tools)
+
+Use this command to:
+- Discover available tools before configuring agents
+- Review tool descriptions and parameter schemas
+- Debug tool filtering configuration
+- Verify MCP server connectivity
+
+Options:
+- Use --apply-filters to only show tools that will be loaded (hides excluded tools)
+- Without --apply-filters, see all available tools with include/exclude status
+
+Note: Schemas are displayed in a concise, readable format instead of verbose JSON
+        """,
+        epilog="""Examples:
+  dao-ai list-mcp-tools -c config/model_config.yaml
+  dao-ai list-mcp-tools -c config/model_config.yaml --apply-filters
+        """,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    list_mcp_parser.add_argument(
+        "-c",
+        "--config",
+        type=str,
+        default="./config/model_config.yaml",
+        required=False,
+        metavar="FILE",
+        help="Path to the model configuration file (default: ./config/model_config.yaml)",
+    )
+    list_mcp_parser.add_argument(
+        "--apply-filters",
+        action="store_true",
+        help="Only show tools that pass include/exclude filters (hide excluded tools)",
+    )
+
     chat_parser: ArgumentParser = subparsers.add_parser(
         "chat",
         help="Interactive chat with the DAO AI system",
@@ -704,6 +752,275 @@ def handle_validate_command(options: Namespace) -> None:
         sys.exit(1)
 
 
+def _format_schema_pretty(schema: dict[str, Any], indent: int = 0) -> str:
+    """
+    Format a JSON schema in a more readable, concise format.
+
+    Args:
+        schema: The JSON schema to format
+        indent: Current indentation level
+
+    Returns:
+        Pretty-formatted schema string
+    """
+    if not schema:
+        return ""
+
+    lines: list[str] = []
+    indent_str = "  " * indent
+
+    # Get required fields
+    required_fields = set(schema.get("required", []))
+
+    # Handle object type with properties
+    if schema.get("type") == "object" and "properties" in schema:
+        properties = schema["properties"]
+
+        for prop_name, prop_schema in properties.items():
+            is_required = prop_name in required_fields
+            req_marker = " (required)" if is_required else " (optional)"
+
+            prop_type = prop_schema.get("type", "any")
+            prop_desc = prop_schema.get("description", "")
+
+            # Handle different types
+            if prop_type == "array":
+                items = prop_schema.get("items", {})
+                item_type = items.get("type", "any")
+                type_str = f"array<{item_type}>"
+            elif prop_type == "object":
+                type_str = "object"
+            else:
+                type_str = prop_type
+
+            # Format enum values if present
+            if "enum" in prop_schema:
+                enum_values = ", ".join(str(v) for v in prop_schema["enum"])
+                type_str = f"{type_str} (one of: {enum_values})"
+
+            # Build the line
+            line = f"{indent_str}{prop_name}: {type_str}{req_marker}"
+            if prop_desc:
+                line += f"\n{indent_str}  └─ {prop_desc}"
+
+            lines.append(line)
+
+            # Recursively handle nested objects
+            if prop_type == "object" and "properties" in prop_schema:
+                nested = _format_schema_pretty(prop_schema, indent + 1)
+                if nested:
+                    lines.append(nested)
+
+    # Handle simple types without properties
+    elif "type" in schema:
+        schema_type = schema["type"]
+        if schema.get("description"):
+            lines.append(f"{indent_str}Type: {schema_type}")
+            lines.append(f"{indent_str}└─ {schema['description']}")
+        else:
+            lines.append(f"{indent_str}Type: {schema_type}")
+
+    return "\n".join(lines)
+
+
+def handle_list_mcp_tools_command(options: Namespace) -> None:
+    """
+    List available MCP tools from configuration.
+
+    Shows all MCP servers and their available tools, indicating which
+    are included/excluded based on filter configuration.
+    """
+    logger.debug(f"Listing MCP tools from configuration: {options.config}")
+
+    try:
+        from dao_ai.config import McpFunctionModel
+        from dao_ai.tools.mcp import MCPToolInfo, _matches_pattern, list_mcp_tools
+
+        # Load configuration
+        config: AppConfig = AppConfig.from_file(options.config)
+
+        # Find all MCP tools in configuration
+        mcp_tools_config: list[tuple[str, McpFunctionModel]] = []
+        if config.tools:
+            for tool_name, tool_model in config.tools.items():
+                logger.debug(
+                    f"Checking tool: {tool_name}, function type: {type(tool_model.function)}"
+                )
+                if tool_model.function and isinstance(
+                    tool_model.function, McpFunctionModel
+                ):
+                    mcp_tools_config.append((tool_name, tool_model.function))
+
+        if not mcp_tools_config:
+            logger.warning("No MCP tools found in configuration")
+            print("\n⚠️  No MCP tools configured in this file.")
+            print(f"   Configuration: {options.config}")
+            print(
+                "\nTo add MCP tools, define them in the 'tools' section with 'type: mcp'"
+            )
+            sys.exit(0)
+
+        # Collect all results first (aggregate before displaying)
+        results: list[dict[str, Any]] = []
+        for tool_name, mcp_function in mcp_tools_config:
+            result = {
+                "tool_name": tool_name,
+                "mcp_function": mcp_function,
+                "error": None,
+                "all_tools": [],
+                "included_tools": [],
+                "excluded_tools": [],
+            }
+
+            try:
+                logger.info(f"Connecting to MCP server: {mcp_function.mcp_url}")
+
+                # Get all available tools (unfiltered)
+                all_tools: list[MCPToolInfo] = list_mcp_tools(
+                    mcp_function, apply_filters=False
+                )
+
+                # Get filtered tools (what will actually be loaded)
+                filtered_tools: list[MCPToolInfo] = list_mcp_tools(
+                    mcp_function, apply_filters=True
+                )
+
+                included_names = {t.name for t in filtered_tools}
+
+                # Categorize tools
+                for tool in sorted(all_tools, key=lambda t: t.name):
+                    if tool.name in included_names:
+                        result["included_tools"].append(tool)
+                    else:
+                        # Determine why it was excluded
+                        reason = ""
+                        if mcp_function.exclude_tools:
+                            if _matches_pattern(tool.name, mcp_function.exclude_tools):
+                                matching_patterns = [
+                                    p
+                                    for p in mcp_function.exclude_tools
+                                    if _matches_pattern(tool.name, [p])
+                                ]
+                                reason = f" (matches exclude pattern: {', '.join(matching_patterns)})"
+                        if not reason and mcp_function.include_tools:
+                            reason = " (not in include list)"
+                        result["excluded_tools"].append((tool, reason))
+
+                result["all_tools"] = all_tools
+
+            except KeyboardInterrupt:
+                result["error"] = "Connection interrupted by user"
+                results.append(result)
+                break
+            except Exception as e:
+                logger.error(f"Failed to list tools from MCP server: {e}")
+                result["error"] = str(e)
+
+            results.append(result)
+
+        # Now display all results at once (no logging interleaving)
+        print(f"\n{'=' * 80}")
+        print("MCP TOOLS DISCOVERY")
+        print(f"Configuration: {options.config}")
+        print(f"{'=' * 80}\n")
+
+        for result in results:
+            tool_name = result["tool_name"]
+            mcp_function = result["mcp_function"]
+
+            print(f"📦 Tool: {tool_name}")
+            print(f"   Server: {mcp_function.mcp_url}")
+
+            # Show connection type
+            if mcp_function.connection:
+                print(f"   Connection: UC Connection '{mcp_function.connection.name}'")
+            else:
+                print(f"   Transport: {mcp_function.transport.value}")
+
+            # Show filters if configured
+            if mcp_function.include_tools or mcp_function.exclude_tools:
+                print("\n   Filters:")
+                if mcp_function.include_tools:
+                    print(f"     Include: {', '.join(mcp_function.include_tools)}")
+                if mcp_function.exclude_tools:
+                    print(f"     Exclude: {', '.join(mcp_function.exclude_tools)}")
+
+            # Check for errors
+            if result["error"]:
+                print(f"\n   ❌ Error: {result['error']}")
+                print("   Could not connect to MCP server")
+                if result["error"] != "Connection interrupted by user":
+                    print(
+                        "   Tip: Verify server URL, authentication, and network connectivity"
+                    )
+            else:
+                all_tools = result["all_tools"]
+                included_tools = result["included_tools"]
+                excluded_tools = result["excluded_tools"]
+
+                # Show stats based on --apply-filters flag
+                if options.apply_filters:
+                    # Simplified view: only show filtered tools count
+                    print(
+                        f"\n   Available Tools: {len(included_tools)} (after filters)"
+                    )
+                else:
+                    # Full view: show all, included, and excluded counts
+                    print(f"\n   Available Tools: {len(all_tools)} total")
+                    print(f"   ├─ ✓ Included: {len(included_tools)}")
+                    print(f"   └─ ✗ Excluded: {len(excluded_tools)}")
+
+                # Show included tools with FULL descriptions and schemas
+                if included_tools:
+                    if options.apply_filters:
+                        print(f"\n   Tools ({len(included_tools)}):")
+                    else:
+                        print(f"\n   ✓ Included Tools ({len(included_tools)}):")
+
+                    for tool in included_tools:
+                        print(f"\n     • {tool.name}")
+                        if tool.description:
+                            # Show full description (no truncation)
+                            print(f"       Description: {tool.description}")
+                        if tool.input_schema:
+                            # Pretty print schema in readable format
+                            print("       Parameters:")
+                            pretty_schema = _format_schema_pretty(
+                                tool.input_schema, indent=0
+                            )
+                            if pretty_schema:
+                                # Indent the schema for better readability
+                                for line in pretty_schema.split("\n"):
+                                    print(f"         {line}")
+                            else:
+                                print("         (none)")
+
+                # Show excluded tools only if NOT applying filters
+                if excluded_tools and not options.apply_filters:
+                    print(f"\n   ✗ Excluded Tools ({len(excluded_tools)}):")
+                    for tool, reason in excluded_tools:
+                        print(f"     • {tool.name}{reason}")
+
+            print(f"\n{'-' * 80}\n")
+
+        # Summary
+        print(f"{'=' * 80}")
+        print(f"Summary: Found {len(mcp_tools_config)} MCP server(s)")
+        print(f"{'=' * 80}\n")
+
+        sys.exit(0)
+
+    except FileNotFoundError:
+        logger.error(f"Configuration file not found: {options.config}")
+        print(f"\n❌ Error: Configuration file not found: {options.config}")
+        sys.exit(1)
+    except Exception as e:
+        logger.error(f"Failed to list MCP tools: {e}")
+        logger.debug(traceback.format_exc())
+        print(f"\n❌ Error: {e}")
+        sys.exit(1)
+
+
 def setup_logging(verbosity: int) -> None:
     levels: dict[int, str] = {
         0: "ERROR",
@@ -925,6 +1242,8 @@ def main() -> None:
             handle_deploy_command(options)
         case "chat":
             handle_chat_command(options)
+        case "list-mcp-tools":
+            handle_list_mcp_tools_command(options)
         case _:
             logger.error(f"Unknown command: {options.command}")
             sys.exit(1)

dao_ai/config.py

@@ -391,10 +391,17 @@ class PermissionModel(BaseModel):
 
 class SchemaModel(BaseModel, HasFullName):
     model_config = ConfigDict(use_enum_values=True, extra="forbid")
-    catalog_name: str
-    schema_name: str
+    catalog_name: AnyVariable
+    schema_name: AnyVariable
     permissions: Optional[list[PermissionModel]] = Field(default_factory=list)
 
+    @model_validator(mode="after")
+    def resolve_variables(self) -> Self:
+        """Resolve AnyVariable fields to their actual string values."""
+        self.catalog_name = value_of(self.catalog_name)
+        self.schema_name = value_of(self.schema_name)
+        return self
+
     @property
     def full_name(self) -> str:
         return f"{self.catalog_name}.{self.schema_name}"
@@ -410,7 +417,13 @@ class SchemaModel(BaseModel, HasFullName):
 class DatabricksAppModel(IsDatabricksResource, HasFullName):
     model_config = ConfigDict(use_enum_values=True, extra="forbid")
     name: str
-    url: str
+    url: AnyVariable
+
+    @model_validator(mode="after")
+    def resolve_variables(self) -> Self:
+        """Resolve AnyVariable fields to their actual string values."""
+        self.url = value_of(self.url)
+        return self
 
     @property
     def full_name(self) -> str:
@@ -1845,6 +1858,26 @@ class McpFunctionModel(BaseFunctionModel, IsDatabricksResource):
     genie_room: Optional[GenieRoomModel] = None
     sql: Optional[bool] = None
     vector_search: Optional[VectorStoreModel] = None
+    # Tool filtering
+    include_tools: Optional[list[str]] = Field(
+        default=None,
+        description=(
+            "Optional list of tool names or glob patterns to include from the MCP server. "
+            "If specified, only tools matching these patterns will be loaded. "
+            "Supports glob patterns: * (any chars), ? (single char), [abc] (char set). "
+            "Examples: ['execute_query', 'list_*', 'get_?_data']"
+        ),
+    )
+    exclude_tools: Optional[list[str]] = Field(
+        default=None,
+        description=(
+            "Optional list of tool names or glob patterns to exclude from the MCP server. "
+            "Tools matching these patterns will not be loaded. "
+            "Takes precedence over include_tools. "
+            "Supports glob patterns: * (any chars), ? (single char), [abc] (char set). "
+            "Examples: ['drop_*', 'delete_*', 'execute_ddl']"
+        ),
+    )
 
     @property
     def api_scopes(self) -> Sequence[str]:
@@ -2020,6 +2053,26 @@ class McpFunctionModel(BaseFunctionModel, IsDatabricksResource):
             self.headers[key] = value_of(value)
         return self
 
+    @model_validator(mode="after")
+    def validate_tool_filters(self) -> "McpFunctionModel":
+        """Validate tool filter configuration."""
+        from loguru import logger
+
+        # Warn if both are empty lists (explicit but pointless)
+        if self.include_tools is not None and len(self.include_tools) == 0:
+            logger.warning(
+                "include_tools is empty list - no tools will be loaded. "
+                "Remove field to load all tools."
+            )
+
+        if self.exclude_tools is not None and len(self.exclude_tools) == 0:
+            logger.warning(
+                "exclude_tools is empty list - has no effect. "
+                "Remove field or add patterns."
+            )
+
+        return self
+
     def as_tools(self, **kwargs: Any) -> Sequence[RunnableLike]:
         from dao_ai.tools import create_mcp_tools
 

dao_ai/middleware/__init__.py

@@ -6,6 +6,7 @@ from langchain.agents.middleware import (
     ClearToolUsesEdit,
     ContextEditingMiddleware,
     HumanInTheLoopMiddleware,
+    LLMToolSelectorMiddleware,
     ModelCallLimitMiddleware,
     ModelRetryMiddleware,
     PIIMiddleware,
@@ -82,6 +83,7 @@ from dao_ai.middleware.summarization import (
 )
 from dao_ai.middleware.tool_call_limit import create_tool_call_limit_middleware
 from dao_ai.middleware.tool_retry import create_tool_retry_middleware
+from dao_ai.middleware.tool_selector import create_llm_tool_selector_middleware
 
 __all__ = [
     # Base class (from LangChain)
@@ -105,6 +107,7 @@ __all__ = [
     "ModelCallLimitMiddleware",
     "ToolRetryMiddleware",
     "ModelRetryMiddleware",
+    "LLMToolSelectorMiddleware",
     "ContextEditingMiddleware",
     "ClearToolUsesEdit",
     "PIIMiddleware",
@@ -150,6 +153,8 @@ __all__ = [
     "create_model_call_limit_middleware",
     "create_tool_retry_middleware",
     "create_model_retry_middleware",
+    # Tool selection middleware factory functions
+    "create_llm_tool_selector_middleware",
     # Context editing middleware factory functions
     "create_context_editing_middleware",
     "create_clear_tool_uses_edit",

dao_ai/middleware/tool_selector.py

@@ -0,0 +1,129 @@
+"""
+Tool selector middleware for intelligently filtering tools before LLM calls.
+
+This middleware uses an LLM to select relevant tools from a large set, improving
+performance and accuracy by reducing context size and improving focus.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain.agents.middleware import LLMToolSelectorMiddleware
+from langchain_core.language_models import LanguageModelLike
+from loguru import logger
+
+from dao_ai.config import ToolModel
+
+
+def create_llm_tool_selector_middleware(
+    model: LanguageModelLike,
+    max_tools: int = 3,
+    always_include: list[str | ToolModel | dict[str, Any]] | None = None,
+) -> LLMToolSelectorMiddleware:
+    """
+    Create an LLMToolSelectorMiddleware for intelligent tool selection.
+
+    Uses an LLM to analyze the current query and select the most relevant tools
+    before calling the main model. This is particularly useful for agents with
+    many tools (10+) where most aren't relevant for any given query.
+
+    Benefits:
+    - Reduces token usage by filtering irrelevant tools
+    - Improves model focus and accuracy
+    - Optimizes cost for agents with large tool sets
+    - Maintains context window efficiency
+
+    Args:
+        model: The LLM to use for tool selection. Typically a smaller, faster
+            model like "gpt-4o-mini" or similar.
+        max_tools: Maximum number of tools to select for each query.
+            Default 3. Adjust based on your use case - higher values
+            increase context but improve tool coverage.
+        always_include: List of tools that should always be included regardless
+            of the LLM's selection. Can be:
+            - str: Tool name
+            - ToolModel: Full tool configuration
+            - dict: Tool configuration dictionary
+            Use this for critical tools that should always be available.
+
+    Returns:
+        LLMToolSelectorMiddleware configured with the specified parameters
+
+    Example:
+        from dao_ai.middleware import create_llm_tool_selector_middleware
+        from dao_ai.llms import create_llm
+
+        # Use a fast, cheap model for tool selection
+        selector_llm = create_llm("databricks-gpt-4o-mini")
+
+        middleware = create_llm_tool_selector_middleware(
+            model=selector_llm,
+            max_tools=3,
+            always_include=["search_web"],  # Always include search
+        )
+
+    Use Cases:
+        - Large tool sets (10+ tools) where most are specialized
+        - Cost optimization by reducing tokens in main model calls
+        - Improved accuracy by reducing tool confusion
+        - Dynamic tool filtering based on query relevance
+
+    Note:
+        The selector model makes an additional LLM call for each agent turn.
+        Choose a fast, inexpensive model to minimize latency and cost overhead.
+    """
+    # Extract tool names from always_include
+    always_include_names: list[str] = []
+    if always_include:
+        always_include_names = _resolve_tool_names(always_include)
+
+    logger.debug(
+        "Creating LLM tool selector middleware",
+        max_tools=max_tools,
+        always_include_count=len(always_include_names),
+        always_include=always_include_names,
+    )
+
+    return LLMToolSelectorMiddleware(
+        model=model,
+        max_tools=max_tools,
+        always_include=always_include_names if always_include_names else None,
+    )
+
+
+def _resolve_tool_names(tools: list[str | ToolModel | dict[str, Any]]) -> list[str]:
+    """
+    Extract tool names from a list of tool specifications.
+
+    Args:
+        tools: List of tool specifications (strings, ToolModels, or dicts)
+
+    Returns:
+        List of tool names as strings
+    """
+    names: list[str] = []
+
+    for tool_spec in tools:
+        if isinstance(tool_spec, str):
+            # Simple string tool name
+            names.append(tool_spec)
+        elif isinstance(tool_spec, ToolModel):
+            # ToolModel - use its name
+            names.append(tool_spec.name)
+        elif isinstance(tool_spec, dict):
+            # Dictionary - try to extract name
+            if "name" in tool_spec:
+                names.append(tool_spec["name"])
+            else:
+                logger.warning(
+                    "Tool dict missing 'name' field, skipping",
+                    tool_spec=tool_spec,
+                )
+        else:
+            logger.warning(
+                "Unknown tool specification type, skipping",
+                tool_spec_type=type(tool_spec).__name__,
+            )
+
+    return names

dao_ai/prompts.py

@@ -61,19 +61,14 @@ def make_prompt(
     @dynamic_prompt
     def dynamic_system_prompt(request: ModelRequest) -> str:
         """Generate dynamic system prompt based on runtime context."""
-        # Get parameters from runtime context
+        # Initialize parameters for template variables
         params: dict[str, Any] = {
             input_variable: "" for input_variable in prompt_template.input_variables
         }
 
-        # Access context from runtime
+        # Apply context fields as template parameters
         context: Context = request.runtime.context
         if context:
-            if context.user_id and "user_id" in params:
-                params["user_id"] = context.user_id
-            if context.thread_id and "thread_id" in params:
-                params["thread_id"] = context.thread_id
-            # Apply all context fields as template parameters
             context_dict = context.model_dump()
             for key, value in context_dict.items():
                 if key in params and value is not None:
@@ -89,56 +84,3 @@ def make_prompt(
         return formatted_prompt
 
     return dynamic_system_prompt
-
-
-def create_prompt_middleware(
-    base_system_prompt: Optional[str | PromptModel],
-) -> AgentMiddleware | None:
-    """
-    Create a dynamic prompt middleware from configuration.
-
-    This always returns an AgentMiddleware suitable for use with
-    LangChain v1's middleware system.
-
-    Args:
-        base_system_prompt: The system prompt string or PromptModel
-
-    Returns:
-        An AgentMiddleware created by @dynamic_prompt, or None if no prompt
-    """
-    if not base_system_prompt:
-        return None
-
-    # Extract template string from PromptModel or use string directly
-    template_str: str
-    if isinstance(base_system_prompt, PromptModel):
-        template_str = base_system_prompt.template
-    else:
-        template_str = base_system_prompt
-
-    prompt_template: PromptTemplate = PromptTemplate.from_template(template_str)
-
-    @dynamic_prompt
-    def prompt_middleware(request: ModelRequest) -> str:
-        """Generate system prompt based on runtime context."""
-        # Get parameters from runtime context
-        params: dict[str, Any] = {
-            input_variable: "" for input_variable in prompt_template.input_variables
-        }
-
-        # Access context from runtime
-        context: Context = request.runtime.context
-        if context:
-            # Apply all context fields as template parameters
-            context_dict = context.model_dump()
-            for key, value in context_dict.items():
-                if key in params and value is not None:
-                    params[key] = value
-
-        # Format the prompt
-        formatted_prompt: str = prompt_template.format(**params)
-        logger.trace("Formatted dynamic prompt with context")
-
-        return formatted_prompt
-
-    return prompt_middleware

dao_ai/tools/__init__.py

@@ -4,7 +4,7 @@ from dao_ai.tools.agent import create_agent_endpoint_tool
 from dao_ai.tools.core import create_tools, say_hello_tool
 from dao_ai.tools.email import create_send_email_tool
 from dao_ai.tools.genie import create_genie_tool
-from dao_ai.tools.mcp import create_mcp_tools
+from dao_ai.tools.mcp import MCPToolInfo, create_mcp_tools, list_mcp_tools
 from dao_ai.tools.memory import create_search_memory_tool
 from dao_ai.tools.python import create_factory_tool, create_python_tool
 from dao_ai.tools.search import create_search_tool
@@ -30,6 +30,8 @@ __all__ = [
     "create_genie_tool",
     "create_hooks",
     "create_mcp_tools",
+    "list_mcp_tools",
+    "MCPToolInfo",
     "create_python_tool",
     "create_search_memory_tool",
     "create_search_tool",

dao_ai/tools/mcp.py

@@ -7,10 +7,16 @@ MCP SDK and langchain-mcp-adapters library.
 For compatibility with Databricks APIs, we use manual tool wrappers
 that give us full control over the response format.
 
+Public API:
+- list_mcp_tools(): List available tools from an MCP server (for discovery/UI)
+- create_mcp_tools(): Create LangChain tools for agent execution
+
 Reference: https://docs.langchain.com/oss/python/langchain/mcp
 """
 
 import asyncio
+import fnmatch
+from dataclasses import dataclass
 from typing import Any, Sequence
 
 from langchain_core.runnables.base import RunnableLike
@@ -26,6 +32,117 @@ from dao_ai.config import (
 )
 
 
+@dataclass
+class MCPToolInfo:
+    """
+    Information about an MCP tool for display and selection.
+
+    This is a simplified representation of an MCP tool that contains
+    only the information needed for UI display and tool selection.
+    It's designed to be easily serializable for use in web UIs.
+
+    Attributes:
+        name: The unique identifier/name of the tool
+        description: Human-readable description of what the tool does
+        input_schema: JSON Schema describing the tool's input parameters
+    """
+
+    name: str
+    description: str | None
+    input_schema: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": self.input_schema,
+        }
+
+
+def _matches_pattern(tool_name: str, patterns: list[str]) -> bool:
+    """
+    Check if tool name matches any of the provided patterns.
+
+    Supports glob patterns:
+    - * matches any characters
+    - ? matches single character
+    - [abc] matches any char in set
+    - [!abc] matches any char NOT in set
+
+    Args:
+        tool_name: Name of the tool to check
+        patterns: List of exact names or glob patterns
+
+    Returns:
+        True if tool name matches any pattern
+
+    Examples:
+        >>> _matches_pattern("query_sales", ["query_*"])
+        True
+        >>> _matches_pattern("list_tables", ["query_*"])
+        False
+        >>> _matches_pattern("tool_a", ["tool_?"])
+        True
+    """
+    for pattern in patterns:
+        if fnmatch.fnmatch(tool_name, pattern):
+            return True
+    return False
+
+
+def _should_include_tool(
+    tool_name: str,
+    include_tools: list[str] | None,
+    exclude_tools: list[str] | None,
+) -> bool:
+    """
+    Determine if a tool should be included based on include/exclude filters.
+
+    Logic:
+    1. If exclude_tools specified and tool matches: EXCLUDE (highest priority)
+    2. If include_tools specified and tool matches: INCLUDE
+    3. If include_tools specified and tool doesn't match: EXCLUDE
+    4. If no filters specified: INCLUDE (default)
+
+    Args:
+        tool_name: Name of the tool
+        include_tools: Optional list of tools/patterns to include
+        exclude_tools: Optional list of tools/patterns to exclude
+
+    Returns:
+        True if tool should be included
+
+    Examples:
+        >>> _should_include_tool("query_sales", ["query_*"], None)
+        True
+        >>> _should_include_tool("drop_table", None, ["drop_*"])
+        False
+        >>> _should_include_tool("query_sales", ["query_*"], ["*_sales"])
+        False  # exclude takes precedence
+    """
+    # Exclude has highest priority
+    if exclude_tools and _matches_pattern(tool_name, exclude_tools):
+        logger.debug("Tool excluded by exclude_tools", tool_name=tool_name)
+        return False
+
+    # If include list exists, tool must match it
+    if include_tools:
+        if _matches_pattern(tool_name, include_tools):
+            logger.debug("Tool included by include_tools", tool_name=tool_name)
+            return True
+        else:
+            logger.debug(
+                "Tool not in include_tools",
+                tool_name=tool_name,
+                include_patterns=include_tools,
+            )
+            return False
+
+    # Default: include all tools
+    return True
+
+
 def _build_connection_config(
     function: McpFunctionModel,
 ) -> dict[str, Any]:
@@ -124,69 +241,33 @@ def _extract_text_content(result: CallToolResult) -> str:
     return "\n".join(text_parts)
 
 
-def create_mcp_tools(
-    function: McpFunctionModel,
-) -> Sequence[RunnableLike]:
+def _fetch_tools_from_server(function: McpFunctionModel) -> list[Tool]:
     """
-    Create tools for invoking Databricks MCP functions.
+    Fetch raw MCP tools from the server.
 
-    Supports both direct MCP connections and UC Connection-based MCP access.
-    Uses manual tool wrappers to ensure response format compatibility with
-    Databricks APIs (which reject extra fields in tool results).
-
-    Based on: https://docs.databricks.com/aws/en/generative-ai/mcp/external-mcp
+    This is the core async operation that connects to the MCP server
+    and retrieves the list of available tools.
 
     Args:
         function: The MCP function model configuration.
 
     Returns:
-        A sequence of LangChain tools that can be used by agents.
-    """
-    mcp_url = function.mcp_url
-    logger.debug("Creating MCP tools", mcp_url=mcp_url)
+        List of raw MCP Tool objects from the server.
 
+    Raises:
+        RuntimeError: If connection to MCP server fails.
+    """
     connection_config = _build_connection_config(function)
-
-    if function.connection:
-        logger.debug(
-            "Using UC Connection for MCP",
-            connection_name=function.connection.name,
-            mcp_url=mcp_url,
-        )
-    else:
-        logger.debug(
-            "Using direct connection for MCP",
-            transport=function.transport,
-            mcp_url=mcp_url,
-        )
-
-    # Create client to list available tools
     client = MultiServerMCPClient({"mcp_function": connection_config})
 
-    async def _list_tools() -> list[Tool]:
-        """List available MCP tools from the server."""
+    async def _list_tools_async() -> list[Tool]:
+        """Async helper to list tools from MCP server."""
         async with client.session("mcp_function") as session:
             result = await session.list_tools()
             return result.tools if hasattr(result, "tools") else list(result)
 
     try:
-        mcp_tools: list[Tool] = asyncio.run(_list_tools())
-
-        # Log discovered tools
-        logger.info(
-            "Discovered MCP tools",
-            tools_count=len(mcp_tools),
-            mcp_url=mcp_url,
-        )
-        for mcp_tool in mcp_tools:
-            logger.debug(
-                "MCP tool discovered",
-                tool_name=mcp_tool.name,
-                tool_description=(
-                    mcp_tool.description[:100] if mcp_tool.description else None
-                ),
-            )
-
+        return asyncio.run(_list_tools_async())
     except Exception as e:
         if function.connection:
             logger.error(
@@ -210,6 +291,216 @@ def create_mcp_tools(
                 f"and URL '{function.url}': {e}"
             ) from e
 
+
+def list_mcp_tools(
+    function: McpFunctionModel,
+    apply_filters: bool = True,
+) -> list[MCPToolInfo]:
+    """
+    List available tools from an MCP server.
+
+    This function connects to an MCP server and returns information about
+    all available tools. It's designed for:
+    - Tool discovery and exploration
+    - UI-based tool selection (e.g., in DAO AI Builder)
+    - Debugging and validation of MCP configurations
+
+    The returned MCPToolInfo objects contain all information needed to
+    display tools in a UI and allow users to select which tools to use.
+
+    Args:
+        function: The MCP function model configuration containing:
+            - Connection details (url, connection, headers, etc.)
+            - Optional filtering (include_tools, exclude_tools)
+        apply_filters: Whether to apply include_tools/exclude_tools filters.
+            Set to False to get the complete list of available tools
+            regardless of filter configuration. Default True.
+
+    Returns:
+        List of MCPToolInfo objects describing available tools.
+        Each contains name, description, and input_schema.
+
+    Raises:
+        RuntimeError: If connection to MCP server fails.
+
+    Example:
+        # List all tools from a DBSQL MCP server
+        from dao_ai.config import McpFunctionModel
+        from dao_ai.tools.mcp import list_mcp_tools
+
+        function = McpFunctionModel(sql=True)
+        tools = list_mcp_tools(function)
+
+        for tool in tools:
+            print(f"{tool.name}: {tool.description}")
+
+        # Get unfiltered list (ignore include_tools/exclude_tools)
+        all_tools = list_mcp_tools(function, apply_filters=False)
+
+    Note:
+        For creating executable LangChain tools, use create_mcp_tools() instead.
+        This function is for discovery/display purposes only.
+    """
+    mcp_url = function.mcp_url
+    logger.debug("Listing MCP tools", mcp_url=mcp_url, apply_filters=apply_filters)
+
+    # Log connection type
+    if function.connection:
+        logger.debug(
+            "Using UC Connection for MCP",
+            connection_name=function.connection.name,
+            mcp_url=mcp_url,
+        )
+    else:
+        logger.debug(
+            "Using direct connection for MCP",
+            transport=function.transport,
+            mcp_url=mcp_url,
+        )
+
+    # Fetch tools from server
+    mcp_tools: list[Tool] = _fetch_tools_from_server(function)
+
+    # Log discovered tools
+    logger.info(
+        "Discovered MCP tools from server",
+        tools_count=len(mcp_tools),
+        tool_names=[t.name for t in mcp_tools],
+        mcp_url=mcp_url,
+    )
+
+    # Apply filtering if requested and configured
+    if apply_filters and (function.include_tools or function.exclude_tools):
+        original_count = len(mcp_tools)
+        mcp_tools = [
+            tool
+            for tool in mcp_tools
+            if _should_include_tool(
+                tool.name,
+                function.include_tools,
+                function.exclude_tools,
+            )
+        ]
+        filtered_count = original_count - len(mcp_tools)
+
+        logger.info(
+            "Filtered MCP tools",
+            original_count=original_count,
+            filtered_count=filtered_count,
+            final_count=len(mcp_tools),
+            include_patterns=function.include_tools,
+            exclude_patterns=function.exclude_tools,
+        )
+
+    # Convert to MCPToolInfo for cleaner API
+    tool_infos: list[MCPToolInfo] = []
+    for mcp_tool in mcp_tools:
+        tool_info = MCPToolInfo(
+            name=mcp_tool.name,
+            description=mcp_tool.description,
+            input_schema=mcp_tool.inputSchema or {},
+        )
+        tool_infos.append(tool_info)
+
+        logger.debug(
+            "MCP tool available",
+            tool_name=mcp_tool.name,
+            tool_description=(
+                mcp_tool.description[:100] if mcp_tool.description else None
+            ),
+        )
+
+    return tool_infos
+
+
+def create_mcp_tools(
+    function: McpFunctionModel,
+) -> Sequence[RunnableLike]:
+    """
+    Create executable LangChain tools for invoking Databricks MCP functions.
+
+    Supports both direct MCP connections and UC Connection-based MCP access.
+    Uses manual tool wrappers to ensure response format compatibility with
+    Databricks APIs (which reject extra fields in tool results).
+
+    This function:
+    1. Fetches available tools from the MCP server
+    2. Applies include_tools/exclude_tools filters
+    3. Wraps each tool for LangChain agent execution
+
+    For tool discovery without creating executable tools, use list_mcp_tools().
+
+    Based on: https://docs.databricks.com/aws/en/generative-ai/mcp/external-mcp
+
+    Args:
+        function: The MCP function model configuration containing:
+            - Connection details (url, connection, headers, etc.)
+            - Optional filtering (include_tools, exclude_tools)
+
+    Returns:
+        A sequence of LangChain tools that can be used by agents.
+
+    Raises:
+        RuntimeError: If connection to MCP server fails.
+
+    Example:
+        from dao_ai.config import McpFunctionModel
+        from dao_ai.tools.mcp import create_mcp_tools
+
+        function = McpFunctionModel(sql=True)
+        tools = create_mcp_tools(function)
+
+        # Use tools in an agent
+        agent = create_agent(model=model, tools=tools)
+    """
+    mcp_url = function.mcp_url
+    logger.debug("Creating MCP tools", mcp_url=mcp_url)
+
+    # Fetch and filter tools using shared logic
+    # We need the raw Tool objects here, not MCPToolInfo
+    mcp_tools: list[Tool] = _fetch_tools_from_server(function)
+
+    # Log discovered tools
+    logger.info(
+        "Discovered MCP tools from server",
+        tools_count=len(mcp_tools),
+        tool_names=[t.name for t in mcp_tools],
+        mcp_url=mcp_url,
+    )
+
+    # Apply filtering if configured
+    if function.include_tools or function.exclude_tools:
+        original_count = len(mcp_tools)
+        mcp_tools = [
+            tool
+            for tool in mcp_tools
+            if _should_include_tool(
+                tool.name,
+                function.include_tools,
+                function.exclude_tools,
+            )
+        ]
+        filtered_count = original_count - len(mcp_tools)
+
+        logger.info(
+            "Filtered MCP tools",
+            original_count=original_count,
+            filtered_count=filtered_count,
+            final_count=len(mcp_tools),
+            include_patterns=function.include_tools,
+            exclude_patterns=function.exclude_tools,
+        )
+
+    # Log final tool list
+    for mcp_tool in mcp_tools:
+        logger.debug(
+            "MCP tool available",
+            tool_name=mcp_tool.name,
+            tool_description=(
+                mcp_tool.description[:100] if mcp_tool.description else None
+            ),
+        )
+
     def _create_tool_wrapper(mcp_tool: Tool) -> RunnableLike:
         """
         Create a LangChain tool wrapper for an MCP tool.

{dao_ai-0.1.5.dist-info → dao_ai-0.1.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dao-ai
-Version: 0.1.5
+Version: 0.1.6
 Summary: DAO AI: A modular, multi-agent orchestration framework for complex AI workflows. Supports agent handoff, tool integration, and dynamic configuration via YAML.
 Project-URL: Homepage, https://github.com/natefleming/dao-ai
 Project-URL: Documentation, https://natefleming.github.io/dao-ai

{dao_ai-0.1.5.dist-info → dao_ai-0.1.6.dist-info}/RECORD

@@ -1,15 +1,15 @@
 dao_ai/__init__.py,sha256=18P98ExEgUaJ1Byw440Ct1ty59v6nxyWtc5S6Uq2m9Q,1062
 dao_ai/agent_as_code.py,sha256=xIlLDpPVfmDVzLvbdY_V_CrC4Jvj2ItCWJ-NzdrszTo,538
 dao_ai/catalog.py,sha256=sPZpHTD3lPx4EZUtIWeQV7VQM89WJ6YH__wluk1v2lE,4947
-dao_ai/cli.py,sha256=FWzddUceOoER2EIMwBx_mIMhCWFFZHoAL3KHy7f0Euc,35377
-dao_ai/config.py,sha256=GWBmrbiixMG0ZszLk_XTRKRIS0QqOk_TIQhauK--MIY,120863
+dao_ai/cli.py,sha256=7LGrVDRgSBpznr8c8EksAhzPW_8NJ9h4St3DSpx-0z4,48196
+dao_ai/config.py,sha256=rUm2wg0TPfj6YwzSoNxy6rgHi6GKWxXIRJ3NgGOjB04,123037
 dao_ai/graph.py,sha256=1-uQlo7iXZQTT3uU8aYu0N5rnhw5_g_2YLwVsAs6M-U,1119
 dao_ai/logging.py,sha256=lYy4BmucCHvwW7aI3YQkQXKJtMvtTnPDu9Hnd7_O4oc,1556
 dao_ai/messages.py,sha256=4ZBzO4iFdktGSLrmhHzFjzMIt2tpaL-aQLHOQJysGnY,6959
 dao_ai/models.py,sha256=AwzwTRTNZF-UOh59HsuXEgFk_YH6q6M-mERNDe64Z8k,81783
 dao_ai/nodes.py,sha256=7W6Ek6Uk9-pKa-H06nVCwuDllCrgX02IYy3rHtuL0aM,10777
 dao_ai/optimization.py,sha256=phK6t4wYmWPObCjGUBHdZzsaFXGhQOjhAek2bAEfwXo,22971
-dao_ai/prompts.py,sha256=G0ng5f2PkzfgdKrSl03Rnd6riZn5APedof0GAzsWQI8,4792
+dao_ai/prompts.py,sha256=4cz5bZ7cOzrjyQ8hMp-K4evK6cVYrkGrAGdUl8-KDEM,2784
 dao_ai/state.py,sha256=0wbbzfQmldkCu26gdTE5j0Rl-_pfilza-YIHPbSWlvI,6394
 dao_ai/types.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 dao_ai/utils.py,sha256=_Urd7Nj2VzrgPKf3NS4E6vt0lWRhEUddBqWN9BksqeE,11543
@@ -28,7 +28,7 @@ dao_ai/memory/base.py,sha256=99nfr2UZJ4jmfTL_KrqUlRSCoRxzkZyWyx5WqeUoMdQ,338
 dao_ai/memory/core.py,sha256=38H-JLIyUrRDIECLvpXK3iJlWG35X97E-DTo_4c3Jzc,6317
 dao_ai/memory/databricks.py,sha256=SM6nwLjhSRJO4hLc3GUuht5YydYtTi3BAOae6jPwTm4,14377
 dao_ai/memory/postgres.py,sha256=q9IIAGs0wuaV-3rUIn4dtzOxbkCCoB-yv1Rtod7ohjI,16467
-dao_ai/middleware/__init__.py,sha256=scEk9Mt9POJe-j9e9t5sf3FNMNPBsu15_oxrlV9IkVE,4871
+dao_ai/middleware/__init__.py,sha256=Qy8wbvjXF7TrUzi3tWziOwxqsrUcT1rzE3UWd3x5CrU,5108
 dao_ai/middleware/assertions.py,sha256=C1K-TnNZfBEwWouioHCt6c48i1ux9QKfQaX6AzghhgE,27408
 dao_ai/middleware/base.py,sha256=uG2tpdnjL5xY5jCKvb_m3UTBtl4ZC6fJQUkDsQvV8S4,1279
 dao_ai/middleware/context_editing.py,sha256=5rNKqH1phFFQTVW-4nzlVH5cbqomD-HFEIy2Z841D4I,7687
@@ -42,6 +42,7 @@ dao_ai/middleware/pii.py,sha256=zetfoz1WlJ-V0vjJp37v8NGimXB27EkZfetUHpGCXno,5137
 dao_ai/middleware/summarization.py,sha256=gp2s9uc4DEJat-mWjWEzMaR-zAAeUOXYvu5EEYtqae4,7143
 dao_ai/middleware/tool_call_limit.py,sha256=WQ3NmA3pLo-pNPBmwM7KwkYpT1segEnWqkhgW1xNkCE,6321
 dao_ai/middleware/tool_retry.py,sha256=QfJ7yTHneME8VtnA88QcmnjXIegSFeJztyngy49wTgM,5568
+dao_ai/middleware/tool_selector.py,sha256=POj72YdzZEiNGfW4AQXPBeVVS1RUBsiG7PBuSENEhe0,4516
 dao_ai/orchestration/__init__.py,sha256=i85CLfRR335NcCFhaXABcMkn6WZfXnJ8cHH4YZsZN0s,1622
 dao_ai/orchestration/core.py,sha256=qoU7uMXBJCth-sqfu0jRE1L0GOn5H4LoZdRUY1Ib3DI,9585
 dao_ai/orchestration/supervisor.py,sha256=alKMEEo9G5LhdpMvTVdAMel234cZj5_MguWl4wFB7XQ,9873
@@ -49,12 +50,12 @@ dao_ai/orchestration/swarm.py,sha256=8tp1eGmsQqqWpaDcjPoJckddPWohZdmmN0RGRJ_xzOA
 dao_ai/providers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 dao_ai/providers/base.py,sha256=-fjKypCOk28h6vioPfMj9YZSw_3Kcbi2nMuAyY7vX9k,1383
 dao_ai/providers/databricks.py,sha256=XxYkyoDYkwGV_Xg1IJBpGOl4d7U5HiFP4RtjjSLgenI,61437
-dao_ai/tools/__init__.py,sha256=SRd7W2DOCXKbWWy8lclRtJiCskz7SDAm94qaFF47urQ,1664
+dao_ai/tools/__init__.py,sha256=NfRpAKds_taHbx6gzLPWgtPXve-YpwzkoOAUflwxceM,1734
 dao_ai/tools/agent.py,sha256=plIWALywRjaDSnot13nYehBsrHRpBUpsVZakoGeajOE,1858
 dao_ai/tools/core.py,sha256=bRIN3BZhRQX8-Kpu3HPomliodyskCqjxynQmYbk6Vjs,3783
 dao_ai/tools/email.py,sha256=A3TsCoQgJR7UUWR0g45OPRGDpVoYwctFs1MOZMTt_d4,7389
 dao_ai/tools/genie.py,sha256=4e_5MeAe7kDzHbYeXuNPFbY5z8ci3ouj8l5254CZ2lA,8874
-dao_ai/tools/mcp.py,sha256=EFcKo_f-kPMnyR5w6oh0g4Hy4jyuVJEcUGzSiI9dXlg,8505
+dao_ai/tools/mcp.py,sha256=0OfP4b4skcjeF2rzkOLYqd65ti1Mj55N_l8VoQlH9qo,17818
 dao_ai/tools/memory.py,sha256=lwObKimAand22Nq3Y63tsv-AXQ5SXUigN9PqRjoWKes,1836
 dao_ai/tools/python.py,sha256=jWFnZPni2sCdtd8D1CqXnZIPHnWkdK27bCJnBXpzhvo,1879
 dao_ai/tools/search.py,sha256=cJ3D9FKr1GAR6xz55dLtRkjtQsI0WRueGt9TPDFpOxc,433
@@ -63,8 +64,8 @@ dao_ai/tools/sql.py,sha256=tKd1gjpLuKdQDyfmyYYtMiNRHDW6MGRbdEVaeqyB8Ok,7632
 dao_ai/tools/time.py,sha256=tufJniwivq29y0LIffbgeBTIDE6VgrLpmVf8Qr90qjw,9224
 dao_ai/tools/unity_catalog.py,sha256=AjQfW7bvV8NurqDLIyntYRv2eJuTwNdbvex1L5CRjOk,15534
 dao_ai/tools/vector_search.py,sha256=oe2uBwl2TfeJIXPpwiS6Rmz7wcHczSxNyqS9P3hE6co,14542
-dao_ai-0.1.5.dist-info/METADATA,sha256=Iz_x_25jQut9i8yghsPmQV08iyLBJdrXTAjFmYOjx1Q,16685
-dao_ai-0.1.5.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-dao_ai-0.1.5.dist-info/entry_points.txt,sha256=Xa-UFyc6gWGwMqMJOt06ZOog2vAfygV_DSwg1AiP46g,43
-dao_ai-0.1.5.dist-info/licenses/LICENSE,sha256=YZt3W32LtPYruuvHE9lGk2bw6ZPMMJD8yLrjgHybyz4,1069
-dao_ai-0.1.5.dist-info/RECORD,,
+dao_ai-0.1.6.dist-info/METADATA,sha256=eux_1l0ANLlbQnRnq0IRgc8Q-ksY6sFmQa1_Vzd5_Kc,16685
+dao_ai-0.1.6.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+dao_ai-0.1.6.dist-info/entry_points.txt,sha256=Xa-UFyc6gWGwMqMJOt06ZOog2vAfygV_DSwg1AiP46g,43
+dao_ai-0.1.6.dist-info/licenses/LICENSE,sha256=YZt3W32LtPYruuvHE9lGk2bw6ZPMMJD8yLrjgHybyz4,1069
+dao_ai-0.1.6.dist-info/RECORD,,