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

mcp_proxy_adapter/examples/generator_validator_compatibility_report.md

@@ -0,0 +1,127 @@
+# Generator-Validator Compatibility Report
+
+**Author**: Vasiliy Zdanovskiy
+**Email**: vasilyvz@gmail.com
+**Date**: 2024-12-19
+
+## Executive Summary
+
+✅ **COMPATIBLE** - The configuration generator and validator are structurally compatible and work correctly together.
+
+## Test Results
+
+### Structure Compatibility Test
+- ✅ **PASS** - All required sections present
+- ✅ **PASS** - All required fields present
+- ✅ **PASS** - Default values correctly set
+- ✅ **PASS** - All features properly disabled by default
+
+### Configuration Modification Test
+- ✅ **PASS** - HTTPS protocol modification works
+- ✅ **PASS** - SSL enablement works
+- ✅ **PASS** - Security enablement works
+- ✅ **PASS** - Roles enablement works
+- ✅ **PASS** - Proxy registration enablement works
+
+### Validator Acceptance Test
+- ✅ **PASS** - Generated configs pass validation
+- ✅ **PASS** - No structural validation errors
+- ✅ **PASS** - All required sections validated
+
+## Key Findings
+
+### 1. Structural Compatibility
+The generator creates configurations with all required sections:
+- `server` - Server configuration
+- `logging` - Logging configuration
+- `commands` - Command system configuration
+- `debug` - Debug settings
+- `ssl` - SSL/TLS configuration
+- `security` - Security settings
+- `roles` - Role-based access control
+- `proxy_registration` - Proxy registration settings
+
+### 2. Default Configuration
+The generator creates a sensible default HTTP configuration:
+- Protocol: `http`
+- SSL: Disabled
+- Security: Disabled
+- Roles: Disabled
+- Proxy Registration: Disabled
+
+### 3. Modification Capability
+Generated configurations can be easily modified for different scenarios:
+- HTTP → HTTPS (enable SSL)
+- Basic → Secure (enable security)
+- Simple → Role-based (enable roles)
+- Standalone → Proxy-registered (enable proxy registration)
+
+### 4. Validation Coverage
+The validator properly checks:
+- Required sections and fields
+- Feature flag dependencies
+- Protocol-specific requirements
+- File existence (when files are specified)
+- Certificate validity (when certificates are provided)
+
+## Recommendations
+
+### 1. Use Generator for Base Configurations
+The `generate_complete_config()` function should be used as the starting point for all configurations.
+
+### 2. Modify for Specific Needs
+After generating a base configuration, modify it for specific requirements:
+```python
+config = generate_complete_config(host="localhost", port=8080)
+
+# For HTTPS
+config["server"]["protocol"] = "https"
+config["ssl"]["enabled"] = True
+config["ssl"]["cert_file"] = "/path/to/cert.crt"
+config["ssl"]["key_file"] = "/path/to/key.key"
+
+# For security
+config["security"]["enabled"] = True
+config["security"]["tokens"] = {"my_token": {"permissions": ["*"]}}
+
+# For roles
+config["roles"]["enabled"] = True
+config["roles"]["config_file"] = "/path/to/roles.json"
+```
+
+### 3. Validate Before Use
+Always validate configurations before using them:
+```python
+validator = ConfigValidator()
+validator.config_data = config
+results = validator.validate_config()
+
+errors = [r for r in results if r.level == "error"]
+if errors:
+    print("Configuration errors:")
+    for error in errors:
+        print(f"  - {error.message}")
+```
+
+## Test Coverage
+
+### Positive Tests
+- ✅ Basic HTTP configuration
+- ✅ Configuration modification
+- ✅ Validator acceptance
+- ✅ Required sections validation
+- ✅ Feature flag validation
+
+### Edge Cases
+- ✅ Empty configuration (correctly fails)
+- ✅ Missing required sections (correctly fails)
+- ✅ Invalid protocols (correctly fails)
+- ✅ SSL without certificates (correctly fails)
+
+## Conclusion
+
+The configuration generator and validator are **fully compatible** and work together seamlessly. The generator creates valid, complete configurations that pass validation, and the validator properly checks all aspects of the configuration.
+
+**Status**: ✅ **READY FOR PRODUCTION USE**
+
+The system provides a robust foundation for configuration management with proper validation and error handling.

mcp_proxy_adapter/examples/http_proxy_example.json

@@ -0,0 +1,17 @@
+{
+  "server": {
+    "host": "127.0.0.1",
+    "port": 20021,
+    "log_level": "INFO",
+    "protocol": "http",
+    "servername": "127.0.0.1"
+  },
+  "registration": {
+    "enabled": true,
+    "server_id": "http_test_server",
+    "server_name": "HTTP Test Server",
+    "heartbeat": {
+      "interval": 30
+    }
+  }
+}

mcp_proxy_adapter/examples/https_proxy_example.json

@@ -0,0 +1,17 @@
+{
+  "server": {
+    "host": "127.0.0.1",
+    "port": 20022,
+    "log_level": "INFO",
+    "protocol": "http",
+    "servername": "127.0.0.1"
+  },
+  "registration": {
+    "enabled": true,
+    "server_id": "https_test_server",
+    "server_name": "HTTPS Test Server",
+    "heartbeat": {
+      "interval": 30
+    }
+  }
+}

mcp_proxy_adapter/examples/job_tracking_demo.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""Reference: JsonRpcClient job tracking (snapshots, message history, WS wait).
+
+What this demonstrates
+----------------------
+In order, the demo runs ``get_job_status(..., sync_from_queue=True)``,
+``get_job_messages(...)``, and (unless skipped) ``wait_for_job(...)``, which
+wraps ``wait_for_job_via_websocket`` and records inbound events to the client
+registry.
+
+Prerequisites (live server)
+-----------------------------
+- A running mcp-proxy-adapter with JSON-RPC and WebSocket ``/ws`` enabled for
+  queue-job subscription.
+- Network reachability to the configured host and port.
+- Transport and auth aligned with your deployment:
+  * ``--protocol http`` — plain HTTP (typical local dev).
+  * ``--protocol https`` — TLS; set token or certificate options if your server
+    requires them (same as ``JsonRpcClient`` constructor).
+  * ``--protocol mtls`` — mutual TLS; pass ``cert``, ``key``, and ``ca`` via
+    code if you extend this script (CLI here uses the default client without
+    extra TLS file paths).
+
+This module does not start a server.
+
+Non-interactive CI / offline path
+--------------------------------
+Run with ``--mock-flow`` to execute the same call sequence against a
+``JsonRpcClient`` with ``queue_get_job_status`` and
+``wait_for_job_via_websocket`` patched (no network I/O).
+
+How to run
+----------
+Show CLI help::
+
+    python -m mcp_proxy_adapter.examples.job_tracking_demo --help
+
+Offline mock sequence (copy-paste)::
+
+    python -m mcp_proxy_adapter.examples.job_tracking_demo --mock-flow
+
+Live adapter: replace ``<job-id>`` with a real queued job id from your server::
+
+    python -m mcp_proxy_adapter.examples.job_tracking_demo \\
+        --host 127.0.0.1 --port 8080 --protocol http --job-id <job-id>
+
+Skip the blocking ``wait_for_job`` step (snapshots and message list only)::
+
+    python -m mcp_proxy_adapter.examples.job_tracking_demo \\
+        --job-id <job-id> --no-wait
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from typing import Any, Dict
+
+from mcp_proxy_adapter.client.jsonrpc_client.client import JsonRpcClient
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    """Parse command-line arguments for the job tracking demo.
+
+    Args:
+        argv: List of command-line arguments (excluding program name).
+
+    Returns:
+        Parsed arguments namespace.
+    """
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--host", default="127.0.0.1")
+    p.add_argument("--port", type=int, default=8080)
+    p.add_argument("--protocol", default="http", choices=("http", "https", "mtls"))
+    p.add_argument(
+        "--job-id",
+        default="",
+        help="Live server: job id for status, messages, and (unless --no-wait) wait.",
+    )
+    p.add_argument(
+        "--no-wait",
+        action="store_true",
+        help="With --job-id only: run get_job_status and get_job_messages; skip wait_for_job.",
+    )
+    p.add_argument(
+        "--mock-flow",
+        action="store_true",
+        help="Run the demo sequence with mocked queue/WS methods (no network).",
+    )
+    return p.parse_args(argv)
+
+
+async def run_job_tracking_demo_sequence(
+    client: JsonRpcClient,
+    job_id: str,
+    *,
+    include_wait: bool = True,
+    wait_timeout: float = 60.0,
+) -> None:
+    """
+    Run ``get_job_status``, ``get_job_messages``, and optionally ``wait_for_job``.
+
+    Intended for reuse from tests and the CLI; prints human-readable lines to stdout.
+    """
+    jid = job_id.strip()
+    if not jid:
+        raise ValueError("job_id must be non-empty")
+
+    snap = await client.get_job_status(jid, sync_from_queue=True)
+    print("get_job_status(sync_from_queue=True):")
+    print(json.dumps(snap.summary, default=str, indent=2))
+
+    msgs = await client.get_job_messages(jid, limit=10)
+    print("get_job_messages(limit=10):", len(msgs), "message(s)")
+
+    if not include_wait:
+        return
+
+    async def on_event(msg: Dict[str, Any]) -> None:
+        """Print inbound job event messages.
+
+        Args:
+            msg: Event message dictionary.
+        """
+        print("event:", msg.get("event") or msg.get("type"))
+
+    result = await client.wait_for_job(jid, timeout=wait_timeout, on_event=on_event)
+    print("terminal:", json.dumps(result, default=str, indent=2))
+
+
+async def _run_mock_flow() -> None:
+    """Execute the tracking sequence with patched queue/WS (no live I/O)."""
+    from unittest.mock import AsyncMock, patch
+
+    client = JsonRpcClient(protocol="http", host="127.0.0.1", port=9)
+    job_id = "mock-job-id"
+
+    async def fake_queue_status(jid: str) -> Dict[str, Any]:
+        """Mock implementation of queue_get_job_status.
+
+        Args:
+            jid: Job ID to query.
+
+        Returns:
+            Mock job status response.
+        """
+        return {"status": "completed", "data": {"job_id": jid}}
+
+    async def fake_wait(
+        jid: str,
+        timeout: float = 1.0,
+        *,
+        on_inbound_message: Any = None,
+    ) -> Dict[str, Any]:
+        """Mock implementation of wait_for_job_via_websocket.
+
+        Args:
+            jid: Job ID to wait for.
+            timeout: Timeout in seconds.
+            on_inbound_message: Callback for inbound messages.
+
+        Returns:
+            Mock job completion response.
+        """
+        if on_inbound_message is not None:
+            await on_inbound_message({"event": "running", "job_id": jid})
+        return {"event": "job_completed", "job_id": jid, "result": {"ok": True}}
+
+    try:
+        with patch.object(
+            client,
+            "queue_get_job_status",
+            new=AsyncMock(side_effect=fake_queue_status),
+        ):
+            with patch.object(
+                client,
+                "wait_for_job_via_websocket",
+                new=AsyncMock(side_effect=fake_wait),
+            ):
+                await run_job_tracking_demo_sequence(
+                    client,
+                    job_id,
+                    include_wait=True,
+                    wait_timeout=30.0,
+                )
+    finally:
+        await client.close()
+
+
+async def main_async(argv: list[str] | None = None) -> None:
+    """Entry point for tests and ``main()``; *argv* is token list only (no ``sys.argv[0]``)."""
+    args = _parse_args(argv)
+    if args.mock_flow:
+        await _run_mock_flow()
+        return
+
+    if args.job_id:
+        client = JsonRpcClient(protocol=args.protocol, host=args.host, port=args.port)
+        try:
+            await run_job_tracking_demo_sequence(
+                client,
+                args.job_id.strip(),
+                include_wait=not args.no_wait,
+                wait_timeout=60.0,
+            )
+        finally:
+            await client.close()
+        return
+
+    print(
+        "No --job-id and no --mock-flow: no network calls.\n"
+        "  Offline / CI:\n"
+        "    python -m mcp_proxy_adapter.examples.job_tracking_demo --mock-flow\n"
+        "  Live server (replace <job-id>):\n"
+        "    python -m mcp_proxy_adapter.examples.job_tracking_demo "
+        "--host 127.0.0.1 --port 8080 --job-id <job-id>\n"
+        "  Snapshot + messages only (no wait_for_job):\n"
+        "    python -m mcp_proxy_adapter.examples.job_tracking_demo "
+        "--job-id <job-id> --no-wait\n",
+        file=sys.stderr,
+    )
+
+
+def main() -> None:
+    """Entry point: run the job tracking demo with command-line arguments."""
+    asyncio.run(main_async())
+
+
+if __name__ == "__main__":
+    main()