mcp-proxy-adapter-dev 8.11.16__py3-none-any.whl

mcp_proxy_adapter/__init__.py

@@ -0,0 +1,73 @@
+"""MCP Proxy API Service package.
+
+This package provides a framework for creating JSON-RPC-enabled microservices.
+"""
+
+from typing import Any, Callable, Optional
+
+from mcp_proxy_adapter.commands.base import Command
+from mcp_proxy_adapter.commands.command_registry import registry
+from mcp_proxy_adapter.commands.result import CommandResult, ErrorResult, SuccessResult
+from mcp_proxy_adapter.core.errors import (
+    CommandError,
+    InternalError,
+    InvalidParamsError,
+    MicroserviceError,
+    NotFoundError,
+    TimeoutError,
+    ValidationError,
+)
+from mcp_proxy_adapter.version import __version__
+
+
+# `create_app` is deliberately NOT imported at module level (bug 7f7ce943):
+# `mcp_proxy_adapter.api.app` pulls in the whole route/websocket stack
+# (api.core.app_factory -> app_factory_routes -> ws_endpoint ->
+# command_session_service -> commands.queue), and `commands/queue/__init__.py`
+# and `core/server_engine.py` both run command/engine registration AS AN
+# IMPORT-TIME SIDE EFFECT that logs at INFO. Since `import mcp_proxy_adapter`
+# always executes this file first (Python imports parent packages before any
+# submodule), that eager import meant every CLI invocation - including plain
+# `--help` - and every downstream library import inherited ten unsolicited
+# log lines before doing anything. `__getattr__` below (PEP 562) defers the
+# import to the first real access, so `from mcp_proxy_adapter import
+# create_app` keeps working unchanged for real server startups (which still
+# log exactly as before, since building an app is precisely when a server
+# needs its commands and engine registered), while `--help` and any
+# import that never touches `create_app` stay clean.
+def __getattr__(name: str) -> Any:
+    if name == "create_app":
+        from mcp_proxy_adapter.api.app import create_app as _create_app
+
+        return _create_app
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+# CLI module
+# Delayed import of CLI to avoid side effects during server startup
+# CLI can be accessed via entrypoint `mcp-proxy-adapter` or `python -m mcp_proxy_adapter`
+cli_main: Optional[Callable[[], int]]
+try:
+    from mcp_proxy_adapter.cli import main as cli_main
+except Exception:
+    # Avoid import errors impacting library/server usage
+    cli_main = None
+
+# Экспортируем основные классы и функции для удобного использования
+__all__ = [
+    "__version__",
+    "create_app",
+    "Command",
+    "CommandResult",
+    "SuccessResult",
+    "ErrorResult",
+    "registry",
+    "MicroserviceError",
+    "CommandError",
+    "ValidationError",
+    "InvalidParamsError",
+    "NotFoundError",
+    "TimeoutError",
+    "InternalError",
+    "cli_main",
+]

mcp_proxy_adapter/__main__.py

@@ -0,0 +1,13 @@
+"""
+MCP Proxy Adapter CLI Entry Point
+
+This module allows running the CLI using: python -m mcp_proxy_adapter
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from .cli.main import main
+
+if __name__ == "__main__":
+    main()

mcp_proxy_adapter/api/__init__.py

@@ -0,0 +1,38 @@
+"""
+API module for MCP Proxy Adapter.
+
+This module provides FastAPI application setup, handlers, middleware,
+and OpenAPI integration for the MCP Proxy Adapter framework.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from typing import Any
+
+__all__ = [
+    "set_health_provider",
+    "get_health_provider",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import of health provider to defer module-level imports.
+
+    This implements PEP 562 to make health_provider available but not loaded
+    on bare package import. The health provider is server-only and should
+    not be eagerly imported by client code.
+    """
+    if name in ("set_health_provider", "get_health_provider"):
+        from mcp_proxy_adapter.api.health_provider import (
+            get_health_provider,
+            set_health_provider,
+        )
+
+        return (
+            set_health_provider
+            if name == "set_health_provider"
+            else get_health_provider
+        )
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

mcp_proxy_adapter/api/app.py

@@ -0,0 +1,64 @@
+"""
+Module for FastAPI application setup.
+"""
+
+from typing import Any, AsyncContextManager, Callable, Dict, Optional
+
+from fastapi import FastAPI
+
+from .core import AppFactory, LifespanManager, SSLContextFactory
+
+
+def create_lifespan(
+    config_path: Optional[str] = None, current_config: Optional[Dict[str, Any]] = None
+) -> Callable[[FastAPI], AsyncContextManager[None]]:
+    """
+    Create lifespan manager for the FastAPI application.
+
+    Args:
+        config_path: Path to configuration file (optional)
+        current_config: Current configuration data (optional)
+
+    Returns:
+        Lifespan context manager
+    """
+    lifespan_manager = LifespanManager()
+    return lifespan_manager.create_lifespan(config_path, current_config)
+
+
+def create_ssl_context(app_config: Optional[Dict[str, Any]] = None) -> Optional[Any]:
+    """
+    Create SSL context based on configuration.
+
+    Args:
+        app_config: Application configuration dictionary (optional)
+
+    Returns:
+        SSL context if SSL is enabled and properly configured, None otherwise
+    """
+    ssl_factory = SSLContextFactory()
+    return ssl_factory.create_ssl_context(app_config)
+
+
+def create_app(
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    version: Optional[str] = None,
+    app_config: Optional[Dict[str, Any]] = None,
+    config_path: Optional[str] = None,
+) -> FastAPI:
+    """
+    Creates and configures FastAPI application.
+
+    Args:
+        title: Application title (default: "MCP Proxy Adapter")
+        description: Application description (default: "JSON-RPC API for interacting with MCP Proxy")
+        version: Application version (default: "1.0.0")
+        app_config: Application configuration dictionary (optional)
+        config_path: Path to configuration file (optional)
+
+    Returns:
+        Configured FastAPI application.
+    """
+    app_factory = AppFactory()
+    return app_factory.create_app(title, description, version, app_config, config_path)

mcp_proxy_adapter/api/command_session_service.py

@@ -0,0 +1,455 @@
+"""Enqueue-first command-session service for WebSocket command execution."""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from dataclasses import dataclass
+from typing import Any, Dict, Mapping, Optional
+
+from mcp_proxy_adapter.api import handlers as _handlers_pkg
+from mcp_proxy_adapter.api.middleware.command_permission_middleware import (
+    check_command_permission,
+)
+from mcp_proxy_adapter.commands.command_registry import registry
+from mcp_proxy_adapter.commands.queue.job_params import (
+    build_command_execution_job_params,
+)
+from mcp_proxy_adapter.commands.queue.jobs import CommandExecutionJob
+from mcp_proxy_adapter.core.errors import MethodNotFoundError, ValidationError
+from mcp_proxy_adapter.core.job_push.events import (
+    build_command_accepted_message,
+    build_command_error_message,
+    build_command_session_result_rpc,
+)
+from mcp_proxy_adapter.core.job_push.subscriptions import SubscriptionCategory
+from mcp_proxy_adapter.core.logging import get_global_logger
+from mcp_proxy_adapter.integrations.queuemgr_integration import (
+    get_global_queue_manager,
+)
+from mcp_proxy_adapter.integrations.queuemgr_integration._process_reap import (
+    _is_emfile_error,
+)
+
+
+@dataclass(frozen=True)
+class CommandSessionMetadata:
+    """Correlation metadata for a WS-started command."""
+
+    request_id: str
+    job_id: str
+    command: str
+    identity: Dict[str, Any]
+    result_channel: str = "rpc"
+
+    @property
+    def result_rpc(self) -> Dict[str, Any]:
+        """RPC reference used by terminal command-session events."""
+        return build_command_session_result_rpc(self.job_id)
+
+
+@dataclass(frozen=True)
+class CommandSessionAccepted:
+    """Accepted command-session response."""
+
+    metadata: CommandSessionMetadata
+    accepted_event: Dict[str, Any]
+
+
+_metadata_lock = asyncio.Lock()
+_metadata_by_job_id: Dict[str, CommandSessionMetadata] = {}
+_cleanup_tasks: Dict[str, asyncio.Task[None]] = {}
+
+
+def _identity_log_fields(identity: Mapping[str, Any]) -> str:
+    """
+    Render a command-session caller's identity as structured ``key=value``
+    text for a log line (bug 4322fb83: the "Command session job ... started"
+    log line carried job_id+command only, with no caller/origin, leaving
+    forensics blind to who invoked a session-executed command - e.g. which
+    principal issued ``stop_worker``/``start_worker`` during an unexplained
+    restart window).
+
+    Reads only what the call path already genuinely has -
+    ``get_identity_from_scope`` (``api/ws_identity.py``, the one real
+    identity source for WS-started command sessions today) always sets
+    ``type`` to one of "token", "mtls", or "anonymous", plus whichever of
+    ``user_id``/``role`` (token) or ``cn``/``fingerprint`` (mtls) it managed
+    to read. No field is invented here: an absent value is left out of the
+    line entirely rather than printed as a placeholder, and a caller with no
+    identity at all (``type`` missing, e.g. a non-WS caller that never
+    passed ``identity=``) renders explicitly as ``caller_type=anonymous``
+    rather than silently dropping the field.
+
+    Args:
+        identity: The command session's ``identity`` mapping (empty dict if
+            the caller never supplied one).
+
+    Returns:
+        A single space-joined ``key=value`` string, e.g.
+        ``"caller_type=token user_id=abc123 role=admin"`` or
+        ``"caller_type=anonymous"``.
+    """
+    caller_type = identity.get("type") or "anonymous"
+    fields = [f"caller_type={caller_type}"]
+    for key in ("user_id", "role", "cn", "fingerprint"):
+        value = identity.get(key)
+        if value is not None:
+            fields.append(f"{key}={value}")
+    return " ".join(fields)
+
+
+def _normalize_request_id(request_id: Optional[str]) -> str:
+    """Return stripped request_id or generate new UUID if missing or empty."""
+    if request_id is not None and str(request_id).strip():
+        return str(request_id).strip()
+    return str(uuid.uuid4())
+
+
+def _normalize_params(params: Optional[Mapping[str, Any]]) -> Dict[str, Any]:
+    """Convert params to dict; raise ValidationError if not a mapping or None."""
+    if params is None:
+        return {}
+    if not isinstance(params, Mapping):
+        raise ValidationError("command params must be an object")
+    return dict(params)
+
+
+async def _remember_metadata(metadata: CommandSessionMetadata) -> None:
+    """Store metadata and cancel any existing cleanup task for this job."""
+    async with _metadata_lock:
+        old_task = _cleanup_tasks.pop(metadata.job_id, None)
+        if old_task is not None and not old_task.done():
+            old_task.cancel()
+        _metadata_by_job_id[metadata.job_id] = metadata
+
+
+async def get_command_session_metadata(
+    job_id: str,
+) -> Optional[CommandSessionMetadata]:
+    """Return metadata for a command-session job, if still retained."""
+    jid = str(job_id).strip()
+    if not jid:
+        return None
+    async with _metadata_lock:
+        return _metadata_by_job_id.get(jid)
+
+
+async def forget_command_session_metadata(job_id: str) -> None:
+    """Forget retained command-session metadata for *job_id*."""
+    jid = str(job_id).strip()
+    if not jid:
+        return
+    async with _metadata_lock:
+        _metadata_by_job_id.pop(jid, None)
+        task = _cleanup_tasks.pop(jid, None)
+        if task is not None and not task.done():
+            task.cancel()
+
+
+async def schedule_command_session_metadata_cleanup(
+    job_id: str,
+    ttl_seconds: float = 3600.0,
+) -> None:
+    """Schedule metadata cleanup after a terminal event replay window."""
+    jid = str(job_id).strip()
+    if not jid:
+        return
+
+    async def _cleanup() -> None:
+        """Sleep for TTL then remove metadata and task from tracking dicts."""
+        await asyncio.sleep(max(0.0, float(ttl_seconds)))
+        async with _metadata_lock:
+            _metadata_by_job_id.pop(jid, None)
+            _cleanup_tasks.pop(jid, None)
+
+    async with _metadata_lock:
+        existing = _cleanup_tasks.pop(jid, None)
+        if existing is not None and not existing.done():
+            existing.cancel()
+        _cleanup_tasks[jid] = asyncio.create_task(_cleanup())
+
+
+async def start_command_session(
+    *,
+    command: str,
+    params: Optional[Mapping[str, Any]],
+    context: Optional[Mapping[str, Any]],
+    request_id: Optional[str],
+    identity: Optional[Mapping[str, Any]] = None,
+    result_channel: str = "rpc",
+    config: Optional[Mapping[str, Any]] = None,
+    app_state: Optional[Any] = None,
+) -> CommandSessionAccepted:
+    """Enqueue a command for isolated execution and return acceptance metadata.
+
+    Args:
+        app_state: The caller's ``FastAPI`` ``app.state`` (e.g.
+            ``ctx.app.state`` from ``ws_endpoint.py``), used only if
+            ``queue_manager.start_job`` fails in the background (bug
+            83afa2ba) - see ``_start_job_background``'s except block, which
+            reads ``job_push_registry``/``job_status_accumulator`` off it to
+            deliver a terminal ``command_error`` the same way
+            ``core/job_push/lifespan_wiring.py`` delivers any other terminal
+            command-session event. Optional and best-effort: a caller that
+            omits it (e.g. existing tests) only loses that terminal push,
+            never breaks the enqueue-first happy path this function's
+            return value is about.
+    """
+    command_name = str(command or "").strip()
+    if not command_name:
+        raise ValidationError("execute_command requires non-empty command")
+    command_params = _normalize_params(params)
+    command_params.pop("poll_interval", None)
+    command_params.pop("max_wait_time", None)
+    command_context: Dict[str, Any] = dict(context or {})
+    identity_dict: Dict[str, Any] = dict(identity or {})
+    rid = _normalize_request_id(request_id)
+    result_channel_name = "rpc"
+
+    try:
+        command_class = registry.get_command(command_name)
+    except Exception as exc:
+        raise MethodNotFoundError(f"Method not found: {command_name}") from exc
+
+    user_context = command_context.get("user")
+    user_mapping = user_context if isinstance(user_context, Mapping) else None
+    if not check_command_permission(command_name, user_mapping, config=config):
+        raise ValidationError(
+            f"Not allowed to execute command: {command_name}",
+            data={"command": command_name},
+        )
+
+    queue_manager = await get_global_queue_manager()
+    job_id = str(uuid.uuid4())
+
+    metadata = CommandSessionMetadata(
+        request_id=rid,
+        job_id=job_id,
+        command=command_name,
+        identity=identity_dict,
+        result_channel=result_channel_name,
+    )
+    await _remember_metadata(metadata)
+
+    logger = get_global_logger()
+
+    identity_fields = _identity_log_fields(identity_dict)
+
+    # Bug 0d64b41c (owner's ruling, option b): honour `use_queue` on the
+    # unified/WS command-session path exactly as the sync `execute_command`
+    # path already does (api/handlers/command_execution.py) - a command
+    # whose class does NOT set `use_queue=True` must run IN THIS SERVER
+    # PROCESS, not in a queuemgr spawn-mode worker (a fresh interpreter with
+    # NO access to this process's in-memory state: session registries,
+    # caches, module-level objects - see docs/HOWTO_CUSTOM_COMMANDS_SPAWN_MODE.md).
+    use_queue = getattr(command_class, "use_queue", False)
+
+    if use_queue:
+        # Bug cf5d11f7: validate BEFORE enqueue, exactly as the JSON-RPC path
+        # does (api/handlers/command_execution.py), so a refusal is immediate
+        # and no job is created. A ValidationError propagates to the caller.
+        registry.get_command_instance(command_name).validate_params(command_params)
+        job_params = build_command_execution_job_params(
+            command_name, command_params, command_context
+        )
+        await queue_manager.add_job(CommandExecutionJob, job_id, job_params)
+
+        async def _start_job_background() -> None:
+            """Start job in queue manager and log result or error.
+
+            The log lines below carry the caller's identity/origin and the
+            request_id (bug 4322fb83) - both already available as parameters to
+            ``start_command_session`` (``identity_dict``/``rid``) - so a
+            forensic read of the log can attribute who started a given
+            session-executed command, not just which job/command ran.
+            """
+            try:
+                await queue_manager.start_job(job_id)
+                logger.info(
+                    "Command session job %s (command=%s) started request_id=%s %s",
+                    job_id,
+                    command_name,
+                    rid,
+                    identity_fields,
+                )
+            except Exception as exc:
+                # A caller may cancel an accepted job while its background
+                # start is still waiting for admission. Native start then
+                # refuses the already-stopped job; that is a successful
+                # cancellation, not a failed start to overwrite and delete.
+                from mcp_proxy_adapter.core.job_push.caller_loss import (
+                    cancel_reason_for,
+                )
+
+                if cancel_reason_for(job_id) is not None:
+                    try:
+                        current = await queue_manager.get_job_status(job_id)
+                    except Exception as status_exc:
+                        logger.debug(
+                            "Command session job %s: reading cancellation "
+                            "state after start refusal failed: %s",
+                            job_id,
+                            status_exc,
+                        )
+                    else:
+                        if current.status == "stopped":
+                            engine = getattr(app_state, "job_push_engine", None)
+                            if engine is not None and hasattr(engine, "watch"):
+                                engine.watch(job_id)
+                                if hasattr(engine, "wake"):
+                                    engine.wake(job_id)
+                            logger.info(
+                                "Command session job %s start superseded by "
+                                "cancellation reason=%s request_id=%s %s",
+                                job_id,
+                                cancel_reason_for(job_id),
+                                rid,
+                                identity_fields,
+                            )
+                            return
+                # Bug 83afa2ba: queuemgr's start_job never mutates job status on
+                # a failed start, so without the recovery below the job stays
+                # "pending" forever and a plain queue_get_job_status poller (or
+                # a WS command-session subscriber) waits indefinitely for an
+                # event that will never arrive. Recover on all three surfaces a
+                # caller might be watching: push a terminal command_error to any
+                # live COMMAND_SESSION subscribers, record it in the
+                # accumulator so a late/resumed subscriber sees it too, and
+                # best-effort delete the job so a plain status poller observes
+                # a terminal (DELETED) status instead of stalling on "pending".
+                is_emfile = _is_emfile_error(exc)
+                logger.warning(
+                    "Command session job %s (command=%s) start failed%s: %s "
+                    "request_id=%s %s",
+                    job_id,
+                    command_name,
+                    " (EMFILE/too many open files)" if is_emfile else "",
+                    exc,
+                    rid,
+                    identity_fields,
+                )
+                command_error = build_command_error_message(
+                    error=str(exc),
+                    job_id=job_id,
+                    request_id=rid,
+                    command=command_name,
+                    status="failed",
+                    result_channel=metadata.result_channel,
+                )
+                if app_state is not None:
+                    acc = getattr(app_state, "job_status_accumulator", None)
+                    if acc is not None and hasattr(acc, "record_command_session"):
+                        try:
+                            await acc.record_command_session(job_id, command_error)
+                        except Exception as acc_exc:
+                            logger.debug(
+                                "Command session job %s: recording start-failure "
+                                "terminal event in accumulator failed: %s",
+                                job_id,
+                                acc_exc,
+                            )
+                    push_registry = getattr(app_state, "job_push_registry", None)
+                    if push_registry is not None:
+                        try:
+                            subscribers = await push_registry.get_subscribers(
+                                job_id, SubscriptionCategory.COMMAND_SESSION
+                            )
+                        except Exception as reg_exc:
+                            logger.debug(
+                                "Command session job %s: fetching subscribers for "
+                                "start-failure terminal push failed: %s",
+                                job_id,
+                                reg_exc,
+                            )
+                            subscribers = []
+                        for sub in subscribers:
+                            try:
+                                await sub.send(command_error)
+                            except Exception as send_exc:
+                                logger.warning(
+                                    "Command session start-failure terminal push "
+                                    "failed for job_id=%s: %s",
+                                    job_id,
+                                    send_exc,
+                                )
+                await forget_command_session_metadata(job_id)
+                try:
+                    await queue_manager.delete_job(job_id)
+                except Exception as delete_exc:
+                    logger.debug(
+                        "Command session job %s: best-effort delete after start "
+                        "failure failed: %s",
+                        job_id,
+                        delete_exc,
+                    )
+
+        asyncio.create_task(_start_job_background())
+    else:
+        # IN-PROCESS BRANCH (bug 0d64b41c). Reuses the exact call the sync
+        # dispatcher's own non-queue branch makes
+        # (api/handlers/command_execution.py execute_command(), "Legacy
+        # sync-start behavior": ``command_class.run(**params,
+        # context=context)``) so parameter validation (``Command.run()`` ->
+        # ``validate_params()``), context handling and the error envelope
+        # (a raised ``ValidationError``/``CommandError`` inside ``execute()``
+        # becomes an ``ErrorResult``, never an uncaught exception) are
+        # IDENTICAL on both paths - nothing here re-implements or forks that
+        # logic. ``asyncio.create_task`` runs it as a task that does not
+        # block this WS handler.
+        #
+        # The task is tracked the SAME way command_execution.py's own
+        # sync-cap timeout fallback already tracks a command that must keep
+        # running in-process (bug e3b822d4): registered on the queue
+        # manager's adapter-side detached-fallback-job store under THIS
+        # job_id via ``register_detached_fallback_job`` /
+        # ``_attach_detached_fallback_completion`` (shared with
+        # ``_handle_sync_timeout_fallback``), so ``queue_get_job_status`` /
+        # ``queue_list_jobs`` / ``queue_stop_job`` / ``queue_delete_job`` all
+        # already handle it correctly with NO new code, and the existing job-
+        # push poll loop (``core/job_push/lifespan_wiring.py``
+        # ``_job_push_poll_loop``, which already drives the terminal
+        # command-session event for a QUEUED job by polling
+        # ``queue_manager.get_job_status``) delivers the terminal
+        # command-session event through the SAME ``COMMAND_SESSION``
+        # subscription this WS session already holds
+        # (``ws_endpoint.py`` ``_handle_execute_command`` subscribes
+        # unconditionally, before branching here) - no separate delivery
+        # path is added for the in-process case.
+        #
+        # job_id / stop / cancel semantics for an in-process run: ``job_id``
+        # identifies this adapter-side store record, not a queuemgr job.
+        # ``queue_stop_job`` NEVER cancels it
+        # (``QueueManagerIntegration._stop_detached_fallback_job``):
+        # cancelling a running coroutine mid-flight here is exactly the
+        # request-body-corruption trigger bug e3b822d4 already documents for
+        # the sync-cap fallback, so a stop answers honestly that the command
+        # is running in-process, cannot be interrupted, and will publish its
+        # own terminal result. ``queue_delete_job`` simply stops tracking
+        # the record; the execution itself always runs to completion.
+        run_task: "asyncio.Future[Any]" = asyncio.create_task(
+            command_class.run(**command_params, context=command_context)
+        )
+        queue_manager.register_detached_fallback_job(
+            job_id, command_name, run_task, cancellable=True
+        )
+        _handlers_pkg._attach_detached_fallback_completion(
+            run_task, queue_manager, job_id, command_name, logger
+        )
+        logger.info(
+            "Command session job %s (command=%s) started in-process "
+            "(use_queue=False) request_id=%s %s",
+            job_id,
+            command_name,
+            rid,
+            identity_fields,
+        )
+
+    accepted_event = build_command_accepted_message(
+        job_id=job_id,
+        request_id=rid,
+        command=command_name,
+        status="pending",
+        result_channel=metadata.result_channel,
+    )
+    return CommandSessionAccepted(metadata=metadata, accepted_event=accepted_event)

mcp_proxy_adapter/api/core/__init__.py

@@ -0,0 +1,19 @@
+"""
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+
+Core API utilities for MCP Proxy Adapter.
+"""
+
+from .app_factory import AppFactory
+from .lifespan_manager import LifespanManager
+from .registration_manager import RegistrationManager, RegistrationSetupError
+from .ssl_context_factory import SSLContextFactory
+
+__all__ = [
+    "AppFactory",
+    "SSLContextFactory",
+    "RegistrationManager",
+    "RegistrationSetupError",
+    "LifespanManager",
+]