agentcheckup 0.4.0__py3-none-any.whl

agentcheckup/discovery.py

@@ -0,0 +1,206 @@
+"""Find MCP client configs without asking the user where they are.
+
+Every client invented its own filename, its own nesting and its own idea of where
+"user config" lives. The point of ``agentcheckup`` is that you type one word and it
+finds them, so this module is the difference between "a linter" and "a doctor".
+
+Coverage is the whole product here. A client we cannot find is a client we cannot
+diagnose, so the path table below is deliberately explicit rather than clever.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+from .models import ServerConfig
+
+HOME = Path.home()
+
+#: Keys that hold a server map at the top level of a config file.
+SERVER_BLOCKS = ("mcpServers", "servers", "mcp_servers", "context_servers")
+
+#: VS Code extension ids that store MCP servers in globalStorage.
+VSCODE_EXTENSIONS = (
+    ("Cline", "saoudrizwan.claude-dev"),
+    ("Roo Code", "rooveterinaryinc.roo-cline"),
+    ("Kilo Code", "kilocode.kilo-code"),
+)
+
+
+def _appdata() -> Path:
+    return Path(os.environ.get("APPDATA", HOME / "AppData" / "Roaming"))
+
+
+def _platform_app_dir() -> Path:
+    """Where GUI apps keep per-user data on this OS."""
+    if sys.platform == "win32":
+        return _appdata()
+    if sys.platform == "darwin":
+        return HOME / "Library" / "Application Support"
+    return HOME / ".config"
+
+
+def _editor_bases() -> list[tuple[str, Path]]:
+    """VS Code and its forks, which share the globalStorage layout."""
+    root = _platform_app_dir()
+    return [
+        ("VS Code", root / "Code"),
+        ("Cursor", root / "Cursor"),
+        ("VSCodium", root / "VSCodium"),
+        ("Windsurf", root / "Windsurf"),
+    ]
+
+
+def candidate_paths(cwd: Path | None = None) -> list[tuple[str, Path]]:
+    """Every known config location, with a human label. May not exist."""
+    cwd = cwd or Path.cwd()
+    app = _platform_app_dir()
+    out: list[tuple[str, Path]] = []
+
+    # Desktop clients
+    out.append(("Claude Desktop", app / "Claude" / "claude_desktop_config.json"))
+    out.append(("Zed", app / "Zed" / "settings.json"))
+
+    # Editors: per-extension globalStorage
+    for editor, base in _editor_bases():
+        for label, extension in VSCODE_EXTENSIONS:
+            out.append(
+                (
+                    f"{label} ({editor})",
+                    base / "User" / "globalStorage" / extension / "settings" / "cline_mcp_settings.json",
+                )
+            )
+        # VS Code 1.102+ keeps MCP servers under `mcp.servers` in settings.json.
+        out.append((f"{editor} settings", base / "User" / "settings.json"))
+
+    # Cross-platform, user-level
+    out += [
+        ("Claude Code", HOME / ".claude.json"),
+        ("Cursor", HOME / ".cursor" / "mcp.json"),
+        ("Zed (config dir)", HOME / ".config" / "zed" / "settings.json"),
+        ("Codex CLI", HOME / ".codex" / "config.toml"),
+        ("Continue", HOME / ".continue" / "config.json"),
+    ]
+
+    # Project-local
+    out += [
+        ("project .mcp.json", cwd / ".mcp.json"),
+        ("project Cursor", cwd / ".cursor" / "mcp.json"),
+        ("project VS Code", cwd / ".vscode" / "mcp.json"),
+    ]
+
+    return out
+
+
+def discover(cwd: Path | None = None) -> list[tuple[str, Path]]:
+    """Return only the configs that actually exist, deduplicated."""
+    found: list[tuple[str, Path]] = []
+    seen: set[str] = set()
+    for label, path in candidate_paths(cwd):
+        try:
+            key = str(path.resolve()).lower()
+        except OSError:
+            key = str(path).lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        try:
+            if path.is_file():
+                found.append((label, path))
+        except OSError:
+            continue
+    return found
+
+
+def _servers_from_block(block: object, source: str) -> list[ServerConfig]:
+    if not isinstance(block, dict):
+        return []
+    return [
+        ServerConfig.from_raw(name, entry, source=source)
+        for name, entry in block.items()
+        if isinstance(entry, dict)
+    ]
+
+
+def _servers_from_payload(payload: dict, tag: str) -> list[ServerConfig]:
+    """Pull every server map out of one config document.
+
+    Three shapes exist in the wild and all three are load-bearing:
+
+    - top level: ``{"mcpServers": {...}}`` - Claude Desktop, Claude Code, Cursor
+    - nested under ``mcp``: ``{"mcp": {"servers": {...}}}`` - VS Code settings.json
+    - per project: ``{"projects": {"/path": {"mcpServers": {...}}}}`` - Claude Code
+    """
+    servers: list[ServerConfig] = []
+
+    for key in SERVER_BLOCKS:
+        servers.extend(_servers_from_block(payload.get(key), tag))
+
+    mcp = payload.get("mcp")
+    if isinstance(mcp, dict):
+        for key in ("servers", "mcpServers"):
+            servers.extend(_servers_from_block(mcp.get(key), f"{tag} [mcp]"))
+
+    projects = payload.get("projects")
+    if isinstance(projects, dict):
+        for project_path, project in projects.items():
+            if not isinstance(project, dict):
+                continue
+            nested = _servers_from_block(
+                project.get("mcpServers"), f"{tag} :: {project_path}"
+            )
+            # Prefix so two projects exposing the same server name stay distinct.
+            for server in nested:
+                server.name = f"{Path(str(project_path)).name}:{server.name}"
+            servers.extend(nested)
+
+    return servers
+
+
+def _load_json(path: Path, label: str) -> list[ServerConfig]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+        return []
+    if not isinstance(payload, dict):
+        return []
+    return _servers_from_payload(payload, f"{label} ({path})")
+
+
+def _load_toml(path: Path, label: str) -> list[ServerConfig]:
+    """Codex CLI keeps its servers in TOML, not JSON.
+
+    ``tomllib`` is stdlib from 3.11. On 3.10 we skip the file rather than add a
+    dependency - the zero-dependency promise is worth more than this one client.
+    """
+    try:
+        import tomllib
+    except ModuleNotFoundError:
+        return []
+
+    try:
+        payload = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return []
+    if not isinstance(payload, dict):
+        return []
+
+    tag = f"{label} ({path})"
+    servers: list[ServerConfig] = []
+    block = payload.get("mcp_servers") or payload.get("mcpServers")
+    if isinstance(block, dict):
+        for name, entry in block.items():
+            if isinstance(entry, dict):
+                servers.append(ServerConfig.from_raw(name, entry, source=tag))
+    return servers
+
+
+def load_servers(path: Path, label: str = "") -> list[ServerConfig]:
+    """Read servers from one config, whatever format it is in."""
+    label = label or path.name
+    if path.suffix.lower() == ".toml":
+        return _load_toml(path, label)
+    return _load_json(path, label)

agentcheckup/engine.py

@@ -0,0 +1,146 @@
+"""Run rules over a manifest and produce a report object."""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass, field
+
+from . import rules as _rules  # noqa: F401 - side effect: registers rules
+from .conflicts import ToolRef, lint_conflicts
+from .models import Finding, ServerConfig, Severity, Tool, grade_for, score_findings
+from .tokens import manifest_tokens
+
+
+@dataclass
+class Report:
+    findings: list[Finding] = field(default_factory=list)
+    tool_count: int = 0
+    tokens: int = 0
+    source: str = ""
+    kind: str = "tools"
+    server_count: int = 0
+
+    @property
+    def score(self) -> int:
+        return score_findings(self.findings, tool_count=self.tool_count)
+
+    @property
+    def grade(self) -> str:
+        return grade_for(self.score)
+
+    def counts(self) -> dict[str, int]:
+        counter = Counter(f.severity.value for f in self.findings)
+        return {s.value: counter.get(s.value, 0) for s in Severity}
+
+    def sorted_findings(self) -> list[Finding]:
+        return sorted(
+            self.findings,
+            key=lambda f: (-f.severity.rank, f.rule, f.tool or "", f.message),
+        )
+
+    def conflicts(self) -> list[Finding]:
+        """Cross-server findings, reported in their own section."""
+        return [f for f in self.sorted_findings() if f.rule.startswith("AGT2")]
+
+    def risks(self) -> list[Finding]:
+        return [f for f in self.sorted_findings() if not f.rule.startswith("AGT2")]
+
+    def worst(self) -> Severity | None:
+        if not self.findings:
+            return None
+        return max((f.severity for f in self.findings), key=lambda s: s.rank)
+
+    def exceeding(self, threshold: Severity) -> list[Finding]:
+        return [f for f in self.findings if f.severity.rank >= threshold.rank]
+
+
+def _tool_findings(tools: list[Tool]) -> list[Finding]:
+    findings: list[Finding] = []
+
+    # Suite-level: duplicate names make selection non-deterministic.
+    seen: dict[str, int] = {}
+    for tool in tools:
+        seen[tool.name] = seen.get(tool.name, 0) + 1
+    for name, count in seen.items():
+        if name and count > 1:
+            findings.append(
+                Finding(
+                    rule="AGT004",
+                    severity=Severity.ERROR,
+                    message=f"Tool name {name!r} appears {count} times.",
+                    tool=name,
+                    hint="Names must be unique; clients keep only one of them.",
+                )
+            )
+
+    for tool in tools:
+        for rule in _rules.TOOL_RULES:
+            findings.extend(rule.check(tool))
+
+    return findings
+
+
+def _server_findings(servers: list[ServerConfig]) -> list[Finding]:
+    findings: list[Finding] = []
+    for server in servers:
+        for rule in _rules.CONFIG_RULES:
+            findings.extend(rule.check(server))
+    return findings
+
+
+def lint_tools(tools: list[Tool], source: str = "") -> Report:
+    return Report(
+        findings=_tool_findings(tools),
+        tool_count=len(tools),
+        tokens=manifest_tokens(tools),
+        source=source,
+    )
+
+
+def lint_servers(servers: list[ServerConfig], source: str = "") -> Report:
+    return Report(
+        findings=_server_findings(servers),
+        tool_count=len(servers),
+        tokens=0,
+        source=source,
+        kind="config",
+    )
+
+
+def lint_audit(
+    servers: list[ServerConfig],
+    tools_by_server: dict[str, list[Tool]],
+    failures: dict[str, str] | None = None,
+    source: str = "",
+) -> Report:
+    """The full check: config risk + per-server tool quality + cross-server conflicts."""
+    failures = failures or {}
+    findings = _server_findings(servers)
+
+    refs: list[ToolRef] = []
+    for server_name, tools in tools_by_server.items():
+        findings.extend(_tool_findings(tools))
+        refs.extend(ToolRef(server=server_name, tool=tool) for tool in tools)
+
+    findings.extend(lint_conflicts(refs))
+
+    for server_name, reason in sorted(failures.items()):
+        findings.append(
+            Finding(
+                rule="AGT105",
+                severity=Severity.INFO,
+                message=f"Server {server_name!r} did not return a tool list: {reason}",
+                tool=server_name,
+                hint="Check that the command runs standalone; unreachable servers are unaudited.",
+            )
+        )
+
+    all_tools = [tool for tools in tools_by_server.values() for tool in tools]
+    return Report(
+        findings=findings,
+        tool_count=len(all_tools),
+        tokens=manifest_tokens(all_tools),
+        source=source,
+        kind="audit",
+        server_count=len(servers),
+    )

agentcheckup/loader.py

@@ -0,0 +1,214 @@
+"""Load tool manifests from a file or from a live stdio server."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+from .models import ServerConfig, Tool
+
+PROTOCOL_VERSION = "2025-06-18"
+
+
+class LoadError(RuntimeError):
+    """Raised when a manifest cannot be read or parsed."""
+
+
+def tools_from_payload(payload: Any) -> list[Tool]:
+    """Accept every shape people actually have lying around.
+
+    Supported: ``{"tools": [...]}``, a bare list, a JSON-RPC envelope
+    ``{"result": {"tools": [...]}}``, or a full session log with ``messages``.
+    """
+    if isinstance(payload, list):
+        return [Tool.from_raw(item) for item in payload if isinstance(item, dict)]
+
+    if isinstance(payload, dict):
+        for key in ("tools",):
+            value = payload.get(key)
+            if isinstance(value, list):
+                return [Tool.from_raw(item) for item in value if isinstance(item, dict)]
+
+        result = payload.get("result")
+        if isinstance(result, dict) and isinstance(result.get("tools"), list):
+            return [Tool.from_raw(item) for item in result["tools"] if isinstance(item, dict)]
+
+        messages = payload.get("messages")
+        if isinstance(messages, list):
+            collected: list[Tool] = []
+            for msg in messages:
+                if isinstance(msg, dict):
+                    collected.extend(tools_from_payload(msg))
+            return collected
+
+    raise LoadError(
+        "Could not find a tools array. Expected {'tools': [...]}, a JSON-RPC "
+        "'result.tools', or a bare list."
+    )
+
+
+def load_from_file(path: str | Path) -> list[Tool]:
+    file = Path(path)
+    if not file.exists():
+        raise LoadError(f"No such file: {file}")
+    try:
+        payload = json.loads(file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise LoadError(f"{file} is not valid JSON: {exc}") from exc
+    return tools_from_payload(payload)
+
+
+def servers_from_config(path: str | Path) -> list[ServerConfig]:
+    """Read a client config (Claude Desktop, Cursor, VS Code, Cline)."""
+    file = Path(path)
+    if not file.exists():
+        raise LoadError(f"No such file: {file}")
+    try:
+        payload = json.loads(file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise LoadError(f"{file} is not valid JSON: {exc}") from exc
+
+    if not isinstance(payload, dict):
+        raise LoadError(f"{file} does not contain a JSON object.")
+
+    blocks: list[tuple[str, dict]] = []
+    for key in ("mcpServers", "servers", "mcp_servers"):
+        value = payload.get(key)
+        if isinstance(value, dict):
+            blocks.append((key, value))
+
+    if not blocks:
+        raise LoadError(
+            f"{file} has no server block. Expected one of: mcpServers, servers, mcp_servers."
+        )
+
+    servers: list[ServerConfig] = []
+    for key, block in blocks:
+        for name, entry in block.items():
+            if isinstance(entry, dict):
+                servers.append(ServerConfig.from_raw(name, entry, source=f"{file}:{key}"))
+    return servers
+
+
+class StdioSession:
+    """Minimal MCP stdio client: initialize -> tools/list -> close.
+
+    Newline-delimited JSON-RPC, per the MCP stdio transport. No SDK dependency,
+    so this keeps working when the SDK's API moves.
+    """
+
+    def __init__(
+        self,
+        command: str | list[str],
+        timeout: float = 30.0,
+        env: dict[str, str] | None = None,
+    ) -> None:
+        """``command`` may be a shell string or an argv list.
+
+        Prefer the list form: it sidesteps quoting entirely, which matters on
+        Windows where ``shell=True`` re-parses every argument through cmd.exe.
+        """
+        self.command = command
+        self.timeout = timeout
+        self.env = env
+        self._label = command if isinstance(command, str) else " ".join(command)
+
+    def __enter__(self) -> StdioSession:
+        creationflags = 0
+        if sys.platform == "win32":  # keep a stray console from flashing up
+            creationflags = getattr(subprocess, "CREATE_NO_WINDOW", 0)
+
+        child_env = None
+        if self.env:
+            child_env = {**os.environ, **self.env}
+
+        try:
+            self.proc = subprocess.Popen(
+                self.command,
+                shell=isinstance(self.command, str),
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                bufsize=1,
+                creationflags=creationflags,
+                env=child_env,
+            )
+        except OSError as exc:
+            raise LoadError(f"Could not start {self._label!r}: {exc}") from exc
+        return self
+
+    def __exit__(self, *exc_info) -> None:
+        proc = getattr(self, "proc", None)
+        if proc is None:
+            return
+        with contextlib.suppress(OSError, ValueError):
+            if proc.stdin:
+                proc.stdin.close()
+        try:
+            proc.terminate()
+            proc.wait(timeout=5)
+        except Exception:  # noqa: BLE001 - teardown must never mask the real error
+            with contextlib.suppress(Exception):
+                proc.kill()
+
+    def _send(self, message: dict[str, Any]) -> None:
+        assert self.proc.stdin is not None
+        self.proc.stdin.write(json.dumps(message) + "\n")
+        self.proc.stdin.flush()
+
+    def _read_until(self, msg_id: int) -> dict[str, Any]:
+        assert self.proc.stdout is not None
+        while True:
+            line = self.proc.stdout.readline()
+            if not line:
+                stderr = ""
+                if self.proc.stderr:
+                    try:
+                        stderr = self.proc.stderr.read()[:800]
+                    except Exception:  # noqa: BLE001
+                        stderr = ""
+                raise LoadError(
+                    f"Server exited before replying to id={msg_id}. stderr: {stderr.strip() or '(empty)'}"
+                )
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                message = json.loads(line)
+            except json.JSONDecodeError:
+                continue  # servers do log to stdout sometimes
+            if isinstance(message, dict) and message.get("id") == msg_id:
+                if "error" in message:
+                    raise LoadError(f"Server returned an error: {message['error']}")
+                return message
+
+    def list_tools(self) -> list[Tool]:
+        self._send(
+            {
+                "jsonrpc": "2.0",
+                "id": 1,
+                "method": "initialize",
+                "params": {
+                    "protocolVersion": PROTOCOL_VERSION,
+                    "capabilities": {},
+                    "clientInfo": {"name": "agentcheckup", "version": "0.1.0"},
+                },
+            }
+        )
+        self._read_until(1)
+        self._send({"jsonrpc": "2.0", "method": "notifications/initialized"})
+        self._send({"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}})
+        reply = self._read_until(2)
+        result = reply.get("result") or {}
+        tools = result.get("tools") if isinstance(result, dict) else None
+        if not isinstance(tools, list):
+            raise LoadError("Server replied to tools/list without a tools array.")
+        return [Tool.from_raw(item) for item in tools if isinstance(item, dict)]