mcptoolforge 0.1.0__py3-none-any.whl

mcptoolforge/resources/resource.py

@@ -0,0 +1,97 @@
+import inspect
+from collections.abc import Callable
+from typing import Any
+from urllib.parse import urlparse
+
+from mcptoolforge.errors import ResourceRegistrationError
+
+
+def validate_uri(uri: str) -> str:
+    """Validate that the URI is a valid format and is non-empty."""
+    if not isinstance(uri, str):
+        raise ResourceRegistrationError("Resource URI must be a string.")
+    if not uri.strip():
+        raise ResourceRegistrationError("Resource URI cannot be empty or whitespace-only.")
+    parsed = urlparse(uri)
+    if not parsed.scheme or not (parsed.netloc or parsed.path):
+        raise ResourceRegistrationError(f"Invalid resource URI format: '{uri}'")
+    return uri.strip()
+
+
+class Resource:
+    """Represents a registered resource in MCPToolForge."""
+
+    def __init__(
+        self,
+        uri: str,
+        fn: Callable[..., Any],
+        name: str | None = None,
+        description: str | None = None,
+        mime_type: str | None = None,
+    ):
+        if not callable(fn):
+            raise ResourceRegistrationError("Registered object must be a callable.")
+
+        self._uri = validate_uri(uri)
+        self._fn = fn
+
+        # Name validation
+        if name is not None:
+            if not isinstance(name, str):
+                raise ResourceRegistrationError("Resource name must be a string.")
+            if not name.strip():
+                raise ResourceRegistrationError("Resource name cannot be empty or whitespace-only.")
+            self._name = name.strip()
+        else:
+            self._name = fn.__name__
+
+        # Description validation
+        if description is not None:
+            if not isinstance(description, str):
+                raise ResourceRegistrationError("Resource description must be a string.")
+            if not description.strip():
+                raise ResourceRegistrationError(
+                    "Resource description cannot be empty or whitespace-only."
+                )
+            self._description = description.strip()
+        else:
+            doc = inspect.getdoc(fn)
+            self._description = doc.strip() if doc else "No description provided."
+
+        # MIME type validation
+        if mime_type is not None:
+            if not isinstance(mime_type, str):
+                raise ResourceRegistrationError("Resource MIME type must be a string.")
+            if not mime_type.strip():
+                raise ResourceRegistrationError(
+                    "Resource MIME type cannot be empty or whitespace-only."
+                )
+            self._mime_type = mime_type.strip()
+        else:
+            self._mime_type = None
+
+    @property
+    def uri(self) -> str:
+        return self._uri
+
+    @property
+    def fn(self) -> Callable[..., Any]:
+        return self._fn
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def description(self) -> str:
+        return self._description
+
+    @property
+    def mime_type(self) -> str | None:
+        return self._mime_type
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self._fn(*args, **kwargs)
+
+    def __repr__(self) -> str:
+        return f"Resource(uri={self.uri!r}, name={self.name!r}, mime_type={self.mime_type!r})"

mcptoolforge/schema.py

@@ -0,0 +1,146 @@
+import enum
+import inspect
+import types
+import typing
+from typing import Any
+
+from mcptoolforge.errors import SchemaGenerationError
+from mcptoolforge.registry import ToolParameter
+
+
+def _map_primitive_type(py_type: Any, param_name: str, tool_name: str) -> str:
+    """Map standard Python primitive types to JSON Schema types."""
+    if py_type is int:
+        return "integer"
+    elif py_type is float:
+        return "number"
+    elif py_type is str:
+        return "string"
+    elif py_type is bool:
+        return "boolean"
+    else:
+        raise SchemaGenerationError(
+            f"Unsupported type '{py_type}' for parameter '{param_name}' in tool '{tool_name}'. "
+            "Currently supported types are: str, int, float, bool, list, dict, Enum, "
+            "and Union/Optional."
+        )
+
+
+def _map_type(ann: Any, param_name: str, tool_name: str) -> dict[str, Any]:
+    """Recursively map Python type annotations to JSON Schema dictionaries."""
+    if ann is inspect.Parameter.empty or ann is Any:
+        return {}
+
+    # Handle None / NoneType
+    if ann is None or ann is type(None):
+        return {"type": "null"}
+
+    # Handle standard Unions and Python 3.10+ UnionTypes
+    origin = getattr(ann, "__origin__", None)
+    if origin is typing.Union or (hasattr(types, "UnionType") and isinstance(ann, types.UnionType)):
+        args = typing.get_args(ann)
+        is_nullable = type(None) in args
+        non_null_args = [arg for arg in args if arg is not type(None)]
+
+        mapped_schemas = [_map_type(arg, param_name, tool_name) for arg in non_null_args]
+
+        if len(mapped_schemas) == 1:
+            schema = mapped_schemas[0].copy()
+            if "type" in schema:
+                t = schema["type"]
+                if isinstance(t, list):
+                    schema["type"] = [*t, "null"] if "null" not in t else t
+                else:
+                    schema["type"] = [t, "null"]
+            else:
+                schema["type"] = "null"
+            return schema
+        else:
+            if is_nullable:
+                return {"anyOf": [*mapped_schemas, {"type": "null"}]}
+            else:
+                return {"anyOf": mapped_schemas}
+
+    # Handle List types (list[T], List[T])
+    if ann is list or origin is list or origin is list:
+        args = typing.get_args(ann)
+        if not args:
+            return {"type": "array"}
+        item_type = args[0]
+        items_schema = _map_type(item_type, param_name, tool_name)
+        return {"type": "array", "items": items_schema}
+
+    # Handle Dict types (dict[K, V], Dict[K, V])
+    if ann is dict or origin is dict or origin is dict:
+        args = typing.get_args(ann)
+        if not args:
+            return {"type": "object"}
+        key_type, val_type = args[0], args[1]
+        if key_type is not str:
+            raise SchemaGenerationError(
+                f"Dictionary keys must be 'str' type for parameter '{param_name}' "
+                f"in tool '{tool_name}'."
+            )
+        val_schema = _map_type(val_type, param_name, tool_name)
+        return {"type": "object", "additionalProperties": val_schema}
+
+    # Handle Enum types
+    if isinstance(ann, type) and issubclass(ann, enum.Enum):
+        values = [m.value for m in ann]
+        if not values:
+            raise SchemaGenerationError(
+                f"Empty enum class '{ann.__name__}' for parameter '{param_name}' "
+                f"in tool '{tool_name}'."
+            )
+        val_types = {type(v) for v in values}
+        if len(val_types) == 1:
+            val_type = next(iter(val_types))
+            json_type = _map_primitive_type(val_type, param_name, tool_name)
+        else:
+            json_type = "string"  # Fallback for mixed types
+        return {"type": json_type, "enum": values}
+
+    # Standard primitive types
+    json_type = _map_primitive_type(ann, param_name, tool_name)
+    return {"type": json_type}
+
+
+def generate_input_schema(parameters: dict[str, ToolParameter], tool_name: str) -> dict[str, Any]:
+    """Generate the input JSON Schema from introspected Tool parameters."""
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+
+    for param_name, param in parameters.items():
+        param_schema = _map_type(param.annotation, param_name, tool_name)
+
+        # Handle defaults
+        if param.default is not inspect.Parameter.empty:
+            param_schema["default"] = param.default
+        else:
+            required.append(param_name)
+
+        properties[param_name] = param_schema
+
+    input_schema = {
+        "type": "object",
+        "properties": properties,
+    }
+    if required:
+        input_schema["required"] = required
+
+    return input_schema
+
+
+def generate_tool_schema(func: Any, name: str, description: str) -> dict[str, Any]:
+    """Generate a JSON Schema representation for a tool's parameters.
+
+    Preserves existing functionality by delegating to input schema generation.
+    """
+    from mcptoolforge.registry import Tool
+
+    tool = Tool(func, name=name, description=description)
+    return {
+        "name": name,
+        "description": description,
+        "inputSchema": generate_input_schema(tool.parameters, name),
+    }

mcptoolforge/server.py

@@ -0,0 +1,91 @@
+from collections.abc import Callable
+
+from mcptoolforge.decorators import ToolDecorator
+from mcptoolforge.prompts import Prompt, PromptDecorator, PromptRegistry
+from mcptoolforge.registry import Tool, ToolRegistry
+from mcptoolforge.resources import Resource, ResourceDecorator, ResourceRegistry
+
+
+class MCPServer:
+    """Core MCPServer abstraction class for registering and exposing tools."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self.registry = ToolRegistry()
+        self.tool = ToolDecorator(self.registry)
+        self.resource_registry = ResourceRegistry()
+        self.resource = ResourceDecorator(self.resource_registry)
+        self.prompt_registry = PromptRegistry()
+        self.prompt = PromptDecorator(self.prompt_registry)
+        self.middlewares: list[Callable] = []
+        self.startup_hooks: list[Callable] = []
+        self.shutdown_hooks: list[Callable] = []
+
+    def middleware(self, fn: Callable) -> Callable:
+        """Decorator to register a middleware function."""
+        self.middlewares.append(fn)
+        return fn
+
+    def add_middleware(self, fn: Callable) -> None:
+        """Programmatically register a middleware function."""
+        self.middlewares.append(fn)
+
+    def on_startup(self, fn: Callable) -> Callable:
+        """Decorator to register a startup lifecycle hook."""
+        self.startup_hooks.append(fn)
+        return fn
+
+    def on_shutdown(self, fn: Callable) -> Callable:
+        """Decorator to register a shutdown lifecycle hook."""
+        self.shutdown_hooks.append(fn)
+        return fn
+
+    def run(self) -> None:
+        """Run the MCP server over STDIO transport."""
+        import anyio
+
+        from mcptoolforge.mcp.server import MCPServerRunner
+
+        runner = MCPServerRunner(self.name, self.registry, server=self)
+        anyio.run(runner.run_async)
+
+    @property
+    def tools(self) -> list[Tool]:
+        """Return a list of all registered tools on this server."""
+        return self.registry.list()
+
+    def get_tool(self, name: str) -> Tool:
+        """Retrieve a registered tool by name."""
+        return self.registry.get(name)
+
+    def has_tool(self, name: str) -> bool:
+        """Check if a tool is registered by name."""
+        return self.registry.contains(name)
+
+    def list_tools(self) -> list[Tool]:
+        """Return a list of all registered tools."""
+        return self.registry.list()
+
+    def get_resource(self, uri: str) -> Resource:
+        """Retrieve a registered resource by URI."""
+        return self.resource_registry.get(uri)
+
+    def has_resource(self, uri: str) -> bool:
+        """Check if a resource is registered by URI."""
+        return self.resource_registry.contains(uri)
+
+    def list_resources(self) -> list[Resource]:
+        """Return a list of all registered resources."""
+        return self.resource_registry.list()
+
+    def get_prompt(self, name: str) -> Prompt:
+        """Retrieve a registered prompt by name."""
+        return self.prompt_registry.get(name)
+
+    def has_prompt(self, name: str) -> bool:
+        """Check if a prompt is registered by name."""
+        return self.prompt_registry.contains(name)
+
+    def list_prompts(self) -> list[Prompt]:
+        """Return a list of all registered prompts."""
+        return self.prompt_registry.list()

mcptoolforge/testing/__init__.py

@@ -0,0 +1,15 @@
+from mcptoolforge.testing.client import (
+    MCPTestClient,
+    MCPToolForgeTestingError,
+    PromptGetResult,
+    PromptMessageResult,
+    ResourceReadResult,
+)
+
+__all__ = [
+    "MCPTestClient",
+    "MCPToolForgeTestingError",
+    "PromptGetResult",
+    "PromptMessageResult",
+    "ResourceReadResult",
+]