mcptoolforge 0.1.0__py3-none-any.whl

mcptoolforge/project.py

@@ -0,0 +1,134 @@
+import importlib.util
+import sys
+import tomllib
+from pathlib import Path
+
+from mcptoolforge.config import MCPToolForgeConfig
+from mcptoolforge.errors import (
+    EntrypointNotFoundError,
+    InvalidConfigurationError,
+    ProjectNotFoundError,
+)
+from mcptoolforge.server import MCPServer
+
+
+class Project:
+    """Represents a discovered MCPToolForge project and its configuration."""
+
+    def __init__(self, root: Path, pyproject_path: Path, config: MCPToolForgeConfig):
+        self.root = root
+        self.pyproject_path = pyproject_path
+        self.config = config
+
+    @classmethod
+    def discover(cls, start_dir: Path | None = None) -> "Project":
+        """Search up directory tree starting from start_dir for pyproject.toml."""
+        current = Path(start_dir or Path.cwd()).resolve()
+
+        while True:
+            pyproject_file = current / "pyproject.toml"
+            if pyproject_file.is_file():
+                try:
+                    with open(pyproject_file, "rb") as f:
+                        data = tomllib.load(f)
+                except Exception as e:
+                    raise InvalidConfigurationError(
+                        f"Failed to parse TOML in '{pyproject_file}': {e}"
+                    ) from e
+
+                # Extract [tool.mcptoolforge] section
+                tool_data = data.get("tool", {})
+                if "mcptoolforge" not in tool_data:
+                    raise ProjectNotFoundError(
+                        "MCPToolForge configuration '[tool.mcptoolforge]' not found "
+                        f"in '{pyproject_file}'."
+                    )
+
+                tf_section = tool_data["mcptoolforge"]
+                if not isinstance(tf_section, dict):
+                    raise InvalidConfigurationError(
+                        "Section '[tool.mcptoolforge]' "
+                        f"in '{pyproject_file}' must be a table/dictionary."
+                    )
+
+                if "name" not in tf_section:
+                    raise InvalidConfigurationError(
+                        "Required configuration field 'name' is missing "
+                        f"from '[tool.mcptoolforge]' in '{pyproject_file}'."
+                    )
+
+                config = MCPToolForgeConfig(
+                    name=tf_section["name"],
+                    entrypoint=tf_section.get("entrypoint", "server.py"),
+                    transport=tf_section.get("transport", "stdio"),
+                )
+
+                return cls(
+                    root=current,
+                    pyproject_path=pyproject_file,
+                    config=config,
+                )
+
+            # Move up to parent directory
+            parent = current.parent
+            if parent == current:
+                raise ProjectNotFoundError(
+                    "Could not find a pyproject.toml file in parent directories."
+                )
+            current = parent
+
+
+def load_server_from_project(project: Project) -> MCPServer:
+    """Safely load and import the MCPServer instance from the project configuration."""
+    entrypoint_path = (project.root / project.config.entrypoint).resolve()
+    return load_server_from_file(entrypoint_path)
+
+
+def load_server_from_file(file_path: Path) -> MCPServer:
+    """Safely load and import the MCPServer instance from a specific file path."""
+    if not file_path.exists():
+        raise EntrypointNotFoundError(f"MCPToolForge entrypoint '{file_path.name}' was not found.")
+
+    if not file_path.is_file() or file_path.suffix != ".py":
+        raise InvalidConfigurationError(
+            f"MCPToolForge entrypoint '{file_path.name}' is not a Python file."
+        )
+
+    try:
+        module_name = "mcptoolforge_user_server"
+        spec = importlib.util.spec_from_file_location(module_name, file_path)
+        if spec is None or spec.loader is None:
+            raise InvalidConfigurationError(
+                f"Failed to load spec for entrypoint '{file_path.name}'."
+            )
+
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        spec.loader.exec_module(module)
+    except Exception as e:
+        raise InvalidConfigurationError(
+            f"Failed to execute entrypoint module '{file_path.name}': {e}"
+        ) from e
+
+    # Find the expected server object in the loaded module variables
+    server_vars = {}
+    for attr_name in dir(module):
+        attr = getattr(module, attr_name)
+        if isinstance(attr, MCPServer):
+            server_vars[attr_name] = attr
+
+    # 1. Enforce naming convention first
+    if "server" in server_vars:
+        return server_vars["server"]
+
+    # 2. Check for multiple instances (ambiguity)
+    if len(server_vars) > 1:
+        raise InvalidConfigurationError(
+            f"Multiple MCPServer instances found in '{file_path.name}', "
+            f"but none are named 'server'. Ambiguity detected: {list(server_vars.keys())}."
+        )
+
+    # 3. No instance or naming convention mismatch
+    raise InvalidConfigurationError(
+        f"Entry point '{file_path.name}' does not define a MCPToolForge MCPServer named 'server'."
+    )

mcptoolforge/prompts/__init__.py

@@ -0,0 +1,5 @@
+from mcptoolforge.prompts.decorator import PromptDecorator
+from mcptoolforge.prompts.prompt import Prompt, PromptParameter
+from mcptoolforge.prompts.registry import PromptRegistry
+
+__all__ = ["Prompt", "PromptDecorator", "PromptParameter", "PromptRegistry"]

mcptoolforge/prompts/decorator.py

@@ -0,0 +1,32 @@
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from mcptoolforge.prompts.prompt import Prompt
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class PromptDecorator:
+    """Decorator to register functions as prompts on a PromptRegistry."""
+
+    def __init__(self, registry: Any) -> None:
+        self._registry = registry
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        # Check if used as @prompt directly
+        if len(args) == 1 and callable(args[0]) and not kwargs:
+            func = args[0]
+            prompt = Prompt(func)
+            self._registry.register(prompt)
+            return func
+
+        # Used as @prompt(name=..., description=...)
+        name: str | None = kwargs.get("name")
+        description: str | None = kwargs.get("description")
+
+        def decorator(func: F) -> F:
+            prompt = Prompt(func, name=name, description=description)
+            self._registry.register(prompt)
+            return func
+
+        return decorator

mcptoolforge/prompts/prompt.py

@@ -0,0 +1,129 @@
+import inspect
+import re
+from collections.abc import Callable
+from typing import Any, get_type_hints
+
+from mcptoolforge.errors import ToolRegistrationError
+
+
+class PromptParameter:
+    """Represents an argument/parameter of a prompt."""
+
+    def __init__(
+        self,
+        name: str,
+        annotation: Any,
+        default: Any,
+        required: bool,
+        kind: inspect._ParameterKind,
+    ):
+        self.name = name
+        self.annotation = annotation
+        self.default = default
+        self.required = required
+        self.kind = kind
+
+    def __repr__(self) -> str:
+        return (
+            f"PromptParameter(name={self.name!r}, annotation={self.annotation!r}, "
+            f"default={self.default!r}, required={self.required!r})"
+        )
+
+
+class Prompt:
+    """Represents a registered prompt template in MCPToolForge."""
+
+    def __init__(
+        self,
+        fn: Callable[..., Any],
+        name: str | None = None,
+        description: str | None = None,
+    ):
+        if not callable(fn):
+            raise ToolRegistrationError("Registered prompt object must be a callable.")
+
+        self._fn = fn
+
+        # Name validation
+        if name is not None:
+            if not isinstance(name, str):
+                raise ToolRegistrationError("Prompt name must be a string.")
+            if not name.strip():
+                raise ToolRegistrationError("Prompt name cannot be empty or whitespace-only.")
+            self._name = name.strip()
+        else:
+            self._name = fn.__name__
+
+        if not re.match(r"^[a-zA-Z_][a-zA-Z0-9_-]*$", self._name):
+            raise ToolRegistrationError(
+                f"Invalid prompt name: '{self._name}'. "
+                "Must be alphanumeric, underscores, or hyphens."
+            )
+
+        # Description validation
+        if description is not None:
+            if not isinstance(description, str):
+                raise ToolRegistrationError("Prompt description must be a string.")
+            if not description.strip():
+                raise ToolRegistrationError(
+                    "Prompt 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."
+
+        # Introspect function parameters
+        self._parameters: dict[str, PromptParameter] = {}
+        try:
+            sig = inspect.signature(fn)
+            try:
+                type_hints = get_type_hints(fn)
+            except (TypeError, NameError):
+                type_hints = {}
+        except Exception as e:
+            raise ToolRegistrationError(f"Failed to inspect prompt function signature: {e}") from e
+
+        for param_name, param in sig.parameters.items():
+            if param_name in ("self", "cls"):
+                continue
+
+            annotation = type_hints.get(param_name, param.annotation)
+            required = param.default is inspect.Parameter.empty
+            default = inspect.Parameter.empty if required else param.default
+
+            self._parameters[param_name] = PromptParameter(
+                name=param_name,
+                annotation=annotation,
+                default=default,
+                required=required,
+                kind=param.kind,
+            )
+
+        self._return_type = type_hints.get("return", sig.return_annotation)
+
+    @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 parameters(self) -> dict[str, PromptParameter]:
+        return self._parameters
+
+    @property
+    def return_type(self) -> Any:
+        return self._return_type
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self._fn(*args, **kwargs)
+
+    def __repr__(self) -> str:
+        return f"Prompt(name={self.name!r}, description={self.description!r})"

mcptoolforge/prompts/registry.py

@@ -0,0 +1,37 @@
+from mcptoolforge.errors import ToolAlreadyRegisteredError, ToolNotFoundError
+from mcptoolforge.prompts.prompt import Prompt
+
+
+class PromptRegistry:
+    """Manages prompt storage, lookup, and deletion."""
+
+    def __init__(self) -> None:
+        self._prompts: dict[str, Prompt] = {}
+
+    def register(self, prompt: Prompt) -> None:
+        """Register a prompt in the registry."""
+        if prompt.name in self._prompts:
+            raise ToolAlreadyRegisteredError(
+                f"Duplicate prompt name: '{prompt.name}' is already registered."
+            )
+        self._prompts[prompt.name] = prompt
+
+    def get(self, name: str) -> Prompt:
+        """Retrieve a prompt by name."""
+        if name not in self._prompts:
+            raise ToolNotFoundError(f"Prompt '{name}' is not registered.")
+        return self._prompts[name]
+
+    def remove(self, name: str) -> None:
+        """Remove a prompt by name."""
+        if name not in self._prompts:
+            raise ToolNotFoundError(f"Prompt '{name}' is not registered and cannot be removed.")
+        del self._prompts[name]
+
+    def list(self) -> list[Prompt]:
+        """Return a list of all registered prompts."""
+        return list(self._prompts.values())
+
+    def contains(self, name: str) -> bool:
+        """Check if a prompt is registered by name."""
+        return name in self._prompts

mcptoolforge/registry.py

@@ -0,0 +1,241 @@
+import inspect
+import re
+from collections.abc import Callable
+from typing import Any, get_type_hints
+
+from mcptoolforge.errors import (
+    ToolAlreadyRegisteredError,
+    ToolNotFoundError,
+    ToolRegistrationError,
+)
+
+
+class ToolParameter:
+    """Represents an input parameter of a tool."""
+
+    def __init__(
+        self,
+        name: str,
+        annotation: Any,
+        default: Any,
+        required: bool,
+        kind: inspect._ParameterKind,
+    ):
+        self.name = name
+        self.annotation = annotation
+        self.default = default
+        self.required = required
+        self.kind = kind
+
+    def __repr__(self) -> str:
+        return (
+            f"ToolParameter(name={self.name!r}, annotation={self.annotation!r}, "
+            f"default={self.default!r}, required={self.required!r}, kind={self.kind!r})"
+        )
+
+
+class Tool:
+    """Represents a registered tool in MCPToolForge."""
+
+    def __init__(
+        self,
+        fn: Callable[..., Any],
+        name: str | None = None,
+        description: str | None = None,
+        tags: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ):
+        if not callable(fn):
+            raise ToolRegistrationError("Registered object must be a callable.")
+
+        self._fn = fn
+
+        # Validate name
+        if name is not None:
+            if not isinstance(name, str):
+                raise ToolRegistrationError("Tool name must be a string.")
+            if not name.strip():
+                raise ToolRegistrationError("Tool name cannot be empty or whitespace-only.")
+            self._name = name.strip()
+        else:
+            self._name = fn.__name__
+
+        # Validate name format (standard identifier conventions)
+        if not re.match(r"^[a-zA-Z_][a-zA-Z0-9_-]*$", self._name):
+            raise ToolRegistrationError(
+                f"Invalid tool name: '{self._name}'. Must be alphanumeric, underscores, or hyphens."
+            )
+
+        # Validate description
+        if description is not None:
+            if not isinstance(description, str):
+                raise ToolRegistrationError("Custom description must be a string.")
+            if not description.strip():
+                raise ToolRegistrationError(
+                    "Custom 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."
+
+        # Validate and store tags
+        self._tags: list[str] = []
+        if tags is not None:
+            if not isinstance(tags, (list, tuple)):
+                raise ToolRegistrationError("Tags must be a list or tuple of strings.")
+            seen = set()
+            clean_tags = []
+            for tag in tags:
+                if not isinstance(tag, str) or not tag.strip():
+                    raise ToolRegistrationError("Each tag must be a non-empty string.")
+                t_stripped = tag.strip()
+                if t_stripped not in seen:
+                    seen.add(t_stripped)
+                    clean_tags.append(t_stripped)
+            self._tags = clean_tags
+
+        # Validate and store metadata
+        self._metadata: dict[str, Any] = {}
+        if metadata is not None:
+            if not isinstance(metadata, dict):
+                raise ToolRegistrationError("Metadata must be a dictionary.")
+            for key in metadata:
+                if not isinstance(key, str):
+                    raise ToolRegistrationError("Metadata keys must be strings.")
+                if key in {
+                    "name",
+                    "description",
+                    "tags",
+                    "parameters",
+                    "return_type",
+                    "input_schema",
+                    "fn",
+                }:
+                    raise ToolRegistrationError(
+                        f"Metadata key '{key}' conflicts with a core Tool field."
+                    )
+            import json
+
+            try:
+                json.dumps(metadata)
+            except (TypeError, ValueError) as e:
+                raise ToolRegistrationError(
+                    f"Metadata values must be JSON serializable: {e}"
+                ) from e
+            self._metadata = metadata
+
+        # Introspect function parameters and return type
+        self._parameters: dict[str, ToolParameter] = {}
+        try:
+            sig = inspect.signature(fn)
+            try:
+                type_hints = get_type_hints(fn)
+            except (TypeError, NameError):
+                # Fallback if types cannot be resolved (e.g. forward refs not in scope)
+                type_hints = {}
+        except Exception as e:
+            raise ToolRegistrationError(f"Failed to inspect function signature: {e}") from e
+
+        for param_name, param in sig.parameters.items():
+            if param_name in ("self", "cls"):
+                continue
+
+            annotation = type_hints.get(param_name, param.annotation)
+            required = param.default is inspect.Parameter.empty
+            default = inspect.Parameter.empty if required else param.default
+
+            self._parameters[param_name] = ToolParameter(
+                name=param_name,
+                annotation=annotation,
+                default=default,
+                required=required,
+                kind=param.kind,
+            )
+
+        self._return_type = type_hints.get("return", sig.return_annotation)
+
+    @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 parameters(self) -> dict[str, ToolParameter]:
+        return self._parameters
+
+    @property
+    def return_type(self) -> Any:
+        return self._return_type
+
+    @property
+    def tags(self) -> list[str]:
+        return self._tags
+
+    @property
+    def metadata(self) -> dict[str, Any]:
+        return self._metadata
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        """Generate the input JSON Schema for this tool's parameters."""
+        from mcptoolforge.schema import generate_input_schema
+
+        return generate_input_schema(self.parameters, self.name)
+
+    @property
+    def schema(self) -> dict[str, Any]:
+        """Lazy schema generation to decouple schema structure from representation."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "inputSchema": self.input_schema,
+        }
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self.fn(*args, **kwargs)
+
+    def __repr__(self) -> str:
+        return f"Tool(name={self.name!r}, description={self.description!r})"
+
+
+class ToolRegistry:
+    """Manages tool storage, lookup, and deletion."""
+
+    def __init__(self) -> None:
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, tool: Tool) -> None:
+        """Register a tool in the registry."""
+        if tool.name in self._tools:
+            raise ToolAlreadyRegisteredError(
+                f"Duplicate tool name: '{tool.name}' is already registered."
+            )
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> Tool:
+        """Retrieve a tool by name."""
+        if name not in self._tools:
+            raise ToolNotFoundError(f"Tool '{name}' is not registered.")
+        return self._tools[name]
+
+    def remove(self, name: str) -> None:
+        """Remove a tool by name."""
+        if name not in self._tools:
+            raise ToolNotFoundError(f"Tool '{name}' is not registered and cannot be removed.")
+        del self._tools[name]
+
+    def list(self) -> list[Tool]:
+        """Return a list of all registered tools."""
+        return list(self._tools.values())
+
+    def contains(self, name: str) -> bool:
+        """Check if a tool is registered by name."""
+        return name in self._tools

mcptoolforge/resources/__init__.py

@@ -0,0 +1,5 @@
+from mcptoolforge.resources.decorator import ResourceDecorator
+from mcptoolforge.resources.registry import ResourceRegistry
+from mcptoolforge.resources.resource import Resource
+
+__all__ = ["Resource", "ResourceDecorator", "ResourceRegistry"]

mcptoolforge/resources/decorator.py

@@ -0,0 +1,33 @@
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from mcptoolforge.resources.resource import Resource
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class ResourceDecorator:
+    """Decorator to register functions as resources on a ResourceRegistry."""
+
+    def __init__(self, registry: Any) -> None:
+        self._registry = registry
+
+    def __call__(
+        self,
+        uri: str,
+        name: str | None = None,
+        description: str | None = None,
+        mime_type: str | None = None,
+    ) -> Callable[[F], F]:
+        def decorator(func: F) -> F:
+            resource = Resource(
+                uri=uri,
+                fn=func,
+                name=name,
+                description=description,
+                mime_type=mime_type,
+            )
+            self._registry.register(resource)
+            return func
+
+        return decorator

mcptoolforge/resources/registry.py

@@ -0,0 +1,39 @@
+from mcptoolforge.errors import ResourceAlreadyRegisteredError, ResourceNotFoundError
+from mcptoolforge.resources.resource import Resource
+
+
+class ResourceRegistry:
+    """Manages resource storage, lookup, and deletion."""
+
+    def __init__(self) -> None:
+        self._resources: dict[str, Resource] = {}
+
+    def register(self, resource: Resource) -> None:
+        """Register a resource in the registry."""
+        if resource.uri in self._resources:
+            raise ResourceAlreadyRegisteredError(
+                f"Duplicate resource URI: '{resource.uri}' is already registered."
+            )
+        self._resources[resource.uri] = resource
+
+    def get(self, uri: str) -> Resource:
+        """Retrieve a resource by its URI."""
+        if uri not in self._resources:
+            raise ResourceNotFoundError(f"Resource with URI '{uri}' is not registered.")
+        return self._resources[uri]
+
+    def remove(self, uri: str) -> None:
+        """Remove a resource by its URI."""
+        if uri not in self._resources:
+            raise ResourceNotFoundError(
+                f"Resource with URI '{uri}' is not registered and cannot be removed."
+            )
+        del self._resources[uri]
+
+    def list(self) -> list[Resource]:
+        """Return a list of all registered resources."""
+        return list(self._resources.values())
+
+    def contains(self, uri: str) -> bool:
+        """Check if a resource is registered by its URI."""
+        return uri in self._resources