universal-mcp 0.1.8rc1__py3-none-any.whl → 0.1.8rc2__py3-none-any.whl

universal_mcp/stores/store.py

@@ -1,63 +1,84 @@
 import os
 from abc import ABC, abstractmethod
+from typing import Any
 
 import keyring
 from loguru import logger
 
 
-class Store(ABC):
+class StoreError(Exception):
+    """Base exception class for store-related errors."""
+    pass
+
+
+class KeyNotFoundError(StoreError):
+    """Exception raised when a key is not found in the store."""
+    pass
+
+
+class BaseStore(ABC):
     """
     Abstract base class defining the interface for credential stores.
     All credential stores must implement get, set and delete methods.
     """
 
     @abstractmethod
-    def get(self, key: str):
+    def get(self, key: str) -> Any:
         """
         Retrieve a value from the store by key.
 
         Args:
             key (str): The key to look up
-
+        
         Returns:
-            The stored value if found, None otherwise
+            Any: The stored value
+            
+        Raises:
+            KeyNotFoundError: If the key is not found in the store
+            StoreError: If there is an error accessing the store
         """
         pass
 
     @abstractmethod
-    def set(self, key: str, value: str):
+    def set(self, key: str, value: str) -> None:
         """
         Store a value in the store with the given key.
 
         Args:
             key (str): The key to store the value under
             value (str): The value to store
+
+        Raises:
+            StoreError: If there is an error storing the value
         """
         pass
 
     @abstractmethod
-    def delete(self, key: str):
+    def delete(self, key: str) -> None:
         """
         Delete a value from the store by key.
 
         Args:
             key (str): The key to delete
+
+        Raises:
+            KeyNotFoundError: If the key is not found in the store
+            StoreError: If there is an error deleting the value
         """
         pass
 
 
-class MemoryStore:
+class MemoryStore(BaseStore):
     """
-    Acts as credential store for the applications.
-    Responsible for storing and retrieving credentials.
-    Ideally should be a key value store that keeps data in memory.
+    In-memory credential store implementation.
+    Stores credentials in a dictionary that persists only for the duration of the program execution.
     """
 
     def __init__(self):
         """Initialize an empty dictionary to store the data."""
-        self.data = {}
+        self.data: dict[str, str] = {}
 
-    def get(self, key: str):
+    def get(self, key: str) -> Any:
         """
         Retrieve a value from the in-memory store by key.
 
@@ -65,11 +86,16 @@ class MemoryStore:
             key (str): The key to look up
 
         Returns:
-            The stored value if found, None otherwise
+            Any: The stored value
+
+        Raises:
+            KeyNotFoundError: If the key is not found in the store
         """
-        return self.data.get(key)
+        if key not in self.data:
+            raise KeyNotFoundError(f"Key '{key}' not found in memory store")
+        return self.data[key]
 
-    def set(self, key: str, value: str):
+    def set(self, key: str, value: str) -> None:
         """
         Store a value in the in-memory store with the given key.
 
@@ -79,27 +105,28 @@ class MemoryStore:
         """
         self.data[key] = value
 
-    def delete(self, key: str):
+    def delete(self, key: str) -> None:
         """
         Delete a value from the in-memory store by key.
 
         Args:
             key (str): The key to delete
+
+        Raises:
+            KeyNotFoundError: If the key is not found in the store
         """
+        if key not in self.data:
+            raise KeyNotFoundError(f"Key '{key}' not found in memory store")
         del self.data[key]
 
 
-class EnvironmentStore(Store):
+class EnvironmentStore(BaseStore):
     """
-    Store that uses environment variables to store credentials.
-    Implements the Store interface using OS environment variables as the backend.
+    Environment variable-based credential store implementation.
+    Uses OS environment variables to store and retrieve credentials.
     """
 
-    def __init__(self):
-        """Initialize the environment store."""
-        pass
-
-    def get(self, key: str):
+    def get(self, key: str) -> Any:
         """
         Retrieve a value from environment variables by key.
 
@@ -107,11 +134,17 @@ class EnvironmentStore(Store):
             key (str): The environment variable name to look up
 
         Returns:
-            dict: Dictionary containing the api_key from environment variable
+            Any: The stored value
+
+        Raises:
+            KeyNotFoundError: If the environment variable is not found
         """
-        return {"api_key": os.getenv(key)}
+        value = os.getenv(key)
+        if value is None:
+            raise KeyNotFoundError(f"Environment variable '{key}' not found")
+        return value
 
-    def set(self, key: str, value: str):
+    def set(self, key: str, value: str) -> None:
         """
         Set an environment variable.
 
@@ -121,20 +154,25 @@ class EnvironmentStore(Store):
         """
         os.environ[key] = value
 
-    def delete(self, key: str):
+    def delete(self, key: str) -> None:
         """
         Delete an environment variable.
 
         Args:
             key (str): The environment variable name to delete
+
+        Raises:
+            KeyNotFoundError: If the environment variable is not found
         """
+        if key not in os.environ:
+            raise KeyNotFoundError(f"Environment variable '{key}' not found")
         del os.environ[key]
 
 
-class KeyringStore(Store):
+class KeyringStore(BaseStore):
     """
-    Store that uses keyring to store credentials.
-    Implements the Store interface using system keyring as the backend.
+    System keyring-based credential store implementation.
+    Uses the system's secure credential storage facility via the keyring library.
     """
 
     def __init__(self, app_name: str = "universal_mcp"):
@@ -146,7 +184,7 @@ class KeyringStore(Store):
         """
         self.app_name = app_name
 
-    def get(self, key: str):
+    def get(self, key: str) -> Any:
         """
         Retrieve a password from the system keyring.
 
@@ -154,28 +192,51 @@ class KeyringStore(Store):
             key (str): The key to look up
 
         Returns:
-            The stored password if found, None otherwise
+            Any: The stored value
+
+        Raises:
+            KeyNotFoundError: If the key is not found in the keyring
+            StoreError: If there is an error accessing the keyring
         """
-        logger.info(f"Getting password for {key} from keyring")
-        return keyring.get_password(self.app_name, key)
+        try:
+            logger.info(f"Getting password for {key} from keyring")
+            value = keyring.get_password(self.app_name, key)
+            if value is None:
+                raise KeyNotFoundError(f"Key '{key}' not found in keyring")
+            return value
+        except Exception as e:
+            raise KeyNotFoundError(f"Key '{key}' not found in keyring") from e
 
-    def set(self, key: str, value: str):
+    def set(self, key: str, value: str) -> None:
         """
         Store a password in the system keyring.
 
         Args:
             key (str): The key to store the password under
             value (str): The password to store
-        """
-        logger.info(f"Setting password for {key} in keyring")
-        keyring.set_password(self.app_name, key, value)
 
-    def delete(self, key: str):
+        Raises:
+            StoreError: If there is an error storing in the keyring
+        """
+        try:
+            logger.info(f"Setting password for {key} in keyring")
+            keyring.set_password(self.app_name, key, value)
+        except Exception as e:
+            raise StoreError(f"Error storing in keyring: {str(e)}") from e
+        
+    def delete(self, key: str) -> None:
         """
         Delete a password from the system keyring.
 
         Args:
             key (str): The key to delete
+
+        Raises:
+            KeyNotFoundError: If the key is not found in the keyring
+            StoreError: If there is an error deleting from the keyring
         """
-        logger.info(f"Deleting password for {key} from keyring")
-        keyring.delete_password(self.app_name, key)
+        try:
+            logger.info(f"Deleting password for {key} from keyring")
+            keyring.delete_password(self.app_name, key)
+        except Exception as e:
+            raise KeyNotFoundError(f"Key '{key}' not found in keyring") from e

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,40 @@
+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,214 @@
+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
+