@plune-ai/cli 0.34.5 → 0.34.6

package/README.md

@@ -232,6 +232,7 @@ code is then the platform's verdict on the run, not the runner's: the summary th
 | an expected case that never reported (`notRun`): a dead shard is not green | `1` |
 | only `passed`, `blocked`, `skipped` and muted failures | `0` |
 | no verdict: the platform could not be reached, the finish was refused, the run was left open or terminated | `1` |
+| no result reached the run and nothing was expected of it: `run import` of a report whose cases the project does not have yet, `run finish` or `sync` of an empty run | `1` |
 | `run exec` where no result reached the run and nothing was expected of it | the command's own code |
 
 Without the flag every command exits as it always did. `plune run` (local evals) is not affected: it stays the
@@ -632,11 +633,15 @@ useful for a self-hosted backend. The Markdown format `pull` writes and `push` r
 ### Plune tools for AI agents: `plune mcp`
 
 `plune mcp serve` gives an agent the same Plune your token reaches — the review queue, cases,
-missions, questions, strategy, reports — as MCP tools over stdio. The agent sees at most 20 tools at
-once; the rest it finds with `plune_discover_tools`. Every write tool takes `dry_run`, batches stop at
-100 items, and the agent is held to the platform's agent rules: a proposed case lands in the review
+missions, questions, strategy, reports — as MCP tools over stdio. The agent is shown 17 tools, 8 with a
+read token or `--read-only`; five more write tools it finds with `plune_discover_tools`. Every write
+tool takes `dry_run`, batches stop at 100 items, and the agent is held to the platform's agent rules: a proposed case lands in the review
 queue, a bulk decision needs a confirm, and nothing is deleted through MCP.
 
+The full guide is [Plune tools for AI agents](https://docs.plune.ai/cli/guides/mcp/): a project
+`.mcp.json` and the Cursor file, the two protocol revisions the server speaks, how to keep the tool list
+small, and what the contract tests check (snapshot, lint, token budget) and what they do not.
+
 `plune_cases_generate` asks the project's AI for case proposals from pasted text (a requirement, a
 story, a ticket's text; 20 words to 12 000 characters, up to 12 proposals, 8 by default). It spends the
 project's AI budget, and its proposals wait in the review queue like any other until a person approves
@@ -671,7 +676,46 @@ per-request `_meta`. In the newer revision a client learns that `plune_discover_
 list through `subscriptions/listen`; `tools/list` is sent with `ttlMs: 0`, so a client that does not
 listen reads the current list every time.
 
-#### Is the server alive: `plune mcp check`
+#### Dependencies
+
+| Package | Version | License | Why |
+|---|---|---|---|
+| `@modelcontextprotocol/server` | 2.4.0 | Apache-2.0 | The MCP server and its stdio transport for `plune mcp serve`; it serves revision `2026-07-28` and the `initialize`-based revisions from one process. |
+
+The version is pinned exactly, not with a range, on purpose: the 2.x line moves fast, and each update is taken
+deliberately with the protocol tests run against it.
+
+## Test an MCP server
+
+Four commands test **any** MCP server, yours or someone else's, started over stdio or reached over
+HTTP. They need no Plune account and no model, and they do not talk to the Plune platform: each one
+starts the server you name after `--`, or connects to the address you give with `--url`, and nothing
+else. Everything after `--` runs as your user, so point them only at a server you would run yourself.
+
+```bash
+npx -y @plune-ai/cli mcp check -- node dist/server.js                            # does it start and answer
+npx -y @plune-ai/cli mcp lint -- node dist/server.js                             # what in its tools confuses a model
+npx -y @plune-ai/cli mcp snapshot --out mcp-snapshot.json -- node dist/server.js # its contract, to commit
+npx -y @plune-ai/cli mcp diff mcp-snapshot.json -- node dist/server.js           # what changed, and what breaks
+```
+
+| Exit | Meaning |
+|------|---------|
+| `0` | Nothing at the `--fail-on` level, and everything was measured. For `snapshot`: the file was written. |
+| `1` | A finding (`lint`), a failed check or smoke call (`check`), or a change (`diff`) at the `--fail-on` level. `snapshot` has no `1`. |
+| `2` | Nothing about the server is proven, and you can fix why: the command was not found or did not start, the server could not be reached or answered `401` or `403`, a file cannot be read, or a flag is wrong. |
+| `3` | Nothing was measured: the server lists no tools, there is nothing to compare, or a check could not run. Not measured is not a pass. |
+
+Each command's own table is in [the CLI reference](docs/guide/cli.md#plune-mcp-check). The guides on
+docs.plune.ai walk through a sample server with three defects, every lint rule with an example, the
+exceptions file, snapshots in a pull request, and the run in Plune through JUnit:
+
+- [Test an MCP server](https://docs.plune.ai/cli/guides/mcp-test-a-server/): the four commands, the exit codes and states, stdio and HTTP, `plune run import`;
+- [Lint an MCP server](https://docs.plune.ai/cli/guides/mcp-lint/): the rules, `--fail-on`, `plune-mcp-ignore.yaml`, `--call`;
+- [Snapshot and diff an MCP server](https://docs.plune.ai/cli/guides/mcp-snapshot-diff/): what a change costs a client, and the security signal;
+- [MCP server checks in CI](https://docs.plune.ai/eval-action/recipes/mcp-in-ci/): `plune-ai/eval-action/mcp@v1` for a stdio or an HTTP server.
+
+### Is the server alive: `plune mcp check`
 
 `plune mcp check` answers the question before any other: does the server start, finish the
 handshake and answer the basic requests? It runs the checks in order (`start`, `initialize`,
@@ -693,7 +737,7 @@ be measured. `--out` writes a report you can attach to a ticket: no URL, command
 header in it, the server's stderr masked. The states, the options and the exit codes are in
 [the CLI reference](docs/guide/cli.md#plune-mcp-check).
 
-#### Checking any MCP server: `plune mcp lint`
+### Checking any MCP server: `plune mcp lint`
 
 `plune mcp lint` reads the whole tool list of a server you name, stdio or HTTP, and reports what
 makes a model choose the wrong tool: missing descriptions, look-alike tools, a string where an `enum`
@@ -711,7 +755,7 @@ It exits `1` on a finding at `--fail-on` (`error` by default; heuristic advice i
 a clean one. Accepted findings go in `plune-mcp-ignore.yaml`, each with a reason. The options, the
 file's format and the exit codes are in [the CLI reference](docs/guide/cli.md#plune-mcp-lint).
 
-#### Contract snapshots: `plune mcp snapshot` and `plune mcp diff`
+### Contract snapshots: `plune mcp snapshot` and `plune mcp diff`
 
 A server's author rarely notices a contract change — a removed tool, a parameter that became
 required, a rewritten description — and clients break later, quietly. `plune mcp snapshot` writes
@@ -730,15 +774,6 @@ destructive, and a new tool that does not say it is read-only carry a `security`
 for a reviewer to look, not a failure by itself. The format, the rules and the exit codes are in
 [the CLI reference](docs/guide/cli.md#plune-mcp-snapshot).
 
-#### Dependencies
-
-| Package | Version | License | Why |
-|---|---|---|---|
-| `@modelcontextprotocol/server` | 2.4.0 | Apache-2.0 | The MCP server and its stdio transport for `plune mcp serve`; it serves revision `2026-07-28` and the `initialize`-based revisions from one process. |
-
-The version is pinned exactly, not with a range, on purpose: the 2.x line moves fast, and each update is taken
-deliberately with the protocol tests run against it.
-
 ## Programmatic API
 
 The same engine that powers `plune run` is exported for use from your own code. Unlike the

package/dist/cli.cjs

@@ -4335,8 +4335,8 @@ function gateExit(verdict, runnerCode) {
   if (counts3 == null) return { code: 1, line: "plune: gate failed \u2014 no verdict from the platform, and no verdict is no pass." };
   const n = (status) => counts3[status] ?? 0;
   const notRun = verdict?.notRun?.length ?? 0;
-  if (runnerCode !== void 0 && notRun === 0 && Object.values(counts3).every((k) => !k)) {
-    return { code: runnerCode, line: `plune: gate \u2014 no result reached the run, so the exit code is the command's own (${runnerCode}).` };
+  if (notRun === 0 && Object.values(counts3).every((k) => !k)) {
+    return runnerCode !== void 0 ? { code: runnerCode, line: `plune: gate \u2014 no result reached the run, so the exit code is the command's own (${runnerCode}).` } : { code: 1, line: "plune: gate failed \u2014 no result reached the run, so there is nothing to pass." };
   }
   const said = `${n("failed")} failed \xB7 ${n("broken")} broken \xB7 ${notRun} not run \xB7 ${n("muted")} muted`;
   return n("failed") + n("broken") > 0 || notRun > 0 ? { code: 1, line: `plune: gate failed \u2014 ${said}` } : { code: 0, line: `plune: gate passed \u2014 ${said}` };

package/dist/index.cjs

@@ -1891,8 +1891,8 @@ function gateExit(verdict, runnerCode) {
   if (counts == null) return { code: 1, line: "plune: gate failed \u2014 no verdict from the platform, and no verdict is no pass." };
   const n = (status) => counts[status] ?? 0;
   const notRun = verdict?.notRun?.length ?? 0;
-  if (runnerCode !== void 0 && notRun === 0 && Object.values(counts).every((k) => !k)) {
-    return { code: runnerCode, line: `plune: gate \u2014 no result reached the run, so the exit code is the command's own (${runnerCode}).` };
+  if (notRun === 0 && Object.values(counts).every((k) => !k)) {
+    return runnerCode !== void 0 ? { code: runnerCode, line: `plune: gate \u2014 no result reached the run, so the exit code is the command's own (${runnerCode}).` } : { code: 1, line: "plune: gate failed \u2014 no result reached the run, so there is nothing to pass." };
   }
   const said = `${n("failed")} failed \xB7 ${n("broken")} broken \xB7 ${notRun} not run \xB7 ${n("muted")} muted`;
   return n("failed") + n("broken") > 0 || notRun > 0 ? { code: 1, line: `plune: gate failed \u2014 ${said}` } : { code: 0, line: `plune: gate passed \u2014 ${said}` };

package/dist/index.js

@@ -1831,8 +1831,8 @@ function gateExit(verdict, runnerCode) {
   if (counts == null) return { code: 1, line: "plune: gate failed \u2014 no verdict from the platform, and no verdict is no pass." };
   const n = (status) => counts[status] ?? 0;
   const notRun = verdict?.notRun?.length ?? 0;
-  if (runnerCode !== void 0 && notRun === 0 && Object.values(counts).every((k) => !k)) {
-    return { code: runnerCode, line: `plune: gate \u2014 no result reached the run, so the exit code is the command's own (${runnerCode}).` };
+  if (notRun === 0 && Object.values(counts).every((k) => !k)) {
+    return runnerCode !== void 0 ? { code: runnerCode, line: `plune: gate \u2014 no result reached the run, so the exit code is the command's own (${runnerCode}).` } : { code: 1, line: "plune: gate failed \u2014 no result reached the run, so there is nothing to pass." };
   }
   const said = `${n("failed")} failed \xB7 ${n("broken")} broken \xB7 ${notRun} not run \xB7 ${n("muted")} muted`;
   return n("failed") + n("broken") > 0 || notRun > 0 ? { code: 1, line: `plune: gate failed \u2014 ${said}` } : { code: 0, line: `plune: gate passed \u2014 ${said}` };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plune-ai/cli",
-  "version": "0.34.5",
+  "version": "0.34.6",
   "description": "AI-powered assertion testing for LLM apps — write assertions, run them against any provider, get a pass/fail report (local, CI, or diff).",
   "keywords": [
     "ai",