mcptoolforge 0.1.0__py3-none-any.whl

mcptoolforge/mcp/adapter.py

@@ -0,0 +1,405 @@
+import logging
+from typing import Any
+
+import mcp.types as t
+from mcp.server.context import ServerRequestContext
+from mcp.shared.exceptions import MCPError
+
+from mcptoolforge.errors import (
+    ConfigurationError,
+    MiddlewareError,
+    ResourceNotFoundError,
+    ToolExecutionError,
+    ToolNotFoundError,
+    ToolValidationError,
+)
+from mcptoolforge.execution import execute_tool
+from mcptoolforge.registry import ToolRegistry
+
+logger = logging.getLogger("mcptoolforge.mcp")
+
+
+class MCPAdapter:
+    """Adapts MCPToolForge ToolRegistry and tools to the MCP protocol server."""
+
+    def __init__(
+        self,
+        registry: ToolRegistry,
+        server: Any = None,
+        resource_registry: Any = None,
+        prompt_registry: Any = None,
+    ) -> None:
+        self.registry = registry
+        self.server = server
+        self.resource_registry = resource_registry or (server.resource_registry if server else None)
+        self.prompt_registry = prompt_registry or (server.prompt_registry if server else None)
+
+    async def handle_list_tools(
+        self,
+        ctx: ServerRequestContext[Any],
+        params: t.PaginatedRequestParams | None,
+    ) -> t.ListToolsResult:
+        """Map registered MCPToolForge tools to MCP Tool representations."""
+        mcp_tools = []
+        for tf_tool in self.registry.list():
+            mcp_tool = t.Tool(
+                name=tf_tool.name,
+                description=tf_tool.description,
+                input_schema=tf_tool.input_schema,
+            )
+            mcp_tools.append(mcp_tool)
+        return t.ListToolsResult(tools=mcp_tools)
+
+    async def handle_call_tool(
+        self,
+        ctx: ServerRequestContext[Any],
+        params: t.CallToolRequestParams,
+    ) -> t.CallToolResult:
+        """Execute the requested tool and translate results/errors to MCP format."""
+        try:
+            # 1. Locate the tool
+            try:
+                tf_tool = self.registry.get(params.name)
+            except ToolNotFoundError as e:
+                raise MCPError(code=-32601, message=str(e)) from e
+
+            # 2. Extract arguments
+            arguments = params.arguments or {}
+
+            # 3. Execute the tool (wrapping with middlewares if configured)
+            try:
+                if self.server and self.server.middlewares:
+                    import inspect
+                    import time
+
+                    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=arguments,
+                        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)
+
+                    try:
+                        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
+                    except Exception as e:
+                        context.duration = time.perf_counter() - start_time
+                        context.error = e
+                        if called_next and isinstance(e, (ToolValidationError, ToolExecutionError)):
+                            raise
+                        else:
+                            raise MiddlewareError(f"Middleware failed during execution: {e}") from e
+                else:
+                    result = await execute_tool(tf_tool, arguments)
+
+            except ToolValidationError as e:
+                return t.CallToolResult(
+                    content=[t.TextContent(type="text", text=str(e))],
+                    is_error=True,
+                )
+            except (ToolExecutionError, MiddlewareError, ConfigurationError) as e:
+                logger.error(f"Execution failed for tool '{params.name}': {e}", exc_info=True)
+                return t.CallToolResult(
+                    content=[t.TextContent(type="text", text=str(e))],
+                    is_error=True,
+                )
+
+            # 4. Map return result to CallToolResult
+            if isinstance(result, dict):
+                return t.CallToolResult(
+                    content=[t.TextContent(type="text", text=str(result))],
+                    structured_content=result,
+                    is_error=False,
+                )
+            else:
+                text_value = result if isinstance(result, str) else str(result)
+                return t.CallToolResult(
+                    content=[t.TextContent(type="text", text=text_value)],
+                    is_error=False,
+                )
+
+        except MCPError:
+            raise
+        except Exception as e:
+            logger.critical(f"Internal MCPToolForge error in call_tool: {e}", exc_info=True)
+            raise MCPError(code=-32603, message=f"Internal MCPToolForge error: {e}") from e
+
+    async def handle_list_resources(
+        self,
+        ctx: ServerRequestContext[Any],
+        params: t.PaginatedRequestParams | None,
+    ) -> t.ListResourcesResult:
+        """Map registered MCPToolForge resources to MCP Resource representations."""
+        mcp_resources = []
+        if self.resource_registry:
+            for tf_resource in self.resource_registry.list():
+                mcp_resource = t.Resource(
+                    uri=tf_resource.uri,
+                    name=tf_resource.name,
+                    description=tf_resource.description,
+                    mime_type=tf_resource.mime_type,
+                )
+                mcp_resources.append(mcp_resource)
+        return t.ListResourcesResult(resources=mcp_resources)
+
+    async def handle_read_resource(
+        self,
+        ctx: ServerRequestContext[Any],
+        params: t.ReadResourceRequestParams,
+    ) -> t.ReadResourceResult:
+        """Read the requested resource and return its contents."""
+        try:
+            if not self.resource_registry:
+                raise MCPError(code=-32601, message="Resources are not supported on this server.")
+
+            # 1. Locate the resource
+            try:
+                tf_resource = self.resource_registry.get(params.uri)
+            except ResourceNotFoundError as e:
+                raise MCPError(code=-32601, message=str(e)) from e
+
+            # 2. Execute the resource handler
+            try:
+                import inspect
+
+                if inspect.iscoroutinefunction(tf_resource.fn):
+                    raw_result = await tf_resource.fn()
+                else:
+                    raw_result = tf_resource.fn()
+            except Exception as e:
+                logger.error(f"Execution failed for resource '{params.uri}': {e}", exc_info=True)
+                raise MCPError(code=-32603, message=f"Resource execution failed: {e}") from e
+
+            # 3. Serialize and map the return value to resource contents
+            import base64
+            import json
+
+            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 MCPError(
+                        code=-32603,
+                        message=f"Failed to serialize resource content to JSON: {json_e}",
+                    ) from json_e
+
+                contents = [
+                    t.TextResourceContents(
+                        uri=tf_resource.uri,
+                        text=serialized_text,
+                        mime_type=mime_type,
+                    )
+                ]
+            elif isinstance(raw_result, str):
+                contents = [
+                    t.TextResourceContents(
+                        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")
+                contents = [
+                    t.BlobResourceContents(
+                        uri=tf_resource.uri,
+                        blob=b64_str,
+                        mime_type=mime_type,
+                    )
+                ]
+            else:
+                raise MCPError(
+                    code=-32603,
+                    message=f"Unsupported resource return type: {type(raw_result).__name__}",
+                )
+
+            return t.ReadResourceResult(contents=contents)
+
+        except MCPError:
+            raise
+        except Exception as e:
+            logger.critical(f"Internal MCPToolForge error in read_resource: {e}", exc_info=True)
+            raise MCPError(code=-32603, message=f"Internal MCPToolForge error: {e}") from e
+
+    async def handle_list_prompts(
+        self,
+        ctx: ServerRequestContext[Any],
+        params: t.PaginatedRequestParams | None,
+    ) -> t.ListPromptsResult:
+        """Map registered MCPToolForge prompts to MCP Prompt representations."""
+        mcp_prompts = []
+        if self.prompt_registry:
+            for tf_prompt in self.prompt_registry.list():
+                mcp_args = []
+                for p_name, p in tf_prompt.parameters.items():
+                    mcp_args.append(
+                        t.PromptArgument(
+                            name=p_name,
+                            description=getattr(p, "description", None),
+                            required=p.required,
+                        )
+                    )
+                mcp_prompt = t.Prompt(
+                    name=tf_prompt.name,
+                    description=tf_prompt.description,
+                    arguments=mcp_args if mcp_args else None,
+                )
+                mcp_prompts.append(mcp_prompt)
+        return t.ListPromptsResult(prompts=mcp_prompts)
+
+    async def handle_get_prompt(
+        self,
+        ctx: ServerRequestContext[Any],
+        params: t.GetPromptRequestParams,
+    ) -> t.GetPromptResult:
+        """Get the requested prompt with client arguments."""
+        try:
+            if not self.prompt_registry:
+                raise MCPError(code=-32601, message="Prompts are not supported on this server.")
+
+            # 1. Locate the prompt
+            try:
+                tf_prompt = self.prompt_registry.get(params.name)
+            except ToolNotFoundError as e:
+                raise MCPError(code=-32601, message=str(e)) from e
+
+            # 2. Extract and validate/coerce arguments
+            raw_args = params.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 MCPError(
+                    code=-32602, message=f"Prompt argument validation failed: {val_e}"
+                ) from val_e
+
+            # 3. Execute prompt template
+            try:
+                import inspect
+
+                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:
+                logger.error(f"Execution failed for prompt '{params.name}': {e}", exc_info=True)
+                raise MCPError(code=-32603, message=f"Prompt execution failed: {e}") from e
+
+            # 4. Map return value to MCP prompt messages format
+            messages = []
+
+            def make_text_message(text_val: str, role_val: str = "user") -> t.PromptMessage:
+                return t.PromptMessage(
+                    role=role_val,
+                    content=t.TextContent(type="text", text=text_val),
+                )
+
+            if isinstance(raw_result, str):
+                messages.append(make_text_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 MCPError(
+                        code=-32603,
+                        message=f"Prompt dict content must be a string, received {tname}",
+                    )
+                messages.append(make_text_message(content, role))
+            elif isinstance(raw_result, list):
+                for item in raw_result:
+                    if isinstance(item, str):
+                        messages.append(make_text_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 MCPError(
+                                code=-32603,
+                                message=f"Prompt dict content must be a string, received {tname}",
+                            )
+                        messages.append(make_text_message(content, role))
+                    elif isinstance(item, t.PromptMessage):
+                        messages.append(item)
+                    else:
+                        tname = type(item).__name__
+                        raise MCPError(
+                            code=-32603,
+                            message=f"Unsupported item type in prompt result list: {tname}",
+                        )
+            elif isinstance(raw_result, t.PromptMessage):
+                messages.append(raw_result)
+            else:
+                raise MCPError(
+                    code=-32603,
+                    message=f"Unsupported prompt return type: {type(raw_result).__name__}",
+                )
+
+            return t.GetPromptResult(
+                description=tf_prompt.description,
+                messages=messages,
+            )
+
+        except MCPError:
+            raise
+        except Exception as e:
+            logger.critical(f"Internal MCPToolForge error in get_prompt: {e}", exc_info=True)
+            raise MCPError(code=-32603, message=f"Internal MCPToolForge error: {e}") from e

mcptoolforge/mcp/server.py

@@ -0,0 +1,111 @@
+import inspect
+import logging
+import sys
+from typing import Any
+
+import mcp.types as t
+from mcp.server.lowlevel import Server
+from mcp.server.models import InitializationOptions
+from mcp.server.stdio import stdio_server
+
+from mcptoolforge.mcp.adapter import MCPAdapter
+from mcptoolforge.registry import ToolRegistry
+
+logger = logging.getLogger("mcptoolforge")
+handler = logging.StreamHandler(sys.stderr)
+formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+handler.setFormatter(formatter)
+logger.addHandler(handler)
+logger.setLevel(logging.INFO)
+
+
+class MCPServerRunner:
+    """Responsible for running a MCPToolForge registry over MCP Stdio transport."""
+
+    def __init__(self, server_name: str, registry: ToolRegistry, server: Any = None) -> None:
+        self.server_name = server_name
+        self.registry = registry
+        self.server = server
+        self.adapter = MCPAdapter(self.registry, server=server)
+
+    async def run_async(self) -> None:
+        """Asynchronously start the stdio server."""
+        # 1. Run startup hooks
+        if self.server:
+            for hook in self.server.startup_hooks:
+                try:
+                    if inspect.iscoroutinefunction(hook):
+                        await hook()
+                    else:
+                        hook()
+                except Exception as e:
+                    logger.error(f"Error in startup hook '{hook.__name__}': {e}", exc_info=True)
+                    raise
+
+        mcp_server = Server(self.server_name)
+
+        # Register request handlers
+        mcp_server.add_request_handler(
+            "tools/list",
+            t.PaginatedRequestParams,
+            self.adapter.handle_list_tools,
+        )
+        mcp_server.add_request_handler(
+            "tools/call",
+            t.CallToolRequestParams,
+            self.adapter.handle_call_tool,
+        )
+        mcp_server.add_request_handler(
+            "resources/list",
+            t.PaginatedRequestParams,
+            self.adapter.handle_list_resources,
+        )
+        mcp_server.add_request_handler(
+            "resources/read",
+            t.ReadResourceRequestParams,
+            self.adapter.handle_read_resource,
+        )
+        mcp_server.add_request_handler(
+            "prompts/list",
+            t.PaginatedRequestParams,
+            self.adapter.handle_list_prompts,
+        )
+        mcp_server.add_request_handler(
+            "prompts/get",
+            t.GetPromptRequestParams,
+            self.adapter.handle_get_prompt,
+        )
+
+        init_options = InitializationOptions(
+            server_name=self.server_name,
+            server_version="0.1.0",
+            capabilities=t.ServerCapabilities(
+                tools=t.ToolsCapability(list_changed=False),
+                resources=t.ResourcesCapability(list_changed=False, subscribe=False),
+                prompts=t.PromptsCapability(list_changed=False),
+            ),
+        )
+
+        logger.info(f"Starting MCP stdio transport loop for '{self.server_name}'...")
+        try:
+            async with stdio_server() as (read_stream, write_stream):
+                await mcp_server.run(
+                    read_stream,
+                    write_stream,
+                    initialization_options=init_options,
+                    raise_exceptions=False,
+                )
+        finally:
+            # 2. Run shutdown hooks
+            if self.server:
+                for hook in self.server.shutdown_hooks:
+                    try:
+                        if inspect.iscoroutinefunction(hook):
+                            await hook()
+                        else:
+                            hook()
+                    except Exception as e:
+                        logger.error(
+                            f"Error in shutdown hook '{hook.__name__}': {e}",
+                            exc_info=True,
+                        )

mcptoolforge/middleware/__init__.py

@@ -0,0 +1,11 @@
+from mcptoolforge.middleware.context import MiddlewareContext
+from mcptoolforge.middleware.logging import logging_middleware, sync_logging_middleware
+from mcptoolforge.middleware.timing import sync_timing_middleware, timing_middleware
+
+__all__ = [
+    "MiddlewareContext",
+    "logging_middleware",
+    "sync_logging_middleware",
+    "sync_timing_middleware",
+    "timing_middleware",
+]

mcptoolforge/middleware/context.py

@@ -0,0 +1,15 @@
+from typing import Any
+
+from mcptoolforge.registry import Tool
+
+
+class MiddlewareContext:
+    """Structured context passed to MCPToolForge middleware containing tool execution details."""
+
+    def __init__(self, tool_name: str, tool: Tool, arguments: dict[str, Any], server: Any) -> None:
+        self.tool_name = tool_name
+        self.tool = tool
+        self.arguments = arguments
+        self.server = server
+        self.error: Exception | None = None
+        self.duration: float | None = None

mcptoolforge/middleware/logging.py

@@ -0,0 +1,30 @@
+import logging
+from typing import Any
+
+from mcptoolforge.middleware.context import MiddlewareContext
+
+logger = logging.getLogger("mcptoolforge.middleware.logging")
+
+
+async def logging_middleware(context: MiddlewareContext, next_callable: Any) -> Any:
+    """Asynchronous built-in middleware for logging tool invocations to stderr."""
+    logger.info(f"Calling tool '{context.tool_name}' with arguments: {context.arguments}")
+    try:
+        result = await next_callable()
+        logger.info(f"Completed tool '{context.tool_name}' successfully.")
+        return result
+    except Exception as e:
+        logger.error(f"Tool '{context.tool_name}' failed with error: {e}")
+        raise
+
+
+def sync_logging_middleware(context: MiddlewareContext, next_callable: Any) -> Any:
+    """Synchronous built-in middleware for logging tool invocations to stderr."""
+    logger.info(f"Calling tool '{context.tool_name}' with arguments: {context.arguments}")
+    try:
+        result = next_callable()
+        logger.info(f"Completed tool '{context.tool_name}' successfully.")
+        return result
+    except Exception as e:
+        logger.error(f"Tool '{context.tool_name}' failed with error: {e}")
+        raise

mcptoolforge/middleware/manager.py

@@ -0,0 +1,68 @@
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from mcptoolforge.errors import ConfigurationError
+from mcptoolforge.middleware.context import MiddlewareContext
+
+
+def is_async_callable(fn: Any) -> bool:
+    """Helper to check if a callable is asynchronous."""
+    if inspect.iscoroutinefunction(fn):
+        return True
+    return bool(callable(fn) and inspect.iscoroutinefunction(fn.__call__))
+
+
+def build_chain(
+    middlewares: list[Callable], context: MiddlewareContext, final_call: Callable
+) -> Callable:
+    """Build a nested execution chain of middlewares.
+
+    Validates sync/async compatibility: synchronous middleware cannot wrap
+    asynchronous tools or middlewares.
+    """
+    # 1. Determine if each stage is async
+    is_async_stage = []
+    for mw in middlewares:
+        is_async_stage.append(is_async_callable(mw))
+    is_async_stage.append(is_async_callable(final_call))
+
+    # 2. Check for invalid sync -> async transitions
+    for i in range(len(middlewares)):
+        if not is_async_stage[i] and any(is_async_stage[i + 1 :]):
+            raise ConfigurationError(
+                f"Synchronous middleware '{middlewares[i].__name__}' cannot be used "
+                "because a subsequent middleware or tool in the pipeline is asynchronous."
+            )
+
+    # 3. Build the closures from the tail to the head
+    current_next = final_call
+
+    for i in reversed(range(len(middlewares))):
+        mw = middlewares[i]
+        is_mw_async = is_async_stage[i]
+
+        if is_mw_async:
+            # Wrap current_next in a coroutine function if it isn't one,
+            # so next() behaves asynchronously
+            wrapped_next = current_next
+            if not is_async_callable(wrapped_next):
+
+                async def async_wrapped(*args, _next=wrapped_next, **kwargs):
+                    return _next(*args, **kwargs)
+
+                wrapped_next = async_wrapped
+
+            # Create the async wrapper closure
+            async def next_step(m=mw, c=context, n=wrapped_next):
+                return await m(c, n)
+
+            current_next = next_step
+        else:
+            # Create the sync wrapper closure
+            def next_step(m=mw, c=context, n=current_next):
+                return m(c, n)
+
+            current_next = next_step
+
+    return current_next

mcptoolforge/middleware/timing.py

@@ -0,0 +1,37 @@
+import logging
+import time
+from typing import Any
+
+from mcptoolforge.middleware.context import MiddlewareContext
+
+logger = logging.getLogger("mcptoolforge.middleware.timing")
+
+
+async def timing_middleware(context: MiddlewareContext, next_callable: Any) -> Any:
+    """Asynchronous built-in middleware for measuring execution duration."""
+    start = time.perf_counter()
+    try:
+        result = await next_callable()
+        context.duration = time.perf_counter() - start
+        logger.info(f"Tool '{context.tool_name}' execution took {context.duration:.4f} seconds.")
+        return result
+    except Exception as e:
+        context.duration = time.perf_counter() - start
+        context.error = e
+        logger.error(f"Tool '{context.tool_name}' failed after {context.duration:.4f} seconds.")
+        raise
+
+
+def sync_timing_middleware(context: MiddlewareContext, next_callable: Any) -> Any:
+    """Synchronous built-in middleware for measuring execution duration."""
+    start = time.perf_counter()
+    try:
+        result = next_callable()
+        context.duration = time.perf_counter() - start
+        logger.info(f"Tool '{context.tool_name}' execution took {context.duration:.4f} seconds.")
+        return result
+    except Exception as e:
+        context.duration = time.perf_counter() - start
+        context.error = e
+        logger.error(f"Tool '{context.tool_name}' failed after {context.duration:.4f} seconds.")
+        raise