digline-mcp 0.1.0__tar.gz

digline_mcp-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Python bytecode and build output
+__pycache__/
+*.py[cod]
+build/
+dist/
+*.egg-info/
+
+# Environment. Recreated by `uv sync`; it pins absolute paths, so it must
+# never be committed.
+.venv/
+.env
+
+# Tool caches. Each already drops its own `.gitignore`; listed here so a
+# fresh clone is clean before the tools have run once.
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# IDE. Excluded because the project files carry machine-specific SDK paths
+# (`digline.iml` names the interpreter by absolute path). Drop these two lines
+# to version the shared part, and keep ignoring `.idea/workspace.xml`.
+.idea/
+*.iml
+
+# Local Claude Code settings. `.claude/settings.json`, if it appears, is shared
+# and stays versioned. `CLAUDE.local.md` is the personal working agreement —
+# how I want to be worked with — as against `CLAUDE.md`, which is the project.
+.claude/settings.local.json
+CLAUDE.local.md
+
+# macOS
+.DS_Store
+
+# Working material that stays local and is not part of the package.
+private/
+
+# NOT ignored: `.digline/`. Decision 2 — baselines are versioned, run
+# artifacts are not — and the split is enforced one level down, by the
+# `.gitignore` the store itself writes into `.digline/` (`*/runs/`).
+# Ignoring `.digline/` here would take the baselines out of git with it.
+to-publish/
+
+# The site checkout that ci.yml's `docs` job makes, and that RELEASING
+# tells you to make to reproduce it. Never committed here.
+_site/

digline_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: digline-mcp
+Version: 0.1.0
+Summary: MCP server for digline: an agent can read a result and measure one, and cannot promote a baseline.
+Author-email: Alessandro Prandini <alessandro.prandini@ict-group.it>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: digline>=0.6.0
+Requires-Dist: mcp<3,>=2.2
+Description-Content-Type: text/markdown
+
+# digline-mcp
+
+The [MCP](https://modelcontextprotocol.io) server for
+[digline](https://github.com/digline/digline): it lets a coding agent **read** a
+digline result and **measure** a new one, and it does not let the agent promote
+a baseline.
+
+Not because promotion is refused. Because there is no such tool.
+
+## The six tools
+
+| tool | what it does |
+|---|---|
+| `list_runs` | every stored run of a suite, newest first, with the baseline marked |
+| `get_run` | one stored run — the verdicts, never the payload |
+| `get_baseline` | the approved reference, same shape |
+| `compare` | a run against the baseline: did it get worse? |
+| `diff` | two runs, neither of them a reference: should I switch? |
+| `run` | execute the suite, with the call count acknowledged first |
+
+`promote` is **absent by construction**, and so are `migrate`, `view` and
+`report`. A baseline is an *approved reference*, and `promote` writes into
+`.digline/<tenant>/baselines/`, which is committed — anything landing there
+arrives in somebody's diff and must arrive because they put it there. A refusal
+would be a conversation an agent could argue with; an absence is not.
+
+The reasoning is [ADR 0011](../../docs/adr/0011-the-mcp-server.md), and the
+judgement layer it turns into surface is [`AGENTS.md`](../../AGENTS.md).
+
+## Install and configure
+
+```bash
+uv pip install digline-mcp
+```
+
+One server serves **one repository**: the perimeter is the repo, and
+multi-project is N named servers rather than a registry.
+
+```json
+{
+  "mcpServers": {
+    "digline-northwind": {
+      "command": "digline-mcp",
+      "args": ["--root", "/Users/you/src/northwind"]
+    }
+  }
+}
+```
+
+`--tenant` and `--env` are accepted and **verify**; they never override. The
+suite decides, as it does everywhere else in digline.
+
+## What `run` costs, before it costs it
+
+`run` takes a mandatory `acknowledge_calls` that must equal the suite's planned
+calls to the target. Called without it, the tool refuses **and hands back the
+number**:
+
+```
+run(suite="suite.py")
+  → refused: this suite plans 100 calls to the target.
+    20 cases × 5 samples = 100 calls to the target; each answer is judged
+    3 times by llm_rubric.
+    Call again with acknowledge_calls=100.
+
+run(suite="suite.py", acknowledge_calls=100)   → executes
+```
+
+The first call is the probe. An agent cannot spend a hundred model calls without
+having stated the number — `AGENTS.md` §7 as a contract rather than as advice.
+
+## What never crosses
+
+An MCP response goes into a model's context, and from there into transcripts and
+caches nobody controls. So the run tools return a **verdict-only projection**:
+the name, the identity, the status, the score, the threshold, the tolerance, the
+measured interval, and the metadata a suite disclosed.
+
+Never the judge's `reason` — the judge quotes the output, so the reason *is* the
+output. Never the sentence explaining a suspension, never undisclosed metadata,
+never a case's inputs, and never a prompt or its digest unless the suite
+declares `Disclosure(artifacts=True)`.

digline_mcp-0.1.0/README.md

@@ -0,0 +1,82 @@
+# digline-mcp
+
+The [MCP](https://modelcontextprotocol.io) server for
+[digline](https://github.com/digline/digline): it lets a coding agent **read** a
+digline result and **measure** a new one, and it does not let the agent promote
+a baseline.
+
+Not because promotion is refused. Because there is no such tool.
+
+## The six tools
+
+| tool | what it does |
+|---|---|
+| `list_runs` | every stored run of a suite, newest first, with the baseline marked |
+| `get_run` | one stored run — the verdicts, never the payload |
+| `get_baseline` | the approved reference, same shape |
+| `compare` | a run against the baseline: did it get worse? |
+| `diff` | two runs, neither of them a reference: should I switch? |
+| `run` | execute the suite, with the call count acknowledged first |
+
+`promote` is **absent by construction**, and so are `migrate`, `view` and
+`report`. A baseline is an *approved reference*, and `promote` writes into
+`.digline/<tenant>/baselines/`, which is committed — anything landing there
+arrives in somebody's diff and must arrive because they put it there. A refusal
+would be a conversation an agent could argue with; an absence is not.
+
+The reasoning is [ADR 0011](../../docs/adr/0011-the-mcp-server.md), and the
+judgement layer it turns into surface is [`AGENTS.md`](../../AGENTS.md).
+
+## Install and configure
+
+```bash
+uv pip install digline-mcp
+```
+
+One server serves **one repository**: the perimeter is the repo, and
+multi-project is N named servers rather than a registry.
+
+```json
+{
+  "mcpServers": {
+    "digline-northwind": {
+      "command": "digline-mcp",
+      "args": ["--root", "/Users/you/src/northwind"]
+    }
+  }
+}
+```
+
+`--tenant` and `--env` are accepted and **verify**; they never override. The
+suite decides, as it does everywhere else in digline.
+
+## What `run` costs, before it costs it
+
+`run` takes a mandatory `acknowledge_calls` that must equal the suite's planned
+calls to the target. Called without it, the tool refuses **and hands back the
+number**:
+
+```
+run(suite="suite.py")
+  → refused: this suite plans 100 calls to the target.
+    20 cases × 5 samples = 100 calls to the target; each answer is judged
+    3 times by llm_rubric.
+    Call again with acknowledge_calls=100.
+
+run(suite="suite.py", acknowledge_calls=100)   → executes
+```
+
+The first call is the probe. An agent cannot spend a hundred model calls without
+having stated the number — `AGENTS.md` §7 as a contract rather than as advice.
+
+## What never crosses
+
+An MCP response goes into a model's context, and from there into transcripts and
+caches nobody controls. So the run tools return a **verdict-only projection**:
+the name, the identity, the status, the score, the threshold, the tolerance, the
+measured interval, and the metadata a suite disclosed.
+
+Never the judge's `reason` — the judge quotes the output, so the reason *is* the
+output. Never the sentence explaining a suspension, never undisclosed metadata,
+never a case's inputs, and never a prompt or its digest unless the suite
+declares `Disclosure(artifacts=True)`.

digline_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "digline-mcp"
+version = "0.1.0"
+description = "MCP server for digline: an agent can read a result and measure one, and cannot promote a baseline."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+authors = [
+    { name = "Alessandro Prandini", email = "alessandro.prandini@ict-group.it" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+    "Typing :: Typed",
+]
+dependencies = [
+    # 0.6.0 is the release that first publishes `digline.wire` and
+    # `digline.host`, and `core.diff` with them. Held there by
+    # `tests/test_plugin_floors.py`, which computes the floor from the newest
+    # name these sources import rather than taking this number on trust.
+    "digline>=0.6.0",
+    # Both halves matter. Unpinned, a resolver could hand somebody 1.x, where
+    # `MCPServer` does not exist and `mcp.server.fastmcp` raises on import: the
+    # 2.0 release renamed FastMCP, and every example written before it is wrong.
+    # The cap is the same lesson the examples' caps gate encodes — a major
+    # version that renames the entry point is not hypothetical here, it happened.
+    "mcp>=2.2,<3",
+]
+
+[project.scripts]
+digline-mcp = "digline_mcp.server:main"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/digline_mcp"]
+
+[tool.uv.sources]
+digline = { workspace = true }

digline_mcp-0.1.0/src/digline_mcp/__main__.py

@@ -0,0 +1,11 @@
+"""`python -m digline_mcp`, the same entry point as the `digline-mcp` script.
+
+Both exist because a client's MCP config may name either: a console script is
+tidier, and `python -m` is what somebody reaches for when the script is not on
+the PATH of whatever launched the process.
+"""
+
+from digline_mcp.server import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

digline_mcp-0.1.0/src/digline_mcp/descriptions.py

@@ -0,0 +1,111 @@
+"""The playbook, where the model that is about to call a tool will read it.
+
+A tool description is not `--help`. It is loaded into the context of the model
+deciding whether to call the tool, at the moment it decides — which makes it the
+one place `AGENTS.md` reaches an agent that never read `AGENTS.md`.
+
+So each description carries the rule that governs its own misuse. The agent that
+loads the tools receives the discipline with the instrument. (ADR 0011 §9)
+
+`tests/test_playbook.py` checks each of these against `AGENTS.md` itself, the
+way `tests/test_agents.py` checks the shipped skill: a rule reworded in one
+place cannot stay stale in the other two.
+"""
+
+from __future__ import annotations
+
+__all__ = ["DESCRIPTIONS"]
+
+LIST_RUNS = """\
+Every stored run of a suite, newest first, with the baseline marked.
+
+This is the table you choose a run from, and choosing is the point: promote from
+the middle of several, never from the first one that goes green. A baseline
+freezes one run, and the first green run is green partly on merit and partly on
+luck — a case recorded at 0.667 where three runs out of three say 1.000 becomes
+a red line nobody can explain a fortnight later.
+
+You cannot promote from here and there is no tool that can. Assemble the
+evidence, name the run whose per-case profile is closest to typical, and
+recommend it; the human runs `digline promote`, or tells you to.
+
+If `skipped` or `note` is non-empty, stored runs were written under an older
+schema and this listing does not show them. Say so, and propose
+`digline migrate` — do not run it."""
+
+GET_RUN = """\
+One stored run: its verdicts, its measured intervals, and the configuration that
+produced it.
+
+Several cases flipping together in one run is a different event from one case
+moving. It is either a real regression or the judge itself moving, and both are
+findings — read the run, name the cases, and look at what they have in common.
+Do not retry it: retrying until it passes destroys the evidence either way.
+
+The judge's reason is not here and cannot be. A reason quotes the output, so it
+is the output, and it stays inside the perimeter it was measured in."""
+
+GET_BASELINE = """\
+The approved reference for this suite: the run a human decided to hold the
+others against.
+
+Same shape as get_run, and the same boundary. If the suite has no baseline yet,
+that is not an error — it is the first round, and what it needs is a person."""
+
+COMPARE = """\
+A run against the baseline. Answers: did it get worse?
+
+`exit_code` is the contract. 0 proceed. 1 stop and report what got worse. 2 stop
+— the run could not be judged, and nothing downstream of it is meaningful,
+including any conclusion you were about to draw from the green checks beside it.
+
+A movement inside the baseline's measured interval is reported as `unchanged`,
+with `within_noise` on the delta. That explains a comparison and excuses
+nothing: an absolute threshold still gates, a flip from passing to failing is
+never rescued by noise, and an exit code of 1 is never argued away by quoting an
+interval. If you find yourself writing "but this is within noise" about a red
+run, you are arguing with the instrument.
+
+A dip that does not recur on re-run is sampling noise: document it and move on.
+Decide the number of re-runs before running them — with a stochastic judge,
+enough re-runs always produce a green one, and a stopping rule chosen after the
+fact measures your patience rather than the system."""
+
+DIFF = """\
+Two runs, neither of them a reference. Answers: should I switch?
+
+Prompt A against prompt B, one model against another, temperature 0.3 against
+0.7. This is a report and never a verdict, so there is **no `worse` field and no
+exit code** — a verdict exists only against an approved reference, and neither
+side of a diff was approved by anybody. Do not synthesise one.
+
+Where both sides were sampled, each check carries the two measured intervals.
+Overlapping intervals mean the two are not distinguishable by that check. That
+is evidence beside the count, never an excuse: a diff has no baseline, so no
+interval has the standing to overrule a difference."""
+
+RUN = """\
+Execute the suite against its target and store the result.
+
+**This spends money.** `acknowledge_calls` must equal the suite's planned calls
+to the target; call without it once and the refusal tells you the number. That
+number counts calls to the target only — where an assertion judges each answer
+several times, the returned `sentence` names the multiplier, and the honest
+figure you report is the whole sentence.
+
+Before proposing a hunt that means several runs, multiply that line by the
+number of runs and say the figure out loud in your recommendation. Five runs
+over a hundred-call suite is five hundred model calls, and that is a decision
+for whoever pays for them.
+
+Decide the number of re-runs before running them, and stop at the signal. Never
+keep rolling until the answer looks right."""
+
+DESCRIPTIONS: dict[str, str] = {
+    "list_runs": LIST_RUNS,
+    "get_run": GET_RUN,
+    "get_baseline": GET_BASELINE,
+    "compare": COMPARE,
+    "diff": DIFF,
+    "run": RUN,
+}

digline_mcp-0.1.0/src/digline_mcp/errors.py

@@ -0,0 +1,68 @@
+"""digline's refusals, translated so they survive the boundary.
+
+The SDK is bimodal about this and the difference is total. A `ToolError`
+reaches the caller with its message, as a `CallToolResult` carrying the text and
+`is_error`. **Anything else is wrapped and its message is discarded** — a custom
+exception arrives as the bare string "Error executing tool <name>".
+
+So every carefully written refusal in digline — the perimeter messages, the
+three promotion conditions, "no runs stored for suite … run it first" — would
+reach an agent as five identical words unless it is translated here. That is the
+whole reason this module exists, and `tests/test_errors.py` is parametrized over
+the list so a new exception type added to digline without a translation fails
+here rather than in front of somebody.
+
+Nothing else is caught. An unexpected exception should stay an unexpected
+exception: dressing one as a tool result hides a bug behind a sentence.
+(ADR 0011 §10)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import wraps
+from typing import NoReturn
+
+from mcp.server.mcpserver.exceptions import ToolError
+
+from digline.core import DifferentJudgesError, DifferentSuitesError
+from digline.host import UsageError
+from digline.store import ConfigMismatchError, ErroredRunError, TenantMismatchError
+from digline.targets import ProviderNotFound
+
+__all__ = ["TRANSLATED", "translated"]
+
+#: The exceptions digline raises deliberately, each carrying a message written
+#: for a reader. Anything not in here is a bug and travels as one.
+TRANSLATED: tuple[type[Exception], ...] = (
+    UsageError,
+    TenantMismatchError,
+    ConfigMismatchError,
+    ErroredRunError,
+    DifferentSuitesError,
+    DifferentJudgesError,
+    ProviderNotFound,
+)
+
+
+# PEP 695 syntax (Python 3.12+): `[**P, R]` declares the type parameters inline
+# instead of the older module-level `ParamSpec`/`TypeVar` pair. `**P` is the
+# parameter *list* of the wrapped function, so the decorator keeps each tool's
+# real signature — which is what the SDK reads to build the input schema.
+def translated[**P, R](fn: Callable[P, R]) -> Callable[P, R]:
+    """Re-raise digline's own refusals as `ToolError`, message intact."""
+
+    @wraps(fn)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        try:
+            return fn(*args, **kwargs)
+        except TRANSLATED as exc:
+            raise ToolError(str(exc)) from exc
+
+    return wrapper
+
+
+def refuse(message: str) -> NoReturn:
+    """A refusal this server itself makes, in the one shape that reaches an
+    agent."""
+    raise ToolError(message)