mcpxray-cli 1.0.0__py3-none-any.whl

mcpxray/runtime.py

@@ -0,0 +1,260 @@
+"""Runtime capture — spawn an MCP server and read its ``tools/list`` over stdio.
+
+For servers whose tools can't be discovered statically (compiled, 3rd-party, or
+built dynamically at runtime), this opt-in path launches the server, performs
+the MCP JSON-RPC 2.0 handshake (``initialize`` → ``notifications/initialized``
+→ ``tools/list``) over its stdio transport, and returns the declared tools.
+The CLI feeds the result to :func:`mcpxray.extract.manifest.from_tools`, so the
+rest of the pipeline (rules → score → verdict) is reused unchanged.
+
+.. warning::
+
+   This **executes the server under inspection**, which may be untrusted code.
+   It is strictly opt-in (``--runtime --command``) and provides process
+   isolation + bounded lifetime only — **there is no OS-level sandbox** (no
+   filesystem or network isolation). Only point it at servers you trust, or run
+   mcpxray inside a container/VM when inspecting untrusted servers.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+import shlex
+import signal
+from dataclasses import dataclass
+from pathlib import Path
+
+from mcpxray import __version__
+
+# --- protocol constants -------------------------------------------------------
+_PROTOCOL_VERSION = "2024-11-05"
+_INIT_ID = 1
+_LIST_ID = 2
+_EXIT_TIMEOUT = 3.0  # grace period for the server to exit on EOF before we kill it
+
+
+class CaptureError(RuntimeError):
+    """Raised for any spawn / handshake / timeout / parse failure during capture."""
+
+
+@dataclass
+class CaptureResult:
+    """The outcome of a successful ``tools/list`` capture."""
+
+    tools: list[dict]
+    server_name: str | None
+    server_version: str | None
+
+
+# --- message builders (pure, unit-tested) ------------------------------------
+def _initialize_msg(req_id: int) -> dict:
+    return {
+        "jsonrpc": "2.0",
+        "id": req_id,
+        "method": "initialize",
+        "params": {
+            "protocolVersion": _PROTOCOL_VERSION,
+            "capabilities": {},
+            "clientInfo": {"name": "mcpxray", "version": __version__},
+        },
+    }
+
+
+def _initialized_notification() -> dict:
+    # A notification carries no ``id`` and expects no response.
+    return {"jsonrpc": "2.0", "method": "notifications/initialized"}
+
+
+def _tools_list_msg(req_id: int) -> dict:
+    return {"jsonrpc": "2.0", "id": req_id, "method": "tools/list", "params": {}}
+
+
+def split_command(command: str) -> list[str]:
+    """POSIX-split a ``--command`` string into an argv list (raises if empty)."""
+    argv = shlex.split(command)
+    if not argv:
+        raise CaptureError(f"could not parse a launch command from {command!r}")
+    return argv
+
+
+# --- stdio transport ----------------------------------------------------------
+async def _send(proc: asyncio.subprocess.Process, msg: dict) -> None:
+    if proc.stdin is None:
+        raise CaptureError("server has no stdin to write to")
+    proc.stdin.write((json.dumps(msg) + "\n").encode("utf-8"))
+    await proc.stdin.drain()
+
+
+async def _read_response(
+    proc: asyncio.subprocess.Process, expected_id: int, timeout: float, label: str
+) -> dict:
+    """Read newline-delimited JSON until the response with ``expected_id`` arrives."""
+
+    async def _read() -> dict:
+        assert proc.stdout is not None
+        while True:
+            line = await proc.stdout.readline()
+            if not line:
+                raise CaptureError(f"server closed its output before answering {label}")
+            text = line.decode("utf-8", "replace").strip()
+            if not text:
+                continue
+            try:
+                obj = json.loads(text)
+            except json.JSONDecodeError:
+                continue  # non-JSON line (log noise on stdout) — skip
+            if isinstance(obj, dict) and obj.get("id") == expected_id:
+                return obj
+            # otherwise a notification / unrelated response — keep reading
+
+    try:
+        return await asyncio.wait_for(_read(), timeout=timeout)
+    except asyncio.TimeoutError as e:
+        raise CaptureError(f"timed out waiting for the server's {label} response") from e
+
+
+async def _drain_stderr(stderr: asyncio.StreamReader, sink: list[str]) -> None:
+    """Continuously read stderr so a full pipe buffer can't deadlock the server."""
+    try:
+        while True:
+            chunk = await stderr.read(4096)
+            if not chunk:
+                break
+            sink.append(chunk.decode("utf-8", "replace"))
+    except (OSError, asyncio.LimitOverrunError):
+        pass
+
+
+def _kill(proc: asyncio.subprocess.Process) -> None:
+    """Force-kill the server (and its process group, where supported)."""
+    try:
+        if os.name == "nt":
+            proc.kill()  # TerminateProcess on the direct child only
+        else:
+            os.killpg(os.getpgid(proc.pid), signal.SIGKILL)  # whole session/group
+    except (ProcessLookupError, OSError):
+        pass
+
+
+async def _shutdown(proc: asyncio.subprocess.Process) -> None:
+    """Close stdin, wait briefly for exit, then force-kill if still alive."""
+    if proc.stdin is not None:
+        with contextlib.suppress(BaseException):
+            proc.stdin.close()
+    try:
+        await asyncio.wait_for(proc.wait(), timeout=_EXIT_TIMEOUT)
+        return
+    except asyncio.TimeoutError:
+        pass
+    _kill(proc)
+    with contextlib.suppress(Exception):
+        await proc.wait()
+
+
+async def _spawn(argv: list[str], cwd: Path | None) -> asyncio.subprocess.Process:
+    kwargs: dict = {}
+    if cwd is not None:
+        kwargs["cwd"] = str(cwd)
+    if os.name != "nt":
+        kwargs["start_new_session"] = True  # own process group → killable as a unit
+    try:
+        return await asyncio.create_subprocess_exec(
+            *argv,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            **kwargs,
+        )
+    except FileNotFoundError as e:
+        raise CaptureError(f"could not start server: executable not found ({argv[0]!r})") from e
+    except OSError as e:
+        raise CaptureError(f"could not start server: {e}") from e
+
+
+async def _handshake(
+    proc: asyncio.subprocess.Process, init_timeout: float, list_timeout: float
+) -> CaptureResult:
+    await _send(proc, _initialize_msg(_INIT_ID))
+    init_resp = await _read_response(proc, _INIT_ID, init_timeout, "initialize")
+    init_result = init_resp.get("result")
+    init_result = init_result if isinstance(init_result, dict) else {}
+    info = init_result.get("serverInfo")
+    info = info if isinstance(info, dict) else {}
+    server_name = info.get("name") if isinstance(info.get("name"), str) else None
+    server_version = info.get("version") if isinstance(info.get("version"), str) else None
+
+    await _send(proc, _initialized_notification())
+    await _send(proc, _tools_list_msg(_LIST_ID))
+    list_resp = await _read_response(proc, _LIST_ID, list_timeout, "tools/list")
+    if isinstance(list_resp.get("error"), dict):
+        msg = list_resp["error"].get("message", "tools/list returned an error")
+        raise CaptureError(f"tools/list failed: {msg}")
+
+    list_result = list_resp.get("result")
+    list_result = list_result if isinstance(list_result, dict) else {}
+    tools = list_result.get("tools")
+    if not isinstance(tools, list):
+        raise CaptureError("tools/list did not return a 'tools' list")
+
+    return CaptureResult(tools=tools, server_name=server_name, server_version=server_version)
+
+
+async def _capture(
+    argv: list[str], *, cwd: Path | None, init_timeout: float, list_timeout: float
+) -> CaptureResult:
+    proc = await _spawn(argv, cwd)
+    # Drain stderr in the background: a server that logs heavily to stderr would
+    # otherwise fill the OS pipe buffer and deadlock before we read its stdout.
+    stderr_sink: list[str] = []
+    stderr_task = (
+        asyncio.create_task(_drain_stderr(proc.stderr, stderr_sink))
+        if proc.stderr is not None
+        else None
+    )
+
+    err: CaptureError | None = None
+    result: CaptureResult | None = None
+    try:
+        result = await _handshake(proc, init_timeout, list_timeout)
+    except CaptureError as e:
+        err = e
+    except Exception as e:  # noqa: BLE001 — surface any protocol-level surprise
+        err = CaptureError(f"unexpected error during capture: {e}")
+
+    # Shut down first: killing the process closes the pipes, letting the drainer finish.
+    await _shutdown(proc)
+    if stderr_task is not None:
+        stderr_task.cancel()
+        with contextlib.suppress(BaseException):
+            await stderr_task
+
+    if err is not None:
+        tail = "".join(stderr_sink).strip()
+        if tail:
+            msg = f"{err.args[0]}\n  server stderr (tail):\n  {tail[-1200:]}"
+            raise CaptureError(msg) from None
+        raise err
+    assert result is not None
+    return result
+
+
+def capture_tools(
+    argv: list[str],
+    *,
+    cwd: Path | None = None,
+    init_timeout: float = 15.0,
+    list_timeout: float = 15.0,
+) -> CaptureResult:
+    """Spawn ``argv``, run the MCP stdio handshake, return the captured tools.
+
+    Raises :class:`CaptureError` on any spawn / handshake / timeout / parse
+    failure. Synchronous wrapper over the async implementation.
+    """
+    if not argv:
+        raise CaptureError("no launch command provided")
+    return asyncio.run(
+        _capture(argv, cwd=cwd, init_timeout=init_timeout, list_timeout=list_timeout)
+    )

mcpxray/score.py

@@ -0,0 +1,71 @@
+"""Score engine — collapse findings into a 0-100 score with an error cap.
+
+Mirrors OpenSSF Scorecard's shape (risk-weighted, hard cap so a single critical
+finding can't be diluted): each finding deducts points by severity, and any
+ERROR-severity finding caps the result at :data:`~mcpxray.ir.ERROR_SCORE_CAP`
+so a server with a leaked secret or poisoned tool never scores green.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mcpxray.ir import ERROR_SCORE_CAP, SEVERITY_ERROR, SEVERITY_INFO, SEVERITY_WARNING, McpServer
+
+# Points deducted per finding, by severity.
+_DEDUCTION = {
+    SEVERITY_ERROR: 20,
+    SEVERITY_WARNING: 6,
+    SEVERITY_INFO: 1,
+}
+
+_MAX_SCORE = 100
+
+
+@dataclass(frozen=True)
+class ScoreResult:
+    """The outcome of scoring a server."""
+
+    score: int
+    errors: int
+    warnings: int
+    infos: int
+    capped: bool  # True when the error-cap lowered the score
+
+    @property
+    def grade(self) -> str:
+        """Letter grade: A ≥90, B ≥80, C ≥70, D ≥60, F <60."""
+        if self.score >= 90:
+            return "A"
+        if self.score >= 80:
+            return "B"
+        if self.score >= 70:
+            return "C"
+        if self.score >= 60:
+            return "D"
+        return "F"
+
+    def passed(self, fail_under: int) -> bool:
+        return self.score >= fail_under
+
+
+def score(doc: McpServer) -> ScoreResult:
+    """Score a server from its diagnostics (run :func:`mcpxray.rules.run_all` first)."""
+    errors = sum(1 for d in doc.diagnostics if d.severity == SEVERITY_ERROR)
+    warnings = sum(1 for d in doc.diagnostics if d.severity == SEVERITY_WARNING)
+    infos = sum(1 for d in doc.diagnostics if d.severity == SEVERITY_INFO)
+
+    deducted = sum(_DEDUCTION.get(d.severity, 0) for d in doc.diagnostics)
+    raw = _MAX_SCORE - deducted
+
+    capped = errors > 0
+    final = min(raw, ERROR_SCORE_CAP) if capped else raw
+    final = max(0, min(_MAX_SCORE, final))
+
+    return ScoreResult(
+        score=final,
+        errors=errors,
+        warnings=warnings,
+        infos=infos,
+        capped=capped,
+    )

mcpxray/source.py

@@ -0,0 +1,253 @@
+"""Resolve a CLI target (URL / local path / manifest) to a local source.
+
+The friendly ``check`` command accepts a GitHub-style URL and clones it into a
+temporary directory so the existing Python extractor can run over it — no new
+dependencies, just ``git`` on the PATH and the standard library. URL handling
+lives here (not under :mod:`mcpxray.extract`) because cloning is a transport
+concern, not extraction: extractors build an IR from an already-local path.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlparse
+
+try:  # Python 3.11+
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python 3.10
+    import tomli as tomllib  # type: ignore[no-redef]
+
+from mcpxray.extract.python_static import _PY_EXTS, _iter_source_files
+from mcpxray.extract.typescript_static import _TS_EXTS
+
+# Combined source extensions so scope detection narrows a TS repo the same way
+# it already narrows a Python one (rather than scanning it wholesale).
+_SOURCE_EXTS = _PY_EXTS + _TS_EXTS
+
+# Hosts we treat as remote VCS URLs even without an http(s):// scheme.
+_VCS_HOSTS = ("github.com", "gitlab.com", "bitbucket.org")
+
+# Schemes ``git clone`` understands. ``file`` is included so tests (and local
+# clones) work without touching the network.
+_URL_SCHEMES = ("http", "https", "ssh", "git", "file")
+
+# Defensive upper bound on a clone so a bad network can't hang CI/tests.
+CLONE_TIMEOUT = 120
+
+
+class SourceError(Exception):
+    """Raised when a target cannot be resolved to a local path or manifest."""
+
+
+@dataclass
+class ResolvedSource:
+    """Where to analyze from, plus an optional tempdir to clean up afterwards."""
+
+    path: Path | None  # scan scope: the tree walked for source (may be a subdir)
+    root: Path | None  # project root for pyproject/lockfiles (== path unless narrowed)
+    manifest: Path | None
+    cleanup: tempfile.TemporaryDirectory | None  # set only when we cloned a URL
+
+
+def is_url(arg: str) -> bool:
+    """True if ``arg`` looks like a remote VCS URL.
+
+    Covers ``http(s)://``, ``ssh://``, ``git://``, ``file://``, the SCP-style
+    ``git@host:owner/repo``, and bare host prefixes (``github.com/owner/repo``).
+    """
+    if "://" in arg:
+        return urlparse(arg).scheme.lower() in _URL_SCHEMES
+    if arg.startswith("git@"):  # git@github.com:owner/repo.git
+        return True
+    return any(arg.startswith(host + "/") or arg.startswith(host + ":") for host in _VCS_HOSTS)
+
+
+def _normalize_url(arg: str) -> str:
+    """Add an ``https://`` scheme to bare host URLs (``github.com/...``)."""
+    if "://" not in arg and not arg.startswith("git@"):
+        return f"https://{arg}"
+    return arg
+
+
+def _clone(url: str) -> tuple[Path, tempfile.TemporaryDirectory]:
+    """Shallow-clone ``url`` into a fresh temp directory; raise ``SourceError`` on failure."""
+    if not shutil.which("git"):
+        raise SourceError("git is not installed; install git or point mcpxray at a local path")
+    tmp = tempfile.TemporaryDirectory(prefix="mcpxray-")
+    # Clone into a subdir named after the repo so the verdict card shows a
+    # readable name ("python-sdk") instead of the tempdir's random suffix.
+    dest = Path(tmp.name) / _repo_name(url)
+    try:
+        subprocess.run(
+            ["git", "clone", "--depth", "1", "--quiet", url, str(dest)],
+            capture_output=True,
+            text=True,
+            timeout=CLONE_TIMEOUT,
+            check=True,
+        )
+    except subprocess.CalledProcessError as e:
+        tmp.cleanup()
+        detail = (e.stderr or "").strip() or "unknown error"
+        raise SourceError(f"could not clone {url}: {detail}") from e
+    except subprocess.TimeoutExpired as e:
+        tmp.cleanup()
+        raise SourceError(f"timed out cloning {url} after {CLONE_TIMEOUT}s") from e
+    except Exception as e:  # FileNotFoundError (git vanished), OSError, etc.
+        tmp.cleanup()
+        raise SourceError(f"could not clone {url}: {e}") from e
+    return dest, tmp
+
+
+def _repo_name(url: str) -> str:
+    """Last path segment of a URL, ``.git`` stripped: ``…/owner/repo.git`` → ``repo``."""
+    name = url.rstrip("/").split("/")[-1]
+    if name.endswith(".git"):
+        name = name[:-4]
+    return name or "repo"
+
+
+# --- scope: locate the *server* source inside a tree -------------------------
+
+# A cheap textual signal for an MCP tool registration/decorator. Catches the
+# Python decorator (``@mcp.tool()``), the high-level registration call
+# (``server.tool(...)`` / ``server.registerTool(...)``) used by both SDKs, and the
+# low-level TS handler anchor (``ListToolsRequestSchema``) — good enough to bucket
+# files by directory for the scope heuristic.
+_TOOL_RE = re.compile(
+    r"\.\s*(?:tool|registerTool)\s*\(" r"|ListToolsRequestSchema" r"|^\s*@tool\b",
+    re.MULTILINE,
+)
+
+
+def _has_source(path: Path) -> bool:
+    """True if ``path`` contains any Python or TypeScript source (a coarse "is code" signal)."""
+    return any(True for _ in _iter_source_files(path, _SOURCE_EXTS))
+
+
+def _has_tool_call(path: Path) -> bool:
+    """True if any source file under ``path`` registers an MCP tool."""
+    for p in _iter_source_files(path, _SOURCE_EXTS):
+        try:
+            if _TOOL_RE.search(p.read_text(encoding="utf-8")):
+                return True
+        except OSError:
+            continue
+    return False
+
+
+def _entry_from_scripts(root: Path) -> Path | None:
+    """Derive the server dir from ``[project.scripts]`` (only if it also has tools).
+
+    Maps each ``"pkg.mod:attr"`` entry point to ``root/src/<topseg>`` or
+    ``root/<topseg>`` and returns the first existing dir that also registers a
+    tool — so a library's CLI entry point never narrows us into a tool-less dir.
+    """
+    pyproject = root / "pyproject.toml"
+    if not pyproject.is_file():
+        return None
+    try:
+        data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    except (tomllib.TOMLDecodeError, OSError):
+        return None
+    scripts = dict((data.get("project") or {}).get("scripts") or {})
+    scripts.update(((data.get("tool") or {}).get("poetry") or {}).get("scripts") or {})
+    for entry in scripts.values():
+        if not isinstance(entry, str) or ":" not in entry:
+            continue
+        top = entry.split(":", 1)[0].split(".")[0]
+        for cand in (root / "src" / top, root / top):
+            if cand.is_dir() and _has_tool_call(cand):
+                return cand
+    return None
+
+
+def _entry_from_tools(root: Path) -> Path | None:
+    """The immediate subdirectory of ``root`` holding the most tool registrations."""
+    counts: dict[Path, int] = {}
+    for f in _iter_source_files(root, _SOURCE_EXTS):
+        try:
+            n = len(_TOOL_RE.findall(f.read_text(encoding="utf-8")))
+        except OSError:
+            continue
+        if n == 0:
+            continue
+        rel = f.relative_to(root).parts
+        if len(rel) < 2:
+            continue  # file sits directly under root — narrowing would be a no-op
+        bucket = root / rel[0]
+        counts[bucket] = counts.get(bucket, 0) + n
+    if not counts:
+        return None
+    return max(counts, key=counts.get)
+
+
+def _detect_entry_dir(root: Path) -> Path:
+    """Best-effort locate the server source dir within ``root``; fall back to ``root``.
+
+    Order: ``[project.scripts]`` entry point → the immediate subdir with the most
+    tool registrations → ``src/`` (if it holds any source) → ``root``. Only
+    narrows to a strict subdirectory on positive evidence, so an ambiguous tree is
+    scanned wholesale (current behaviour) rather than wrongly narrowed.
+    """
+    return (
+        _entry_from_scripts(root)
+        or _entry_from_tools(root)
+        or ((root / "src") if (root / "src").is_dir() and _has_source(root / "src") else None)
+        or root
+    )
+
+
+def _scope_path(root: Path, override: str | None) -> Path:
+    """Resolve the scan scope within ``root``: an explicit override, else auto-detect."""
+    if override:
+        candidate = root / override
+        try:
+            candidate.resolve().relative_to(root.resolve())
+        except ValueError:
+            raise SourceError(f"--scope must stay under the target: {override!r}") from None
+        if not candidate.is_dir():
+            raise SourceError(f"--scope is not a directory under the target: {override!r}")
+        return candidate
+    return _detect_entry_dir(root)
+
+
+def resolve_target(
+    arg: str | None, manifest: Path | None, scope: str | None = None
+) -> ResolvedSource:
+    """Resolve a CLI target into a local path/manifest (+ optional tempdir).
+
+    * ``manifest`` wins — pass it straight through (existence is validated later).
+    * ``None``/``"."`` → the current working directory (scanned literally, no scope).
+    * a URL → shallow-cloned into a temp directory (caller cleans ``cleanup`` up),
+      then narrowed to the server source dir unless ``scope`` says otherwise.
+    * anything else → treated as a local path (must exist); a directory is narrowed
+      to the server source dir unless ``scope`` says otherwise.
+
+    ``ResolvedSource.path`` is the *scan scope* (possibly a subdir of ``root``);
+    ``ResolvedSource.root`` is the project root used for ``pyproject.toml`` /
+    lockfiles, so dependency checks survive scope narrowing.
+    """
+    if manifest is not None:
+        return ResolvedSource(path=None, root=None, manifest=manifest, cleanup=None)
+
+    if arg is None or arg == ".":
+        cwd = Path.cwd()
+        return ResolvedSource(path=cwd, root=cwd, manifest=None, cleanup=None)
+
+    if is_url(arg):
+        clone_root, cleanup = _clone(_normalize_url(arg))
+        scope_dir = _scope_path(clone_root, scope) if clone_root.is_dir() else clone_root
+        return ResolvedSource(path=scope_dir, root=clone_root, manifest=None, cleanup=cleanup)
+
+    local = Path(arg)
+    if not local.exists():
+        raise SourceError(f"path not found: {arg}")
+    if local.is_dir():
+        scope_dir = _scope_path(local, scope)
+        return ResolvedSource(path=scope_dir, root=local, manifest=None, cleanup=None)
+    return ResolvedSource(path=local, root=local, manifest=None, cleanup=None)