crapkit 0.4.12__tar.gz → 0.4.14__tar.gz

{crapkit-0.4.12/src/crapkit.egg-info → crapkit-0.4.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crapkit
-Version: 0.4.12
+Version: 0.4.14
 Summary: Scores every function on complexity times uncovered risk, ranks the worst, and blocks commits that add more.
 Author: Jean-Francois Gagne
 License: MIT
@@ -39,10 +39,13 @@ Dynamic: license-file
 
 # crapkit
 
+<!-- mcp-name: io.github.jeanfrancoisgagne/crapkit -->
+
 [![ci](https://github.com/JeanFrancoisGagne/crapkit/actions/workflows/ci.yml/badge.svg)](https://github.com/JeanFrancoisGagne/crapkit/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/crapkit)](https://pypi.org/project/crapkit/)
 [![Python](https://img.shields.io/pypi/pyversions/crapkit)](https://pypi.org/project/crapkit/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/JeanFrancoisGagne/crapkit/blob/main/LICENSE)
+[![crapkit MCP server](https://glama.ai/mcp/servers/JeanFrancoisGagne/crapkit/badges/score.svg)](https://glama.ai/mcp/servers/JeanFrancoisGagne/crapkit)
 
 ![crapkit init, coverage and worklist --top 5 on a small Python repo, then a shell heredoc adding a function at ccn 7: the per-edit advisory reports it and exits 2, and the commit gate refuses the staged file with exit 6](https://raw.githubusercontent.com/JeanFrancoisGagne/crapkit/main/docs/demo.gif)
 
@@ -165,7 +168,7 @@ leaves the box
 
 ```
 $ crapkit --version
-crapkit 0.4.12
+crapkit 0.4.14
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -395,7 +398,7 @@ crapkit ships a `.pre-commit-hooks.yaml` declaring `id: crapkit-gate`. In your
 repos:
   - repo: https://github.com/JeanFrancoisGagne/crapkit
     # crapkit's release step rewrites this line to the tag it just cut
-    rev: v0.4.12
+    rev: v0.4.14
     hooks:
       - id: crapkit-gate
 ```
@@ -501,7 +504,7 @@ to a workflow, and every input has a default:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: JeanFrancoisGagne/crapkit@v0.4.12
+      - uses: JeanFrancoisGagne/crapkit@v0.4.14
 ```
 
 The whole job those four lines sit in:
@@ -521,7 +524,7 @@ jobs:
         with:
           python-version: "3.12"       # the interpreter the install below lands in
       - run: pip install -e ".[dev]"   # whatever your lanes need to run
-      - uses: JeanFrancoisGagne/crapkit@v0.4.12
+      - uses: JeanFrancoisGagne/crapkit@v0.4.14
         with:
           gate: "false"
 ```
@@ -1189,6 +1192,7 @@ that block is advisory unless `diff_uncovered_max` is set
 | [docs/lanes.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/lanes.md) | The lane model, vitest and jest and pytest recipes, artifact reuse, flake retest, containers. |
 | [docs/ratchet.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/ratchet.md) | Seeding, pruning, the git merge driver, metric stamps, debt policy, overrides. |
 | [docs/agent-json.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/agent-json.md) | The machine surface: `schema`, every payload field, real captured examples. |
+| [docs/comparison.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/comparison.md) | Where crapkit sits next to radon, xenon, wily, coverage.py and SonarQube, and how they run together. |
 | [AGENTS.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/AGENTS.md) | The burn-down loop an agent runs, and the rules for changing crapkit itself. |
 | [plugin/](https://github.com/JeanFrancoisGagne/crapkit/tree/main/plugin) | The Claude Code plugin: three skills, the read-side MCP server, and the advisory PostToolUse hook. |
 

{crapkit-0.4.12 → crapkit-0.4.14}/README.md

@@ -1,9 +1,12 @@
 # crapkit
 
+<!-- mcp-name: io.github.jeanfrancoisgagne/crapkit -->
+
 [![ci](https://github.com/JeanFrancoisGagne/crapkit/actions/workflows/ci.yml/badge.svg)](https://github.com/JeanFrancoisGagne/crapkit/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/crapkit)](https://pypi.org/project/crapkit/)
 [![Python](https://img.shields.io/pypi/pyversions/crapkit)](https://pypi.org/project/crapkit/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/JeanFrancoisGagne/crapkit/blob/main/LICENSE)
+[![crapkit MCP server](https://glama.ai/mcp/servers/JeanFrancoisGagne/crapkit/badges/score.svg)](https://glama.ai/mcp/servers/JeanFrancoisGagne/crapkit)
 
 ![crapkit init, coverage and worklist --top 5 on a small Python repo, then a shell heredoc adding a function at ccn 7: the per-edit advisory reports it and exits 2, and the commit gate refuses the staged file with exit 6](https://raw.githubusercontent.com/JeanFrancoisGagne/crapkit/main/docs/demo.gif)
 
@@ -126,7 +129,7 @@ leaves the box
 
 ```
 $ crapkit --version
-crapkit 0.4.12
+crapkit 0.4.14
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -356,7 +359,7 @@ crapkit ships a `.pre-commit-hooks.yaml` declaring `id: crapkit-gate`. In your
 repos:
   - repo: https://github.com/JeanFrancoisGagne/crapkit
     # crapkit's release step rewrites this line to the tag it just cut
-    rev: v0.4.12
+    rev: v0.4.14
     hooks:
       - id: crapkit-gate
 ```
@@ -462,7 +465,7 @@ to a workflow, and every input has a default:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: JeanFrancoisGagne/crapkit@v0.4.12
+      - uses: JeanFrancoisGagne/crapkit@v0.4.14
 ```
 
 The whole job those four lines sit in:
@@ -482,7 +485,7 @@ jobs:
         with:
           python-version: "3.12"       # the interpreter the install below lands in
       - run: pip install -e ".[dev]"   # whatever your lanes need to run
-      - uses: JeanFrancoisGagne/crapkit@v0.4.12
+      - uses: JeanFrancoisGagne/crapkit@v0.4.14
         with:
           gate: "false"
 ```
@@ -1150,6 +1153,7 @@ that block is advisory unless `diff_uncovered_max` is set
 | [docs/lanes.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/lanes.md) | The lane model, vitest and jest and pytest recipes, artifact reuse, flake retest, containers. |
 | [docs/ratchet.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/ratchet.md) | Seeding, pruning, the git merge driver, metric stamps, debt policy, overrides. |
 | [docs/agent-json.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/agent-json.md) | The machine surface: `schema`, every payload field, real captured examples. |
+| [docs/comparison.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/comparison.md) | Where crapkit sits next to radon, xenon, wily, coverage.py and SonarQube, and how they run together. |
 | [AGENTS.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/AGENTS.md) | The burn-down loop an agent runs, and the rules for changing crapkit itself. |
 | [plugin/](https://github.com/JeanFrancoisGagne/crapkit/tree/main/plugin) | The Claude Code plugin: three skills, the read-side MCP server, and the advisory PostToolUse hook. |
 

{crapkit-0.4.12 → crapkit-0.4.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "crapkit"
-version = "0.4.12"
+version = "0.4.14"
 description = "Scores every function on complexity times uncovered risk, ranks the worst, and blocks commits that add more."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { text = "MIT" }

{crapkit-0.4.12 → crapkit-0.4.14}/src/crapkit/__init__.py

@@ -1,2 +1,2 @@
 """crapkit: deterministic CRAP-score framework."""
-__version__ = "0.4.12"
+__version__ = "0.4.14"

{crapkit-0.4.12 → crapkit-0.4.14}/src/crapkit/mcp_server.py

@@ -13,9 +13,13 @@ from pathlib import Path
 
 from .invocation import _self
 
-PROTOCOL_VERSION = "2024-11-05"
+# Newest first. Everything this server does — tools, annotations, structured
+# results over stdio — is inside the 2025-06-18 revision, and nothing it does
+# was removed from the older two, so any of the three can be spoken verbatim.
+SUPPORTED_PROTOCOLS = ("2025-06-18", "2025-03-26", "2024-11-05")
 
-_REPO = {"repo": {"type": "string", "description": "repo root (default: the server's)"}}
+_REPO = {"repo": {"type": "string", "description": (
+    "path to the scored repo's root (default: the repo the server was started in)")}}
 
 # brief and explain resolve NAME by one rule, so they describe it with one
 # string. The bare identifier is the long name's leading token, which is all
@@ -28,45 +32,80 @@ _NAME_DESCRIPTION = ("the bare identifier (classify, or route for a Rust "
 TOOLS: tuple[dict, ...] = (
     {"name": "next_item", "argv": ["next-item"], "json_flag": False, "positional": (),
      "flags": {"top": "--top", "exclude": "--exclude"},
-     "description": "The highest-risk function(s) to refactor next, with scores and effort estimates",
-     "properties": {"top": {"type": "integer"}, "exclude": {"type": "array", "items": {"type": "string"}}}},
+     "description": "The highest-risk function to refactor next, as one work packet: score, "
+                    "uncovered lines, effort estimate and the commands that verify the fix. "
+                    "Reach for it when you want one item to act on; worklist is the same "
+                    "ranking as a survey.",
+     "properties": {"top": {"type": "integer",
+                            "description": "return the next N packets instead of one (>= 1, default 1)"},
+                    "exclude": {"type": "array", "items": {"type": "string"},
+                                "description": "skip items whose path or function name contains "
+                                               "this fragment (repeatable)"}}},
     {"name": "worklist", "argv": ["worklist"], "json_flag": True, "positional": (),
      "flags": {"top": "--top"},
-     "description": "Risk-ranked decomposition queue (ccn x recency-weighted churn)",
-     "properties": {"top": {"type": "integer"}}},
+     "description": "The run's whole risk ranking: every function over its ceiling, then the "
+                    "queue under it ordered by ccn times recency-weighted churn. Use it to "
+                    "survey the repo; next_item hands out one packet from the top.",
+     "properties": {"top": {"type": "integer",
+                            "description": "cap the active list (default: the config's worklist_top)"}}},
     {"name": "runs", "argv": ["runs"], "json_flag": True, "positional": (), "flags": {},
-     "description": "Run history: id, kind, verdict, commit, lane set", "properties": {}},
+     "description": "Run history, newest first: id, kind, verdict, commit and lane set. Use it "
+                    "to date the store or to check which commit the other tools answer from.",
+     "properties": {}},
     {"name": "brief", "argv": ["brief"], "json_flag": True, "positional": ("path", "name"),
      "flags": {},
-     "description": "One function's whole context: scored row, ratchet mark, uncovered lines, "
-                    "duplication twins, churn and change-coupling partners",
+     "description": "One function's whole context in one call: scored row, ratchet mark, "
+                    "uncovered lines, duplication twins, churn and change-coupling partners. "
+                    "The deepest single read; explain is the slimmer history-only view.",
      "properties": {"path": {"type": "string", "description": "repo-relative source file"},
                     "name": {"type": "string", "description": _NAME_DESCRIPTION}}},
     {"name": "explain", "argv": ["explain"], "json_flag": False, "positional": ("path", "name"),
      "flags": {},
-     "description": "One function's score trajectory across runs plus its ratchet mark",
-     "properties": {"path": {"type": "string"},
+     "description": "One function's score trajectory across runs plus its ratchet mark. Use it "
+                    "to see whether a function is improving or decaying; brief adds the full "
+                    "context around the newest score.",
+     "properties": {"path": {"type": "string", "description": "repo-relative source file"},
                     "name": {"type": "string", "description": _NAME_DESCRIPTION}}},
     {"name": "doctor", "argv": ["doctor"], "json_flag": False, "positional": (), "flags": {},
-     "description": "Config/repo agreement check: typo keys, empty scopes, missing lane cwds",
+     "description": "Config and repo agreement check: typo keys, empty scopes, missing lane "
+                    "cwds, unresolvable runners. Run it first when any other tool answers "
+                    "strangely or an expected file is missing from the ranking.",
      "properties": {}},
     {"name": "coupling", "argv": ["coupling"], "json_flag": True, "positional": (),
      "flags": {"min_support": "--min-support", "min_confidence": "--min-confidence"},
-     "description": "File pairs that keep landing in the same commits (hidden dependencies)",
-     "properties": {"min_support": {"type": "integer"}, "min_confidence": {"type": "number"}}},
+     "description": "File pairs that keep landing in the same commits: dependencies no import "
+                    "statement reveals. Use it to learn what else an edit usually drags along "
+                    "before touching a file.",
+     "properties": {"min_support": {"type": "integer",
+                                    "description": "minimum shared commits before a pair counts (default 5)"},
+                    "min_confidence": {"type": "number",
+                                       "description": "minimum P(pair changes together), 0 to 1 (default 0.5)"}}},
     {"name": "duplication", "argv": ["duplication"], "json_flag": True, "positional": (),
      "flags": {"similarity": "--similarity"},
-     "description": "Near-duplicate functions by normalized line shingles",
-     "properties": {"similarity": {"type": "number"}}},
+     "description": "Near-duplicate function pairs by normalized line shingles, with the "
+                    "containment percent. Use it before a refactor so twins get folded "
+                    "together instead of one copy getting fixed alone.",
+     "properties": {"similarity": {"type": "number",
+                                   "description": "containment threshold, shared over smaller, "
+                                                  "0 to 1 (default 0.8)"}}},
     {"name": "ratchet_report", "argv": ["ratchet", "report"], "json_flag": True, "positional": (),
      "flags": {},
-     "description": "Debt burn-down: open mark ages and repayment velocity from git history",
+     "description": "The debt burn-down: every open ratchet mark with its age, plus repayment "
+                    "velocity from git history. Use it to see whether marked debt is being "
+                    "paid down or piling up.",
      "properties": {}},
 )
 
+# Every tool shells to a read-only CLI command against a store on this machine:
+# nothing writes, reruns answer the same, and no call leaves the repo. Declared
+# once, in the field clients read, so the module docstring's promise reaches the
+# model that plans with these tools.
+_ANNOTATIONS = {"readOnlyHint": True, "idempotentHint": True, "openWorldHint": False}
+
 
 def tool_listing() -> list[dict]:
     return [{"name": t["name"], "description": t["description"],
+             "annotations": dict(_ANNOTATIONS),
              "inputSchema": {"type": "object", "properties": {**_REPO, **t["properties"]}}}
             for t in TOOLS]
 
@@ -116,7 +155,7 @@ def _run_cli(tool: dict, arguments: dict, repo: str) -> dict:
     proc = subprocess.run([sys.executable, "-m", "crapkit", *argv],
                           capture_output=True, text=True, timeout=600)
     text = proc.stdout if proc.stdout.strip() else proc.stderr
-    return _result(text, is_error=proc.returncode != 0)
+    return _structured(_result(text, is_error=proc.returncode != 0))
 
 
 def _call_tool(root: Path, name: str, arguments: dict) -> dict:
@@ -130,6 +169,43 @@ def _call_tool(root: Path, name: str, arguments: dict) -> dict:
     return _run_cli(tool, arguments, repo)
 
 
+# What a connected model needs before its first call, in the one field the
+# protocol reserves for it. The nine error results a model would otherwise
+# collect from an unmeasured repo teach the same thing nine times, slower.
+_INSTRUCTIONS = (
+    "crapkit scores every function as ccn^2 x (1 - coverage)^3 + ccn; these nine tools read "
+    "the newest scored run and every one is read-only: nothing here runs a test suite or "
+    "writes to the repo. They need a repo measured once (crapkit init, then crapkit "
+    "coverage); an unmeasured repo answers with a one-line pointer instead of data. Start "
+    "with next_item for one function to fix, worklist for the whole ranking, brief for "
+    "everything about one function.")
+
+
+def _negotiated(params: dict) -> str:
+    """The client's revision when this server implements it, else the newest it
+    does; the spec leaves proceeding or disconnecting to the client from there."""
+    offered = params.get("protocolVersion")
+    return offered if offered in SUPPORTED_PROTOCOLS else SUPPORTED_PROTOCOLS[0]
+
+
+def _structured(result: dict) -> dict:
+    """Attach the parsed object beside the text when the text is a JSON object.
+
+    The --json commands print for machines; a client on the 2025-06-18 revision
+    reads structuredContent directly. Prose, JSON arrays and error text stay
+    text-only rather than getting wrapped into shapes the tools never promised.
+    """
+    if result["isError"]:
+        return result
+    try:
+        parsed = json.loads(result["content"][0]["text"])
+    except ValueError:
+        return result
+    if isinstance(parsed, dict):
+        return {**result, "structuredContent": parsed}
+    return result
+
+
 def _respond(msg_id, result=None, error=None) -> dict:
     resp = {"jsonrpc": "2.0", "id": msg_id}
     resp["error" if error else "result"] = error if error else result
@@ -142,9 +218,10 @@ def _handle(root: Path, msg: dict) -> dict | None:
         return None  # a notification (e.g. notifications/initialized) needs no reply
     if method == "initialize":
         return _respond(msg["id"], {
-            "protocolVersion": PROTOCOL_VERSION,
+            "protocolVersion": _negotiated(msg.get("params", {})),
             "capabilities": {"tools": {}},
-            "serverInfo": {"name": "crapkit", "version": _version()}})
+            "serverInfo": {"name": "crapkit", "version": _version()},
+            "instructions": _INSTRUCTIONS})
     if method == "tools/list":
         return _respond(msg["id"], {"tools": tool_listing()})
     if method == "tools/call":

{crapkit-0.4.12 → crapkit-0.4.14/src/crapkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crapkit
-Version: 0.4.12
+Version: 0.4.14
 Summary: Scores every function on complexity times uncovered risk, ranks the worst, and blocks commits that add more.
 Author: Jean-Francois Gagne
 License: MIT
@@ -39,10 +39,13 @@ Dynamic: license-file
 
 # crapkit
 
+<!-- mcp-name: io.github.jeanfrancoisgagne/crapkit -->
+
 [![ci](https://github.com/JeanFrancoisGagne/crapkit/actions/workflows/ci.yml/badge.svg)](https://github.com/JeanFrancoisGagne/crapkit/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/crapkit)](https://pypi.org/project/crapkit/)
 [![Python](https://img.shields.io/pypi/pyversions/crapkit)](https://pypi.org/project/crapkit/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/JeanFrancoisGagne/crapkit/blob/main/LICENSE)
+[![crapkit MCP server](https://glama.ai/mcp/servers/JeanFrancoisGagne/crapkit/badges/score.svg)](https://glama.ai/mcp/servers/JeanFrancoisGagne/crapkit)
 
 ![crapkit init, coverage and worklist --top 5 on a small Python repo, then a shell heredoc adding a function at ccn 7: the per-edit advisory reports it and exits 2, and the commit gate refuses the staged file with exit 6](https://raw.githubusercontent.com/JeanFrancoisGagne/crapkit/main/docs/demo.gif)
 
@@ -165,7 +168,7 @@ leaves the box
 
 ```
 $ crapkit --version
-crapkit 0.4.12
+crapkit 0.4.14
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -395,7 +398,7 @@ crapkit ships a `.pre-commit-hooks.yaml` declaring `id: crapkit-gate`. In your
 repos:
   - repo: https://github.com/JeanFrancoisGagne/crapkit
     # crapkit's release step rewrites this line to the tag it just cut
-    rev: v0.4.12
+    rev: v0.4.14
     hooks:
       - id: crapkit-gate
 ```
@@ -501,7 +504,7 @@ to a workflow, and every input has a default:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: JeanFrancoisGagne/crapkit@v0.4.12
+      - uses: JeanFrancoisGagne/crapkit@v0.4.14
 ```
 
 The whole job those four lines sit in:
@@ -521,7 +524,7 @@ jobs:
         with:
           python-version: "3.12"       # the interpreter the install below lands in
       - run: pip install -e ".[dev]"   # whatever your lanes need to run
-      - uses: JeanFrancoisGagne/crapkit@v0.4.12
+      - uses: JeanFrancoisGagne/crapkit@v0.4.14
         with:
           gate: "false"
 ```
@@ -1189,6 +1192,7 @@ that block is advisory unless `diff_uncovered_max` is set
 | [docs/lanes.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/lanes.md) | The lane model, vitest and jest and pytest recipes, artifact reuse, flake retest, containers. |
 | [docs/ratchet.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/ratchet.md) | Seeding, pruning, the git merge driver, metric stamps, debt policy, overrides. |
 | [docs/agent-json.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/agent-json.md) | The machine surface: `schema`, every payload field, real captured examples. |
+| [docs/comparison.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/comparison.md) | Where crapkit sits next to radon, xenon, wily, coverage.py and SonarQube, and how they run together. |
 | [AGENTS.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/AGENTS.md) | The burn-down loop an agent runs, and the rules for changing crapkit itself. |
 | [plugin/](https://github.com/JeanFrancoisGagne/crapkit/tree/main/plugin) | The Claude Code plugin: three skills, the read-side MCP server, and the advisory PostToolUse hook. |