mcp-server-framework 1.1.0__py3-none-any.whl

mcp_server_factory/__init__.py

@@ -0,0 +1,11 @@
+"""mcp_server_factory — Builds MCP servers from tool modules.
+
+Everything is a plugin. External tools and internal management
+commands use the same interface: register(mcp, config).
+"""
+
+__version__ = "1.1.0"
+
+from .factory import Factory
+
+__all__ = ["Factory"]

mcp_server_factory/commands.py

@@ -0,0 +1,80 @@
+"""CLI — Entry point for the MCP Server Factory."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from mcp_server_framework import load_config, create_server, run_server, start_health_server
+from mcp_server_framework.plugins.loader import add_plugin_dir
+from mcp_server_framework.plugins.tracker import set_log_callback
+from .factory import Factory
+
+logger = logging.getLogger(__name__)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog="mcp-factory", description="MCP Server Factory — loads tool modules as plugins.")
+    parser.add_argument("--plugins", "-p", nargs="+", default=[], help="Plugin names to load")
+    parser.add_argument("--config", "-c", type=Path, default=None, help="YAML config file")
+    parser.add_argument("--http", type=int, metavar="PORT", help="HTTP transport on given port")
+    parser.add_argument("--health-port", type=int, metavar="PORT", help="Health endpoint port")
+    parser.add_argument(
+        "--plugin-dir", "-d", type=Path, action="append", default=[],
+        help="Additional plugin search directory (can be repeated)",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    config = load_config(args.config)
+    if args.http:
+        config["transport"] = "http"
+        config["port"] = args.http
+    if args.health_port:
+        config["health_port"] = args.health_port
+    if config.get("server_name") == "MCP Server":
+        config["server_name"] = "MCP Factory"
+
+    from mcp_server_framework import setup_logging
+    setup_logging(
+        level=config.get("log_level", "INFO"),
+        json_format=config.get("log_format") == "json",
+    )
+
+    plugin_names = args.plugins or config.get("plugins_load", [])
+    plugins_config = config.get("plugins", {})
+    if not plugin_names and isinstance(plugins_config, dict):
+        plugin_names = [n for n, c in plugins_config.items() if isinstance(c, dict) and c.get("enabled", True)]
+    if not plugin_names:
+        print("Error: No plugins specified (use --plugins or config)")
+        sys.exit(1)
+
+    # Set up plugin infrastructure
+    add_plugin_dir(Path(__file__).parent.parent.parent / "plugins")
+    for plugin_dir in args.plugin_dir:
+        add_plugin_dir(plugin_dir.resolve())
+    from .plugins.logging import log_settings
+    set_log_callback(log_settings.log_call)
+
+    mcp = create_server(config)
+    factory = Factory(mcp, config)
+    config["_factory"] = factory
+    factory.load_internals()
+    loaded = factory.load_externals(plugin_names)
+    if not loaded:
+        logger.error("No plugins loaded successfully — aborting")
+        sys.exit(1)
+    logger.info("%d plugin(s) loaded: %s", len(loaded), ", ".join(loaded))
+
+    if config.get("transport") != "stdio":
+        start_health_server(port=config["health_port"], title=f"{config['server_name']} Health")
+
+    run_server(mcp, config)
+
+
+if __name__ == "__main__":
+    main()

mcp_server_factory/factory.py

@@ -0,0 +1,113 @@
+"""Factory — Core orchestrator for plugin loading and management."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from types import ModuleType
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+from mcp_server_framework.plugins import LoadedPlugin, load_module, find_register, ToolTracker
+
+logger = logging.getLogger(__name__)
+
+
+class Factory:
+    """Plugin-based MCP server factory."""
+
+    def __init__(self, mcp: FastMCP, config: dict[str, Any]):
+        self.mcp = mcp
+        self.config = config
+        self.plugins: dict[str, LoadedPlugin] = {}
+        self._all_tools: set[str] = set()
+        self._all_resources: set[str] = set()
+        self._all_prompts: set[str] = set()
+
+    def load_internals(self) -> None:
+        """Load internal factory plugins (management, logging)."""
+        from .plugins import management, logging as factory_logging
+        internal_config = {"_factory": self}
+        self._load_module(management, "factory_management", internal_config, internal=True)
+        self._load_module(factory_logging, "factory_logging", internal_config, internal=True)
+
+    def load_externals(self, plugin_names: list[str]) -> list[str]:
+        """Load external plugins by name. Returns list of successfully loaded names."""
+        loaded = []
+        plugins_config = self.config.get("plugins", {})
+        for name in plugin_names:
+            plugin_config = plugins_config.get(name, {})
+            if isinstance(plugin_config, dict) and not plugin_config.get("enabled", True):
+                logger.info("Plugin '%s' disabled in config, skipping", name)
+                continue
+            module = load_module(name, self.config)
+            if module is None:
+                logger.error("Plugin '%s' not found", name)
+                continue
+            if self._load_module(module, name, plugin_config, internal=False):
+                loaded.append(name)
+        return loaded
+
+    def _load_module(self, module: ModuleType, name: str, plugin_config: dict, internal: bool) -> bool:
+        """Load a single module: find register(), track tools, check collisions."""
+        register_fn = find_register(module)
+        if register_fn is None:
+            logger.error("Plugin '%s' has no register(mcp, config) function", name)
+            return False
+        tracker = ToolTracker(self.mcp)
+        try:
+            register_fn(tracker, plugin_config)
+        except Exception as e:
+            logger.error("Plugin '%s' register() failed: %s", name, e)
+            return False
+        new_tools = tracker.registered_tools
+        new_resources = tracker.registered_resources
+        new_prompts = tracker.registered_prompts
+        collisions = self._all_tools & set(new_tools)
+        if collisions:
+            for tool_name in collisions:
+                owner = self._find_tool_owner(tool_name)
+                logger.error("Tool collision: '%s' already in plugin '%s', cannot load '%s'", tool_name, owner, name)
+            return False
+        res_collisions = self._all_resources & set(new_resources)
+        if res_collisions:
+            logger.error("Resource collision: %s, cannot load '%s'", res_collisions, name)
+            return False
+        prompt_collisions = self._all_prompts & set(new_prompts)
+        if prompt_collisions:
+            logger.error("Prompt collision: %s, cannot load '%s'", prompt_collisions, name)
+            return False
+        self._all_tools.update(new_tools)
+        self._all_resources.update(new_resources)
+        self._all_prompts.update(new_prompts)
+        self.plugins[name] = LoadedPlugin(
+            name=name, module=module, tools=new_tools,
+            resources=new_resources, prompts=new_prompts,
+            loaded_at=datetime.now(), config=plugin_config, internal=internal,
+        )
+        label = "internal" if internal else "external"
+        logger.info("Plugin '%s' loaded (%s): %d tools", name, label, len(new_tools))
+        return True
+
+    def _find_tool_owner(self, tool_name: str) -> str:
+        for plugin in self.plugins.values():
+            if tool_name in plugin.tools:
+                return plugin.name
+        return "unknown"
+
+    def get_plugin_summary(self) -> dict[str, Any]:
+        return {
+            "total_tools": len(self._all_tools),
+            "total_resources": len(self._all_resources),
+            "total_prompts": len(self._all_prompts),
+            "total_plugins": len(self.plugins),
+            "plugins": {
+                name: {
+                    "tools": p.tools, "tool_count": len(p.tools),
+                    "resources": p.resources, "resource_count": len(p.resources),
+                    "prompts": p.prompts, "prompt_count": len(p.prompts),
+                    "internal": p.internal, "loaded_at": p.loaded_at.isoformat(),
+                }
+                for name, p in self.plugins.items()
+            },
+        }

mcp_server_factory/loader.py

@@ -0,0 +1,10 @@
+"""Loader — Re-export from framework for backwards compatibility."""
+
+from mcp_server_framework.plugins.loader import (
+    load_module,
+    find_register,
+    set_plugin_dirs,
+    add_plugin_dir,
+)
+
+__all__ = ["load_module", "find_register", "set_plugin_dirs", "add_plugin_dir"]

mcp_server_factory/plugins/__init__.py

@@ -0,0 +1 @@
+"""Internal factory plugins."""

mcp_server_factory/plugins/logging.py

@@ -0,0 +1,121 @@
+"""Logging plugin — factory__log, factory__transcript."""
+
+from __future__ import annotations
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Optional
+
+LOG_DIR = Path.home() / ".mcp_factory"
+DEFAULT_LOG_FILE = LOG_DIR / "factory.log"
+TRANSCRIPT_DIR = LOG_DIR / "transcripts"
+MAX_LOG_SIZE = 5 * 1024 * 1024
+LOG_BACKUP_COUNT = 3
+MAX_TRANSCRIPT_SIZE = 10 * 1024 * 1024
+
+
+class LogSettings:
+    def __init__(self):
+        self.log_enabled: bool = False
+        self.log_file: Optional[Path] = None
+        self.transcript_enabled: bool = False
+        self.transcript_file: Optional[Path] = None
+
+    def set_logging(self, enabled: bool) -> str:
+        if enabled:
+            LOG_DIR.mkdir(parents=True, exist_ok=True)
+            self.log_file = DEFAULT_LOG_FILE
+            self.log_enabled = True
+            return f"Log ON → {self.log_file}"
+        self.log_enabled = False
+        self.log_file = None
+        return "Log OFF"
+
+    def start_transcript(self) -> str:
+        TRANSCRIPT_DIR.mkdir(parents=True, exist_ok=True)
+        now = datetime.now()
+        filename = now.strftime("%Y-%m-%d-%H-%M-%S.md")
+        self.transcript_file = TRANSCRIPT_DIR / filename
+        self.transcript_enabled = True
+        header = f"# MCP Factory Transcript\n**Started:** {now.strftime('%Y-%m-%d %H:%M:%S')}\n\n---\n\n"
+        self.transcript_file.write_text(header, encoding="utf-8")
+        return f"Transcript ON → {self.transcript_file}"
+
+    def stop_transcript(self) -> str:
+        if not self.transcript_enabled:
+            return "No active transcript"
+        if self.transcript_file and self.transcript_file.exists():
+            with open(self.transcript_file, "a", encoding="utf-8") as f:
+                f.write(f"\n---\n**Ended:** {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
+        result = f"Transcript OFF (saved: {self.transcript_file})"
+        self.transcript_enabled = False
+        self.transcript_file = None
+        return result
+
+    def log_call(self, tool: str, params: dict, result: str, success: bool) -> None:
+        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        status = "OK" if success else "FAIL"
+        if self.log_enabled and self.log_file:
+            params_str = str(params)[:100] + ("..." if len(str(params)) > 100 else "")
+            try:
+                self._rotate_if_needed()
+                with open(self.log_file, "a", encoding="utf-8") as f:
+                    f.write(f"[{timestamp}] {status} {tool} {params_str}\n")
+            except Exception:
+                pass
+        if self.transcript_enabled and self.transcript_file:
+            self._write_transcript(timestamp, tool, params, result, success)
+
+    def _rotate_if_needed(self) -> None:
+        if not self.log_file or not self.log_file.exists():
+            return
+        if self.log_file.stat().st_size < MAX_LOG_SIZE:
+            return
+        for i in range(LOG_BACKUP_COUNT, 0, -1):
+            old = self.log_file.with_suffix(f".log.{i}")
+            if old.exists():
+                if i == LOG_BACKUP_COUNT:
+                    old.unlink()
+                else:
+                    old.rename(self.log_file.with_suffix(f".log.{i + 1}"))
+        self.log_file.rename(self.log_file.with_suffix(".log.1"))
+
+    def _write_transcript(self, timestamp, tool, params, result, success) -> None:
+        if not self.transcript_file:
+            return
+        if self.transcript_file.exists() and self.transcript_file.stat().st_size > MAX_TRANSCRIPT_SIZE:
+            self.stop_transcript()
+            self.start_transcript()
+        status_emoji = "✓" if success else "✗"
+        params_fmt = "\n".join(f"  {k}: {v}" for k, v in params.items()) if params else "  (none)"
+        result_text = result[:50000] + f"\n\n... (truncated, {len(result)} chars)" if len(result) > 50000 else result
+        entry = f"\n## [{timestamp}] {status_emoji} `{tool}`\n\n**Parameters:**\n{params_fmt}\n\n**Result:**\n```\n{result_text}\n```\n\n---\n"
+        try:
+            with open(self.transcript_file, "a", encoding="utf-8") as f:
+                f.write(entry)
+        except Exception:
+            pass
+
+
+log_settings = LogSettings()
+
+
+def register(mcp, config: dict[str, Any]) -> None:
+    @mcp.tool()
+    def factory__log(mode: str = "status") -> str:
+        """Control tool call logging. Args: mode: 'on', 'off', or 'status'"""
+        if mode == "on":
+            return log_settings.set_logging(True)
+        elif mode == "off":
+            return log_settings.set_logging(False)
+        return f"Log {'ON → ' + str(log_settings.log_file) if log_settings.log_enabled else 'OFF'}"
+
+    @mcp.tool()
+    def factory__transcript(mode: str = "status") -> str:
+        """Control full transcript recording. Args: mode: 'on', 'off', or 'status'"""
+        if mode == "on":
+            if log_settings.transcript_enabled:
+                return f"Transcript already active: {log_settings.transcript_file}"
+            return log_settings.start_transcript()
+        elif mode == "off":
+            return log_settings.stop_transcript()
+        return f"Transcript {'ON → ' + str(log_settings.transcript_file) if log_settings.transcript_enabled else 'OFF'}"

mcp_server_factory/plugins/management.py

@@ -0,0 +1,52 @@
+"""Management plugin — factory__status, factory__list."""
+
+from __future__ import annotations
+from typing import Any
+from mcp_server_factory import __version__
+
+_factory = None
+
+
+def register(mcp, config: dict[str, Any]) -> None:
+    global _factory
+    _factory = config.get("_factory")
+
+    @mcp.tool()
+    def factory__status() -> str:
+        """Show factory status: version, transport, plugins, tools."""
+        if _factory is None:
+            return "Factory reference not available"
+        summary = _factory.get_plugin_summary()
+        fc = _factory.config
+        lines = [
+            f"MCP Factory v{__version__}",
+            f"  Server:    {fc.get('server_name', 'MCP Factory')}",
+            f"  Transport: {fc.get('transport', 'stdio')}",
+        ]
+        if fc.get("transport") != "stdio":
+            lines.append(f"  Port:      {fc.get('port', 'n/a')}")
+            lines.append(f"  Health:    {fc.get('health_port', 'n/a')}")
+        lines.append(f"  Plugins:   {summary['total_plugins']} loaded")
+        lines.append(f"  Tools:     {summary['total_tools']} registered")
+        from .logging import log_settings
+        lines.append(f"  Log:       {'ON' if log_settings.log_enabled else 'OFF'}")
+        lines.append(f"  Transcript: {'ON' if log_settings.transcript_enabled else 'OFF'}")
+        return "\n".join(lines)
+
+    @mcp.tool()
+    def factory__list() -> str:
+        """List loaded plugins and their tools."""
+        if _factory is None:
+            return "Factory reference not available"
+        summary = _factory.get_plugin_summary()
+        lines = ["Loaded plugins:\n"]
+        for name, info in summary["plugins"].items():
+            label = " (internal)" if info["internal"] else ""
+            tools_str = ", ".join(info["tools"][:5])
+            if len(info["tools"]) > 5:
+                tools_str += f", ... (+{len(info['tools']) - 5})"
+            lines.append(f"  {name:<20} {info['tool_count']:>3} tools{label}")
+            lines.append(f"    [{tools_str}]")
+        lines.append(f"  {'─' * 40}")
+        lines.append(f"  Total: {summary['total_tools']} tools, {summary['total_plugins']} plugins")
+        return "\n".join(lines)

mcp_server_factory/tracker.py

@@ -0,0 +1,8 @@
+"""ToolTracker — Re-export from framework for backwards compatibility.
+
+The Factory hooks into the tracker's logging via set_log_callback().
+"""
+
+from mcp_server_framework.plugins.tracker import ToolTracker, set_log_callback
+
+__all__ = ["ToolTracker", "set_log_callback"]

mcp_server_framework/__init__.py

@@ -0,0 +1,36 @@
+"""mcp_server_framework — Shared framework for MCP servers.
+
+Provides transport, health monitoring, configuration and plugin infrastructure.
+Imported as a library — by standalone MCP servers, the Factory and the Proxy.
+
+Public API:
+    load_config(path)              → Config from YAML + ENV
+    create_server(config)          → FastMCP instance
+    run_server(mcp, config)        → Start server (stdio or HTTP)
+    start_health_server(port, ...) → Start health thread
+    create_health_app(...)         → Create health app directly
+
+Plugin API (via mcp_server_framework.plugins):
+    LoadedPlugin                   → Plugin record dataclass
+    load_module(name, config)      → Resolve and import plugin
+    find_register(module)          → Find register() function
+    ToolTracker(mcp)               → Proxy that tracks tool registrations
+"""
+
+__version__ = "1.1.0"
+
+from .config import load_config
+from .server import create_server, run_server
+from .health import start_health_server, create_health_app
+from .logging import setup_logging
+from .oauth import IntrospectionTokenVerifier
+
+__all__ = [
+    "load_config",
+    "create_server",
+    "run_server",
+    "start_health_server",
+    "create_health_app",
+    "setup_logging",
+    "IntrospectionTokenVerifier",
+]

mcp_server_framework/config.py

@@ -0,0 +1,109 @@
+"""Configuration — YAML + environment variables.
+
+Three-tier merge: Defaults → YAML → ENV (last wins).
+"""
+
+from __future__ import annotations
+
+import os
+import copy
+import logging
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def _parse_bool(value: str) -> bool:
+    """Parse bool from ENV string."""
+    return value.lower() in ("true", "1", "yes", "on")
+
+
+# Immutable defaults — mutable values (tools) are
+# deep-copied in load_config() for each call.
+_DEFAULTS: dict[str, Any] = {
+    "server_name": "MCP Server",
+    "version": "0.1.0",
+    "instructions": "",
+    "service_type": "generic",
+    "log_level": "INFO",
+    # Transport
+    "host": "0.0.0.0",
+    "port": 12201,
+    "transport": "stdio",
+    # Health
+    "health_port": None,  # Default: port + 1
+    # OAuth (enabled by default for HTTP, ignored for stdio)
+    "oauth_enabled": True,
+    "oauth_server_url": None,
+    "oauth_public_url": None,
+    # Tool names (for registry/monitoring)
+    "tools": [],
+}
+
+# ENV key → (config key, type cast)
+_ENV_MAPPING: dict[str, tuple[str, type]] = {
+    "MCP_SERVER_NAME": ("server_name", str),
+    "MCP_LOG_LEVEL": ("log_level", str),
+    "MCP_HOST": ("host", str),
+    "MCP_PORT": ("port", int),
+    "MCP_HEALTH_PORT": ("health_port", int),
+    "MCP_TRANSPORT": ("transport", str),
+    "MCP_OAUTH_ENABLED": ("oauth_enabled", _parse_bool),
+    "MCP_OAUTH_SERVER_URL": ("oauth_server_url", str),
+    "MCP_PUBLIC_URL": ("oauth_public_url", str),
+}
+
+
+def load_config(
+    config_path: Path | None = None,
+) -> dict[str, Any]:
+    """Load configuration: Defaults → YAML → ENV.
+
+    Args:
+        config_path: Optional path to YAML file.
+
+    Returns:
+        Merged config dict (own copy, safe to mutate).
+    """
+    config = copy.deepcopy(_DEFAULTS)
+
+    if config_path and config_path.exists():
+        _load_yaml(config, config_path)
+
+    _apply_env(config)
+
+    # Computed defaults
+    if config["health_port"] is None:
+        config["health_port"] = config["port"] + 1
+
+    return config
+
+
+def _load_yaml(
+    config: dict[str, Any],
+    path: Path,
+) -> None:
+    """Load YAML file into config dict."""
+    try:
+        import yaml
+    except ImportError:
+        logger.warning("PyYAML not installed, YAML config ignored")
+        return
+
+    with open(path) as f:
+        yaml_config = yaml.safe_load(f) or {}
+    config.update(yaml_config)
+    logger.info("Config loaded: %s", path)
+
+
+def _apply_env(config: dict[str, Any]) -> None:
+    """Apply ENV overrides to config."""
+    for env_key, (config_key, cast) in _ENV_MAPPING.items():
+        value = os.getenv(env_key)
+        if value is None:
+            continue
+        try:
+            config[config_key] = cast(value)
+        except (ValueError, TypeError):
+            logger.warning("ENV %s=%r: invalid value", env_key, value)