shadow-mcp 0.1.0__py3-none-any.whl

shadow_mcp/__init__.py

@@ -0,0 +1,9 @@
+"""shadow-mcp: discover and risk-grade the MCP servers present on this machine.
+
+Discovery is strictly read-only: collectors parse configs and list processes,
+and never mutate anything they find. Risk-grading delegates to the existing
+engines (MCPAudit for a 0-10 capability composite, mcp-trust for an A-F danger
+grade) rather than reimplementing them.
+"""
+
+__version__ = "0.1.0"

shadow_mcp/cli.py

@@ -0,0 +1,268 @@
+"""shadow-mcp command line: discover -> inventory -> grade -> report.
+
+    shadow-mcp scan                 full pipeline, rich terminal report
+    shadow-mcp scan --json out.json write the machine-readable inventory
+    shadow-mcp scan --format markdown
+    shadow-mcp discover             inventory only, skip grading
+    shadow-mcp sources              what each collector found, no grading
+
+Discovery is read-only throughout.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import socket
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+
+from .collectors import discover_all
+from .config import DiscoveryPaths, GradingPaths
+from .grading import grade_inventory
+from .inventory import build_inventory
+from .models import GradedServer, RiskAssessment
+from .report import build_report, render_markdown, render_terminal
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).isoformat(timespec="seconds")
+
+
+def _discovery_paths(args: argparse.Namespace) -> DiscoveryPaths:
+    home = Path(args.home).expanduser() if args.home else None
+    return DiscoveryPaths.default(home)
+
+
+def _grading_paths(args: argparse.Namespace) -> GradingPaths:
+    gp = GradingPaths.default()
+    if args.registry_db:
+        gp.mcptrust_registry_db = Path(args.registry_db).expanduser()
+    return gp
+
+
+def _run_pipeline(args: argparse.Namespace, *, grade: bool, only: list[str] | None = None):
+    paths = _discovery_paths(args)
+    result = discover_all(
+        paths,
+        include_processes=not args.no_processes,
+        include_cli=not args.no_cli,
+    )
+    inventory = build_inventory(result.servers)
+    if only:
+        wanted = {n.lower() for n in only}
+        inventory = [
+            e
+            for e in inventory
+            if e.canonical_name.lower() in wanted or any(a.lower() in wanted for a in e.aliases)
+        ]
+    if grade:
+        connect = getattr(args, "connect", False)
+        if connect:
+            print(
+                "warning: --connect spawns each stdio MCP server to enumerate its "
+                "tools. Servers needing real secrets will fail to start and fall "
+                "back to their static grade.",
+                file=sys.stderr,
+            )
+        graded = grade_inventory(
+            inventory,
+            grading_paths=_grading_paths(args),
+            run_mcpaudit=not getattr(args, "no_mcpaudit", False),
+            compute_missing=not getattr(args, "no_compute", False),
+            connect=connect,
+            connect_timeout=getattr(args, "connect_timeout", 8),
+        )
+    else:
+        graded = [
+            GradedServer(
+                entry=e,
+                risk=RiskAssessment(band="unknown", headline="ungraded"),
+            )
+            for e in inventory
+        ]
+    report = build_report(
+        graded,
+        host=socket.gethostname(),
+        generated_at=_now_iso(),
+        source_counts=result.source_counts,
+        errors=result.errors,
+    )
+    return report
+
+
+def _emit(report, args: argparse.Namespace) -> None:
+    if args.json:
+        Path(args.json).write_text(
+            json.dumps(report.model_dump(mode="json"), indent=2), encoding="utf-8"
+        )
+        print(f"wrote {args.json}", file=sys.stderr)
+    fmt = args.format
+    if fmt == "json" and not args.json:
+        print(json.dumps(report.model_dump(mode="json"), indent=2))
+    elif fmt == "markdown":
+        print(render_markdown(report))
+    elif fmt == "terminal":
+        render_terminal(report)
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    report = _run_pipeline(args, grade=True)
+    _emit(report, args)
+    return 0
+
+
+def cmd_discover(args: argparse.Namespace) -> int:
+    report = _run_pipeline(args, grade=False)
+    _emit(report, args)
+    return 0
+
+
+def cmd_deep_scan(args: argparse.Namespace) -> int:
+    """Connect to (spawn) the named servers (or all), enumerate tools, grade."""
+    args.connect = True
+    report = _run_pipeline(args, grade=True, only=args.names or None)
+    _emit(report, args)
+    return 0
+
+
+def cmd_grade_missing(args: argparse.Namespace) -> int:
+    """Show servers the mcp-trust registry had no grade for, with a computed letter."""
+    report = _run_pipeline(args, grade=True)
+    computed = [g for g in report.servers if g.risk.mcptrust and g.risk.mcptrust.computed]
+    in_registry = [
+        g
+        for g in report.servers
+        if g.risk.mcptrust
+        and g.risk.mcptrust.grade not in ("unknown",)
+        and not g.risk.mcptrust.computed
+    ]
+    if args.format == "json":
+        payload = {
+            "computed": [g.model_dump(mode="json") for g in computed],
+            "in_registry": [g.entry.canonical_name for g in in_registry],
+        }
+        print(json.dumps(payload, indent=2))
+        return 0
+    print(
+        f"{len(in_registry)} server(s) graded by the mcp-trust registry; "
+        f"{len(computed)} computed from MCPAudit dimensions via mcp-trust grade():\n"
+    )
+    for g in sorted(computed, key=lambda g: g.risk.mcptrust.grade):
+        e = g.entry
+        print(f"  {g.risk.mcptrust.grade}  {e.canonical_name:28} ({','.join(e.sources)})")
+    return 0
+
+
+def cmd_mcp_serve(args: argparse.Namespace) -> int:
+    """Run shadow-mcp as an MCP server over stdio."""
+    from . import mcp_server
+
+    mcp_server.run()
+    return 0
+
+
+def cmd_sources(args: argparse.Namespace) -> int:
+    paths = _discovery_paths(args)
+    result = discover_all(
+        paths,
+        include_processes=not args.no_processes,
+        include_cli=not args.no_cli,
+    )
+    for source, count in sorted(result.source_counts.items()):
+        print(f"{source:18} {count}")
+    if result.errors:
+        print("\nerrors:")
+        for e in result.errors:
+            print(f"  {e}")
+    return 0
+
+
+def _add_common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--home", help="override $HOME for discovery (testing)")
+    p.add_argument("--no-processes", action="store_true", help="skip live process scan")
+    p.add_argument("--no-cli", action="store_true", help="skip `claude mcp list`")
+    p.add_argument("--json", metavar="PATH", help="write machine-readable inventory JSON")
+    p.add_argument(
+        "--format",
+        choices=["terminal", "json", "markdown"],
+        default="terminal",
+        help="output format (default: terminal)",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="shadow-mcp",
+        description="Discover and risk-grade the MCP servers present on this machine.",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    p_scan = sub.add_parser("scan", help="discover, grade, and report (default)")
+    _add_common(p_scan)
+    p_scan.add_argument("--no-mcpaudit", action="store_true", help="skip MCPAudit grading")
+    p_scan.add_argument("--registry-db", help="path to mcp-trust registry.db")
+    p_scan.add_argument(
+        "--no-compute",
+        action="store_true",
+        help="don't compute a grade for servers the registry hasn't scanned",
+    )
+    p_scan.add_argument(
+        "--connect",
+        action="store_true",
+        help="spawn each stdio server to grade its real tools (opt-in; executes servers)",
+    )
+    p_scan.add_argument(
+        "--connect-timeout", type=int, default=8, help="per-server connect timeout (s)"
+    )
+    p_scan.set_defaults(func=cmd_scan)
+
+    p_disc = sub.add_parser("discover", help="inventory only, no grading")
+    _add_common(p_disc)
+    p_disc.set_defaults(func=cmd_discover)
+
+    p_deep = sub.add_parser(
+        "deep-scan",
+        help="connect to (spawn) named servers (or all), enumerate tools, grade",
+    )
+    _add_common(p_deep)
+    p_deep.add_argument("names", nargs="*", help="server names to connect to (default: all stdio)")
+    p_deep.add_argument("--no-mcpaudit", action="store_true", help="skip MCPAudit grading")
+    p_deep.add_argument("--no-compute", action="store_true", help="skip computed grade fill")
+    p_deep.add_argument("--registry-db", help="path to mcp-trust registry.db")
+    p_deep.add_argument(
+        "--connect-timeout", type=int, default=10, help="per-server connect timeout (s)"
+    )
+    p_deep.set_defaults(func=cmd_deep_scan)
+
+    p_grade = sub.add_parser(
+        "grade-missing",
+        help="grade servers the mcp-trust registry has no scan for, via mcp-trust grade()",
+    )
+    _add_common(p_grade)
+    p_grade.add_argument("--no-mcpaudit", action="store_true", help="skip MCPAudit grading")
+    p_grade.add_argument("--registry-db", help="path to mcp-trust registry.db")
+    p_grade.set_defaults(func=cmd_grade_missing)
+
+    p_src = sub.add_parser("sources", help="per-collector counts")
+    _add_common(p_src)
+    p_src.set_defaults(func=cmd_sources)
+
+    p_mcp = sub.add_parser("mcp-serve", help="run as an MCP server over stdio")
+    p_mcp.set_defaults(func=cmd_mcp_serve)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "command", None):
+        # default to scan with terminal output
+        args = parser.parse_args(["scan", *(argv or [])])
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

shadow_mcp/collectors/__init__.py

@@ -0,0 +1,5 @@
+"""Read-only collectors, one per place an MCP server can be declared or run."""
+
+from .base import DiscoveryResult, discover_all
+
+__all__ = ["DiscoveryResult", "discover_all"]

shadow_mcp/collectors/_common.py

@@ -0,0 +1,120 @@
+"""Shared parsing for the common ``mcpServers`` config shape.
+
+Used by every collector whose source stores servers as a name -> spec map
+(Claude Code, project .mcp.json, Claude Desktop). Codex (TOML), the CLI, the
+DXT manifests, and process discovery have their own shapes.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from ..models import DiscoveredServer, Provenance, ServerSpec, SourceKind, Transport
+
+
+def _resolve_rel(value: str, base_dir: str | None) -> str:
+    """Canonicalize an explicitly-relative path (``./x``, ``../x``) against the
+    config's directory.
+
+    A config that declares ``node ./mcp-server.js`` and the same server seen as an
+    absolute path in the process table would otherwise produce different identity
+    signatures and false-split into a config entry plus a phantom running server.
+    Only ``./`` / ``../`` forms are touched, so package names and flags are left
+    alone.
+    """
+    if base_dir and (value.startswith("./") or value.startswith("../")):
+        return os.path.normpath(os.path.join(base_dir, value))
+    return value
+
+
+def _config_base_dir(location: str) -> str | None:
+    """The filesystem directory a config's relative paths resolve against."""
+    # Claude Code encodes the project dir after '#projects.' (project scope).
+    if "#projects." in location:
+        return location.split("#projects.", 1)[1] or None
+    if "#" in location:  # other synthetic locations have no filesystem base
+        return None
+    return os.path.dirname(location) or None
+
+
+def load_json(path: Path) -> dict[str, Any] | None:
+    """Read + parse a JSON file, returning None on any read/parse failure.
+
+    Read-only and fail-soft: a missing or malformed config must never break
+    discovery.
+    """
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (OSError, ValueError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def infer_spec(raw: dict[str, Any], base_dir: str | None = None) -> ServerSpec:
+    """Normalize one raw server dict into a redacted ServerSpec.
+
+    ``base_dir`` (the config's directory) canonicalizes relative command/script
+    paths so they match the absolute form seen in the process table.
+    """
+    command = raw.get("command")
+    command = _resolve_rel(str(command), base_dir) if command else None
+    args_raw = raw.get("args") or []
+    args = [_resolve_rel(str(a), base_dir) for a in args_raw] if isinstance(args_raw, list) else []
+    url = raw.get("url") or raw.get("serverUrl") or raw.get("endpoint")
+    env = raw.get("env")
+    env_keys = sorted(env.keys()) if isinstance(env, dict) else []
+
+    declared = (raw.get("type") or raw.get("transport") or "").lower()
+    transport: Transport
+    if declared in ("stdio", "http", "sse"):
+        transport = declared  # type: ignore[assignment]
+    elif url and not command:
+        transport = "sse" if "sse" in str(url).lower() else "http"
+    elif command:
+        transport = "stdio"
+    else:
+        transport = "unknown"
+
+    return ServerSpec(
+        transport=transport,
+        command=str(command) if command else None,
+        args=args,
+        url=str(url) if url else None,
+        env_keys=env_keys,
+    )
+
+
+def parse_mcp_servers_block(
+    block: Any,
+    *,
+    source: SourceKind,
+    location: str,
+    scope: str,
+) -> list[DiscoveredServer]:
+    """Turn a ``mcpServers`` map into DiscoveredServer records."""
+    if not isinstance(block, dict):
+        return []
+    base_dir = _config_base_dir(location)
+    out: list[DiscoveredServer] = []
+    for name, raw in block.items():
+        if not isinstance(raw, dict):
+            continue
+        enabled = raw.get("enabled")
+        out.append(
+            DiscoveredServer(
+                name=str(name),
+                spec=infer_spec(raw, base_dir),
+                provenance=Provenance(
+                    source=source,
+                    location=location,
+                    scope=scope,
+                    declared_name=str(name),
+                    enabled=enabled if isinstance(enabled, bool) else None,
+                ),
+            )
+        )
+    return out

shadow_mcp/collectors/base.py

@@ -0,0 +1,72 @@
+"""Discovery orchestration: run every collector, fail-soft, and tally sources.
+
+A single collector raising must never break discovery, so each is wrapped; its
+error is recorded as a note and the sweep continues.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..config import DiscoveryPaths
+from ..models import DiscoveredServer
+from .claude_cli import ClaudeCliCollector
+from .claude_code import ClaudeCodeCollector
+from .claude_desktop import ClaudeDesktopCollector
+from .codex import CodexCollector
+from .dxt import DxtCollector
+from .processes import ProcessCollector
+from .project_mcp import ProjectMcpJsonCollector
+
+
+@dataclass
+class DiscoveryResult:
+    servers: list[DiscoveredServer] = field(default_factory=list)
+    source_counts: dict[str, int] = field(default_factory=dict)
+    errors: list[str] = field(default_factory=list)
+
+
+def default_collectors(
+    paths: DiscoveryPaths,
+    *,
+    include_processes: bool = True,
+    include_cli: bool = True,
+) -> list[object]:
+    collectors: list[object] = [
+        ClaudeCodeCollector(paths),
+        ClaudeDesktopCollector(paths),
+        CodexCollector(paths),
+        DxtCollector(paths),
+        ProjectMcpJsonCollector(paths),
+    ]
+    if include_cli:
+        collectors.append(ClaudeCliCollector())
+    if include_processes:
+        collectors.append(ProcessCollector())
+    return collectors
+
+
+def discover_all(
+    paths: DiscoveryPaths | None = None,
+    *,
+    include_processes: bool = True,
+    include_cli: bool = True,
+    collectors: list[object] | None = None,
+) -> DiscoveryResult:
+    paths = paths or DiscoveryPaths.default()
+    cols = (
+        collectors
+        if collectors is not None
+        else default_collectors(paths, include_processes=include_processes, include_cli=include_cli)
+    )
+    result = DiscoveryResult()
+    for col in cols:
+        source = getattr(col, "source", col.__class__.__name__)
+        try:
+            found = col.collect()  # type: ignore[attr-defined]
+        except Exception as exc:  # a collector must never break the sweep
+            result.errors.append(f"{source}: {type(exc).__name__}: {exc}")
+            continue
+        result.servers.extend(found)
+        result.source_counts[source] = result.source_counts.get(source, 0) + len(found)
+    return result

shadow_mcp/collectors/claude_cli.py

@@ -0,0 +1,100 @@
+"""Collector: ``claude mcp list``.
+
+The CLI roster is the ground truth for Claude Code: it resolves servers that no
+JSON file contains (remote ``claude.ai`` HTTP servers and plugin servers). We
+shell out read-only and parse the line-oriented output tolerantly across CLI
+versions.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from collections.abc import Callable
+
+from ..models import DiscoveredServer, Provenance, ServerSpec, Transport
+
+SOURCE = "claude_cli"
+
+Runner = Callable[[], "tuple[int, str]"]
+
+_URL_RE = re.compile(r"https?://\S+")
+# Trailing status decoration: " - ✓ Connected", " (HTTP)", " - Failed to connect"
+_STATUS_RE = re.compile(r"\s+-\s+.*$")
+
+
+def _default_runner() -> tuple[int, str]:
+    exe = shutil.which("claude")
+    if not exe:
+        return (127, "")
+    try:
+        proc = subprocess.run(
+            [exe, "mcp", "list"],
+            capture_output=True,
+            text=True,
+            timeout=20,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return (1, "")
+    return (proc.returncode, proc.stdout or "")
+
+
+def parse_claude_mcp_list(text: str) -> list[DiscoveredServer]:
+    """Parse ``claude mcp list`` output into DiscoveredServer records."""
+    out: list[DiscoveredServer] = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or ":" not in line:
+            continue
+        name, _, rest = line.partition(":")
+        name = name.strip()
+        rest = rest.strip()
+        if not name or not rest:
+            continue
+        # drop a "- Connected" / "- Failed" status tail and any "(HTTP)" hint
+        had_http_hint = "(http" in rest.lower()
+        rest = _STATUS_RE.sub("", rest).strip()
+        rest = re.sub(r"\((?:HTTP|SSE|STDIO)\)", "", rest, flags=re.IGNORECASE).strip()
+
+        url_match = _URL_RE.search(rest)
+        if url_match:
+            url = url_match.group(0)
+            transport: Transport = "sse" if "sse" in url.lower() else "http"
+            spec = ServerSpec(transport=transport, url=url)
+        else:
+            tokens = rest.split()
+            if not tokens:
+                continue
+            transport = "http" if had_http_hint else "stdio"
+            spec = ServerSpec(
+                transport=transport,
+                command=tokens[0],
+                args=tokens[1:],
+            )
+        out.append(
+            DiscoveredServer(
+                name=name,
+                spec=spec,
+                provenance=Provenance(
+                    source=SOURCE,
+                    location="claude mcp list",
+                    scope="user",
+                    declared_name=name,
+                ),
+            )
+        )
+    return out
+
+
+class ClaudeCliCollector:
+    source = SOURCE
+
+    def __init__(self, runner: Runner | None = None) -> None:
+        self.runner = runner or _default_runner
+
+    def collect(self) -> list[DiscoveredServer]:
+        code, text = self.runner()
+        if code != 0 or not text.strip():
+            return []
+        return parse_claude_mcp_list(text)

shadow_mcp/collectors/claude_code.py

@@ -0,0 +1,43 @@
+"""Collector: Claude Code ``~/.claude.json``.
+
+Two scopes live in this file: top-level ``mcpServers`` (user scope) and
+per-project ``projects.<path>.mcpServers`` (project scope).
+"""
+
+from __future__ import annotations
+
+from ..config import DiscoveryPaths
+from ..models import DiscoveredServer
+from ._common import load_json, parse_mcp_servers_block
+
+SOURCE = "claude_code"
+
+
+class ClaudeCodeCollector:
+    source = SOURCE
+
+    def __init__(self, paths: DiscoveryPaths) -> None:
+        self.paths = paths
+
+    def collect(self) -> list[DiscoveredServer]:
+        data = load_json(self.paths.claude_json)
+        if data is None:
+            return []
+        loc = str(self.paths.claude_json)
+        out = parse_mcp_servers_block(
+            data.get("mcpServers"), source=SOURCE, location=loc, scope="user"
+        )
+        projects = data.get("projects")
+        if isinstance(projects, dict):
+            for proj_path, proj in projects.items():
+                if not isinstance(proj, dict):
+                    continue
+                out.extend(
+                    parse_mcp_servers_block(
+                        proj.get("mcpServers"),
+                        source=SOURCE,
+                        location=f"{loc}#projects.{proj_path}",
+                        scope="project",
+                    )
+                )
+        return out

shadow_mcp/collectors/claude_desktop.py

@@ -0,0 +1,27 @@
+"""Collector: Claude Desktop ``claude_desktop_config.json``."""
+
+from __future__ import annotations
+
+from ..config import DiscoveryPaths
+from ..models import DiscoveredServer
+from ._common import load_json, parse_mcp_servers_block
+
+SOURCE = "claude_desktop"
+
+
+class ClaudeDesktopCollector:
+    source = SOURCE
+
+    def __init__(self, paths: DiscoveryPaths) -> None:
+        self.paths = paths
+
+    def collect(self) -> list[DiscoveredServer]:
+        data = load_json(self.paths.claude_desktop_config)
+        if data is None:
+            return []
+        return parse_mcp_servers_block(
+            data.get("mcpServers"),
+            source=SOURCE,
+            location=str(self.paths.claude_desktop_config),
+            scope="desktop",
+        )