compendium-mcp 0.6.0 → 0.6.2

package/README.md

@@ -8,6 +8,21 @@ MCP server that **minimizes LLM token usage** by compressing, summarizing, filte
 
 Built in Rust with the official [`rmcp`](https://crates.io/crates/rmcp) SDK.
 
+## Why / when to use Compendium
+
+Use it when an agent is about to paste **large or noisy context** into the model (build logs, test dumps, API JSON, untrusted web/tool text, long chat, or a fresh workspace). The goal is a **smaller, safer, still-useful** prompt — not another planner or agent runtime.
+
+| Situation | Call |
+|-----------|------|
+| Unsure which action | `catalog` → `help` + `id` (or read `cmp://skill/…`) |
+| New task in a repo | `brief` with a short `query` |
+| Noisy terminal / CLI dump | `filter` (generic) or `compress_output` (cargo/npm/docker/git/…) |
+| Bulky text/JSON to densify | `compress` (small inputs bypass unless `force`) |
+| Untrusted paste / secrets / IPI | `sanitize` (or `sanitize_input: true` on the next action) |
+| Guided recipe | `playbooks` → `playbook` |
+
+Heuristic paths work with **no local model**. Optional loopback LLM improves `summarize_smart` / hybrid `rerank` / smart `filter_relevant`.
+
 ## Quick start (Cursor)
 
 You need **Node.js 18+**. Compendium itself arrives via npm — no Rust install required.
@@ -90,14 +105,14 @@ Binary packaging details for maintainers: [npm/DISTRIBUTION.md](npm/DISTRIBUTION
 
 | Mode | Command | Notes |
 |------|---------|-------|
-| **stdio** (default) | `compendium` / `compendium stdio` | Cursor / Claude Desktop |
-| **Streamable HTTP/SSE** | `compendium http [BIND]` | Requires `--features http`. Endpoint: `http://{bind}/mcp` |
+| **stdio** (default) | `compendium` / `compendium stdio` | Cursor / Claude Desktop — dual-compat (legacy initialize or modern connect) |
+| **Streamable HTTP** | `compendium http [BIND]` | Requires `--features http`. Endpoint: `http://{bind}/mcp`. Sessionless (`2026-07-28`); JSON preferred, SSE fallback |
 
-Default HTTP bind: `127.0.0.1:8788` (override with arg or `COMPENDIUM_HTTP_BIND`).
+Default HTTP bind: `127.0.0.1:8788` (override with arg or `COMPENDIUM_HTTP_BIND`). App cache (`COMPENDIUM_CACHE_DIR`) is not an MCP session — set it for multi-request HTTP. See playbook `http-transport`.
 
 ## Tools
 
-Single MCP tool: **`compendium`**. Choose the operation with `action`:
+Single MCP tool: **`compendium`**. Choose the operation with `action`. Prefer the [Why / when](#why--when-to-use-compendium) table for the first call; use the full list below only when you need a specific field.
 
 | `action` | Purpose | Main fields |
 |----------|---------|-------------|
@@ -144,7 +159,7 @@ Optional on most text actions: `sanitize_input: true` scrubs before processing.
 
 `brief` walks `brief.root` (default: process cwd) with `.gitignore` / `.ignore`, BM25-ranks paths/chunks, window-reads oversized files (not head-truncate), and returns a structured `briefing`: **Task / Status / Evidence / Caveats / Sources / Read next**, plus `cache_key`. Status uses a local SLM when `COMPENDIUM_LOCAL_LLM_URL` is set (`backend: local_llm`); otherwise heuristic bullets. Caveats flag truncated files and docs older than selected code. **Read next** includes source paths plus suggested `cmp://skill/playbook/…` / action URIs. Optional `COMPENDIUM_BRIEF_ROOT` restricts allowed roots. Briefings are sanitized by default.
 
-Example:
+Example — noisy log (canonical first call after install):
 
 ```json
 {
@@ -154,6 +169,8 @@ Example:
 }
 ```
 
+Discover more without reading this README: `{"action":"catalog"}` then `{"action":"help","id":"compress_output"}`. Sample payloads: [`examples/`](examples/).
+
 Response envelope: `{ "ok": true, "action": "filter", "result_json": "{...}" }`. Parse `result_json` as JSON for the action-specific payload.
 
 ## Project layout
@@ -162,14 +179,14 @@ Response envelope: `{ "ok": true, "action": "filter", "result_json": "{...}" }`.
 assets/                # brand mark (SVG/PNG); baked into MCP icons via data URI
 docs/                  # architecture notes
 examples/              # sample MCP tool-call JSON payloads
-testdata/              # eval fixtures (noisy logs, cargo fail, …)
+testdata/              # eval fixtures (logs, audit, PR JSON, untrusted paste, …)
 src/
   main.rs              # CLI: stdio | http
   lib.rs
   brand.rs             # SEP-973 icons for serverInfo + tool
   config.rs            # COMPENDIUM_* env config
   server/              # MCP tool + resources + action handlers (rmcp)
-  http.rs              # Streamable HTTP/SSE (feature = "http")
+  http.rs              # Streamable HTTP, sessionless (feature = "http")
   pipeline/
     brief/             # workspace brief (walk / window / pack / synthesize)
     tokens.rs          # heuristic or tiktoken BPE (feature = "real-tokens")
@@ -192,7 +209,7 @@ tests/
   e2e_smoke.rs         # spawns binary, MCP handshake, tools + resources
   eval_regression.rs   # B1 heuristic quality + latency smoke
 CHANGELOG.md
-REPORT.md              # design essay + Shipped/Next/Deferred roadmap
+REPORT.md              # design essay + Shipped (A–C) / Next ops / Deferred roadmap
 ```
 
 ## Build
@@ -392,7 +409,7 @@ cargo test --test e2e_smoke
 cargo run --features http -- http 127.0.0.1:8788
 ```
 
-`e2e_smoke` spawns `CARGO_BIN_EXE_compendium`, completes the MCP initialize handshake over stdio, lists tools, then calls gateway actions. `http_smoke` (requires `--features http`) exercises streamable HTTP in-process.
+`e2e_smoke` spawns `CARGO_BIN_EXE_compendium`, completes MCP connect (legacy initialize) over stdio, lists tools, then calls gateway actions. `http_smoke` (requires `--features http`) exercises sessionless streamable HTTP in-process.
 
 ## Design notes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compendium-mcp",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "MCP server that compresses, summarizes, and filters context to minimize LLM token usage",
   "license": "MIT",
   "keywords": [
@@ -34,17 +34,21 @@
     "LICENSE"
   ],
   "scripts": {
-    "prepack": "node npm/scripts/check-wrapper.js",
+    "check-npm-gates": "node npm/scripts/check-versions-selftest.js && node npm/scripts/check-versions.js && node npm/scripts/check-residual-npm.js",
+    "check-versions": "node npm/scripts/check-versions.js",
+    "check-versions-selftest": "node npm/scripts/check-versions-selftest.js",
+    "check-residual-npm": "node npm/scripts/check-residual-npm.js",
+    "prepack": "node npm/scripts/check-wrapper.js && node npm/scripts/check-versions.js",
     "prepare": "node npm/scripts/link-bins.js"
   },
   "optionalDependencies": {
-    "compendium-mcp-darwin-arm64": "0.6.0",
-    "compendium-mcp-darwin-x64": "0.6.0",
-    "compendium-mcp-linux-x64": "0.6.0",
-    "compendium-mcp-linux-x64-musl": "0.6.0",
-    "compendium-mcp-linux-arm64": "0.6.0",
-    "compendium-mcp-win32-x64": "0.6.0",
-    "compendium-mcp-win32-arm64": "0.6.0"
+    "compendium-mcp-darwin-arm64": "0.6.2",
+    "compendium-mcp-darwin-x64": "0.6.2",
+    "compendium-mcp-linux-x64": "0.6.2",
+    "compendium-mcp-linux-x64-musl": "0.6.2",
+    "compendium-mcp-linux-arm64": "0.6.2",
+    "compendium-mcp-win32-x64": "0.6.2",
+    "compendium-mcp-win32-arm64": "0.6.2"
   },
   "preferUnplugged": true
 }