universal-mcp 0.1.7rc1__py3-none-any.whl → 0.1.8__py3-none-any.whl

universal_mcp/tools/__init__.py

@@ -0,0 +1,3 @@
+from .tools import Tool, ToolManager
+
+__all__ = ["Tool", "ToolManager"]

universal_mcp/tools/adapters.py

@@ -0,0 +1,43 @@
+from universal_mcp.tools.tools import Tool
+
+
+def convert_tool_to_mcp_tool(
+    tool: Tool,
+):
+    from mcp.server.fastmcp.server import MCPTool
+
+    return MCPTool(
+        name=tool.name,
+        description=tool.description or "",
+        inputSchema=tool.parameters,
+    )
+
+
+def convert_tool_to_langchain_tool(
+    tool: Tool,
+):
+    from langchain_core.tools import StructuredTool
+
+    """Convert an tool to a LangChain tool.
+
+    NOTE: this tool can be executed only in a context of an active MCP client session.
+
+    Args:
+        tool: Tool to convert
+
+    Returns:
+        a LangChain tool
+    """
+
+    async def call_tool(
+        **arguments: dict[str, any],
+    ):
+        call_tool_result = await tool.run(arguments)
+        return call_tool_result
+
+    return StructuredTool(
+        name=tool.name,
+        description=tool.description or "",
+        coroutine=call_tool,
+        response_format="content",
+    )

universal_mcp/tools/func_metadata.py

@@ -0,0 +1,213 @@
+import inspect
+import json
+from collections.abc import Awaitable, Callable, Sequence
+from typing import (
+    Annotated,
+    Any,
+    ForwardRef,
+)
+
+from mcp.server.fastmcp.exceptions import InvalidSignature
+from pydantic import BaseModel, ConfigDict, Field, WithJsonSchema, create_model
+from pydantic._internal._typing_extra import eval_type_backport
+from pydantic.fields import FieldInfo
+from pydantic_core import PydanticUndefined
+
+
+def _get_typed_annotation(annotation: Any, globalns: dict[str, Any]) -> Any:
+    def try_eval_type(
+        value: Any, globalns: dict[str, Any], localns: dict[str, Any]
+    ) -> tuple[Any, bool]:
+        try:
+            return eval_type_backport(value, globalns, localns), True
+        except NameError:
+            return value, False
+
+    if isinstance(annotation, str):
+        annotation = ForwardRef(annotation)
+        annotation, status = try_eval_type(annotation, globalns, globalns)
+
+        # This check and raise could perhaps be skipped, and we (FastMCP) just call
+        # model_rebuild right before using it 🤷
+        if status is False:
+            raise InvalidSignature(f"Unable to evaluate type annotation {annotation}")
+
+    return annotation
+
+
+def _get_typed_signature(call: Callable[..., Any]) -> inspect.Signature:
+    """Get function signature while evaluating forward references"""
+    signature = inspect.signature(call)
+    globalns = getattr(call, "__globals__", {})
+    typed_params = [
+        inspect.Parameter(
+            name=param.name,
+            kind=param.kind,
+            default=param.default,
+            annotation=_get_typed_annotation(param.annotation, globalns),
+        )
+        for param in signature.parameters.values()
+    ]
+    typed_signature = inspect.Signature(typed_params)
+    return typed_signature
+
+
+class ArgModelBase(BaseModel):
+    """A model representing the arguments to a function."""
+
+    def model_dump_one_level(self) -> dict[str, Any]:
+        """Return a dict of the model's fields, one level deep.
+
+        That is, sub-models etc are not dumped - they are kept as pydantic models.
+        """
+        kwargs: dict[str, Any] = {}
+        for field_name in self.model_fields:
+            kwargs[field_name] = getattr(self, field_name)
+        return kwargs
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+    )
+
+
+class FuncMetadata(BaseModel):
+    arg_model: Annotated[type[ArgModelBase], WithJsonSchema(None)]
+    # We can add things in the future like
+    #  - Maybe some args are excluded from attempting to parse from JSON
+    #  - Maybe some args are special (like context) for dependency injection
+
+    async def call_fn_with_arg_validation(
+        self,
+        fn: Callable[..., Any] | Awaitable[Any],
+        fn_is_async: bool,
+        arguments_to_validate: dict[str, Any],
+        arguments_to_pass_directly: dict[str, Any] | None,
+    ) -> Any:
+        """Call the given function with arguments validated and injected.
+
+        Arguments are first attempted to be parsed from JSON, then validated against
+        the argument model, before being passed to the function.
+        """
+        arguments_pre_parsed = self.pre_parse_json(arguments_to_validate)
+        arguments_parsed_model = self.arg_model.model_validate(arguments_pre_parsed)
+        arguments_parsed_dict = arguments_parsed_model.model_dump_one_level()
+
+        arguments_parsed_dict |= arguments_to_pass_directly or {}
+
+        if fn_is_async:
+            if isinstance(fn, Awaitable):
+                return await fn
+            return await fn(**arguments_parsed_dict)
+        if isinstance(fn, Callable):
+            return fn(**arguments_parsed_dict)
+        raise TypeError("fn must be either Callable or Awaitable")
+
+    def pre_parse_json(self, data: dict[str, Any]) -> dict[str, Any]:
+        """Pre-parse data from JSON.
+
+        Return a dict with same keys as input but with values parsed from JSON
+        if appropriate.
+
+        This is to handle cases like `["a", "b", "c"]` being passed in as JSON inside
+        a string rather than an actual list. Claude desktop is prone to this - in fact
+        it seems incapable of NOT doing this. For sub-models, it tends to pass
+        dicts (JSON objects) as JSON strings, which can be pre-parsed here.
+        """
+        new_data = data.copy()  # Shallow copy
+        for field_name, _field_info in self.arg_model.model_fields.items():
+            if field_name not in data:
+                continue
+            if isinstance(data[field_name], str):
+                try:
+                    pre_parsed = json.loads(data[field_name])
+                except json.JSONDecodeError:
+                    continue  # Not JSON - skip
+                if isinstance(pre_parsed, str | int | float):
+                    # This is likely that the raw value is e.g. `"hello"` which we
+                    # Should really be parsed as '"hello"' in Python - but if we parse
+                    # it as JSON it'll turn into just 'hello'. So we skip it.
+                    continue
+                new_data[field_name] = pre_parsed
+        assert new_data.keys() == data.keys()
+        return new_data
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+    )
+
+    @classmethod
+    def func_metadata(
+        cls, func: Callable[..., Any], skip_names: Sequence[str] = ()
+    ) -> "FuncMetadata":
+        """Given a function, return metadata including a pydantic model representing its
+        signature.
+
+        The use case for this is
+        ```
+        meta = func_to_pyd(func)
+        validated_args = meta.arg_model.model_validate(some_raw_data_dict)
+        return func(**validated_args.model_dump_one_level())
+        ```
+
+        **critically** it also provides pre-parse helper to attempt to parse things from
+        JSON.
+
+        Args:
+            func: The function to convert to a pydantic model
+            skip_names: A list of parameter names to skip. These will not be included in
+                the model.
+        Returns:
+            A pydantic model representing the function's signature.
+        """
+        sig = _get_typed_signature(func)
+        params = sig.parameters
+        dynamic_pydantic_model_params: dict[str, Any] = {}
+        globalns = getattr(func, "__globals__", {})
+        for param in params.values():
+            if param.name.startswith("_"):
+                raise InvalidSignature(
+                    f"Parameter {param.name} of {func.__name__} cannot start with '_'"
+                )
+            if param.name in skip_names:
+                continue
+            annotation = param.annotation
+
+            # `x: None` / `x: None = None`
+            if annotation is None:
+                annotation = Annotated[
+                    None,
+                    Field(
+                        default=param.default
+                        if param.default is not inspect.Parameter.empty
+                        else PydanticUndefined
+                    ),
+                ]
+
+            # Untyped field
+            if annotation is inspect.Parameter.empty:
+                annotation = Annotated[
+                    Any,
+                    Field(),
+                    # 🤷
+                    WithJsonSchema({"title": param.name, "type": "string"}),
+                ]
+
+            field_info = FieldInfo.from_annotated_attribute(
+                _get_typed_annotation(annotation, globalns),
+                param.default
+                if param.default is not inspect.Parameter.empty
+                else PydanticUndefined,
+            )
+            dynamic_pydantic_model_params[param.name] = (
+                field_info.annotation,
+                field_info,
+            )
+            continue
+
+        arguments_model = create_model(
+            f"{func.__name__}Arguments",
+            **dynamic_pydantic_model_params,
+            __base__=ArgModelBase,
+        )
+        resp = FuncMetadata(arg_model=arguments_model)
+        return resp

universal_mcp/tools/tools.py

@@ -0,0 +1,342 @@
+from __future__ import annotations as _annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any, Literal
+
+import httpx
+from loguru import logger
+from pydantic import BaseModel, Field
+
+from universal_mcp.analytics import analytics
+from universal_mcp.applications.application import Application
+from universal_mcp.exceptions import NotAuthorizedError, ToolError
+from universal_mcp.utils.docstring_parser import parse_docstring
+
+from .func_metadata import FuncMetadata
+
+
+def convert_tool_to_openai_tool(
+    tool: Tool,
+):
+    """Convert a Tool object to an OpenAI function."""
+    return {
+        "type": "function",
+        "function": {
+            "name": tool.name,
+            "description": tool.description,
+            "parameters": tool.parameters,
+        },
+    }
+
+
+def convert_tool_to_mcp_tool(
+    tool: Tool,
+):
+    from mcp.server.fastmcp.server import MCPTool
+
+    return MCPTool(
+        name=tool.name,
+        description=tool.description or "",
+        inputSchema=tool.parameters,
+    )
+
+
+def convert_tool_to_langchain_tool(
+    tool: Tool,
+):
+    """Convert a Tool object to a LangChain StructuredTool.
+
+    NOTE: this tool can be executed only in a context of an active MCP client session.
+
+    Args:
+        tool: Tool object to convert
+
+    Returns:
+        a LangChain StructuredTool
+    """
+    from langchain_core.tools import (  # Keep import inside if preferred, or move top
+        StructuredTool,
+        ToolException,
+    )
+
+    async def call_tool(
+        **arguments: dict[
+            str, any
+        ],  # arguments received here are validated by StructuredTool
+    ):
+        # tool.run already handles validation via fn_metadata.call_fn_with_arg_validation
+        # It should be able to handle the validated/coerced types from StructuredTool
+        try:
+            call_tool_result = await tool.run(arguments)
+            return call_tool_result
+        except ToolError as e:
+            # Langchain expects ToolException for controlled errors
+            raise ToolException(f"Error running tool '{tool.name}': {e}") from e
+        except Exception as e:
+            # Catch unexpected errors
+            raise ToolException(f"Unexpected error in tool '{tool.name}': {e}") from e
+
+    return StructuredTool(
+        name=tool.name,
+        description=tool.description
+        or f"Tool named {tool.name}.",  # Provide fallback description
+        coroutine=call_tool,
+        args_schema=tool.fn_metadata.arg_model,  # <<< --- ADD THIS LINE
+        # handle_tool_error=True, # Optional: Consider adding error handling config
+        # return_direct=False,    # Optional: Default is usually fine
+        # response_format="content", # This field might not be valid for StructuredTool, check LangChain docs if needed. Let's remove for now.
+    )
+
+
+class Tool(BaseModel):
+    """Internal tool registration info."""
+
+    fn: Callable[..., Any] = Field(exclude=True)
+    name: str = Field(description="Name of the tool")
+    description: str = Field(description="Summary line from the tool's docstring")
+    args_description: dict[str, str] = Field(
+        default_factory=dict, description="Descriptions of arguments from the docstring"
+    )
+    returns_description: str = Field(
+        default="", description="Description of the return value from the docstring"
+    )
+    raises_description: dict[str, str] = Field(
+        default_factory=dict,
+        description="Descriptions of exceptions raised from the docstring",
+    )
+    tags: list[str] = Field(
+        default_factory=list, description="Tags for categorizing the tool"
+    )
+    parameters: dict[str, Any] = Field(description="JSON schema for tool parameters")
+    fn_metadata: FuncMetadata = Field(
+        description="Metadata about the function including a pydantic model for tool"
+        " arguments"
+    )
+    is_async: bool = Field(description="Whether the tool is async")
+
+    @classmethod
+    def from_function(
+        cls,
+        fn: Callable[..., Any],
+        name: str | None = None,
+    ) -> Tool:
+        """Create a Tool from a function."""
+
+        func_name = name or fn.__name__
+
+        if func_name == "<lambda>":
+            raise ValueError("You must provide a name for lambda functions")
+
+        raw_doc = inspect.getdoc(fn)
+        parsed_doc = parse_docstring(raw_doc)
+
+        is_async = inspect.iscoroutinefunction(fn)
+
+        func_arg_metadata = FuncMetadata.func_metadata(
+            fn,
+        )
+        parameters = func_arg_metadata.arg_model.model_json_schema()
+
+        return cls(
+            fn=fn,
+            name=func_name,
+            description=parsed_doc["summary"],
+            args_description=parsed_doc["args"],
+            returns_description=parsed_doc["returns"],
+            raises_description=parsed_doc["raises"],
+            tags=parsed_doc["tags"],
+            parameters=parameters,
+            fn_metadata=func_arg_metadata,
+            is_async=is_async,
+        )
+
+    async def run(
+        self,
+        arguments: dict[str, Any],
+        context=None,
+    ) -> Any:
+        """Run the tool with arguments."""
+        try:
+            return await self.fn_metadata.call_fn_with_arg_validation(
+                self.fn, self.is_async, arguments, None
+            )
+        except NotAuthorizedError as e:
+            message = f"Not authorized to call tool {self.name}: {e.message}"
+            return message
+        except httpx.HTTPError as e:
+            message = f"HTTP error calling tool {self.name}: {str(e)}"
+            raise ToolError(message) from e
+        except ValueError as e:
+            message = f"Invalid arguments for tool {self.name}: {e}"
+            raise ToolError(message) from e
+        except Exception as e:
+            raise ToolError(f"Error executing tool {self.name}: {e}") from e
+
+
+class ToolManager:
+    """Manages FastMCP tools."""
+
+    def __init__(self, warn_on_duplicate_tools: bool = True):
+        self._tools: dict[str, Tool] = {}
+        self.warn_on_duplicate_tools = warn_on_duplicate_tools
+
+    def get_tool(self, name: str) -> Tool | None:
+        """Get tool by name."""
+        return self._tools.get(name)
+
+    def list_tools(
+        self, format: Literal["mcp", "langchain", "openai"] = "mcp"
+    ) -> list[Tool]:
+        """List all registered tools."""
+        if format == "mcp":
+            return [convert_tool_to_mcp_tool(tool) for tool in self._tools.values()]
+        elif format == "langchain":
+            return [
+                convert_tool_to_langchain_tool(tool) for tool in self._tools.values()
+            ]
+        elif format == "openai":
+            return [convert_tool_to_openai_tool(tool) for tool in self._tools.values()]
+        else:
+            raise ValueError(f"Invalid format: {format}")
+
+    # Modified add_tool to accept name override explicitly
+    def add_tool(
+        self, fn: Callable[..., Any] | Tool, name: str | None = None
+    ) -> Tool:  # Changed any to Any
+        """Add a tool to the server, allowing name override."""
+        # Create the Tool object using the provided name if available
+        tool = fn if isinstance(fn, Tool) else Tool.from_function(fn, name=name)
+        existing = self._tools.get(tool.name)
+        if existing:
+            if self.warn_on_duplicate_tools:
+                # Check if it's the *exact* same function object being added again
+                if existing.fn is not tool.fn:
+                    logger.warning(
+                        f"Tool name '{tool.name}' conflicts with an existing tool. Skipping addition of new function."
+                    )
+                else:
+                    logger.debug(
+                        f"Tool '{tool.name}' with the same function already exists."
+                    )
+            return existing  # Return the existing tool if name conflicts
+
+        logger.debug(f"Adding tool: {tool.name}")
+        self._tools[tool.name] = tool
+        return tool
+
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any],
+        context=None,
+    ) -> Any:
+        """Call a tool by name with arguments."""
+        tool = self.get_tool(name)
+        if not tool:
+            raise ToolError(f"Unknown tool: {name}")
+        try:
+            result = await tool.run(arguments)
+            analytics.track_tool_called(name, "success")
+            return result
+        except Exception as e:
+            analytics.track_tool_called(name, "error", str(e))
+            raise
+
+    def get_tools_by_tags(self, tags: list[str]) -> list[Tool]:
+        """Get tools by tags."""
+        return [
+            tool
+            for tool in self._tools.values()
+            if any(tag in tool.tags for tag in tags)
+        ]
+
+    def register_tools_from_app(
+        self,
+        app: Application,
+        tools: list[str] | None = None,
+        tags: list[str] | None = None,
+    ) -> None:
+        try:
+            available_tool_functions = app.list_tools()
+        except TypeError as e:
+            logger.error(
+                f"Error calling list_tools for app '{app.name}'. Does its list_tools method accept arguments? It shouldn't. Error: {e}"
+            )
+            return
+        except Exception as e:
+            logger.error(f"Failed to get tool list from app '{app.name}': {e}")
+            return
+
+        if not isinstance(available_tool_functions, list):
+            logger.error(
+                f"App '{app.name}' list_tools() did not return a list. Skipping registration."
+            )
+            return
+
+        # Determine the effective filter lists *before* the loop for efficiency
+        # Use an empty list if None is passed, simplifies checks later
+        tools_name_filter = tools or []
+
+        # For tags, determine the filter list based on priority: passed 'tags' or default 'important'
+        # This list is only used if tools_name_filter is empty.
+        active_tags_filter = tags if tags else ["important"]  # Default filter
+
+        logger.debug(
+            f"Registering tools for '{app.name}'. Name filter: {tools_name_filter or 'None'}. Tag filter (if name filter empty): {active_tags_filter}"
+        )
+
+        for tool_func in available_tool_functions:
+            if not callable(tool_func):
+                logger.warning(
+                    f"Item returned by {app.name}.list_tools() is not callable: {tool_func}. Skipping."
+                )
+                continue
+
+            try:
+                # Create the Tool metadata object from the function.
+                # This parses docstring (including tags), gets signature etc.
+                tool_instance = Tool.from_function(tool_func)
+            except Exception as e:
+                logger.error(
+                    f"Failed to create Tool object from function '{getattr(tool_func, '__name__', 'unknown')}' in app '{app.name}': {e}"
+                )
+                continue  # Skip this tool if metadata creation fails
+
+            # --- Modify the Tool instance before filtering/registration ---
+            original_name = tool_instance.name
+            prefixed_name = f"{app.name}_{original_name}"
+            tool_instance.name = prefixed_name  # Update the name
+
+            # Add the app name itself as a tag for categorization
+            if app.name not in tool_instance.tags:
+                tool_instance.tags.append(app.name)
+
+            # --- Filtering Logic ---
+            should_register = False  # Default to not registering
+
+            if tools_name_filter:
+                # --- Primary Filter: Check against specific tool names ---
+                if tool_instance.name in tools_name_filter:
+                    should_register = True
+                    logger.debug(f"Tool '{tool_instance.name}' matched name filter.")
+                # If not in the name filter, it's skipped (should_register remains False)
+
+            else:
+                # --- Secondary Filter: Check against tags (since tools_name_filter is empty) ---
+                # Check if *any* tag in active_tags_filter exists in the tool's tags
+                # tool_instance.tags includes tags parsed from the docstring + app.name
+                if any(tag in tool_instance.tags for tag in active_tags_filter):
+                    should_register = True
+                    logger.debug(
+                        f"Tool '{tool_instance.name}' matched tag filter {active_tags_filter}."
+                    )
+                # else:
+                #     logger.debug(f"Tool '{tool_instance.name}' did NOT match tag filter {active_tags_filter}. Tool tags: {tool_instance.tags}")
+
+            # --- Add the tool if it passed the filters ---
+            if should_register:
+                # Pass the fully configured Tool *instance* to add_tool
+                self.add_tool(tool_instance)
+            # else: If not registered, optionally log it for debugging:
+            #    logger.trace(f"Tool '{tool_instance.name}' skipped due to filters.") # Use trace level