mcptoolforge 0.1.0__py3-none-any.whl

mcptoolforge/__init__.py

@@ -0,0 +1,64 @@
+from mcptoolforge.config import MCPToolForgeConfig
+from mcptoolforge.errors import (
+    ConfigurationError,
+    EntrypointNotFoundError,
+    InvalidConfigurationError,
+    MCPToolForgeError,
+    MiddlewareError,
+    ProjectNotFoundError,
+    ResourceAlreadyRegisteredError,
+    ResourceExecutionError,
+    ResourceNotFoundError,
+    ResourceRegistrationError,
+    SchemaGenerationError,
+    ToolAlreadyRegisteredError,
+    ToolExecutionError,
+    ToolNotFoundError,
+    ToolRegistrationError,
+    ToolValidationError,
+)
+from mcptoolforge.middleware import (
+    MiddlewareContext,
+    logging_middleware,
+    sync_logging_middleware,
+    sync_timing_middleware,
+    timing_middleware,
+)
+from mcptoolforge.project import Project, load_server_from_file, load_server_from_project
+from mcptoolforge.prompts import Prompt, PromptParameter, PromptRegistry
+from mcptoolforge.resources import Resource, ResourceRegistry
+from mcptoolforge.server import MCPServer
+
+__all__ = [
+    "ConfigurationError",
+    "EntrypointNotFoundError",
+    "InvalidConfigurationError",
+    "MCPServer",
+    "MCPToolForgeConfig",
+    "MCPToolForgeError",
+    "MiddlewareContext",
+    "MiddlewareError",
+    "Project",
+    "ProjectNotFoundError",
+    "Prompt",
+    "PromptParameter",
+    "PromptRegistry",
+    "Resource",
+    "ResourceAlreadyRegisteredError",
+    "ResourceExecutionError",
+    "ResourceNotFoundError",
+    "ResourceRegistrationError",
+    "ResourceRegistry",
+    "SchemaGenerationError",
+    "ToolAlreadyRegisteredError",
+    "ToolExecutionError",
+    "ToolNotFoundError",
+    "ToolRegistrationError",
+    "ToolValidationError",
+    "load_server_from_file",
+    "load_server_from_project",
+    "logging_middleware",
+    "sync_logging_middleware",
+    "sync_timing_middleware",
+    "timing_middleware",
+]

mcptoolforge/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI module for MCPToolForge."""

mcptoolforge/cli/commands.py

@@ -0,0 +1,278 @@
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from mcptoolforge.errors import ConfigurationError
+from mcptoolforge.project import Project, load_server_from_file, load_server_from_project
+
+
+def resolve_server_instance(file_path: str | None) -> tuple[Any, Project | None]:
+    """Resolve the MCPServer instance and the discovered Project config context."""
+    if file_path is not None:
+        server = load_server_from_file(Path(file_path))
+        try:
+            project = Project.discover()
+        except Exception:
+            project = None
+        return server, project
+
+    try:
+        project = Project.discover()
+        server = load_server_from_project(project)
+        return server, project
+    except ConfigurationError as e:
+        # If configuration error was raised (like invalid entrypoint or transport), bubble it up
+        raise e
+    except Exception:
+        # Fallback to default "server.py" in current working directory
+        default_path = Path.cwd() / "server.py"
+        server = load_server_from_file(default_path)
+        return server, None
+
+
+def init_command(directory: str, force: bool = False) -> None:
+    """Initialize a new MCPToolForge project directory with a working MCPServer template."""
+    target_dir = os.path.abspath(directory)
+    project_name = os.path.basename(target_dir.rstrip(os.sep)) or "my-server"
+
+    if os.path.exists(target_dir) and os.listdir(target_dir):
+        conflicts = [
+            f
+            for f in ["server.py", "pyproject.toml", "README.md", ".gitignore"]
+            if os.path.exists(os.path.join(target_dir, f))
+        ]
+        if conflicts and not force:
+            print(
+                f"Error: Destination contains conflicts (e.g. '{conflicts[0]}' already exists). "
+                "Use --force to overwrite.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+    os.makedirs(target_dir, exist_ok=True)
+
+    server_content = f"""from mcptoolforge import MCPServer
+
+server = MCPServer("{project_name}")
+
+@server.tool
+def add(a: int, b: int) -> int:
+    \"\"\"Add two numbers.\"\"\"
+    return a + b
+
+if __name__ == "__main__":
+    server.run()
+"""
+
+    pyproject_content = f"""[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "{project_name}"
+version = "0.1.0"
+dependencies = [
+    "mcptoolforge",
+]
+
+[tool.mcptoolforge]
+name = "{project_name}"
+entrypoint = "server.py"
+transport = "stdio"
+"""
+
+    readme_content = f"""# {project_name}
+
+A MCPToolForge MCP tool server.
+
+## Running
+
+```bash
+python server.py
+```
+"""
+
+    gitignore_content = """__pycache__/
+.venv/
+*.pyc
+"""
+
+    with open(os.path.join(target_dir, "server.py"), "w") as f:
+        f.write(server_content)
+    with open(os.path.join(target_dir, "pyproject.toml"), "w") as f:
+        f.write(pyproject_content)
+    with open(os.path.join(target_dir, "README.md"), "w") as f:
+        f.write(readme_content)
+    with open(os.path.join(target_dir, ".gitignore"), "w") as f:
+        f.write(gitignore_content)
+
+    print(f"Initialized MCPToolForge project in '{target_dir}'", file=sys.stderr)
+
+
+def run_command(file_path: str | None) -> None:
+    """Execute the discovered MCPServer instance loop."""
+    try:
+        server, _ = resolve_server_instance(file_path)
+    except ConfigurationError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    server.run()
+
+
+def list_command(file_path: str | None) -> None:
+    """Print all registered tools, resources, and prompts in the project.
+
+    Does so without booting the server.
+    """
+    try:
+        server, _ = resolve_server_instance(file_path)
+    except ConfigurationError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"MCPToolForge Server: {server.name}")
+    print()
+    print("Tools")
+    print("─────────────────────────")
+    for tool in server.tools:
+        desc = tool.description or ""
+        first_line = desc.split("\n")[0] if desc else ""
+        print(f"{tool.name:<9} {first_line}")
+
+    resources = server.list_resources()
+    if resources:
+        print()
+        print("Resources")
+        print("─────────────────────────")
+        for res in resources:
+            desc = res.description or ""
+            first_line = desc.split("\n")[0] if desc else ""
+            print(f"{res.uri:<15} {first_line}")
+
+    prompts = server.list_prompts()
+    if prompts:
+        print()
+        print("Prompts")
+        print("─────────────────────────")
+        for pr in prompts:
+            desc = pr.description or ""
+            first_line = desc.split("\n")[0] if desc else ""
+            print(f"{pr.name:<15} {first_line}")
+
+
+def inspect_command(file_path: str | None, tool_name: str | None = None) -> None:
+    """Inspect the server configuration, specific tool, resource, or prompt detail."""
+    try:
+        server, project = resolve_server_instance(file_path)
+    except ConfigurationError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if tool_name is None:
+        print("MCPToolForge Project")
+        print("─────────────────────────")
+        if project is not None:
+            print(f"Name: {project.config.name}")
+            print(f"Root: {project.root}")
+            print(f"Entrypoint: {project.config.entrypoint}")
+            print(f"Transport: {project.config.transport}")
+        else:
+            print(f"Name: {server.name}")
+            print(f"Root: {Path.cwd()}")
+            print(f"Entrypoint: {Path(file_path or 'server.py').name}")
+            print("Transport: stdio")
+        print()
+        print("Tools")
+        print("─────────────────────────")
+        for tool in server.tools:
+            print(tool.name)
+
+        resources = server.list_resources()
+        if resources:
+            print()
+            print("Resources")
+            print("─────────────────────────")
+            for res in resources:
+                print(res.uri)
+
+        prompts = server.list_prompts()
+        if prompts:
+            print()
+            print("Prompts")
+            print("─────────────────────────")
+            for pr in prompts:
+                print(pr.name)
+    else:
+        # 1. Try to find a matching tool
+        target_tool = None
+        for tool in server.tools:
+            if tool.name == tool_name:
+                target_tool = tool
+                break
+
+        if target_tool is not None:
+            print(f"Tool: {target_tool.name}")
+            print()
+            print("Description:")
+            print(target_tool.description or "")
+            print()
+            print("Parameters:")
+            print()
+            for p_name, p in target_tool.parameters.items():
+                required_str = "yes" if p.required else "no"
+                type_name = getattr(p.annotation, "__name__", str(p.annotation))
+                print(f"{p_name}")
+                print(f"  type: {type_name}")
+                print(f"  required: {required_str}")
+                print()
+            print("Input Schema:")
+            print(json.dumps(target_tool.input_schema, indent=4))
+            return
+
+        # 2. Try to find a matching resource
+        target_resource = None
+        for res in server.list_resources():
+            if res.uri == tool_name:
+                target_resource = res
+                break
+
+        if target_resource is not None:
+            print(f"Resource: {target_resource.uri}")
+            print()
+            print(f"  Name: {target_resource.name}")
+            print(f"  MIME: {target_resource.mime_type or 'unspecified'}")
+            print(f"  Description: {target_resource.description or ''}")
+            return
+
+        # 3. Try to find a matching prompt
+        target_prompt = None
+        for pr in server.list_prompts():
+            if pr.name == tool_name:
+                target_prompt = pr
+                break
+
+        if target_prompt is not None:
+            print(f"Prompt: {target_prompt.name}")
+            print()
+            print("Description:")
+            print(target_prompt.description or "")
+            print()
+            print("Arguments:")
+            for p_name, p in target_prompt.parameters.items():
+                required_str = "yes" if p.required else "no"
+                type_name = getattr(p.annotation, "__name__", str(p.annotation))
+                if type_name == "str":
+                    type_name = "string"
+                print(f"  {p_name}")
+                print(f"    type: {type_name}")
+                print(f"    required: {required_str}")
+                print()
+            return
+
+        print(
+            f"Error: tool, resource, or prompt '{tool_name}' is not registered.",
+            file=sys.stderr,
+        )
+        sys.exit(1)

mcptoolforge/cli/main.py

@@ -0,0 +1,101 @@
+import argparse
+import importlib.metadata
+import sys
+
+from mcptoolforge.cli.commands import (
+    init_command,
+    inspect_command,
+    list_command,
+    run_command,
+)
+
+
+def get_version() -> str:
+    """Retrieve authoritative package version or fallback to 0.1.0."""
+    try:
+        return importlib.metadata.version("mcptoolforge")
+    except Exception:
+        return "0.1.0"
+
+
+def main() -> None:
+    """Entrypoint parsing CLI commands."""
+    parser = argparse.ArgumentParser(
+        prog="mcptoolforge",
+        description="MCPToolForge\nBuild MCP-ready tools with minimal boilerplate.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"mcptoolforge {get_version()}",
+        help="Show version information.",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", title="Available commands")
+
+    # 1. init subcommand
+    init_parser = subparsers.add_parser("init", help="Initialize a new MCPToolForge project.")
+    init_parser.add_argument(
+        "directory",
+        nargs="?",
+        default=".",
+        help="Directory to initialize the project in. (default: current directory)",
+    )
+    init_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Force overwrite existing files in the destination directory.",
+    )
+
+    # 2. run subcommand
+    run_parser = subparsers.add_parser("run", help="Start the MCPToolForge MCP server.")
+    run_parser.add_argument(
+        "--file",
+        default=None,
+        help="Path to the python file containing the MCPServer instance. (default: server.py)",
+    )
+
+    # 3. list subcommand
+    list_parser = subparsers.add_parser("list", help="List registered tools locally.")
+    list_parser.add_argument(
+        "--file",
+        default=None,
+        help="Path to the python file containing the MCPServer instance. (default: server.py)",
+    )
+
+    # 4. inspect subcommand
+    inspect_parser = subparsers.add_parser(
+        "inspect", help="Inspect server or specific tool details."
+    )
+    inspect_parser.add_argument(
+        "tool_name",
+        nargs="?",
+        default=None,
+        help="Name of the specific tool to inspect.",
+    )
+    inspect_parser.add_argument(
+        "--file",
+        default=None,
+        help="Path to the python file containing the MCPServer instance. (default: server.py)",
+    )
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    if args.command == "init":
+        init_command(args.directory, args.force)
+    elif args.command == "run":
+        run_command(args.file)
+    elif args.command == "list":
+        list_command(args.file)
+    elif args.command == "inspect":
+        inspect_command(args.file, args.tool_name)
+
+
+if __name__ == "__main__":
+    main()

mcptoolforge/config.py

@@ -0,0 +1,45 @@
+from dataclasses import dataclass
+
+from mcptoolforge.errors import InvalidConfigurationError
+
+
+@dataclass
+class MCPToolForgeConfig:
+    """Typed, validated representation of MCPToolForge project configuration."""
+
+    name: str
+    entrypoint: str = "server.py"
+    transport: str = "stdio"
+
+    def __post_init__(self) -> None:
+        # Validate name
+        if not isinstance(self.name, str) or not self.name.strip():
+            raise InvalidConfigurationError(
+                "MCPToolForge configuration 'name' must be a non-empty string."
+            )
+        self.name = self.name.strip()
+
+        # Validate entrypoint
+        if not isinstance(self.entrypoint, str) or not self.entrypoint.strip():
+            raise InvalidConfigurationError(
+                "MCPToolForge configuration 'entrypoint' must be a non-empty string."
+            )
+        self.entrypoint = self.entrypoint.strip()
+
+        if not self.entrypoint.endswith(".py"):
+            raise InvalidConfigurationError(
+                f"MCPToolForge entrypoint '{self.entrypoint}' is not a Python file."
+            )
+
+        # Validate transport
+        if not isinstance(self.transport, str) or not self.transport.strip():
+            raise InvalidConfigurationError(
+                "MCPToolForge configuration 'transport' must be a non-empty string."
+            )
+        self.transport = self.transport.strip()
+
+        if self.transport != "stdio":
+            raise InvalidConfigurationError(
+                f"Unsupported transport '{self.transport}' for MCPToolForge server. "
+                "Only 'stdio' is currently supported."
+            )

mcptoolforge/decorators.py

@@ -0,0 +1,49 @@
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from mcptoolforge.registry import Tool
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class ToolDecorator:
+    """Decorator to register functions as tools on a ToolRegistry.
+
+    Supports both direct decorator style:
+        @server.tool
+        def my_tool(): ...
+
+    And parameter style:
+        @server.tool(name="custom_name", description="custom_desc")
+        def my_tool(): ...
+    """
+
+    def __init__(self, registry: Any) -> None:
+        self._registry = registry
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        # Check if used as @tool directly
+        if len(args) == 1 and callable(args[0]) and not kwargs:
+            func = args[0]
+            tool = Tool(func)
+            self._registry.register(tool)
+            return func
+
+        # Used as @tool(name=..., description=...)
+        name: str | None = kwargs.get("name")
+        description: str | None = kwargs.get("description")
+        tags: list[str] | None = kwargs.get("tags")
+        metadata: dict[str, Any] | None = kwargs.get("metadata")
+
+        def decorator(func: F) -> F:
+            tool = Tool(
+                func,
+                name=name,
+                description=description,
+                tags=tags,
+                metadata=metadata,
+            )
+            self._registry.register(tool)
+            return func
+
+        return decorator

mcptoolforge/errors.py

@@ -0,0 +1,94 @@
+class MCPToolForgeError(Exception):
+    """Base exception for all MCPToolForge errors."""
+
+    pass
+
+
+class ToolRegistrationError(MCPToolForgeError):
+    """Raised when registering a tool fails."""
+
+    pass
+
+
+class ToolAlreadyRegisteredError(ToolRegistrationError):
+    """Raised when trying to register a tool that is already registered."""
+
+    pass
+
+
+class ToolNotFoundError(MCPToolForgeError):
+    """Raised when a tool is looked up but not found."""
+
+    pass
+
+
+class ToolExecutionError(MCPToolForgeError):
+    """Raised when executing a tool fails."""
+
+    pass
+
+
+class SchemaGenerationError(MCPToolForgeError):
+    """Raised when generating schema for a tool fails."""
+
+    pass
+
+
+class ToolValidationError(MCPToolForgeError):
+    """Raised when validating tool arguments fails."""
+
+    pass
+
+
+class ConfigurationError(MCPToolForgeError):
+    """Base exception for all configuration and project loading errors."""
+
+    pass
+
+
+class ProjectNotFoundError(ConfigurationError):
+    """Raised when pyproject.toml is missing or does not contain a MCPToolForge configuration."""
+
+    pass
+
+
+class InvalidConfigurationError(ConfigurationError):
+    """Raised when configuration values fail validation checks."""
+
+    pass
+
+
+class EntrypointNotFoundError(ConfigurationError):
+    """Raised when the specified entrypoint cannot be located."""
+
+    pass
+
+
+class MiddlewareError(MCPToolForgeError):
+    """Raised when middleware logic fails or raises an error."""
+
+    pass
+
+
+class ResourceRegistrationError(MCPToolForgeError):
+    """Raised when registering a resource fails."""
+
+    pass
+
+
+class ResourceAlreadyRegisteredError(ResourceRegistrationError):
+    """Raised when a resource with the same URI is already registered."""
+
+    pass
+
+
+class ResourceNotFoundError(MCPToolForgeError):
+    """Raised when a resource is looked up but not found."""
+
+    pass
+
+
+class ResourceExecutionError(MCPToolForgeError):
+    """Raised when executing/reading a resource fails."""
+
+    pass

mcptoolforge/execution.py

@@ -0,0 +1,25 @@
+import inspect
+from typing import Any
+
+from mcptoolforge.errors import ToolExecutionError
+from mcptoolforge.registry import Tool
+
+
+async def execute_tool(tool: Tool, arguments: dict[str, Any]) -> Any:
+    """Execute a tool asynchronously with the provided arguments.
+
+    If the underlying function is synchronous, it runs directly.
+    If it is a coroutine, it is awaited.
+    """
+    from mcptoolforge.validation import validate_tool_arguments
+
+    # Validate and normalize arguments
+    validated_args = validate_tool_arguments(tool, arguments)
+
+    try:
+        if inspect.iscoroutinefunction(tool.fn):
+            return await tool.fn(**validated_args)
+        else:
+            return tool.fn(**validated_args)
+    except Exception as e:
+        raise ToolExecutionError(f"Error executing tool '{tool.name}': {e}") from e

mcptoolforge/mcp/__init__.py

@@ -0,0 +1,4 @@
+from mcptoolforge.mcp.adapter import MCPAdapter
+from mcptoolforge.mcp.server import MCPServerRunner
+
+__all__ = ["MCPAdapter", "MCPServerRunner"]