mcptoolforge 0.1.0__py3-none-any.whl

mcptoolforge/testing/client.py

@@ -0,0 +1,364 @@
+import asyncio
+import base64
+import inspect
+import json
+import time
+from typing import Any
+
+from mcptoolforge.errors import (
+    MCPToolForgeError,
+    ResourceExecutionError,
+    ResourceNotFoundError,
+    ToolExecutionError,
+    ToolNotFoundError,
+    ToolValidationError,
+)
+
+
+class MCPToolForgeTestingError(MCPToolForgeError):
+    """Exception raised for general MCPToolForge test client errors."""
+
+    pass
+
+
+class ResourceReadResult:
+    """Convenient result container for reading resources in tests."""
+
+    def __init__(
+        self,
+        uri: str,
+        text: str | None = None,
+        blob: str | None = None,
+        mime_type: str | None = None,
+    ):
+        self.uri = uri
+        self.text = text
+        self.blob = blob
+        self.mime_type = mime_type
+
+    @property
+    def is_blob(self) -> bool:
+        return self.blob is not None
+
+    def __repr__(self) -> str:
+        return (
+            f"ResourceReadResult(uri={self.uri!r}, text={self.text!r}, "
+            f"blob={self.blob!r}, mime_type={self.mime_type!r})"
+        )
+
+
+class PromptMessageResult:
+    """Represents a message result of a prompt retrieval in tests."""
+
+    def __init__(self, role: str, content: str):
+        self.role = role
+        self.content = content
+
+    def __repr__(self) -> str:
+        return f"PromptMessageResult(role={self.role!r}, content={self.content!r})"
+
+
+class PromptGetResult:
+    """Convenient result container for retrieved prompts in tests."""
+
+    def __init__(self, messages: list[PromptMessageResult], description: str | None = None):
+        self.messages = messages
+        self.description = description
+
+    def __repr__(self) -> str:
+        return f"PromptGetResult(messages={self.messages!r}, description={self.description!r})"
+
+
+class MCPTestClient:
+    """First-class in-process testing client for MCPToolForge MCPServers."""
+
+    def __init__(self, server: Any) -> None:
+        self._server = server
+
+    def _run_sync(self, coro_fn: Any) -> Any:
+        import anyio
+
+        try:
+            asyncio.get_running_loop()
+            # If there's already a running loop, running anyio.run raises a RuntimeError.
+            # We must await or warn. To be safe:
+            raise MCPToolForgeTestingError(
+                "Cannot execute synchronous test method inside a running event loop. "
+                "Use the async version (e.g. `await client.call_tool_async(...)`) instead."
+            )
+        except RuntimeError:
+            pass
+
+        return anyio.run(coro_fn)
+
+    # --- Startup/Shutdown Lifecycle ---
+
+    def start(self) -> None:
+        """Run startup hooks synchronously."""
+        for hook in self._server.startup_hooks:
+            if inspect.iscoroutinefunction(hook):
+                self._run_sync(lambda h=hook: h())
+            else:
+                hook()
+
+    def stop(self) -> None:
+        """Run shutdown hooks synchronously."""
+        for hook in self._server.shutdown_hooks:
+            if inspect.iscoroutinefunction(hook):
+                self._run_sync(lambda h=hook: h())
+            else:
+                hook()
+
+    async def start_async(self) -> None:
+        """Run startup hooks asynchronously."""
+        for hook in self._server.startup_hooks:
+            if inspect.iscoroutinefunction(hook):
+                await hook()
+            else:
+                hook()
+
+    async def stop_async(self) -> None:
+        """Run shutdown hooks asynchronously."""
+        for hook in self._server.shutdown_hooks:
+            if inspect.iscoroutinefunction(hook):
+                await hook()
+            else:
+                hook()
+
+    def __enter__(self) -> "MCPTestClient":
+        self.start()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.stop()
+
+    async def __aenter__(self) -> "MCPTestClient":
+        await self.start_async()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self.stop_async()
+
+    # --- Tools ---
+
+    def list_tools(self) -> list[Any]:
+        """List registered tools from the MCPServer."""
+        return self._server.list_tools()
+
+    async def call_tool_async(self, name: str, arguments: dict[str, Any] | None = None) -> Any:
+        """Execute a tool asynchronously through the server's validation and middleware pipeline."""
+        if not self._server.has_tool(name):
+            raise ToolNotFoundError(f"Tool '{name}' is not registered.")
+
+        tf_tool = self._server.get_tool(name)
+        raw_args = arguments or {}
+
+        if self._server.middlewares:
+            from mcptoolforge.middleware.context import MiddlewareContext
+            from mcptoolforge.middleware.manager import build_chain, is_async_callable
+
+            context = MiddlewareContext(
+                tool_name=tf_tool.name,
+                tool=tf_tool,
+                arguments=raw_args,
+                server=self._server,
+            )
+
+            called_next = False
+
+            if inspect.iscoroutinefunction(tf_tool.fn):
+
+                async def final_call() -> Any:
+                    nonlocal called_next
+                    called_next = True
+                    from mcptoolforge.validation import validate_tool_arguments
+
+                    validated_args = validate_tool_arguments(tf_tool, context.arguments)
+                    try:
+                        return await tf_tool.fn(**validated_args)
+                    except Exception as inner_e:
+                        if not isinstance(inner_e, (ToolValidationError, ToolExecutionError)):
+                            raise ToolExecutionError(
+                                f"Error executing tool '{tf_tool.name}': {inner_e}"
+                            ) from inner_e
+                        raise
+
+            else:
+
+                def final_call() -> Any:
+                    nonlocal called_next
+                    called_next = True
+                    from mcptoolforge.validation import validate_tool_arguments
+
+                    validated_args = validate_tool_arguments(tf_tool, context.arguments)
+                    try:
+                        return tf_tool.fn(**validated_args)
+                    except Exception as inner_e:
+                        if not isinstance(inner_e, (ToolValidationError, ToolExecutionError)):
+                            raise ToolExecutionError(
+                                f"Error executing tool '{tf_tool.name}': {inner_e}"
+                            ) from inner_e
+                        raise
+
+            start_time = time.perf_counter()
+            chain_callable = build_chain(self._server.middlewares, context, final_call)
+
+            if inspect.iscoroutinefunction(chain_callable) or is_async_callable(chain_callable):
+                result = await chain_callable()
+            else:
+                result = chain_callable()
+
+            context.duration = time.perf_counter() - start_time
+            return result
+        else:
+            from mcptoolforge.execution import execute_tool
+
+            return await execute_tool(tf_tool, raw_args)
+
+    def call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> Any:
+        """Execute a tool synchronously through the server's validation and middleware pipeline."""
+        return self._run_sync(lambda: self.call_tool_async(name, arguments))
+
+    # --- Resources ---
+
+    def list_resources(self) -> list[Any]:
+        """List registered resources from the MCPServer."""
+        return self._server.list_resources()
+
+    async def read_resource_async(self, uri: str) -> ResourceReadResult:
+        """Read a resource asynchronously through the server's resource handler."""
+        if not self._server.has_resource(uri):
+            raise ResourceNotFoundError(f"Resource '{uri}' is not registered.")
+
+        tf_resource = self._server.get_resource(uri)
+
+        try:
+            if inspect.iscoroutinefunction(tf_resource.fn):
+                raw_result = await tf_resource.fn()
+            else:
+                raw_result = tf_resource.fn()
+        except Exception as e:
+            raise ResourceExecutionError(f"Resource execution failed: {e}") from e
+
+        mime_type = tf_resource.mime_type
+        if isinstance(raw_result, (dict, list)):
+            if mime_type is None:
+                mime_type = "application/json"
+            try:
+                serialized_text = json.dumps(raw_result)
+            except Exception as json_e:
+                raise ResourceExecutionError(
+                    f"Failed to serialize resource content to JSON: {json_e}"
+                ) from json_e
+            return ResourceReadResult(
+                uri=tf_resource.uri,
+                text=serialized_text,
+                mime_type=mime_type,
+            )
+        elif isinstance(raw_result, str):
+            return ResourceReadResult(
+                uri=tf_resource.uri,
+                text=raw_result,
+                mime_type=mime_type,
+            )
+        elif isinstance(raw_result, bytes):
+            b64_str = base64.b64encode(raw_result).decode("utf-8")
+            return ResourceReadResult(
+                uri=tf_resource.uri,
+                blob=b64_str,
+                mime_type=mime_type,
+            )
+        else:
+            raise ResourceExecutionError(
+                f"Unsupported resource return type: {type(raw_result).__name__}"
+            )
+
+    def read_resource(self, uri: str) -> ResourceReadResult:
+        """Read a resource synchronously through the server's resource handler."""
+        return self._run_sync(lambda: self.read_resource_async(uri))
+
+    # --- Prompts ---
+
+    def list_prompts(self) -> list[Any]:
+        """List registered prompts from the MCPServer."""
+        return self._server.list_prompts()
+
+    async def get_prompt_async(
+        self, name: str, arguments: dict[str, Any] | None = None
+    ) -> PromptGetResult:
+        """Retrieve a prompt template asynchronously with validation and mapping."""
+        if not self._server.has_prompt(name):
+            raise ToolNotFoundError(f"Prompt '{name}' is not registered.")
+
+        tf_prompt = self._server.get_prompt(name)
+        raw_args = arguments or {}
+
+        from mcptoolforge.validation import validate_prompt_arguments
+
+        try:
+            validated_args = validate_prompt_arguments(tf_prompt, raw_args)
+        except Exception as val_e:
+            raise ToolValidationError(f"Prompt argument validation failed: {val_e}") from val_e
+
+        try:
+            if inspect.iscoroutinefunction(tf_prompt.fn):
+                raw_result = await tf_prompt.fn(**validated_args)
+            else:
+                raw_result = tf_prompt.fn(**validated_args)
+        except Exception as e:
+            raise ToolExecutionError(f"Prompt execution failed: {e}") from e
+
+        messages = []
+
+        def make_message(text_val: str, role_val: str = "user") -> PromptMessageResult:
+            if role_val not in ("user", "assistant"):
+                raise ToolExecutionError(
+                    f"Role '{role_val}' is not supported. Only 'user' or 'assistant' are allowed."
+                )
+            return PromptMessageResult(role=role_val, content=text_val)
+
+        if isinstance(raw_result, str):
+            messages.append(make_message(raw_result))
+        elif isinstance(raw_result, dict):
+            role = raw_result.get("role", "user")
+            content = raw_result.get("content", "")
+            if not isinstance(content, str):
+                tname = type(content).__name__
+                raise ToolExecutionError(f"Prompt dict content must be a string, received {tname}")
+            messages.append(make_message(content, role))
+        elif isinstance(raw_result, list):
+            for item in raw_result:
+                if isinstance(item, str):
+                    messages.append(make_message(item))
+                elif isinstance(item, dict):
+                    role = item.get("role", "user")
+                    content = item.get("content", "")
+                    if not isinstance(content, str):
+                        tname = type(content).__name__
+                        raise ToolExecutionError(
+                            f"Prompt dict content must be a string, received {tname}"
+                        )
+                    messages.append(make_message(content, role))
+                elif hasattr(item, "role") and hasattr(item, "content"):
+                    content_text = item.content
+                    if hasattr(content_text, "text"):
+                        content_text = content_text.text
+                    messages.append(make_message(str(content_text), str(item.role)))
+                else:
+                    tname = type(item).__name__
+                    raise ToolExecutionError(
+                        f"Unsupported item type in prompt result list: {tname}"
+                    )
+        elif hasattr(raw_result, "role") and hasattr(raw_result, "content"):
+            content_text = raw_result.content
+            if hasattr(content_text, "text"):
+                content_text = content_text.text
+            messages.append(make_message(str(content_text), str(raw_result.role)))
+        else:
+            raise ToolExecutionError(f"Unsupported prompt return type: {type(raw_result).__name__}")
+
+        return PromptGetResult(messages=messages, description=tf_prompt.description)
+
+    def get_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> PromptGetResult:
+        """Retrieve a prompt template synchronously with validation and mapping."""
+        return self._run_sync(lambda: self.get_prompt_async(name, arguments))

mcptoolforge/transports/__init__.py

@@ -0,0 +1 @@
+# Transport package placeholder for MCPToolForge

mcptoolforge/validation.py

@@ -0,0 +1,229 @@
+import enum
+import inspect
+import types
+import typing
+from typing import Any
+
+from mcptoolforge.errors import ToolValidationError
+
+
+def _validate_type(val: Any, ann: Any, param_name: str, tool_name: str) -> Any:
+    """Validate and normalize a value against a type annotation."""
+    if ann is inspect.Parameter.empty or ann is Any:
+        return val
+
+    # None / NoneType
+    if ann is None or ann is type(None):
+        if val is None:
+            return None
+        raise ToolValidationError(
+            f"Tool '{tool_name}': parameter '{param_name}' expected None, "
+            f"received {type(val).__name__}."
+        )
+
+    # Union Types / Optional
+    origin = getattr(ann, "__origin__", None)
+    if origin is typing.Union or (hasattr(types, "UnionType") and isinstance(ann, types.UnionType)):
+        args = typing.get_args(ann)
+        # Try to validate against each union type option
+        for arg in args:
+            try:
+                return _validate_type(val, arg, param_name, tool_name)
+            except ToolValidationError:
+                continue
+
+        # If all options failed, build a clean error message
+        expected_types = " | ".join(
+            getattr(arg, "__name__", str(arg)) for arg in args if arg is not type(None)
+        )
+        if type(None) in args:
+            expected_types += " | None"
+        raise ToolValidationError(
+            f"Tool '{tool_name}': parameter '{param_name}' expected {expected_types}, "
+            f"received {type(val).__name__}."
+        )
+
+    # Lists (list, List)
+    if ann is list or origin is list or origin is list:
+        if not isinstance(val, list):
+            raise ToolValidationError(
+                f"Tool '{tool_name}': parameter '{param_name}' expected list, "
+                f"received {type(val).__name__}."
+            )
+        args = typing.get_args(ann)
+        if not args:
+            return val
+        item_type = args[0]
+        validated_list = []
+        for i, item in enumerate(val):
+            try:
+                validated_list.append(
+                    _validate_type(item, item_type, f"{param_name}[{i}]", tool_name)
+                )
+            except ToolValidationError as e:
+                raise ToolValidationError(
+                    f"Tool '{tool_name}': parameter '{param_name}' "
+                    f"element at index {i} invalid: {e}"
+                ) from e
+        return validated_list
+
+    # Dictionaries (dict, Dict)
+    if ann is dict or origin is dict or origin is dict:
+        if not isinstance(val, dict):
+            raise ToolValidationError(
+                f"Tool '{tool_name}': parameter '{param_name}' expected dict, "
+                f"received {type(val).__name__}."
+            )
+        args = typing.get_args(ann)
+        if not args:
+            return val
+        key_type, val_type = args[0], args[1]
+        validated_dict = {}
+        for k, v in val.items():
+            try:
+                validated_k = _validate_type(k, key_type, f"{param_name}.key", tool_name)
+            except ToolValidationError as e:
+                raise ToolValidationError(
+                    f"Tool '{tool_name}': parameter '{param_name}' "
+                    f"dictionary key '{k}' invalid: {e}"
+                ) from e
+            try:
+                validated_v = _validate_type(v, val_type, f"{param_name}['{k}']", tool_name)
+            except ToolValidationError as e:
+                raise ToolValidationError(
+                    f"Tool '{tool_name}': parameter '{param_name}' "
+                    f"dictionary value for key '{k}' invalid: {e}"
+                ) from e
+            validated_dict[validated_k] = validated_v
+        return validated_dict
+
+    # Enums
+    if isinstance(ann, type) and issubclass(ann, enum.Enum):
+        if isinstance(val, ann):
+            return val
+        try:
+            return ann(val)
+        except ValueError:
+            for member in ann:
+                if member.name == val:
+                    return member
+            valid_choices = [m.value for m in ann]
+            raise ToolValidationError(
+                f"Tool '{tool_name}': parameter '{param_name}' expected one of {valid_choices}, "
+                f"received '{val}'."
+            ) from None
+
+    # Primitive types (strictly rejecting booleans from matching integer/string/float)
+    if ann is str:
+        if isinstance(val, str) and not isinstance(val, bool):
+            return val
+        raise ToolValidationError(
+            f"Tool '{tool_name}': parameter '{param_name}' expected string, "
+            f"received {type(val).__name__}."
+        )
+    elif ann is int:
+        if isinstance(val, int) and not isinstance(val, bool):
+            return val
+        raise ToolValidationError(
+            f"Tool '{tool_name}': parameter '{param_name}' expected integer, "
+            f"received {type(val).__name__}."
+        )
+    elif ann is float:
+        if isinstance(val, (int, float)) and not isinstance(val, bool):
+            return float(val)
+        raise ToolValidationError(
+            f"Tool '{tool_name}': parameter '{param_name}' expected float, "
+            f"received {type(val).__name__}."
+        )
+    elif ann is bool:
+        if isinstance(val, bool):
+            return val
+        raise ToolValidationError(
+            f"Tool '{tool_name}': parameter '{param_name}' expected boolean, "
+            f"received {type(val).__name__}."
+        )
+
+    # Fallback for unhandled type annotations
+    return val
+
+
+def validate_tool_arguments(tool: Any, arguments: dict[str, Any]) -> dict[str, Any]:
+    """Validate and normalize incoming arguments against a Tool's parameters."""
+    validated: dict[str, Any] = {}
+
+    # 1. Reject unexpected parameters
+    for k in arguments:
+        if k not in tool.parameters:
+            raise ToolValidationError(f"Tool '{tool.name}': unexpected parameter '{k}'.")
+
+    # 2. Validate expected parameters
+    for name, param in tool.parameters.items():
+        if name not in arguments:
+            if param.required:
+                raise ToolValidationError(
+                    f"Tool '{tool.name}': missing required parameter '{name}'."
+                )
+            else:
+                validated[name] = param.default
+        else:
+            val = arguments[name]
+            validated[name] = _validate_type(val, param.annotation, name, tool.name)
+
+    return validated
+
+
+def _coerce_prompt_type(val: Any, ann: Any) -> Any:
+    """Attempt to coerce string values into correct types for prompt parameters."""
+    if isinstance(val, str):
+        if ann is int:
+            try:
+                return int(val)
+            except ValueError:
+                pass
+        elif ann is float:
+            try:
+                return float(val)
+            except ValueError:
+                pass
+        elif ann is bool:
+            if val.lower() == "true":
+                return True
+            if val.lower() == "false":
+                return False
+
+        # Support unions (e.g. Union[int, str], int | None)
+        origin = getattr(ann, "__origin__", None)
+        if origin is typing.Union or (
+            hasattr(types, "UnionType") and isinstance(ann, types.UnionType)
+        ):
+            for arg in typing.get_args(ann):
+                coerced = _coerce_prompt_type(val, arg)
+                if coerced is not val:
+                    return coerced
+    return val
+
+
+def validate_prompt_arguments(prompt: Any, arguments: dict[str, Any]) -> dict[str, Any]:
+    """Validate and normalize incoming arguments against a Prompt's parameters."""
+    validated: dict[str, Any] = {}
+
+    # 1. Reject unexpected parameters
+    for k in arguments:
+        if k not in prompt.parameters:
+            raise ToolValidationError(f"Prompt '{prompt.name}': unexpected parameter '{k}'.")
+
+    # 2. Validate expected parameters
+    for name, param in prompt.parameters.items():
+        if name not in arguments:
+            if param.required:
+                raise ToolValidationError(
+                    f"Prompt '{prompt.name}': missing required parameter '{name}'."
+                )
+            else:
+                validated[name] = param.default
+        else:
+            val = arguments[name]
+            coerced_val = _coerce_prompt_type(val, param.annotation)
+            validated[name] = _validate_type(coerced_val, param.annotation, name, prompt.name)
+
+    return validated