agentcheckup 0.4.0__py3-none-any.whl

agentcheckup/rules/schema.py

@@ -0,0 +1,143 @@
+"""Input schema rules.
+
+The schema is the contract. A loose contract does not fail loudly - it produces
+a plausible-looking wrong call, which is far more expensive to debug.
+"""
+
+from __future__ import annotations
+
+from ..models import Finding, Severity, Tool
+from .base import tool_rule
+
+#: Verbs that imply unbounded input size.
+UNBOUNDED_HINTS = ("query", "sql", "text", "content", "body", "data", "html", "code")
+
+
+@tool_rule("AGT020", Severity.ERROR, "inputSchema is not an object schema")
+def schema_not_object(tool: Tool):
+    """MCP requires ``{"type": "object", ...}``.
+
+    Providers that emit ``{"type": "array"}`` or omit ``type`` break client-side
+    validation in strict implementations.
+    """
+    schema = tool.input_schema
+    if not schema:
+        return Finding(
+            rule="AGT020",
+            severity=Severity.ERROR,
+            message=f"Tool {tool.name!r} has no inputSchema.",
+            tool=tool.name,
+            hint='Use {"type": "object", "properties": {}} for a no-argument tool.',
+        )
+    if schema.get("type") != "object":
+        return Finding(
+            rule="AGT020",
+            severity=Severity.ERROR,
+            message=f"Tool {tool.name!r} inputSchema type is {schema.get('type')!r}, expected 'object'.",
+            tool=tool.name,
+            hint="MCP tool arguments are always a JSON object.",
+        )
+    return None
+
+
+@tool_rule("AGT021", Severity.WARNING, "Required references an undeclared property")
+def required_unknown(tool: Tool):
+    """A dangling ``required`` entry makes every call fail validation client-side."""
+    props = tool.properties()
+    unknown = [r for r in tool.required() if r not in props]
+    if unknown:
+        return Finding(
+            rule="AGT021",
+            severity=Severity.WARNING,
+            message=f"Tool {tool.name!r} requires undeclared property/properties: {', '.join(unknown)}.",
+            tool=tool.name,
+            hint="Every name in `required` must exist under `properties`.",
+        )
+    return None
+
+
+@tool_rule("AGT022", Severity.INFO, "Schema allows undeclared properties")
+def additional_properties_open(tool: Tool):
+    """Models happily invent extra keys when the schema permits it.
+
+    ``additionalProperties: false`` turns a silent wrong-argument bug into a
+    visible validation error.
+    """
+    if tool.input_schema and tool.input_schema.get("additionalProperties") is not False:
+        return Finding(
+            rule="AGT022",
+            severity=Severity.INFO,
+            message=f"Tool {tool.name!r} schema does not set additionalProperties: false.",
+            tool=tool.name,
+            hint="Closing the schema stops the model from inventing extra keys.",
+        )
+    return None
+
+
+@tool_rule("AGT023", Severity.INFO, "Parameter has no enum or format constraint")
+def unconstrained_string(tool: Tool):
+    """Free-form strings are the main source of retry loops.
+
+    A ``format`` (date-time, uri, email) or an ``enum`` costs one line and
+    removes an entire failure class.
+    """
+    offenders: list[str] = []
+    for name, spec in tool.properties().items():
+        if not isinstance(spec, dict):
+            continue
+        if spec.get("type") != "string":
+            continue
+        if not any(k in spec for k in ("enum", "format", "pattern", "const")):
+            offenders.append(name)
+    if offenders:
+        preview = ", ".join(sorted(offenders)[:5])
+        more = "" if len(offenders) <= 5 else f" (+{len(offenders) - 5} more)"
+        return Finding(
+            rule="AGT023",
+            severity=Severity.INFO,
+            message=f"Tool {tool.name!r} has unconstrained string param(s): {preview}{more}.",
+            tool=tool.name,
+            hint="Add `enum`, `format` or `pattern` where the value space is finite.",
+        )
+    return None
+
+
+@tool_rule("AGT024", Severity.INFO, "Array parameter has no size bound")
+def unbounded_array(tool: Tool):
+    """Without ``maxItems`` a single call can blow the context window."""
+    offenders = [
+        name
+        for name, spec in tool.properties().items()
+        if isinstance(spec, dict)
+        and spec.get("type") == "array"
+        and "maxItems" not in spec
+    ]
+    if offenders:
+        return Finding(
+            rule="AGT024",
+            severity=Severity.INFO,
+            message=f"Tool {tool.name!r} array param(s) without maxItems: {', '.join(sorted(offenders)[:5])}.",
+            tool=tool.name,
+            hint="Set `maxItems` and document the cap in the description.",
+        )
+    return None
+
+
+@tool_rule("AGT025", Severity.WARNING, "Parameter name is ambiguous")
+def ambiguous_param_name(tool: Tool):
+    """`data`, `value`, `arg`, `input`, `options` tell the model nothing.
+
+    The model has to infer the expected shape from the type alone, which is
+    exactly where hallucinated payloads come from.
+    """
+    vague = {"data", "value", "arg", "args", "input", "param", "options", "obj", "thing"}
+    hits = [n for n in tool.properties() if n.lower() in vague]
+    if hits:
+        return Finding(
+            rule="AGT025",
+            severity=Severity.WARNING,
+            message=f"Tool {tool.name!r} has ambiguous param name(s): {', '.join(sorted(hits))}.",
+            tool=tool.name,
+            hint="Name the payload for what it is: `markdown_body`, `filter_expression`.",
+        )
+    return None

agentcheckup/tokens.py

@@ -0,0 +1,69 @@
+"""Rough token estimation with no tokenizer dependency.
+
+Why not tiktoken: it ships native wheels per platform and pulls a network
+download at first use. For a linter that runs in CI on arbitrary machines that
+is a bad trade. The heuristic below is intentionally conservative and is
+documented as an estimate everywhere it surfaces.
+
+Calibration: OpenAI's cl100k / o200k families average ~4 characters per token
+for English prose and ~1 token per CJK character. JSON punctuation is denser
+than prose, so we apply a slight structural discount.
+"""
+
+from __future__ import annotations
+
+import json
+import unicodedata
+from typing import Any
+
+_CJK_RANGES = (
+    (0x3040, 0x30FF),  # kana
+    (0x3400, 0x4DBF),  # CJK ext A
+    (0x4E00, 0x9FFF),  # CJK unified
+    (0xAC00, 0xD7AF),  # hangul
+    (0xF900, 0xFAFF),  # CJK compat
+    (0xFF00, 0xFFEF),  # fullwidth forms
+)
+
+
+def _is_cjk(ch: str) -> bool:
+    cp = ord(ch)
+    return any(lo <= cp <= hi for lo, hi in _CJK_RANGES)
+
+
+def estimate_tokens(text: str) -> int:
+    """Estimate token count for a string."""
+    if not text:
+        return 0
+    cjk = 0
+    other = 0
+    for ch in text:
+        if _is_cjk(ch):
+            cjk += 1
+        else:
+            other += 1
+    return cjk + max(1, round(other / 4)) if other else cjk
+
+
+def estimate_json_tokens(payload: Any) -> int:
+    """Estimate tokens for a JSON-serialisable structure."""
+    dumped = json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+    return estimate_tokens(dumped)
+
+
+def manifest_tokens(tools: list[Any]) -> int:
+    """Estimate how many tokens the whole tool manifest costs in context.
+
+    This is the number an agent pays on *every* request, so it matters more
+    than any single description.
+    """
+    return estimate_json_tokens([t.raw if hasattr(t, "raw") else t for t in tools])
+
+
+def has_invisible_chars(text: str) -> list[str]:
+    """Return code points of characters that hide text from human review."""
+    suspects: list[str] = []
+    for ch in text:
+        if ch in ("\u200b", "\u200c", "\u200d", "\u2060", "\ufeff") or unicodedata.category(ch) == "Cf":
+            suspects.append(f"U+{ord(ch):04X}")
+    return sorted(set(suspects))

agentcheckup-0.4.0.dist-info/METADATA

@@ -0,0 +1,261 @@
+Metadata-Version: 2.5
+Name: agentcheckup
+Version: 0.4.0
+Summary: Diagnose your agent setup: tool conflicts, risky config, context budget.
+Project-URL: Homepage, https://github.com/wanjiaqing/agentcheckup
+Project-URL: Issues, https://github.com/wanjiaqing/agentcheckup/issues
+Project-URL: Changelog, https://github.com/wanjiaqing/agentcheckup/blob/main/CHANGELOG.md
+Author: wanjiaqing
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,cli,linter,mcp,model-context-protocol,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentcheckup
+
+> Diagnose your agent setup before your agent does.
+
+[![CI](https://github.com/wanjiaqing/agentcheckup/actions/workflows/ci.yml/badge.svg)](https://github.com/wanjiaqing/agentcheckup/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/agentcheckup.svg)](https://pypi.org/project/agentcheckup/)
+[![Python](https://img.shields.io/pypi/pyversions/agentcheckup.svg)](https://pypi.org/project/agentcheckup/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Every other MCP tool looks at **one server**. None of them look at what happens
+when you load five.
+
+```console
+$ agentcheckup
+
+agentcheckup 0.4.0  |  3 server(s)  |  4 tool(s)  |  ~442 tokens per request
+
+  Grade C    Score  79/100   1 error  2 warning  1 info
+
+  CONFLICTS (1)
+    AGT201  Tool name 'read_file' is exposed by both 'files' and 'git'.
+            [files/read_file <-> git/read_file]
+            fix: Hard collision: the client keeps one and the other is
+                 unreachable. Rename one, or use a gateway that prefixes.
+
+  RISKS (2)
+    AGT101  Server 'github' runs unpinned npx package
+            '@modelcontextprotocol/server-github'.
+    AGT107  Server 'github' stores credential(s) inline:
+            GITHUB_PERSONAL_ACCESS_TOKEN.
+
+  NUDGES (1 across 1 rule(s), no score impact)
+    AGT105  Server did not return a tool list  (1)
+            github
+```
+
+## The problem nobody is testing for
+
+Two servers cannot see each other. Your model can. It gets a flat list of 47
+tools from five servers and picks by description similarity — with no way to know
+that `files.read_file` and `git.read_file` are different things.
+
+Three failure modes follow, and no existing tool catches them:
+
+**1. Hard collision.** Two servers expose the same tool name. The client keeps
+one, the other is silently unreachable. You spend an afternoon debugging "why
+won't it read the file" when the answer is "it's calling the other one".
+
+**2. Soft collision.** `github.search` and `docs.search` with 70% overlapping
+descriptions. Selection becomes a coin flip that looks exactly like model
+flakiness. It isn't — it's your manifest.
+
+**3. Context tax.** An agent pays for the full tool manifest on **every** request.
+47 tools with 200-character descriptions is thousands of tokens before the user
+says anything. Nobody budgets for it because nobody measures it.
+
+`agentcheckup` measures all three, in one command, from the configs you already
+have.
+
+## What it checks
+
+| Layer | Question it answers | Rules |
+|---|---|---|
+| **Conflicts** | Will my agent pick the wrong tool? | AGT201–AGT203 |
+| **Risks** | Is my setup unsafe? | AGT001–AGT107 |
+| **Budget** | What does my manifest cost per request? | reported on every run |
+
+36 rules in total. Full reference: [docs/rules.md](docs/rules.md).
+
+## Install
+
+```bash
+pip install agentcheckup
+# or run without installing
+uvx agentcheckup
+```
+
+Python 3.10+. **Zero runtime dependencies** — no SDK, no tokenizer, no embeddings,
+no network calls. It reads JSON, starts processes, prints text.
+
+## Usage
+
+### One command, no arguments
+
+```bash
+agentcheckup
+```
+
+Finds your configs automatically — 27 known locations across Claude Desktop,
+Claude Code (including its per-project `mcpServers`), Cursor, VS Code, Cline,
+Roo Code, Kilo Code, Windsurf, Zed, Codex CLI and Continue, plus project-local
+`.mcp.json` / `.cursor/mcp.json` / `.vscode/mcp.json` — starts each server,
+collects its tools, and reports.
+
+Servers that fail to start are reported as `AGT105` and skipped, not fatal. A
+broken server should not stop you auditing the other four.
+
+### Common flags
+
+```bash
+agentcheckup --no-spawn          # configs only, no processes started
+agentcheckup --config path.json  # add a config the discovery missed
+agentcheckup --no-discover       # audit only what you passed with --config
+agentcheckup --timeout 40        # slow server? give it longer
+agentcheckup --format json       # machine-readable
+agentcheckup --fail-on warning   # CI gate
+```
+
+### One server at a time
+
+```bash
+agentcheckup scan tools.json                    # {"tools": [...]}, {"result": {...}} or a log
+agentcheckup scan --cmd "python my_server.py"   # live stdio handshake
+agentcheckup config ~/.claude.json              # config rules only
+agentcheckup rules                              # list every rule
+```
+
+### As a GitHub Action
+
+The fastest way to keep a manifest from regressing, and the version you pin is
+the version you run — the action installs from its own checkout.
+
+```yaml
+- uses: wanjiaqing/agentcheckup@v0.3.0
+  with:
+    config: .mcp.json
+    fail-on: warning
+```
+
+Full reference, including SARIF upload and score gates: [docs/github-action.md](docs/github-action.md).
+
+### Raw CLI in CI
+
+```yaml
+- name: Diagnose agent setup
+  run: |
+    pip install agentcheckup
+    agentcheckup --no-spawn --fail-on warning
+```
+
+For GitHub code scanning, emit SARIF:
+
+```yaml
+- run: agentcheckup --format sarif --fail-on never > agentcheckup.sarif
+- uses: github/codeql-action/upload-sarif@v4
+  with:
+    sarif_file: agentcheckup.sarif
+```
+
+One run can produce all three outputs:
+
+```bash
+agentcheckup --format text --json-out report.json --sarif-out report.sarif
+```
+
+Exit codes: `0` clean, `1` findings at or above `--fail-on`, `2` usage/load error.
+
+## How conflicts are detected
+
+No embeddings, no model, no network — because a linter that needs a 200MB wheel
+is a linter that stops running on a plane.
+
+Each tool pair across servers is scored on two signals:
+
+- **name overlap** — normalised token Jaccard (`read_files` ≡ `read_file`)
+- **description overlap** — token Jaccard over stopword-stripped, plural-stemmed words
+
+A pair is flagged when the descriptions overlap ≥ 65% **and** the names share a
+head noun, or when the blended score clears 0.55. The shared-noun requirement is
+what keeps `search_repositories` and `search_documents` apart — without it the
+false-positive rate made the report untrustworthy, which is worse than no report.
+
+It is a heuristic, and the docs say so. `AGT203` is a warning, not a verdict.
+
+## How the score works
+
+Most linters fail here: a rule that fires on 18 of 18 tools is a *preference*,
+not a defect, and charging one point each scores the official MCP servers 0/100.
+That number is useless, so the model is calibrated instead of invented:
+
+| Severity | Cost | Why |
+|---|---|---|
+| `error` | 10 | breaks a run, or endangers the host |
+| `warning` | 3 | likely to cause wrong behaviour |
+| `info` | 1, **capped at 10 total** | a human should decide |
+
+Budget is **20 points per tool**, so a 200-tool manifest is not punished for
+being large, and a 4-tool manifest with one hard collision is not let off easy.
+
+Calibration against four real inputs:
+
+| Input | Tools | Result |
+|---|---|---|
+| Clean fixture | 2 | A · 100 |
+| Official `fetch` + `git` + `time` servers | 18 | B · 87 |
+| Hard collision + unpinned package + plaintext token | 4 | C · 79 |
+| Deliberately broken fixture | 7 | F · 36 |
+
+Repeated findings are collapsed: 12 tools missing parameter descriptions print
+as one line naming all twelve, and info findings are summarised one line per
+rule. A report nobody can read is a report nobody acts on.
+
+## Design principles
+
+- **Zero runtime dependencies.** A diagnostic that breaks because a transitive
+  dep broke is worse than no diagnostic.
+- **Stable rule IDs.** `AGT201` never changes meaning. Suppressions and CI
+  thresholds keep working across releases.
+- **Every finding has a fix.** A rule that only says "this is bad" trains people
+  to ignore the output.
+- **Degrade, don't die.** A server that will not start is one finding, not an
+  aborted run.
+- **No network calls, ever.** Your config never leaves the machine. This is the
+  one thing a commercial scanner structurally cannot promise.
+- **Heuristics are labelled as heuristics.** `info` means "a human should
+  decide". The score is a conversation starter, not a certification.
+
+## What this is not
+
+- Not a sandbox. It tells you the manifest looks risky; it cannot stop the server.
+- Not a runtime guard. Nothing here runs during an agent session.
+- Not an MCP protocol validator. It checks quality and safety, not conformance —
+  the official `modelcontextprotocol/conformance` suite does that.
+
+## Contributing
+
+Adding a rule takes about ten minutes and one small file — see
+[CONTRIBUTING.md](CONTRIBUTING.md). Rules and client adapters are the whole point
+of this project, so those PRs are the most welcome kind.
+
+## License
+
+MIT

agentcheckup-0.4.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+agentcheckup/__init__.py,sha256=7I4aeGtWdYsj3cMwvyxRw6oBYNaUqE2ej7LrGOdwqs0,664
+agentcheckup/__main__.py,sha256=UP0yjf5bUzmplYRElA6c5FuXZNu3sTDMJfOpZsy3Bqg,115
+agentcheckup/cli.py,sha256=e-gEeRx3uu4IXCs64-MaCP7vVfqwgXcNAmJk9PCTolU,8322
+agentcheckup/conflicts.py,sha256=60Q4r5NV1O6Bh-JDAkiNXj2RhNBDhIb8HWeJD9-_BTA,8683
+agentcheckup/discovery.py,sha256=S6kz4FndIydQYcW-Ttyfer8nhidD_NRX3fmw2DokEew,6906
+agentcheckup/engine.py,sha256=MzppSFmp4REQ4jMZYlTrula7eYjNcX8hYQvGI-6NvEk,4625
+agentcheckup/loader.py,sha256=zVxkyWdW9sW1aP9EMSKRKhnLAKb-v3kEqYlxZMuQ3ts,7584
+agentcheckup/models.py,sha256=YzaDPYKTwXPqVtAnSZSp_cAaGLIwKouM_P__R9ZIJZU,5066
+agentcheckup/report.py,sha256=vykhYz_oVQwScRXk-95Ae51jtKON-ZdpuGFmW7BDPd8,9733
+agentcheckup/tokens.py,sha256=BEAWi0iF4CP2BQRjGO3ozIiauMUosJ-OYBu0807wFkE,2190
+agentcheckup/rules/__init__.py,sha256=9N49niQgWcrVUWhrqnDS2KTI8y7T0LwYf7QXdUMlLlE,371
+agentcheckup/rules/base.py,sha256=i3lZ6EutpHKTTlunHeEQ6uV1AefRTMsM6yPBpameAZw,2567
+agentcheckup/rules/config_rules.py,sha256=wpvh6_Exd2srAWr13hnZGTlrtRTBz5wwfpOE_TCVE3g,6537
+agentcheckup/rules/docs.py,sha256=g1cVvz99y87nNYd_qWtsfHZpwELohAf-VXEOCyhR0zI,4434
+agentcheckup/rules/injection.py,sha256=pRvDDff2zZAWeHE1NTh1zmMM36bTI8a9pgnoAJcZuow,5330
+agentcheckup/rules/naming.py,sha256=c9bPgbqmojNVYo1jR7AQ8w9ns0spox6fWt-eBB-qg0Y,3315
+agentcheckup/rules/safety.py,sha256=PTodMfCSvIAkDdqAMQc-Y_ZVxVm1JwxxRzQjCOCW83E,4947
+agentcheckup/rules/schema.py,sha256=b3Ft-DxbKPMJA1eVQwmQ8B5O7I5DqaM0UDRDp1Rn2ks,5374
+agentcheckup-0.4.0.dist-info/METADATA,sha256=VDSo_e-pv-ps7U4QQ-gf0lII75XtA5JyECcvqw0swiU,9702
+agentcheckup-0.4.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+agentcheckup-0.4.0.dist-info/entry_points.txt,sha256=OlI4_uXpibTwRdGpYauao_fpFZ0ddNXq-jnMgROTiHY,55
+agentcheckup-0.4.0.dist-info/licenses/LICENSE,sha256=wPwTNSFI27eV7y5LmMjg1J2GZaOVrpyC5AQB1-6H46o,1067
+agentcheckup-0.4.0.dist-info/RECORD,,

agentcheckup-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentcheckup-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentcheckup = agentcheckup.cli:main

agentcheckup-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wanjiaqing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.