compendium-mcp 0.6.1 → 0.6.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +37 -29
  2. package/package.json +8 -8
package/README.md CHANGED
@@ -8,6 +8,21 @@ MCP server that **minimizes LLM token usage** by compressing, summarizing, filte
8
8
 
9
9
  Built in Rust with the official [`rmcp`](https://crates.io/crates/rmcp) SDK.
10
10
 
11
+ ## Why / when to use Compendium
12
+
13
+ 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.
14
+
15
+ | Situation | Call |
16
+ |-----------|------|
17
+ | Unsure which action | `catalog` → `help` + `id` (or read `cmp://skill/…`) |
18
+ | New task in a repo | `brief` with a short `query` |
19
+ | Noisy terminal / CLI dump | `filter` (generic) or `compress_output` (cargo/npm/docker/git/…) |
20
+ | Bulky text/JSON to densify | `compress` (small inputs bypass unless `force`) |
21
+ | Untrusted paste / secrets / IPI | `sanitize` (or `sanitize_input: true` on the next action) |
22
+ | Guided recipe | `playbooks` → `playbook` |
23
+
24
+ Heuristic paths work with **no local model**. Optional loopback LLM improves `summarize_smart` / hybrid `rerank` / smart `filter_relevant`.
25
+
11
26
  ## Quick start (Cursor)
12
27
 
13
28
  You need **Node.js 18+**. Compendium itself arrives via npm — no Rust install required.
@@ -33,35 +48,23 @@ That alone is enough: filter, compress, summarize, cache, and BM25 actions all w
33
48
 
34
49
  ### 2. (Optional) Smarter summaries with Ollama
35
50
 
36
- Want better `summarize_smart` / `filter_relevant`? Run a small model on your machine and point Compendium at it.
37
-
38
- 1. Install [Ollama](https://ollama.com/) and start it (default: `http://127.0.0.1:11434`).
39
- 2. Pull a chat model, for example:
51
+ Want better `summarize_smart` / `filter_relevant` / hybrid `rerank`? One command after the MCP server is added:
40
52
 
41
53
  ```bash
42
- ollama pull qwen:latest
43
- # or a smaller one: ollama pull qwen2.5:3b
54
+ npx -y compendium-mcp setup-ollama --write-mcp
44
55
  ```
45
56
 
46
- 3. Extend the MCP `env` block (URL must stay on **localhost** — Compendium blocks remote hosts on purpose):
57
+ That detects (or `--install`s) [Ollama](https://ollama.com/), pulls a small chat + embed model (`qwen2.5:3b` + `nomic-embed-text`), probes loopback `http://127.0.0.1:11434/v1`, and merges `COMPENDIUM_LOCAL_LLM_*` into `~/.cursor/mcp.json`. Use `--project` for `.cursor/mcp.json`. Reload MCP, then `action: "llm_status"` should show `reachable: true`. `"backend": "local_llm"` on smart actions means Ollama answered; `"heuristic"` means it fell back.
47
58
 
48
- ```json
49
- {
50
- "mcpServers": {
51
- "compendium": {
52
- "command": "npx",
53
- "args": ["-y", "compendium-mcp"],
54
- "env": {
55
- "COMPENDIUM_LOCAL_LLM_URL": "http://127.0.0.1:11434/v1",
56
- "COMPENDIUM_LOCAL_LLM_MODEL": "qwen:latest"
57
- }
58
- }
59
- }
60
- }
59
+ ```bash
60
+ npx -y compendium-mcp setup-ollama --help
61
+ npx -y compendium-mcp setup-ollama --install --write-mcp --project
62
+ npx -y compendium-mcp setup-ollama --dry-run --json
61
63
  ```
62
64
 
63
- 4. Reload MCP, then ask the agent to call `compendium` with `action: "summarize_smart"`.
64
- In the result, `"backend": "local_llm"` means Ollama answered; `"heuristic"` means it fell back (Ollama down, wrong model name, or URL missing).
65
+ Agent recipe: playbook `setup-ollama` (`cmp://skill/playbook/setup-ollama`).
66
+
67
+ Manual / Lemonade / custom models: set `COMPENDIUM_LOCAL_LLM_URL` yourself (must stay on **localhost** — Compendium blocks remote hosts on purpose). See [Environment](#environment).
65
68
 
66
69
  **Notes**
67
70
 
@@ -92,12 +95,13 @@ Binary packaging details for maintainers: [npm/DISTRIBUTION.md](npm/DISTRIBUTION
92
95
  |------|---------|-------|
93
96
  | **stdio** (default) | `compendium` / `compendium stdio` | Cursor / Claude Desktop — dual-compat (legacy initialize or modern connect) |
94
97
  | **Streamable HTTP** | `compendium http [BIND]` | Requires `--features http`. Endpoint: `http://{bind}/mcp`. Sessionless (`2026-07-28`); JSON preferred, SSE fallback |
98
+ | **Ollama setup** | `compendium setup-ollama` | Not an MCP transport — CLI helper (`--write-mcp`, `--dry-run`, `--json`). Alias: `compendium ollama` |
95
99
 
96
100
  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`.
97
101
 
98
102
  ## Tools
99
103
 
100
- Single MCP tool: **`compendium`**. Choose the operation with `action`:
104
+ 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.
101
105
 
102
106
  | `action` | Purpose | Main fields |
103
107
  |----------|---------|-------------|
@@ -144,7 +148,7 @@ Optional on most text actions: `sanitize_input: true` scrubs before processing.
144
148
 
145
149
  `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.
146
150
 
147
- Example:
151
+ Example — noisy log (canonical first call after install):
148
152
 
149
153
  ```json
150
154
  {
@@ -154,6 +158,8 @@ Example:
154
158
  }
155
159
  ```
156
160
 
161
+ Discover more without reading this README: `{"action":"catalog"}` then `{"action":"help","id":"compress_output"}`. Sample payloads: [`examples/`](examples/).
162
+
157
163
  Response envelope: `{ "ok": true, "action": "filter", "result_json": "{...}" }`. Parse `result_json` as JSON for the action-specific payload.
158
164
 
159
165
  ## Project layout
@@ -162,9 +168,10 @@ Response envelope: `{ "ok": true, "action": "filter", "result_json": "{...}" }`.
162
168
  assets/ # brand mark (SVG/PNG); baked into MCP icons via data URI
163
169
  docs/ # architecture notes
164
170
  examples/ # sample MCP tool-call JSON payloads
165
- testdata/ # eval fixtures (noisy logs, cargo fail, …)
171
+ testdata/ # eval fixtures (logs, audit, PR JSON, untrusted paste, …)
166
172
  src/
167
- main.rs # CLI: stdio | http
173
+ main.rs # CLI: stdio | http | setup-ollama
174
+ setup_ollama.rs # `compendium setup-ollama` (detect/pull/probe/write MCP env)
168
175
  lib.rs
169
176
  brand.rs # SEP-973 icons for serverInfo + tool
170
177
  config.rs # COMPENDIUM_* env config
@@ -229,7 +236,8 @@ Same `command` / `args` / `env` as Cursor, in Claude’s MCP config file.
229
236
  "COMPENDIUM_DEFAULT_MAX_TOKENS": "2048",
230
237
  "COMPENDIUM_TOKENIZER": "cl100k_base",
231
238
  "COMPENDIUM_LOCAL_LLM_URL": "http://127.0.0.1:11434/v1",
232
- "COMPENDIUM_LOCAL_LLM_MODEL": "qwen:latest"
239
+ "COMPENDIUM_LOCAL_LLM_MODEL": "qwen2.5:3b",
240
+ "COMPENDIUM_LOCAL_EMBED_MODEL": "nomic-embed-text"
233
241
  }
234
242
  ```
235
243
 
@@ -275,7 +283,7 @@ Point an MCP streamable-HTTP client at that URL (e.g. `StreamableHttpClientTrans
275
283
  | `COMPENDIUM_SIMILARITY_THRESHOLD` | `0.85` | Jaccard line-dedupe threshold |
276
284
  | `COMPENDIUM_HTTP_BIND` | `127.0.0.1:8788` | Default HTTP listen address |
277
285
  | `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. |
278
- | `COMPENDIUM_LOCAL_LLM_MODEL` | `Qwen3-4B-GGUF` | Model id on that server (Ollama: e.g. `qwen:latest`) |
286
+ | `COMPENDIUM_LOCAL_LLM_MODEL` | `Qwen3-4B-GGUF` | Model id on that server (Ollama setup default: `qwen2.5:3b`) |
279
287
  | `COMPENDIUM_LOCAL_EMBED_MODEL` | _(same as chat)_ | Embeddings model for hybrid `rerank` / `brief` (e.g. `nomic-embed-text`) |
280
288
  | `COMPENDIUM_HYBRID_ALPHA` | `0.55` | BM25 weight in hybrid score (0–1); remainder is embedding cosine |
281
289
  | `COMPENDIUM_RERANK_CROSS_ENCODER` | _(off)_ | When `1`/`true`, `rerank` SLM-rescores top-N after BM25/hybrid |
@@ -372,7 +380,7 @@ Start the new turn with the returned `briefing` (or `cache_get` the `cache_key`)
372
380
 
373
381
  ## Local small language model
374
382
 
375
- Follow [Quick start §2](#2-optional-smarter-summaries-with-ollama) for Ollama.
383
+ Follow [Quick start §2](#2-optional-smarter-summaries-with-ollama) (`npx -y compendium-mcp setup-ollama`).
376
384
 
377
385
  Rules of thumb:
378
386
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "compendium-mcp",
3
- "version": "0.6.1",
3
+ "version": "0.6.3",
4
4
  "description": "MCP server that compresses, summarizes, and filters context to minimize LLM token usage",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -42,13 +42,13 @@
42
42
  "prepare": "node npm/scripts/link-bins.js"
43
43
  },
44
44
  "optionalDependencies": {
45
- "compendium-mcp-darwin-arm64": "0.6.1",
46
- "compendium-mcp-darwin-x64": "0.6.1",
47
- "compendium-mcp-linux-x64": "0.6.1",
48
- "compendium-mcp-linux-x64-musl": "0.6.1",
49
- "compendium-mcp-linux-arm64": "0.6.1",
50
- "compendium-mcp-win32-x64": "0.6.1",
51
- "compendium-mcp-win32-arm64": "0.6.1"
45
+ "compendium-mcp-darwin-arm64": "0.6.3",
46
+ "compendium-mcp-darwin-x64": "0.6.3",
47
+ "compendium-mcp-linux-x64": "0.6.3",
48
+ "compendium-mcp-linux-x64-musl": "0.6.3",
49
+ "compendium-mcp-linux-arm64": "0.6.3",
50
+ "compendium-mcp-win32-x64": "0.6.3",
51
+ "compendium-mcp-win32-arm64": "0.6.3"
52
52
  },
53
53
  "preferUnplugged": true
54
54
  }