mcpxray-cli 1.0.0__py3-none-any.whl

mcpxray/fix.py

@@ -0,0 +1,166 @@
+"""Auto-fix machinery: turn rule-proposed :class:`~mcpxray.ir.Fix`es into file
+edits and diffs.
+
+Only **MCP108** (unpinned dependencies) is mechanically fixable today — it pins
+a floating version spec to its concrete floor (``requests>=2.30`` →
+``requests==2.30.0``, ``"^1.2.3"`` → ``"1.2.3"``). Specs with no resolvable
+floor (``*``, ``latest``, a bare name like ``flask``) are skipped and left for
+manual pinning — mcpxray never invents a version by resolving a registry.
+
+``--fix`` is opt-in and **static-source-only** (it rewrites files in place);
+``--diff`` prints a unified diff of the same edits without writing. Both flow
+through :func:`plan_fixes`, which collects every diagnostic's ``fix`` and groups
+it by file.
+
+Safety: every edit is a *literal* substring replacement applied only when its
+``old`` text occurs exactly once in the file (see :func:`_apply_edits`) — so a
+spec that doesn't match the common form, or that would match more than one site,
+is skipped rather than applied wrongly. Writes are atomic (temp file + replace).
+"""
+
+from __future__ import annotations
+
+import difflib
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from mcpxray.ir import Fix, McpServer, TextEdit
+
+# A concrete MAJOR.MINOR.PATCH (optionally with pre-release/build) extractable
+# from a floating spec — the floor it pins down to. The lookbehind only rejects a
+# preceding digit/dot (so we don't match a partial version mid-number); version
+# prefix chars (``v``/``=``/``^``/``~``/``>``/``<``) and letters are allowed.
+_FLOOR_RE = re.compile(r"(?<![0-9.])(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)")
+
+
+def pin_floor(spec: str) -> str | None:
+    """The concrete ``X.Y.Z`` a floating spec resolves down to, or ``None``.
+
+    ``^1.2.3`` / ``~1.2.3`` / ``>=1.2.3`` / ``=1.2.3`` / ``v1.2.3`` → ``1.2.3``.
+    ``*`` / ``latest`` / a bare name (``flask``) / ``1.x`` / ``>=2`` → ``None``
+    (no full floor → can't pin without resolving from a registry).
+    """
+    m = _FLOOR_RE.search(spec)
+    return m.group(1) if m else None
+
+
+def exact_pin(spec: str, *, pip: bool) -> str | None:
+    """Exact pinned form of ``spec`` for its ecosystem, or ``None`` if unresolvable.
+
+    pip → ``==X.Y.Z``; npm → ``X.Y.Z``. Returns ``None`` when :func:`pin_floor`
+    can't find a floor.
+    """
+    floor = pin_floor(spec)
+    if floor is None:
+        return None
+    return f"=={floor}" if pip else floor
+
+
+@dataclass
+class ApplySummary:
+    """Outcome of :func:`apply_fixes`: how much changed and what was declined."""
+
+    files_changed: int = 0
+    edits_applied: int = 0
+    skipped: list[str] = field(default_factory=list)
+
+
+def plan_fixes(doc: McpServer) -> list[Fix]:
+    """Collect every diagnostic's ``fix`` and merge them into one :class:`Fix` per file."""
+    by_file: dict[str, Fix] = {}
+    for diag in doc.diagnostics:
+        fix = diag.fix
+        if fix is None:
+            continue
+        bucket = by_file.setdefault(fix.file, Fix(description=fix.description, file=fix.file))
+        bucket.edits.extend(fix.edits)
+    return list(by_file.values())
+
+
+def _apply_edits(text: str, edits: list[TextEdit]) -> tuple[str, list[TextEdit], list[str]]:
+    """Apply ``edits`` to ``text``; return ``(new_text, applied, skipped_messages)``.
+
+    An edit is applied only when its ``old`` occurs exactly once and its span
+    doesn't overlap another kept edit. Absent/ambiguous/overlapping edits are
+    skipped (never applied partially).
+    """
+    spans: list[tuple[int, int, TextEdit]] = []
+    skipped: list[str] = []
+    for edit in edits:
+        if not edit.old or edit.old == edit.new:
+            continue
+        first = text.find(edit.old)
+        if first == -1:
+            skipped.append(f"not found in source: {edit.old!r}")
+            continue
+        if text.find(edit.old, first + 1) != -1:
+            skipped.append(f"ambiguous — matches more than one site: {edit.old!r}")
+            continue
+        spans.append((first, first + len(edit.old), edit))
+
+    spans.sort()
+    kept: list[TextEdit] = []
+    last_end = -1
+    for start, end, edit in spans:
+        if start < last_end:
+            skipped.append(f"overlaps another edit: {edit.old!r}")
+            continue
+        kept.append(edit)
+        last_end = end
+
+    out = text
+    for edit in kept:  # each `old` is unique, so order is irrelevant
+        out = out.replace(edit.old, edit.new, 1)
+    return out, kept, skipped
+
+
+def _atomic_write(path: Path, text: str) -> None:
+    tmp = path.with_name(path.name + ".mcpxray-tmp")
+    tmp.write_text(text, encoding="utf-8")
+    tmp.replace(path)
+
+
+def apply_fixes(fixes: list[Fix]) -> ApplySummary:
+    """Write every fix's file in place (atomic); return an :class:`ApplySummary`."""
+    summary = ApplySummary()
+    for fix in fixes:
+        path = Path(fix.file)
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError:
+            summary.skipped.append(f"unreadable file: {fix.file}")
+            continue
+        new_text, applied, skipped = _apply_edits(text, fix.edits)
+        summary.skipped.extend(skipped)
+        if not applied:
+            continue
+        _atomic_write(path, new_text)
+        summary.files_changed += 1
+        summary.edits_applied += len(applied)
+    return summary
+
+
+def render_diff(fixes: list[Fix]) -> str:
+    """Unified diff of every fix's planned edits — writes nothing."""
+    parts: list[str] = []
+    for fix in fixes:
+        path = Path(fix.file)
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        new_text, _applied, _skipped = _apply_edits(text, fix.edits)
+        diff = difflib.unified_diff(
+            text.splitlines(keepends=True),
+            new_text.splitlines(keepends=True),
+            fromfile=path.name,
+            tofile=path.name,
+        )
+        parts.append("".join(diff))
+    return "".join(parts)
+
+
+def has_pending(fixes: list[Fix]) -> bool:
+    """True if any planned fix carries at least one edit."""
+    return any(fix.edits for fix in fixes)

mcpxray/ir.py

@@ -0,0 +1,186 @@
+"""Intermediate representation for an MCP server under analysis.
+
+Every extractor emits a :class:`McpServer`; every rule consumes one. The IR is
+extractor-agnostic — it models the union of what static source parsing and a
+``tools/list`` manifest can tell us, with provenance (``location``) so findings
+point back to real source lines.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# Public, stable surface for this module. Names listed here are the plugin API
+# (see CONTRIBUTING.md → "Plugin API stability"); everything else — including
+# ``_SEVERITY_RANK`` and ``RISK_WEIGHT`` — is internal and may change at any
+# release. ``from mcpxray.ir import *`` yields exactly this list.
+__all__ = [
+    # severities
+    "SEVERITY_ERROR",
+    "SEVERITY_WARNING",
+    "SEVERITY_INFO",
+    # risk tiers
+    "RISK_CRITICAL",
+    "RISK_HIGH",
+    "RISK_MEDIUM",
+    "RISK_LOW",
+    # scoring
+    "ERROR_SCORE_CAP",
+    # how the IR was obtained
+    "SOURCE_STATIC",
+    "SOURCE_MANIFEST",
+    "SOURCE_RUNTIME",
+    # helpers
+    "severity_rank",
+    # dataclasses
+    "Diagnostic",
+    "Tool",
+    "Resource",
+    "Prompt",
+    "ServerMeta",
+    "McpServer",
+]
+
+# --- severities --------------------------------------------------------------
+SEVERITY_ERROR = "error"
+SEVERITY_WARNING = "warning"
+SEVERITY_INFO = "info"
+_SEVERITY_RANK = {SEVERITY_ERROR: 3, SEVERITY_WARNING: 2, SEVERITY_INFO: 1}
+
+# --- risk tiers (drive score weighting, mirroring OpenSSF Scorecard) ---------
+# Higher weight = a failing check drags the score down harder.
+RISK_CRITICAL = "critical"
+RISK_HIGH = "high"
+RISK_MEDIUM = "medium"
+RISK_LOW = "low"
+RISK_WEIGHT = {
+    RISK_CRITICAL: 10,
+    RISK_HIGH: 5,
+    RISK_MEDIUM: 2,
+    RISK_LOW: 1,
+}
+
+# A score ceiling applied whenever any ERROR-severity finding exists, so a single
+# critical bug can't be diluted to a green score by clean tooling elsewhere.
+ERROR_SCORE_CAP = 60
+
+SOURCE_STATIC = "static"
+SOURCE_MANIFEST = "manifest"
+SOURCE_RUNTIME = "runtime"  # tools captured by spawning the server (tools/list)
+
+
+def severity_rank(sev: str) -> int:
+    """Higher = more severe. Unknown severities rank below INFO."""
+    return _SEVERITY_RANK.get(sev, 0)
+
+
+@dataclass
+class TextEdit:
+    """A single literal substring replacement (auto-fix machinery).
+
+    ``old`` must occur exactly once in the target file or the edit is skipped —
+    it is never applied ambiguously. Experimental: not part of the stable plugin
+    API (``__all__``) until a second rule emits fixes.
+    """
+
+    old: str
+    new: str
+
+
+@dataclass
+class Fix:
+    """A proposed auto-fix: apply ``edits`` to ``file`` (non-overlapping).
+
+    Experimental plugin surface (pre-stable); see CONTRIBUTING.md → "Plugin API
+    stability". A rule attaches one to :attr:`Diagnostic.fix`.
+    """
+
+    description: str
+    file: str
+    edits: list[TextEdit] = field(default_factory=list)
+
+
+@dataclass
+class Diagnostic:
+    """A single lint finding. Stable ``rule_id``; ``line``/``col`` are 1-indexed."""
+
+    rule_id: str
+    severity: str
+    message: str
+    tool: str | None = None  # name of the offending tool, if any
+    file: str | None = None
+    line: int | None = None
+    col: int | None = None
+    fix: Fix | None = None  # proposed auto-fix, if the rule can produce one
+
+
+@dataclass
+class Tool:
+    """An MCP tool: name + LLM-visible description + JSON Schema for its inputs."""
+
+    name: str
+    description: str | None = None
+    input_schema: dict[str, Any] = field(default_factory=dict)
+    source_path: str | None = None  # file the tool was declared in
+    line: int | None = None  # 1-indexed line of the declaration
+    runtime_only: bool = False  # True when learned from a manifest, not source
+    # Destructured handler parameter names, for MCP105 (schema/impl drift).
+    # ``None`` = undeterminable (bare ``args`` identifier, Python, or a manifest
+    # tool with no source handler) → the rule can't compare and skips.
+    # ``[]``   = the handler explicitly takes no params (``()``).
+    # ``[...]``= the names a destructured ``{a, b}`` handler actually reads.
+    handler_params: list[str] | None = None
+
+
+@dataclass
+class Resource:
+    """An MCP resource (``resources/list``). Analyzed in v0.2."""
+
+    uri: str
+    name: str | None = None
+    description: str | None = None
+    mime_type: str | None = None
+
+
+@dataclass
+class Prompt:
+    """An MCP prompt template (``prompts/list``). Analyzed in v0.2."""
+
+    name: str
+    description: str | None = None
+
+
+@dataclass
+class ServerMeta:
+    """Identity metadata for the server under analysis. All optional."""
+
+    name: str | None = None
+    version: str | None = None
+    language: str | None = None  # "python" | "typescript" | None
+    path: str | None = None  # root path analyzed
+    repo: str | None = None  # optional repo URL
+
+
+@dataclass
+class McpServer:
+    """The universal IR for an MCP server. Extractors emit it; rules read it."""
+
+    meta: ServerMeta
+    tools: list[Tool] = field(default_factory=list)
+    resources: list[Resource] = field(default_factory=list)
+    prompts: list[Prompt] = field(default_factory=list)
+    dependencies: dict[str, str] = field(default_factory=dict)  # name -> spec
+    sources: dict[str, str] = field(default_factory=dict)  # source_path -> text
+    lockfiles: list[str] = field(default_factory=list)  # lockfile basenames found
+    diagnostics: list[Diagnostic] = field(default_factory=list)
+    source_mode: str = SOURCE_STATIC  # how the IR was obtained
+    dep_file: str | None = None  # pyproject.toml/package.json that supplied deps (fix provenance)
+
+    @property
+    def errors(self) -> list[Diagnostic]:
+        return [d for d in self.diagnostics if d.severity == SEVERITY_ERROR]
+
+    @property
+    def has_errors(self) -> bool:
+        return any(d.severity == SEVERITY_ERROR for d in self.diagnostics)

mcpxray/report/__init__.py

@@ -0,0 +1,47 @@
+"""Report formatters: plain, json, github, sarif.
+
+Every formatter shares the signature ``render(diags, doc, score_result) -> str``
+so the CLI can dispatch by name. ``doc`` and ``score_result`` are optional;
+formatters include the score line only when a :class:`~mcpxray.score.ScoreResult`
+is supplied.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mcpxray.report import card as card_fmt
+from mcpxray.report import github as github_fmt
+from mcpxray.report import json as json_fmt
+from mcpxray.report import plain, sarif
+
+if TYPE_CHECKING:
+    from mcpxray.ir import Diagnostic, McpServer
+    from mcpxray.score import ScoreResult
+
+_FORMATTERS = {
+    "plain": plain.render,
+    "json": json_fmt.render,
+    "github": github_fmt.render,
+    "sarif": sarif.render,
+    "card": card_fmt.render,
+}
+
+SUPPORTED_FORMATS = tuple(_FORMATTERS)
+
+
+def render(
+    diags: list[Diagnostic],
+    fmt: str,
+    *,
+    doc: McpServer | None = None,
+    score_result: ScoreResult | None = None,
+) -> str:
+    """Render diagnostics in the requested format."""
+    try:
+        formatter = _FORMATTERS[fmt.lower()]
+    except KeyError as e:
+        raise ValueError(
+            f"unknown format {fmt!r}; choose from {', '.join(SUPPORTED_FORMATS)}"
+        ) from e
+    return formatter(diags, doc, score_result)

mcpxray/report/card.py

@@ -0,0 +1,137 @@
+"""Consumer-facing verdict card — a traffic-light summary, not a raw score.
+
+``render`` shares the standard formatter signature so ``mcpxray scan -f card``
+works for free; ``render_verdict`` is the richer entry point the ``check``
+command uses (it already holds a :class:`~mcpxray.verdict.Verdict` and wants
+``--details`` control).
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+from mcpxray.ir import SOURCE_RUNTIME
+from mcpxray.report import plain as plain_fmt
+from mcpxray.verdict import TIER_CAUTION, TIER_DANGER, TIER_OK, TIER_UNKNOWN, Verdict, verdict
+
+if TYPE_CHECKING:
+    from mcpxray.ir import Diagnostic, McpServer
+    from mcpxray.score import ScoreResult
+
+# (emoji, ascii tag) per tier. The tag embeds the label so the ASCII fallback
+# reads "[DANGER]" while the emoji form renders "🔴 DANGER".
+_GLYPHS = {
+    TIER_OK: ("🟢", "[OK]"),
+    TIER_CAUTION: ("🟡", "[CAUTION]"),
+    TIER_DANGER: ("🔴", "[DANGER]"),
+    TIER_UNKNOWN: ("⚪", "[?]"),
+}
+
+
+def _supports_unicode() -> bool:
+    """True when stdout can render emoji/bullets. Monkeypatchable in tests."""
+    enc = (sys.stdout.encoding or "").lower().replace("-", "").replace("_", "")
+    return "utf8" in enc
+
+
+def _header(v: Verdict) -> str:
+    emoji, tag = _GLYPHS[v.tier]
+    return f"{emoji} {v.tier.upper()}" if _supports_unicode() else tag
+
+
+def _bullet() -> str:
+    return "•" if _supports_unicode() else "-"
+
+
+def _times() -> str:
+    return "×" if _supports_unicode() else "x"
+
+
+def _dash() -> str:
+    return "—" if _supports_unicode() else "-"
+
+
+def _tool_detail(doc: McpServer | None) -> str:
+    """The '(Python, 3 tools)' qualifier for the checked line."""
+    if doc is None:
+        return ""
+    n = len(doc.tools)
+    word = "tool" if n == 1 else "tools"
+    lang = doc.meta.language if doc.meta else None
+    if not lang and getattr(doc, "source_mode", None) == SOURCE_RUNTIME:
+        lang = "runtime"  # tools captured live — not a parsed source language
+    if lang:
+        return f" ({lang}, {n} {word})"
+    if n:
+        return f" ({n} {word})"
+    return ""
+
+
+def _checked_line(v: Verdict, doc: McpServer | None, sr: ScoreResult | None) -> str:
+    name = (doc.meta.name if doc is not None and doc.meta else None) or "server"
+    if v.tier == TIER_UNKNOWN:
+        return f'mcpxray checked "{name}" {_dash()} no MCP tool definitions found.'
+    score_part = f" {_dash()} score {sr.score}/100 ({sr.grade})" if sr is not None else ""
+    return f'mcpxray checked "{name}"{_tool_detail(doc)}{score_part}'
+
+
+def render_verdict(
+    v: Verdict,
+    *,
+    doc: McpServer | None = None,
+    score_result: ScoreResult | None = None,
+    details: bool = False,
+) -> str:
+    """Render a :class:`Verdict` as the human-facing card text."""
+    lines: list[str] = [
+        f"{_header(v)}  {_dash()} {v.headline}",
+        "",
+        _checked_line(v, doc, score_result),
+        "",
+    ]
+
+    if v.tier == TIER_UNKNOWN:
+        lines += [
+            "mcpxray couldn't find tool definitions statically (unsupported",
+            "language, or tools built dynamically at runtime).",
+            "",
+            "To check it anyway:",
+            "  1. Capture its tools/list response to a JSON file, then run:",
+            "       mcpxray check --manifest tools-list.json",
+            "  2. Or spawn it and let mcpxray capture tools/list live:",
+            "       mcpxray check --runtime --command '<launch cmd>'",
+        ]
+    elif v.reasons:
+        lines.append("Why:")
+        width = max(len(r.phrase) for r in v.reasons)
+        for r in v.reasons:
+            lines.append(f"  {_bullet()} {r.phrase.ljust(width)}   {r.rule_id} {_times()}{r.count}")
+    else:
+        lines.append("No issues found.")
+
+    lines += ["", f"Recommendation: {v.recommendation}"]
+
+    if v.tier != TIER_OK and v.reasons and not details:
+        lines += ["", "Pass --details for the full finding list."]
+
+    if details and doc is not None and doc.diagnostics:
+        lines += [
+            "",
+            f"--- full findings ({len(doc.diagnostics)}) ---",
+            plain_fmt.render(doc.diagnostics, doc=doc, score_result=score_result),
+        ]
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render(
+    diags: list[Diagnostic],
+    doc: McpServer | None = None,
+    score_result: ScoreResult | None = None,
+) -> str:
+    """Standard formatter signature — render the card from a server + score."""
+    if doc is None:
+        return plain_fmt.render(diags, doc=doc, score_result=score_result)
+    v = verdict(doc, score_result)
+    return render_verdict(v, doc=doc, score_result=score_result, details=False)

mcpxray/report/github.py

@@ -0,0 +1,35 @@
+"""GitHub Actions annotations (::error / ::warning / ::notice)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mcpxray.ir import SEVERITY_ERROR, SEVERITY_INFO, SEVERITY_WARNING
+
+if TYPE_CHECKING:
+    from mcpxray.ir import Diagnostic, McpServer
+    from mcpxray.score import ScoreResult
+
+_LEVEL = {
+    SEVERITY_ERROR: "error",
+    SEVERITY_WARNING: "warning",
+    SEVERITY_INFO: "notice",
+}
+
+
+def render(
+    diags: list[Diagnostic],
+    doc: McpServer | None = None,
+    score_result: ScoreResult | None = None,
+) -> str:
+    lines: list[str] = []
+    for d in diags:
+        level = _LEVEL.get(d.severity, "warning")
+        loc = ""
+        if d.file:
+            loc = f" file={d.file}"
+            if d.line:
+                loc += f",line={d.line}"
+        message = d.message.replace("\n", " ")
+        lines.append(f"::{level}{loc}::{d.rule_id}: {message}")
+    return "\n".join(lines)

mcpxray/report/json.py

@@ -0,0 +1,50 @@
+"""JSON report (machine-readable)."""
+
+from __future__ import annotations
+
+import json as _json
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mcpxray.ir import Diagnostic, McpServer
+    from mcpxray.score import ScoreResult
+
+
+def render(
+    diags: list[Diagnostic],
+    doc: McpServer | None = None,
+    score_result: ScoreResult | None = None,
+) -> str:
+    summary: dict[str, object] = {}
+    if score_result is not None:
+        summary = {
+            "score": score_result.score,
+            "grade": score_result.grade,
+            "errors": score_result.errors,
+            "warnings": score_result.warnings,
+            "infos": score_result.infos,
+            "capped": score_result.capped,
+        }
+    payload = {
+        "summary": summary,
+        "findings": [
+            {
+                "rule_id": d.rule_id,
+                "severity": d.severity,
+                "message": d.message,
+                "tool": d.tool,
+                "file": d.file,
+                "line": d.line,
+                "col": d.col,
+            }
+            for d in diags
+        ],
+    }
+    if doc is not None:
+        payload["server"] = {
+            "name": doc.meta.name,
+            "language": doc.meta.language,
+            "tools": len(doc.tools),
+            "source_mode": doc.source_mode,
+        }
+    return _json.dumps(payload, indent=2)

mcpxray/report/plain.py

@@ -0,0 +1,35 @@
+"""Human-readable plain-text report."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mcpxray.ir import Diagnostic, McpServer
+    from mcpxray.score import ScoreResult
+
+
+def render(
+    diags: list[Diagnostic],
+    doc: McpServer | None = None,
+    score_result: ScoreResult | None = None,
+) -> str:
+    lines: list[str] = []
+    if score_result is not None:
+        cap = "  [capped by error finding]" if score_result.capped else ""
+        lines.append(f"Score: {score_result.score}/100 (grade {score_result.grade}){cap}")
+        lines.append(
+            f"  {score_result.errors} error(s), "
+            f"{score_result.warnings} warning(s), {score_result.infos} info"
+        )
+    if not diags:
+        lines.append("No findings.")
+        return "\n".join(lines)
+    for d in diags:
+        loc = d.file or ""
+        if d.line:
+            loc = f"{loc}:{d.line}" if loc else f"line {d.line}"
+        loc = f" {loc}" if loc else ""
+        tool = f" [{d.tool}]" if d.tool else ""
+        lines.append(f"{d.rule_id:<7} {d.severity:<8}{loc}{tool}  {d.message}")
+    return "\n".join(lines)