compendium-mcp 0.1.2 → 0.2.0

package/README.md

@@ -1,5 +1,9 @@
 # Compendium
 
+<p align="center">
+  <img src="assets/logo.svg" alt="Compendium" width="420" />
+</p>
+
 MCP server that **minimizes LLM token usage** by compressing, summarizing, filtering, and chunk-referencing large context before it reaches the model.
 
 Built in Rust with the official [`rmcp`](https://crates.io/crates/rmcp) SDK.
@@ -76,6 +80,8 @@ Binary packaging details for maintainers: [npm/DISTRIBUTION.md](npm/DISTRIBUTION
 ## Community
 
 - [Contributing](CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)
+- [Architecture](docs/architecture.md)
 - [Code of Conduct](CODE_OF_CONDUCT.md)
 - [Security policy](SECURITY.md)
 - [Support](SUPPORT.md)
@@ -110,14 +116,33 @@ Single MCP tool: **`compendium`**. Choose the operation with `action`:
 | `cache_get` | Retrieve by key | `key` |
 | `cache_invalidate` | Drop one key or clear cache | `key?` |
 | `sanitize` | Redact secrets + neutralize IPI phrases | `text`, `sanitize?` |
-| `rerank` | BM25-rank candidates / chunks for a query | `query`, `items` or `text` or chunk `map`, `rerank?` |
-| `brief` | Scan a workspace for task-relevant slices; pack a starter briefing + cache key | `query`, `brief?` (`root`, caps), optional `text` hint |
+| `rerank` | BM25 (+ optional loopback embeddings) rank candidates / chunks | `query`, `items` or `text` or chunk `map`, `rerank?` |
+| `brief` | Scan a workspace; pack a structured starter briefing + cache key | `query`, `brief?` (`root`, caps), optional `text` hint |
+| `catalog` | Short action (+ playbook) ads; prefer before guessing | _(none)_ |
+| `help` | Usage notes for one action (default **compressed**; `force: true` → full) | `id`, `force?` |
+| `playbooks` | List playbook ads | _(none)_ |
+| `playbook` | Load one playbook body | `id` |
+| `pack` | Zip text/files into a bounded archive | `text` or `items`, `pack?` |
+| `unpack` | Unpack zip with size caps into chunks (never runs scripts) | `text` or `key`, `pack?` |
+| `llm_status` | Probe configured local LLM (models; `force` = chat ping) | `force?` |
+
+### Progressive disclosure (skills)
+
+Tool description/instructions stay thin. Discover details on demand:
+
+- **Tool bridge:** `action=catalog` → `action=help` with `id`, or `playbooks` → `playbook`
+- **MCP resources:** `resources/list` / `resources/read` on:
+  - `cmp://skill/index` — JSON index of actions + playbooks
+  - `cmp://skill/action/{name}` — full action help (markdown)
+  - `cmp://skill/playbook/{id}` — playbook body
+
+Bundled playbooks live under [`playbooks/`](playbooks/). Override/extend with `COMPENDIUM_PLAYBOOKS_DIR` (same `id` wins). Archives honor `COMPENDIUM_ARCHIVE_MAX_BYTES` / `_UNCOMPRESSED` / `_FILES` (defaults 2 MiB / 4 MiB / 50).
 
 Optional on most text actions: `sanitize_input: true` scrubs before processing. Soft payloads under `COMPENDIUM_SIGNAL_MIN_CHARS` (default 1000) bypass `compress` / `summarize` / `summarize_smart` unless `force: true`.
 
 `filter` accepts optional `query` (top-level or `filter.query`) for BM25 line keep. `prune_history` supports `prune.strategy: "afm"` (Critical / Thematic / Distant tiers; distant blob cached for `cache_get`).
 
-`brief` walks `brief.root` (default: process cwd) with `.gitignore` / `.ignore` via the `ignore` crate, BM25-ranks paths and chunks for `query`, then returns a compact `briefing` plus `cache_key` (`cache://brief/…`, also stored in the session cache). Use that briefing to start a fresh agent turn without pasting the whole repo. Optional `COMPENDIUM_BRIEF_ROOT` restricts allowed roots (useful for HTTP). Briefings are sanitized by default.
+`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:
 
@@ -134,14 +159,15 @@ Response envelope: `{ "ok": true, "action": "filter", "result_json": "{...}" }`.
 ## Project layout
 
 ```
-package.json / bin/run.js  # npm wrapper for npx compendium-mcp
-npm/                       # platform packages + distribution docs
-.github/workflows/         # release cross-compile + npm publish
+assets/                # brand mark (SVG/PNG); baked into MCP icons via data URI
+docs/                  # architecture notes
+examples/              # sample MCP tool-call JSON payloads
 src/
   main.rs              # CLI: stdio | http
   lib.rs
+  brand.rs             # SEP-973 icons for serverInfo + tool
   config.rs            # COMPENDIUM_* env config
-  server.rs            # MCP tool handlers (rmcp macros)
+  server.rs            # MCP tool + resources handlers (rmcp)
   http.rs              # Streamable HTTP/SSE (feature = "http")
   pipeline/
     tokens.rs          # heuristic or tiktoken BPE (feature = "real-tokens")
@@ -151,13 +177,19 @@ src/
     smart.rs           # summarize_smart + filter_relevant
     local_llm.rs       # OpenAI-compatible local SLM client
     chunk.rs           # chunk + resolve
-    cache.rs           # session key/value cache
+    cache.rs           # session key/value cache (+ optional disk)
+    catalog.rs         # action ads + help (progressive disclosure)
+    playbook.rs        # bundled / dir playbooks
+    pack.rs            # zip pack/unpack with size caps
     stats.rs           # session savings counters
     prune.rs           # conversation history pruning
     output.rs          # domain-aware compress_output
+playbooks/             # embedded skill-md playbooks
 tests/
   integration.rs
-  e2e_smoke.rs         # spawns binary, MCP handshake, all tools
+  e2e_smoke.rs         # spawns binary, MCP handshake, tools + resources
+CHANGELOG.md
+REPORT.md              # design essay + Shipped/Next/Deferred roadmap
 ```
 
 ## Build
@@ -235,10 +267,20 @@ Point an MCP streamable-HTTP client at that URL (e.g. `StreamableHttpClientTrans
 | `COMPENDIUM_HTTP_BIND` | `127.0.0.1:8788` | Default HTTP listen address |
 | `COMPENDIUM_LOCAL_LLM_URL` | _(unset)_ | OpenAI-compatible base URL (e.g. `http://127.0.0.1:11434/v1` or `http://127.0.0.1:13305/api/v1`). Enables smart actions. |
 | `COMPENDIUM_LOCAL_LLM_MODEL` | `Qwen3-4B-GGUF` | Model id on that server (Ollama: e.g. `qwen:latest`) |
+| `COMPENDIUM_LOCAL_EMBED_MODEL` | _(same as chat)_ | Embeddings model for hybrid `rerank` / `brief` (e.g. `nomic-embed-text`) |
+| `COMPENDIUM_HYBRID_ALPHA` | `0.55` | BM25 weight in hybrid score (0–1); remainder is embedding cosine |
+| `COMPENDIUM_AUDIT_PATH` | _(unset)_ | Append-only JSONL audit log (action metadata only; no payloads) |
 | `COMPENDIUM_LOCAL_LLM_API_KEY` | _(unset)_ | Optional bearer token for locked loopback servers |
 | `COMPENDIUM_LOCAL_LLM_TIMEOUT_SECS` | `120` | HTTP timeout (first model load can be slow) |
 | `COMPENDIUM_SIGNAL_MIN_CHARS` | `1000` | Bypass compress/summarize below this length (`0` disables) |
 | `COMPENDIUM_BRIEF_ROOT` | _(unset)_ | When set, `action=brief` may only scan roots under this canonical path |
+| `COMPENDIUM_PLAYBOOKS_DIR` | _(unset)_ | Extra/override playbook `*.md` directory (same `id` replaces embedded) |
+| `COMPENDIUM_ARCHIVE_MAX_BYTES` | `2097152` | Max compressed archive size for pack/unpack |
+| `COMPENDIUM_ARCHIVE_MAX_UNCOMPRESSED` | `4194304` | Max total uncompressed bytes for pack/unpack |
+| `COMPENDIUM_ARCHIVE_MAX_FILES` | `50` | Max files per archive |
+| `COMPENDIUM_SKILL_TTL_MS` | `300000` | Soft TTL (ms) on skill `resources/read` responses |
+| `COMPENDIUM_CACHE_DIR` | _(unset)_ | Persist session cache (chunks/cache keys) across restarts; default size cap 64 MiB |
+| `COMPENDIUM_CACHE_MAX_BYTES` | _(unset / 64MiB with dir)_ | Soft cap on total cached payload bytes |
 | `RUST_LOG` | `compendium=info` | Logs on **stderr** only |
 
 ## Example tool calls
@@ -319,7 +361,7 @@ Without `COMPENDIUM_LOCAL_LLM_URL`, `summarize_smart` / `filter_relevant` automa
 }
 ```
 
-Start the new turn with the returned `briefing` (or `cache_get` the `cache_key`). The host should not paste the whole tree into the prompt first.
+Start the new turn with the returned `briefing` (or `cache_get` the `cache_key`). The host should not paste the whole tree into the prompt first. Treat Status as a starter synthesis — verify Caveats and Read next before large edits.
 
 ## Local small language model
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compendium-mcp",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "MCP server that compresses, summarizes, and filters context to minimize LLM token usage",
   "license": "MIT",
   "keywords": [
@@ -38,11 +38,11 @@
     "prepare": "node npm/scripts/link-bins.js"
   },
   "optionalDependencies": {
-    "compendium-mcp-darwin-arm64": "0.1.2",
-    "compendium-mcp-darwin-x64": "0.1.2",
-    "compendium-mcp-linux-x64": "0.1.2",
-    "compendium-mcp-linux-arm64": "0.1.2",
-    "compendium-mcp-win32-x64": "0.1.2"
+    "compendium-mcp-darwin-arm64": "0.2.0",
+    "compendium-mcp-darwin-x64": "0.2.0",
+    "compendium-mcp-linux-x64": "0.2.0",
+    "compendium-mcp-linux-arm64": "0.2.0",
+    "compendium-mcp-win32-x64": "0.2.0"
   },
   "preferUnplugged": true
 }