mcpxray-cli 1.0.0__py3-none-any.whl

mcpxray/__init__.py

@@ -0,0 +1,18 @@
+"""mcpxray — static linter + 0-100 scorecard for MCP servers."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+# The installed distribution is `mcpxray-cli` (the PyPI name; `mcpxray` is
+# taken there by an unrelated project) — the import package is `mcpxray`.
+try:
+    __version__ = version("mcpxray-cli")
+except PackageNotFoundError:
+    try:
+        __version__ = version("mcpxray")  # pre-rename installs
+    except PackageNotFoundError:  # source tree that isn't installed
+        __version__ = "0.0.0"
+
+# The top-level package surface is intentionally tiny (just the version). The
+# stable plugin API lives at its submodule paths — see CONTRIBUTING.md →
+# "Plugin API stability" for the full contract.
+__all__ = ["__version__"]

mcpxray/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m mcpxray`."""
+
+from mcpxray.cli import app
+
+if __name__ == "__main__":
+    app()

mcpxray/badge.py

@@ -0,0 +1,49 @@
+"""Score badge as an SVG (shields-style, embeddable in a README)."""
+
+from __future__ import annotations
+
+from mcpxray.score import ScoreResult
+
+_GRADE_COLOR = {
+    "A": "#4c1",  # brightgreen
+    "B": "#97ca00",  # green
+    "C": "#dfb317",  # yellow
+    "D": "#fe7d37",  # orange
+    "F": "#e05d44",  # red
+}
+
+_HEIGHT = 20
+_FONT = "Verdana, 'DejaVu Sans', sans-serif"
+_FONT_SIZE = 11
+_CHAR_WIDTH = 6.2  # approx average advance for the badge font at size 11
+_PAD = 6
+
+
+def _text_width(text: str) -> int:
+    return int(len(text) * _CHAR_WIDTH) + 2 * _PAD
+
+
+def badge_svg(score_result: ScoreResult, *, label: str = "mcp score") -> str:
+    """Render a flat SVG badge for the given score."""
+    color = _GRADE_COLOR[score_result.grade]
+    value = f"{score_result.score}/100"
+    label_w = _text_width(label)
+    value_w = _text_width(value)
+    total_w = label_w + value_w
+
+    return (
+        f'<svg xmlns="http://www.w3.org/2000/svg"'
+        f' width="{total_w}" height="{_HEIGHT}"'
+        f' role="img" aria-label="{label}: {value}">'
+        f'<linearGradient id="s" x2="0" y2="100%">'
+        f'<stop offset="0" stop-color="#bbb" stop-opacity=".1"/>'
+        f'<stop offset="1" stop-opacity=".1"/></linearGradient>'
+        f'<rect width="{total_w}" height="{_HEIGHT}" fill="#555"/>'
+        f'<rect x="{label_w}" width="{value_w}" height="{_HEIGHT}" fill="{color}"/>'
+        f'<rect width="{total_w}" height="{_HEIGHT}" fill="url(#s)"/>'
+        f'<text x="{_PAD}" y="14" fill="#fff" font-family="{_FONT}" font-size="{_FONT_SIZE}">'
+        f"{label}</text>"
+        f'<text x="{label_w + _PAD}" y="14" fill="#fff" font-family="{_FONT}"'
+        f' font-size="{_FONT_SIZE}">{value}</text>'
+        f"</svg>"
+    )

mcpxray/cli.py

@@ -0,0 +1,322 @@
+"""mcpxray CLI — `scan`, `score`, `badge`, `version`.
+
+The CLI is a thin shell over the extractor → rule-engine → score → render
+pipeline. `scan` lints and reports; `score` collapses to a 0-100 number;
+`badge` emits an SVG; `version` prints the version.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import typer
+
+from mcpxray import __version__
+from mcpxray.badge import badge_svg
+from mcpxray.extract import extractor_for
+from mcpxray.extract.manifest import ManifestExtractor
+from mcpxray.extract.manifest import from_tools as manifest_from_tools
+from mcpxray.fix import apply_fixes, has_pending, plan_fixes, render_diff
+from mcpxray.ir import SEVERITY_ERROR, SOURCE_STATIC, McpServer, ServerMeta
+from mcpxray.report import SUPPORTED_FORMATS, render
+from mcpxray.report.card import render_verdict
+from mcpxray.rules import run_all
+from mcpxray.runtime import CaptureError, capture_tools, split_command
+from mcpxray.score import ScoreResult
+from mcpxray.score import score as score_doc
+from mcpxray.source import ResolvedSource, SourceError, is_url, resolve_target
+from mcpxray.verdict import verdict
+
+app = typer.Typer(
+    name="mcpxray",
+    help="Static linter + 0-100 scorecard for MCP servers.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _extract_doc(
+    resolved: ResolvedSource, runtime_argv: list[str] | None, *, graceful: bool
+) -> McpServer:
+    """Build a :class:`McpServer` from a manifest file, a runtime capture, or source.
+
+    The three input modes are mutually exclusive (enforced in :func:`_run`).
+    ``graceful`` only affects the static no-extractor case: ``check`` synthesizes
+    an empty static doc (→ an honest UNKNOWN card); ``scan``/``score`` exit-2.
+    """
+    if resolved.manifest is not None:
+        if not resolved.manifest.is_file():
+            typer.echo(f"error: manifest not found: {resolved.manifest}", err=True)
+            raise typer.Exit(code=2)
+        return ManifestExtractor().extract(resolved.manifest)
+
+    if runtime_argv is not None:
+        captured = capture_tools(runtime_argv, cwd=resolved.path)
+        return manifest_from_tools(
+            captured.tools,
+            name=captured.server_name or "runtime",
+            path_str=str(resolved.path or resolved.root or Path.cwd()),
+            version=captured.server_version,
+        )
+
+    path = resolved.path if resolved.path is not None else Path.cwd()
+    extractor = extractor_for(path)
+    if extractor is None:
+        if graceful:
+            return McpServer(
+                meta=ServerMeta(name=path.name, language=None, path=str(resolved.root or path)),
+                source_mode=SOURCE_STATIC,
+            )
+        typer.echo(
+            f"error: no extractor matched {path} "
+            "(point at a source tree, pass --manifest <tools/list.json>, "
+            "or use --runtime --command '<launch>')",
+            err=True,
+        )
+        raise typer.Exit(code=2)
+    return extractor.extract(path, root=resolved.root)
+
+
+def _analyze(
+    resolved: ResolvedSource, runtime_argv: list[str] | None, *, graceful: bool
+) -> tuple[McpServer, ScoreResult]:
+    """Extract, run all rules, score. Returns (doc, score_result)."""
+    doc = _extract_doc(resolved, runtime_argv, graceful=graceful)
+    run_all(doc)
+    return doc, score_doc(doc)
+
+
+def _run(
+    target: str | None,
+    manifest: Path | None,
+    scope: str | None,
+    runtime: bool,
+    command: str | None,
+    *,
+    graceful: bool,
+) -> tuple[McpServer, ScoreResult]:
+    """Resolve a target (URL / path / manifest, optionally scoped) and analyze it.
+
+    Shared by every command so URL input, ``--scope``, ``--runtime``, and tempdir
+    cleanup live in one place. ``graceful`` selects UNKNOWN-on-no-extractor
+    (``check``) vs the exit-2 that ``scan``/``score``/``badge`` raise.
+    """
+    if manifest is not None and runtime:
+        typer.echo("error: --manifest and --runtime are mutually exclusive", err=True)
+        raise typer.Exit(code=2)
+    if runtime and not command:
+        typer.echo("error: --runtime needs --command <launch cmd>", err=True)
+        raise typer.Exit(code=2)
+
+    resolved: ResolvedSource | None = None
+    try:
+        runtime_argv = split_command(command) if runtime else None
+        resolved = resolve_target(target, manifest, scope)
+        return _analyze(resolved, runtime_argv, graceful=graceful)
+    except CaptureError as e:
+        typer.echo(f"error: runtime capture failed: {e}", err=True)
+        raise typer.Exit(code=2) from None
+    finally:
+        if resolved is not None and resolved.cleanup is not None:
+            try:
+                resolved.cleanup.cleanup()
+            except OSError:  # git may briefly hold pack-locks on Windows
+                shutil.rmtree(resolved.cleanup.name, ignore_errors=True)
+
+
+@app.command()
+def check(
+    target: str = typer.Argument(None, help="GitHub URL or local path to the MCP server source."),
+    manifest: Path = typer.Option(
+        None, "--manifest", help="Captured tools/list JSON dump instead of source/URL."
+    ),
+    runtime: bool = typer.Option(
+        False,
+        "--runtime",
+        help=(
+            "Spawn the server and capture its tools/list over MCP stdio (opt-in; "
+            "needs --command; executes the server — trusted/container only)."
+        ),
+    ),
+    command: str = typer.Option(
+        None,
+        "--command",
+        help="Launch command for --runtime, e.g. 'python -m srv' / 'node server.js' (POSIX split).",
+    ),
+    scope: str = typer.Option(
+        None, "--scope", help="Subdirectory to scan/run in, relative to the target."
+    ),
+    details: bool = typer.Option(
+        False, "--details", "-v", help="Also print the full finding list."
+    ),
+    fail_under: int = typer.Option(
+        0, "--fail-under", help="Gate: exit 1 if the score is below N (CI mode)."
+    ),
+) -> None:
+    """Friendly safety check: is this MCP server safe to install?"""
+    try:
+        doc, score_result = _run(target, manifest, scope, runtime, command, graceful=True)
+    except SourceError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(code=2) from None
+
+    v = verdict(doc, score_result)
+    typer.echo(render_verdict(v, doc=doc, score_result=score_result, details=details))
+
+    if v.tier == "danger" or not score_result.passed(fail_under):
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def version() -> None:
+    """Print the mcpxray version."""
+    typer.echo(__version__)
+
+
+@app.command()
+def scan(
+    target: str = typer.Argument(None, help="Path or URL to the MCP server source."),
+    manifest: Path = typer.Option(
+        None, "--manifest", help="Captured tools/list JSON dump instead of source."
+    ),
+    runtime: bool = typer.Option(
+        False,
+        "--runtime",
+        help=(
+            "Spawn the server and capture its tools/list over MCP stdio (opt-in; needs --command)."
+        ),
+    ),
+    command: str = typer.Option(
+        None,
+        "--command",
+        help="Launch command for --runtime, e.g. 'python -m srv' / 'node server.js'.",
+    ),
+    scope: str = typer.Option(
+        None, "--scope", help="Subdirectory to scan/run in, relative to the target."
+    ),
+    fmt: str = typer.Option(
+        "plain", "-f", "--format", help=f"Report format: {', '.join(SUPPORTED_FORMATS)}."
+    ),
+    check: bool = typer.Option(
+        False, "--check", help="Gate: exit 1 on any ERROR finding (CI mode)."
+    ),
+    fix: bool = typer.Option(
+        False,
+        "--fix",
+        help="Apply auto-fixes in place (unpinned deps → pinned). Local source only.",
+    ),
+    diff: bool = typer.Option(
+        False,
+        "--diff",
+        help="Print a unified diff of planned fixes; write nothing (exits 1 if any pending).",
+    ),
+) -> None:
+    """Lint an MCP server and print findings in the chosen format."""
+    if fix or diff:
+        if fix and diff:
+            typer.echo("error: --fix and --diff are mutually exclusive", err=True)
+            raise typer.Exit(code=2)
+        if manifest is not None or runtime:
+            typer.echo(
+                "error: --fix/--diff rewrite source files — use a local path, "
+                "not --manifest/--runtime",
+                err=True,
+            )
+            raise typer.Exit(code=2)
+        if target is not None and is_url(target):
+            typer.echo(
+                "error: --fix/--diff rewrite files in place — point at a local path, not a URL",
+                err=True,
+            )
+            raise typer.Exit(code=2)
+    try:
+        doc, score_result = _run(target, manifest, scope, runtime, command, graceful=False)
+    except SourceError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(code=2) from None
+
+    if fix or diff:
+        fixes = plan_fixes(doc)
+        if diff:
+            out = render_diff(fixes)
+            if out:
+                typer.echo(out, nl=False)
+            if has_pending(fixes):
+                raise typer.Exit(code=1)
+            return
+        summary = apply_fixes(fixes)
+        typer.echo(f"applied {summary.edits_applied} fix(es) in {summary.files_changed} file(s)")
+        for msg in summary.skipped:
+            typer.echo(f"skipped: {msg}", err=True)
+        return
+
+    typer.echo(render(doc.diagnostics, fmt, doc=doc, score_result=score_result))
+    if check and any(d.severity == SEVERITY_ERROR for d in doc.diagnostics):
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def score(
+    target: str = typer.Argument(None, help="Path or URL to the MCP server source."),
+    manifest: Path = typer.Option(None, "--manifest", help="Captured tools/list JSON dump."),
+    runtime: bool = typer.Option(
+        False,
+        "--runtime",
+        help=(
+            "Spawn the server and capture its tools/list over MCP stdio (opt-in; needs --command)."
+        ),
+    ),
+    command: str = typer.Option(
+        None,
+        "--command",
+        help="Launch command for --runtime, e.g. 'python -m srv' / 'node server.js'.",
+    ),
+    scope: str = typer.Option(
+        None, "--scope", help="Subdirectory to scan/run in, relative to the target."
+    ),
+    fail_under: int = typer.Option(0, "--fail-under", help="Gate: exit 1 if the score is below N."),
+) -> None:
+    """Print the 0-100 score and grade; exit 1 if below --fail-under."""
+    try:
+        _doc, score_result = _run(target, manifest, scope, runtime, command, graceful=False)
+    except SourceError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(code=2) from None
+    cap = "  [capped by error finding]" if score_result.capped else ""
+    typer.echo(f"score {score_result.score}/100 (grade {score_result.grade}){cap}")
+    if not score_result.passed(fail_under):
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def badge(
+    target: str = typer.Argument(None, help="Path or URL to the MCP server source to score."),
+    score_value: int = typer.Option(None, "--score", help="Render a literal score (0-100)."),
+    output: Path = typer.Option(
+        Path("badge.svg"), "-o", "--output", help="Output SVG path ('-' for stdout)."
+    ),
+) -> None:
+    """Render a score badge as SVG (from a path/URL, or a literal --score)."""
+    if score_value is not None:
+        result = ScoreResult(score=score_value, errors=0, warnings=0, infos=0, capped=False)
+    elif target is not None:
+        try:
+            _doc, result = _run(target, None, None, False, None, graceful=False)
+        except SourceError as e:
+            typer.echo(f"error: {e}", err=True)
+            raise typer.Exit(code=2) from None
+    else:
+        typer.echo("error: provide a PATH or --score N", err=True)
+        raise typer.Exit(code=2)
+
+    svg = badge_svg(result)
+    if str(output) == "-":
+        typer.echo(svg)
+    else:
+        output.write_text(svg, encoding="utf-8")
+        typer.echo(f"wrote {output}")
+
+
+if __name__ == "__main__":
+    app()

mcpxray/extract/__init__.py

@@ -0,0 +1,16 @@
+"""Extractors turn a path (source tree or manifest) into a :class:`McpServer` IR."""
+
+from __future__ import annotations
+
+# Importing the builtin extractors triggers @register_extractor self-registration.
+from mcpxray.extract import manifest as _manifest  # noqa: F401
+from mcpxray.extract import python_static as _python_static  # noqa: F401
+from mcpxray.extract import typescript_static as _typescript_static  # noqa: F401
+from mcpxray.extract.base import (
+    Extractor,
+    extractor_for,
+    extractors,
+    register_extractor,
+)
+
+__all__ = ["Extractor", "extractor_for", "extractors", "register_extractor"]

mcpxray/extract/base.py

@@ -0,0 +1,61 @@
+"""Extractor API + registry.
+
+An :class:`Extractor` reads a path (a source tree or a manifest file) and emits
+a :class:`~mcpxray.ir.McpServer`. Builtins self-register via
+:func:`register_extractor`; external packages declare an entry-point in the
+``mcpxray.extractors`` group (loaded in v0.1 alongside rule entry-points).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from mcpxray.ir import McpServer
+
+# Stable plugin API for extractor authors (see CONTRIBUTING.md → "Plugin API
+# stability"). ``_EXTRACTORS`` and any ``_``-prefixed name are internal.
+__all__ = ["Extractor", "register_extractor", "extractors", "extractor_for"]
+
+_EXTRACTORS: list[type[Extractor]] = []
+
+
+class Extractor(ABC):
+    """Base class for all extractors."""
+
+    language: str = ""  # "python" | "typescript" | "" (manifest)
+
+    @abstractmethod
+    def applies_to(self, path: Path) -> bool:
+        """True if this extractor can read ``path`` (file or directory)."""
+
+    @abstractmethod
+    def extract(self, path: Path, *, root: Path | None = None) -> McpServer:
+        """Build a :class:`McpServer` from ``path``.
+
+        ``path`` is the *scan scope* — the tree walked for source files. ``root``,
+        when given, is the wider *project root* to read ``pyproject.toml`` /
+        lockfiles from (it differs from ``path`` only when the caller has narrowed
+        the scan to a subpackage). Defaults to ``path`` so unscoped calls behave
+        exactly as before.
+        """
+
+
+def register_extractor(cls: type[Extractor]) -> type[Extractor]:
+    """Class decorator: register an :class:`Extractor` subclass."""
+    _EXTRACTORS.append(cls)
+    return cls
+
+
+def extractors() -> list[type[Extractor]]:
+    """All registered extractor classes (builtins first, registration order)."""
+    return list(_EXTRACTORS)
+
+
+def extractor_for(path: Path) -> Extractor | None:
+    """Return the first registered extractor whose ``applies_to`` matches."""
+    for cls in _EXTRACTORS:
+        ext = cls()
+        if ext.applies_to(path):
+            return ext
+    return None

mcpxray/extract/manifest.py

@@ -0,0 +1,97 @@
+"""Manifest extractor — parse a captured ``tools/list`` JSON dump.
+
+For servers whose source we can't (or don't want to) parse — any language,
+compiled, or third-party — a user captures ``tools/list`` and feeds the JSON
+here. Tools learned this way carry ``runtime_only=True``.
+
+The per-tool construction (:func:`_tool_from_entry`) and the
+:class:`~mcpxray.ir.McpServer` assembly (:func:`_build`) are shared with the
+runtime capture path (:mod:`mcpxray.runtime` → :func:`from_tools`), so a
+hand-fed manifest file and a live ``tools/list`` capture produce the same IR.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from mcpxray.extract.base import Extractor, register_extractor
+from mcpxray.ir import SOURCE_MANIFEST, SOURCE_RUNTIME, McpServer, ServerMeta, Tool
+
+
+def _find_tools(payload: object) -> list[dict]:
+    """Locate the tools list in either a raw or JSON-RPC-wrapped response."""
+    if isinstance(payload, dict):
+        if isinstance(payload.get("tools"), list):
+            return payload["tools"]
+        result = payload.get("result")
+        if isinstance(result, dict) and isinstance(result.get("tools"), list):
+            return result["tools"]
+    return []
+
+
+def _looks_like_manifest(path: Path) -> bool:
+    if not path.is_file() or path.suffix != ".json":
+        return False
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return False
+    return bool(_find_tools(payload))
+
+
+def _tool_from_entry(entry: object) -> Tool | None:
+    """Build a single ``runtime_only`` tool from a tools/list entry, or skip it."""
+    if not isinstance(entry, dict) or not entry.get("name"):
+        return None
+    return Tool(
+        name=entry["name"],
+        description=entry.get("description"),
+        input_schema=entry.get("inputSchema") or entry.get("input_schema") or {},
+        runtime_only=True,
+    )
+
+
+def _build(
+    tools: list[dict],
+    *,
+    name: str,
+    path_str: str,
+    version: str | None = None,
+    source_mode: str = SOURCE_MANIFEST,
+) -> McpServer:
+    """Assemble a runtime-only :class:`McpServer` from a tools/list list."""
+    server = McpServer(
+        meta=ServerMeta(name=name, version=version, language=None, path=path_str),
+        source_mode=source_mode,
+    )
+    for entry in tools:
+        tool = _tool_from_entry(entry)
+        if tool is not None:
+            server.tools.append(tool)
+    return server
+
+
+def from_tools(
+    tools: list[dict],
+    *,
+    name: str = "runtime",
+    path_str: str = "<runtime>",
+    version: str | None = None,
+) -> McpServer:
+    """Build an IR from a captured ``tools/list`` tool list (runtime path)."""
+    return _build(tools, name=name, path_str=path_str, version=version, source_mode=SOURCE_RUNTIME)
+
+
+@register_extractor
+class ManifestExtractor(Extractor):
+    """Extract tools from a captured ``tools/list`` JSON dump."""
+
+    language = ""  # language-agnostic
+
+    def applies_to(self, path: Path) -> bool:
+        return _looks_like_manifest(path)
+
+    def extract(self, path: Path, *, root: Path | None = None) -> McpServer:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        return _build(_find_tools(payload), name=path.stem, path_str=str(path))