longrun-mcp-proxy 1.2.0__tar.gz

longrun_mcp_proxy-1.2.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: longrun-mcp-proxy
+Version: 1.2.0
+Summary: MCP proxy with async wrapper for long-running tools and persistent SSE mode
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=2.0.0

longrun_mcp_proxy-1.2.0/README.md

@@ -0,0 +1,172 @@
+# LongRunMCPProxy
+
+MCP proxy that wraps downstream MCP servers and converts long-running tools into an async start/poll pattern — so they never hit the client's timeout (e.g. Cursor's 60-second limit).
+
+## Problem
+
+AI coding agents (Cursor, Claude Code, VS Code Copilot) have built-in timeouts for MCP tool calls. Operations like Xcode builds or test runs can take minutes, causing the agent to drop the connection and lose results.
+
+## Solution
+
+LongRunMCPProxy sits between the AI agent and the MCP server. It:
+
+1. Discovers downstream tools on startup
+2. Auto-detects known long-running tools (or uses an explicit list)
+3. Wraps them in an async pattern: `tool()` → returns `job_id` instantly, agent polls `check_job(job_id)` for the result
+4. Passes all other tools through unchanged
+
+## Installation
+
+```bash
+# Install globally (recommended — instant startup)
+uv tool install "git+https://github.com/maximtart/LongRunMCPProxy.git@v1.1.0"
+
+# Or run without installing
+uvx --from "git+https://github.com/maximtart/LongRunMCPProxy.git@v1.1.0" longrun-mcp-proxy --help
+```
+
+### Updating
+
+```bash
+uv tool install "git+https://github.com/maximtart/LongRunMCPProxy.git@vX.Y.Z"
+```
+
+## Modes
+
+### stdio (recommended)
+
+For most MCP servers. Communicates with the AI agent via stdin/stdout.
+
+```bash
+longrun-mcp-proxy stdio -- xcrun mcpbridge
+longrun-mcp-proxy stdio -- npx -y xcodebuildmcp@latest mcp
+```
+
+### persistent
+
+Starts an SSE server on a local port. Use when the downstream server requires `outputSchema` or when multiple clients need to connect.
+
+```bash
+longrun-mcp-proxy persistent --port 8421 -- xcrun mcpbridge
+```
+
+## Auto-detection (v1.1.0+)
+
+When `--async-tools` is not specified, the proxy automatically detects known long-running tools from the downstream server:
+
+| Tool | Source |
+|------|--------|
+| `BuildProject` | Xcode native MCP |
+| `RunAllTests` | Xcode native MCP |
+| `RunSomeTests` | Xcode native MCP |
+| `RenderPreview` | Xcode native MCP |
+| `ExecuteSnippet` | Xcode native MCP |
+| `build_sim` | xcodebuildmcp |
+| `build_run_sim` | xcodebuildmcp |
+| `test_sim` | xcodebuildmcp |
+| `clean` | xcodebuildmcp |
+
+You can still override with `--async-tools` if needed:
+
+```bash
+longrun-mcp-proxy stdio --async-tools BuildProject,RunAllTests -- xcrun mcpbridge
+```
+
+## Configuration
+
+### Claude Code (`.mcp.json` in project root)
+
+```json
+{
+  "mcpServers": {
+    "xcode": {
+      "command": "longrun-mcp-proxy",
+      "args": ["stdio", "--", "xcrun", "mcpbridge"]
+    },
+    "xcode-build": {
+      "command": "longrun-mcp-proxy",
+      "args": ["stdio", "--", "npx", "-y", "xcodebuildmcp@latest", "mcp"]
+    }
+  }
+}
+```
+
+### VS Code (`.vscode/mcp.json`)
+
+```json
+{
+  "servers": {
+    "xcode": {
+      "type": "stdio",
+      "command": "longrun-mcp-proxy",
+      "args": ["stdio", "--", "xcrun", "mcpbridge"]
+    },
+    "xcode-build": {
+      "type": "stdio",
+      "command": "longrun-mcp-proxy",
+      "args": ["stdio", "--", "npx", "-y", "xcodebuildmcp@latest", "mcp"]
+    }
+  }
+}
+```
+
+### Cursor (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "xcode": {
+      "command": "longrun-mcp-proxy",
+      "args": ["stdio", "--", "xcrun", "mcpbridge"]
+    },
+    "xcode-build": {
+      "command": "longrun-mcp-proxy",
+      "args": ["stdio", "--", "npx", "-y", "xcodebuildmcp@latest", "mcp"]
+    }
+  }
+}
+```
+
+## How it works
+
+For async-wrapped tools, the agent sees:
+
+```
+1. Agent calls BuildProject(...)
+2. Proxy returns: {"job_id": "abc123", "status": "running"}
+3. Agent calls check_job(job_id="abc123")
+4. Proxy returns: {"status": "running", "elapsed_sec": 12.5}
+   ... agent keeps polling ...
+5. Proxy returns: {"status": "completed", "result": "Build succeeded."}
+```
+
+Two extra tools are added automatically:
+- `check_job(job_id)` — poll for result
+- `cancel_job(job_id)` — cancel a running job
+
+## Persistent mode extras
+
+```bash
+# Set Xcode MCP permission defaults (skip approval dialogs)
+longrun-mcp-proxy persistent --xcode-defaults --port 8421 -- xcrun mcpbridge
+
+# Auto-approve Xcode MCP permission dialogs via AppleScript
+longrun-mcp-proxy persistent --auto-approve --port 8421 -- xcrun mcpbridge
+```
+
+## Options
+
+| Flag | Mode | Description |
+|------|------|-------------|
+| `--async-tools TOOLS` | both | Comma-separated tool names to wrap (overrides auto-detect) |
+| `-v, --verbose` | both | Enable debug logging |
+| `--port PORT` | persistent | SSE server port (default: 8421) |
+| `--host HOST` | persistent | SSE server host (default: 127.0.0.1) |
+| `--name NAME` | persistent | Proxy server name |
+| `--xcode-defaults` | persistent | Set Xcode permission defaults |
+| `--auto-approve` | persistent | Auto-approve Xcode dialogs |
+
+## Requirements
+
+- Python >= 3.11
+- FastMCP >= 2.0.0

longrun_mcp_proxy-1.2.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "longrun-mcp-proxy"
+version = "1.2.0"
+description = "MCP proxy with async wrapper for long-running tools and persistent SSE mode"
+requires-python = ">=3.11"
+dependencies = [
+    "fastmcp>=2.0.0",
+]
+
+[project.scripts]
+longrun-mcp-proxy = "longrun_mcp_proxy.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

longrun_mcp_proxy-1.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

longrun_mcp_proxy-1.2.0/src/longrun_mcp_proxy/__init__.py

@@ -0,0 +1,23 @@
+"""MCP proxy with async wrapper for long-running tools."""
+
+__version__ = "0.1.0"
+
+from longrun_mcp_proxy.job_store import Job, JobStore
+from longrun_mcp_proxy.output_filter import filter_large_output
+from longrun_mcp_proxy.proxy_stdio import build_proxy, connect_and_register
+from longrun_mcp_proxy.proxy_persistent import (
+    PersistentDownstream,
+    start_persistent_proxy,
+    stop_persistent_proxy,
+)
+
+__all__ = [
+    "Job",
+    "JobStore",
+    "build_proxy",
+    "connect_and_register",
+    "filter_large_output",
+    "PersistentDownstream",
+    "start_persistent_proxy",
+    "stop_persistent_proxy",
+]

longrun_mcp_proxy-1.2.0/src/longrun_mcp_proxy/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m longrun_mcp_proxy`."""
+
+from longrun_mcp_proxy.cli import main
+
+main()

longrun_mcp_proxy-1.2.0/src/longrun_mcp_proxy/cli.py

@@ -0,0 +1,174 @@
+"""CLI entry point for longrun-mcp-proxy.
+
+Subcommands:
+    stdio      — Stdio proxy (FastMCP create_proxy + middleware).
+                 For servers WITHOUT outputSchema (e.g. XcodeBuildMCP).
+    persistent — Persistent SSE proxy with manual tool registration.
+                 For servers WITH outputSchema (e.g. native Xcode MCP).
+
+Usage:
+    longrun-mcp-proxy stdio --async-tools build_sim,test_sim \
+        -- npx -y xcodebuildmcp@latest mcp
+
+    longrun-mcp-proxy persistent --async-tools BuildProject,RunAllTests \
+        --port 8421 -- xcrun mcpbridge
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import sys
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="longrun-mcp-proxy",
+        description="MCP proxy with async wrapper for long-running tools",
+    )
+    parser.add_argument(
+        "-v", "--verbose", action="store_true", help="Enable debug logging"
+    )
+
+    sub = parser.add_subparsers(dest="mode", required=True)
+
+    # --- stdio ---
+    stdio_p = sub.add_parser(
+        "stdio",
+        help="Stdio proxy (for servers without outputSchema)",
+    )
+    stdio_p.add_argument(
+        "--async-tools",
+        default="",
+        help="Comma-separated tool names to wrap in async start/poll pattern",
+    )
+    stdio_p.add_argument(
+        "command", nargs=argparse.REMAINDER, help="Downstream MCP server command"
+    )
+
+    # --- persistent ---
+    pers_p = sub.add_parser(
+        "persistent",
+        help="Persistent SSE proxy (for servers with outputSchema)",
+    )
+    pers_p.add_argument(
+        "--async-tools",
+        default="",
+        help="Comma-separated tool names to wrap in async start/poll pattern",
+    )
+    pers_p.add_argument(
+        "--port", type=int, default=8421, help="SSE server port (default: 8421)"
+    )
+    pers_p.add_argument(
+        "--host", default="127.0.0.1", help="SSE server host (default: 127.0.0.1)"
+    )
+    pers_p.add_argument(
+        "--name",
+        default="longrun-mcp-proxy",
+        help="Proxy server name (default: longrun-mcp-proxy)",
+    )
+    pers_p.add_argument(
+        "--xcode-defaults",
+        action="store_true",
+        help="Set Xcode MCP permission defaults before starting",
+    )
+    pers_p.add_argument(
+        "--auto-approve",
+        action="store_true",
+        help="Start AppleScript auto-approver for Xcode MCP dialogs",
+    )
+    pers_p.add_argument(
+        "command", nargs=argparse.REMAINDER, help="Downstream MCP server command"
+    )
+
+    args = parser.parse_args(argv)
+
+    # Strip leading '--' from command
+    if args.command and args.command[0] == "--":
+        args.command = args.command[1:]
+
+    if not args.command:
+        parser.error("No downstream command specified")
+
+    return args
+
+
+def _run_stdio(args: argparse.Namespace) -> None:
+    """Run stdio proxy."""
+    from longrun_mcp_proxy.proxy_stdio import build_proxy, connect_and_register
+
+    async_tools = {t.strip() for t in args.async_tools.split(",") if t.strip()}
+
+    proxy = build_proxy(args.command, async_tools)
+
+    async def _main():
+        await connect_and_register(proxy)
+        await proxy.run_async(transport="stdio")
+
+    asyncio.run(_main())
+
+
+def _run_persistent(args: argparse.Namespace) -> None:
+    """Run persistent SSE proxy."""
+    from longrun_mcp_proxy.proxy_persistent import (
+        start_persistent_proxy,
+        stop_persistent_proxy,
+    )
+
+    async_tools = {t.strip() for t in args.async_tools.split(",") if t.strip()}
+
+    if args.xcode_defaults:
+        from longrun_mcp_proxy.extras.xcode_defaults import set_xcode_mcp_defaults
+
+        set_xcode_mcp_defaults()
+
+    approver_proc = None
+    if args.auto_approve:
+        from longrun_mcp_proxy.extras.xcode_approver import start_auto_approver
+
+        approver_proc = start_auto_approver()
+
+    async def _main() -> None:
+        task = await start_persistent_proxy(
+            command=args.command,
+            async_tools=async_tools,
+            port=args.port,
+            host=args.host,
+            name=args.name,
+        )
+        try:
+            await task
+        except asyncio.CancelledError:
+            pass
+        finally:
+            await stop_persistent_proxy(task)
+
+    try:
+        asyncio.run(_main())
+    finally:
+        if approver_proc:
+            from longrun_mcp_proxy.extras.xcode_approver import stop_auto_approver
+
+            stop_auto_approver()
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = _parse_args(argv)
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(name)s %(levelname)s %(message)s",
+    )
+
+    if args.mode == "stdio":
+        _run_stdio(args)
+    elif args.mode == "persistent":
+        _run_persistent(args)
+    else:
+        print(f"Unknown mode: {args.mode}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

longrun_mcp_proxy-1.2.0/src/longrun_mcp_proxy/extras/__init__.py

@@ -0,0 +1 @@
+"""Xcode-specific extras for longrun-mcp-proxy."""

longrun_mcp_proxy-1.2.0/src/longrun_mcp_proxy/extras/xcode_approver.py

@@ -0,0 +1,51 @@
+"""Auto-approve Xcode MCP agent permission dialogs via AppleScript."""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+from pathlib import Path
+
+logger = logging.getLogger("longrun-mcp-proxy")
+
+_approver_proc: subprocess.Popen | None = None
+
+# AppleScript is bundled with the package
+_SCRIPT_PATH = Path(__file__).parent.parent.parent.parent / "deploy" / "auto_approve_xcode_mcp.applescript"
+
+
+def start_auto_approver(script_path: Path | None = None) -> subprocess.Popen | None:
+    """Start the AppleScript auto-approver for Xcode MCP dialogs.
+
+    Requires: macOS with Accessibility access for the calling process.
+    """
+    global _approver_proc
+    script = script_path or _SCRIPT_PATH
+    if not script.exists():
+        logger.warning("Auto-approver script not found: %s", script)
+        return None
+    try:
+        proc = subprocess.Popen(
+            ["osascript", str(script)],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        _approver_proc = proc
+        logger.info("Auto-approver started (PID %d)", proc.pid)
+        return proc
+    except Exception as e:
+        logger.warning("Failed to start auto-approver: %s", e)
+        return None
+
+
+def stop_auto_approver() -> None:
+    """Stop the auto-approver process."""
+    global _approver_proc
+    if _approver_proc and _approver_proc.poll() is None:
+        _approver_proc.terminate()
+        try:
+            _approver_proc.wait(timeout=3)
+        except subprocess.TimeoutExpired:
+            _approver_proc.kill()
+        logger.info("Auto-approver stopped")
+    _approver_proc = None

longrun_mcp_proxy-1.2.0/src/longrun_mcp_proxy/extras/xcode_defaults.py

@@ -0,0 +1,56 @@
+"""Set Xcode defaults for MCP permissions."""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+
+logger = logging.getLogger("longrun-mcp-proxy")
+
+XCODE_MCP_DEFAULTS = (
+    "IDEAllowUnauthenticatedAgents",
+    "IDEChatAllowAgents",
+    "IDEChatAgenticChatSkipPermissions",
+    "IDEChatInternalAllowUntrustedAgentsWithoutUserInteraction",
+    "IDEChatSkipPermissionsForTools",
+    "IDEChatSkipPermissionsForTrustedTools",
+)
+
+# Default async tools for native Xcode MCP (xcrun mcpbridge)
+XCODE_NATIVE_ASYNC_TOOLS = {
+    "BuildProject",
+    "RunAllTests",
+    "RunSomeTests",
+    "RenderPreview",
+    "ExecuteSnippet",
+}
+
+# Default async tools for XcodeBuildMCP (Sentry)
+XCODE_BUILD_ASYNC_TOOLS = {
+    "build_sim",
+    "build_run_sim",
+    "test_sim",
+    "clean",
+}
+
+# Combined set of all known long-running tools for auto-detection.
+# When --async-tools is not specified, proxy matches discovered downstream
+# tool names against this set and wraps any matches automatically.
+KNOWN_ASYNC_TOOLS = XCODE_NATIVE_ASYNC_TOOLS | XCODE_BUILD_ASYNC_TOOLS
+
+# Tools that need a retry after completion to get a warmed-up result.
+# For example, RenderPreview returns a screenshot before async images load;
+# a second call after a delay returns the correct screenshot with cached images.
+KNOWN_RETRY_TOOLS: dict[str, float] = {
+    "RenderPreview": 3.0,  # seconds to wait before retry
+}
+
+
+def set_xcode_mcp_defaults() -> None:
+    """Set all known Xcode defaults that may help with MCP permissions."""
+    for key in XCODE_MCP_DEFAULTS:
+        subprocess.run(
+            ["defaults", "write", "com.apple.dt.Xcode", key, "-bool", "YES"],
+            capture_output=True,
+        )
+    logger.info("Xcode MCP defaults set (%d keys)", len(XCODE_MCP_DEFAULTS))

longrun_mcp_proxy-1.2.0/src/longrun_mcp_proxy/job_store.py

@@ -0,0 +1,52 @@
+"""In-memory job store for async-wrapped tool calls."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from uuid import uuid4
+
+JOB_TTL_SEC = 600  # clean up completed jobs after 10 min
+
+
+@dataclass
+class Job:
+    id: str
+    tool_name: str
+    status: str = "running"  # running | completed | failed
+    result: object | None = None
+    error: str | None = None
+    created_at: float = field(default_factory=time.time)
+    completed_at: float | None = None
+    _task: asyncio.Task | None = field(default=None, repr=False)
+
+
+class JobStore:
+    """In-memory store for async jobs."""
+
+    def __init__(self) -> None:
+        self._jobs: dict[str, Job] = {}
+
+    def create(self, tool_name: str) -> Job:
+        job = Job(id=uuid4().hex[:12], tool_name=tool_name)
+        self._jobs[job.id] = job
+        return job
+
+    def get(self, job_id: str) -> Job | None:
+        self._cleanup()
+        return self._jobs.get(job_id)
+
+    def all(self) -> list[Job]:
+        self._cleanup()
+        return list(self._jobs.values())
+
+    def _cleanup(self) -> None:
+        now = time.time()
+        expired = [
+            jid
+            for jid, j in self._jobs.items()
+            if j.completed_at and now - j.completed_at > JOB_TTL_SEC
+        ]
+        for jid in expired:
+            del self._jobs[jid]

longrun_mcp_proxy-1.2.0/src/longrun_mcp_proxy/middleware.py

@@ -0,0 +1,48 @@
+"""Async wrapper middleware for long-running MCP tools."""
+
+from __future__ import annotations
+
+import asyncio
+
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.tools.tool import ToolResult
+from mcp.types import CallToolRequestParams
+
+from longrun_mcp_proxy.job_store import JobStore
+
+
+class AsyncWrapperMiddleware(Middleware):
+    """Intercept designated tools and run them in background tasks."""
+
+    def __init__(self, async_tools: set[str], store: JobStore) -> None:
+        self._async_tools = async_tools
+        self._store = store
+
+    async def on_call_tool(
+        self,
+        context: MiddlewareContext[CallToolRequestParams],
+        call_next: CallNext[CallToolRequestParams, ToolResult],
+    ) -> ToolResult:
+        tool_name = context.message.name
+        if tool_name not in self._async_tools:
+            return await call_next(context)
+
+        job = self._store.create(tool_name)
+
+        async def _run() -> None:
+            try:
+                result = await call_next(context)
+                job.result = result
+                job.status = "completed"
+            except Exception as exc:
+                job.error = str(exc)
+                job.status = "failed"
+            job.completed_at = __import__("time").time()
+
+        job._task = asyncio.create_task(_run())
+
+        return ToolResult(
+            content=f"Job started: {job.id}\n"
+            f"Tool: {tool_name}\n"
+            f'Poll with check_job(job_id="{job.id}") to get the result.',
+        )

longrun_mcp_proxy-1.2.0/src/longrun_mcp_proxy/output_filter.py

@@ -0,0 +1,54 @@
+"""Filter large build output to keep only diagnostic lines."""
+
+from __future__ import annotations
+
+import re
+
+MAX_RESULT_CHARS = 30_000
+
+_DEFAULT_DIAG_RE = re.compile(
+    r"(?:error:|warning:|note:|\bfailure\b|\bBUILD )", re.IGNORECASE
+)
+
+
+def filter_large_output(
+    text: str,
+    max_chars: int = MAX_RESULT_CHARS,
+    pattern: re.Pattern | None = None,
+) -> str:
+    """Extract only diagnostic lines from large output.
+
+    If the output is small enough, return as-is. For large outputs,
+    keep only lines matching the diagnostic pattern.
+
+    Args:
+        text: The raw output text.
+        max_chars: Maximum characters to return.
+        pattern: Regex pattern for diagnostic lines. Defaults to
+                 error:/warning:/note:/failure/BUILD.
+    """
+    if len(text) <= max_chars:
+        return text
+
+    diag_re = pattern or _DEFAULT_DIAG_RE
+    lines = text.split("\n")
+    filtered = [ln for ln in lines if diag_re.search(ln)]
+
+    if not filtered:
+        return text[: max_chars // 2] + "\n...\n" + text[-max_chars // 2 :]
+
+    result = "\n".join(filtered)
+    if len(result) <= max_chars:
+        return result
+
+    # Deduplicate identical messages, then truncate
+    seen: set[str] = set()
+    unique: list[str] = []
+    for ln in filtered:
+        if ln not in seen:
+            seen.add(ln)
+            unique.append(ln)
+    result = "\n".join(unique)
+    if len(result) > max_chars:
+        result = result[:max_chars] + f"\n... (truncated, {len(text)} total chars)"
+    return result