compendium-mcp 0.1.0 → 0.1.2

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 +101 -39
  2. package/package.json +10 -8
package/README.md CHANGED
@@ -4,29 +4,81 @@ MCP server that **minimizes LLM token usage** by compressing, summarizing, filte
4
4
 
5
5
  Built in Rust with the official [`rmcp`](https://crates.io/crates/rmcp) SDK.
6
6
 
7
- ## Install via npm / npx
7
+ ## Quick start (Cursor)
8
8
 
9
- Package name: **`compendium-mcp`** (the npm name `compendium` is taken). CLI bin: `compendium`.
9
+ You need **Node.js 18+**. Compendium itself arrives via npm — no Rust install required.
10
+
11
+ ### 1. Add the MCP server
12
+
13
+ Open Cursor MCP settings (`~/.cursor/mcp.json` or the project `.cursor/mcp.json`) and add:
14
+
15
+ ```json
16
+ {
17
+ "mcpServers": {
18
+ "compendium": {
19
+ "command": "npx",
20
+ "args": ["-y", "compendium-mcp"]
21
+ }
22
+ }
23
+ }
24
+ ```
25
+
26
+ Restart MCP / reload Cursor. You should see one tool named **`compendium`**.
27
+
28
+ That alone is enough: filter, compress, summarize, cache, and BM25 actions all work **without** a local model (fast heuristics).
29
+
30
+ ### 2. (Optional) Smarter summaries with Ollama
31
+
32
+ Want better `summarize_smart` / `filter_relevant`? Run a small model on your machine and point Compendium at it.
33
+
34
+ 1. Install [Ollama](https://ollama.com/) and start it (default: `http://127.0.0.1:11434`).
35
+ 2. Pull a chat model, for example:
10
36
 
11
37
  ```bash
12
- npx -y compendium-mcp --help
13
- # or: npm install -g compendium-mcp
38
+ ollama pull qwen:latest
39
+ # or a smaller one: ollama pull qwen2.5:3b
14
40
  ```
15
41
 
16
- **Cursor / Claude Desktop**
42
+ 3. Extend the MCP `env` block (URL must stay on **localhost** — Compendium blocks remote hosts on purpose):
17
43
 
18
44
  ```json
19
45
  {
20
46
  "mcpServers": {
21
47
  "compendium": {
22
48
  "command": "npx",
23
- "args": ["-y", "compendium-mcp"]
49
+ "args": ["-y", "compendium-mcp"],
50
+ "env": {
51
+ "COMPENDIUM_LOCAL_LLM_URL": "http://127.0.0.1:11434/v1",
52
+ "COMPENDIUM_LOCAL_LLM_MODEL": "qwen:latest"
53
+ }
24
54
  }
25
55
  }
26
56
  }
27
57
  ```
28
58
 
29
- Distribution uses **optional platform packages** (`compendium-mcp-darwin-arm64`, …) with a **GitHub Releases download fallback**. See [npm/DISTRIBUTION.md](npm/DISTRIBUTION.md) for local testing, CI release, and publishing.
59
+ 4. Reload MCP, then ask the agent to call `compendium` with `action: "summarize_smart"`.
60
+ In the result, `"backend": "local_llm"` means Ollama answered; `"heuristic"` means it fell back (Ollama down, wrong model name, or URL missing).
61
+
62
+ **Notes**
63
+
64
+ - Package name on npm is **`compendium-mcp`** (`compendium` was already taken). The CLI binary name is still `compendium`.
65
+ - First Ollama reply can be slow while the model loads; later calls are faster.
66
+ - Other local OpenAI-compatible servers work the same way (e.g. Lemonade `http://127.0.0.1:13305/api/v1`). See [Environment](#environment).
67
+
68
+ Smoke-check from a terminal (any folder **except** this git repo root is fine):
69
+
70
+ ```bash
71
+ npx -y compendium-mcp --help
72
+ ```
73
+
74
+ Binary packaging details for maintainers: [npm/DISTRIBUTION.md](npm/DISTRIBUTION.md).
75
+
76
+ ## Community
77
+
78
+ - [Contributing](CONTRIBUTING.md)
79
+ - [Code of Conduct](CODE_OF_CONDUCT.md)
80
+ - [Security policy](SECURITY.md)
81
+ - [Support](SUPPORT.md)
30
82
 
31
83
  ## Transports
32
84
 
@@ -59,11 +111,14 @@ Single MCP tool: **`compendium`**. Choose the operation with `action`:
59
111
  | `cache_invalidate` | Drop one key or clear cache | `key?` |
60
112
  | `sanitize` | Redact secrets + neutralize IPI phrases | `text`, `sanitize?` |
61
113
  | `rerank` | BM25-rank candidates / chunks for a query | `query`, `items` or `text` or chunk `map`, `rerank?` |
114
+ | `brief` | Scan a workspace for task-relevant slices; pack a starter briefing + cache key | `query`, `brief?` (`root`, caps), optional `text` hint |
62
115
 
63
116
  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`.
64
117
 
65
118
  `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`).
66
119
 
120
+ `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.
121
+
67
122
  Example:
68
123
 
69
124
  ```json
@@ -123,27 +178,27 @@ cargo build --release --features real-tokens,http
123
178
 
124
179
  Binary: `target/release/compendium`
125
180
 
126
- ## Configure (Cursor / Claude Desktop)
181
+ ## Configure (advanced)
182
+
183
+ The [Quick start](#quick-start-cursor) config is enough for most people. Extra options:
127
184
 
128
- ### Cursor (`~/.cursor/mcp.json` or project `.cursor/mcp.json`)
185
+ ### Claude Desktop
186
+
187
+ Same `command` / `args` / `env` as Cursor, in Claude’s MCP config file.
188
+
189
+ ### Optional tuning env
129
190
 
130
191
  ```json
131
- {
132
- "mcpServers": {
133
- "compendium": {
134
- "command": "npx",
135
- "args": ["-y", "compendium-mcp"],
136
- "env": {
137
- "RUST_LOG": "compendium=info",
138
- "COMPENDIUM_DEFAULT_MAX_TOKENS": "2048",
139
- "COMPENDIUM_TOKENIZER": "cl100k_base"
140
- }
141
- }
142
- }
192
+ "env": {
193
+ "RUST_LOG": "compendium=info",
194
+ "COMPENDIUM_DEFAULT_MAX_TOKENS": "2048",
195
+ "COMPENDIUM_TOKENIZER": "cl100k_base",
196
+ "COMPENDIUM_LOCAL_LLM_URL": "http://127.0.0.1:11434/v1",
197
+ "COMPENDIUM_LOCAL_LLM_MODEL": "qwen:latest"
143
198
  }
144
199
  ```
145
200
 
146
- Or point at a local release binary:
201
+ ### Local Cargo binary (developers)
147
202
 
148
203
  ```json
149
204
  {
@@ -152,9 +207,7 @@ Or point at a local release binary:
152
207
  "command": "/absolute/path/to/Compendium/target/release/compendium",
153
208
  "env": {
154
209
  "RUST_LOG": "compendium=info",
155
- "COMPENDIUM_DEFAULT_MAX_TOKENS": "2048",
156
- "COMPENDIUM_CHARS_PER_TOKEN": "4.0",
157
- "COMPENDIUM_TOKENIZER": "cl100k_base"
210
+ "COMPENDIUM_DEFAULT_MAX_TOKENS": "2048"
158
211
  }
159
212
  }
160
213
  }
@@ -181,10 +234,11 @@ Point an MCP streamable-HTTP client at that URL (e.g. `StreamableHttpClientTrans
181
234
  | `COMPENDIUM_SIMILARITY_THRESHOLD` | `0.85` | Jaccard line-dedupe threshold |
182
235
  | `COMPENDIUM_HTTP_BIND` | `127.0.0.1:8788` | Default HTTP listen address |
183
236
  | `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. |
184
- | `COMPENDIUM_LOCAL_LLM_MODEL` | `Qwen3-4B-GGUF` | Model id accepted by the local server |
237
+ | `COMPENDIUM_LOCAL_LLM_MODEL` | `Qwen3-4B-GGUF` | Model id on that server (Ollama: e.g. `qwen:latest`) |
185
238
  | `COMPENDIUM_LOCAL_LLM_API_KEY` | _(unset)_ | Optional bearer token for locked loopback servers |
186
239
  | `COMPENDIUM_LOCAL_LLM_TIMEOUT_SECS` | `120` | HTTP timeout (first model load can be slow) |
187
240
  | `COMPENDIUM_SIGNAL_MIN_CHARS` | `1000` | Bypass compress/summarize below this length (`0` disables) |
241
+ | `COMPENDIUM_BRIEF_ROOT` | _(unset)_ | When set, `action=brief` may only scan roots under this canonical path |
188
242
  | `RUST_LOG` | `compendium=info` | Logs on **stderr** only |
189
243
 
190
244
  ## Example tool calls
@@ -250,26 +304,34 @@ Prefer the returned `index_text` in the model context; pull individual chunk con
250
304
 
251
305
  Without `COMPENDIUM_LOCAL_LLM_URL`, `summarize_smart` / `filter_relevant` automatically use heuristics and set `backend: "heuristic"` plus `fallback_reason` in the result.
252
306
 
253
- ## Local small language model
254
-
255
- Smart actions call a **loopback-only** OpenAI-compatible chat endpoint — never a cloud API. `COMPENDIUM_LOCAL_LLM_URL` must be `127.0.0.1`, `::1`, or `localhost` (SSRF guard). Requests use `temperature=0` and `seed=0` for stable outputs. Point Compendium at Ollama, Lemonade, or llama.cpp:
307
+ **Pack a workspace briefing for a fresh agent turn**
256
308
 
257
309
  ```json
258
310
  {
259
- "mcpServers": {
260
- "compendium": {
261
- "command": "npx",
262
- "args": ["-y", "compendium-mcp"],
263
- "env": {
264
- "COMPENDIUM_LOCAL_LLM_URL": "http://127.0.0.1:11434/v1",
265
- "COMPENDIUM_LOCAL_LLM_MODEL": "qwen2.5:3b"
266
- }
267
- }
311
+ "action": "brief",
312
+ "query": "fix the OAuth refresh token path",
313
+ "brief": {
314
+ "root": "/path/to/repo",
315
+ "max_files": 40,
316
+ "top_k_chunks": 12,
317
+ "max_brief_tokens": 2048
268
318
  }
269
319
  }
270
320
  ```
271
321
 
272
- Lemonade example: `COMPENDIUM_LOCAL_LLM_URL=http://127.0.0.1:13305/api/v1` and `COMPENDIUM_LOCAL_LLM_MODEL=Qwen3-4B-GGUF`.
322
+ 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.
323
+
324
+ ## Local small language model
325
+
326
+ Follow [Quick start §2](#2-optional-smarter-summaries-with-ollama) for Ollama.
327
+
328
+ Rules of thumb:
329
+
330
+ - **Only loopback** URLs (`127.0.0.1`, `::1`, `localhost`) — no cloud endpoints.
331
+ - Without `COMPENDIUM_LOCAL_LLM_URL`, smart actions use heuristics and set `backend: "heuristic"`.
332
+ - Calls use `temperature=0` and `seed=0` for stable outputs.
333
+ - Lemonade example: `COMPENDIUM_LOCAL_LLM_URL=http://127.0.0.1:13305/api/v1` and `COMPENDIUM_LOCAL_LLM_MODEL=Qwen3-4B-GGUF`.
334
+ - llama.cpp OpenAI server: same pattern — set URL to its `/v1` base and the served model id.
273
335
 
274
336
  ## Develop / test
275
337
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "compendium-mcp",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "MCP server that compresses, summarizes, and filters context to minimize LLM token usage",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -24,7 +24,8 @@
24
24
  "node": ">=18"
25
25
  },
26
26
  "bin": {
27
- "compendium": "bin/run.js"
27
+ "compendium": "bin/run.js",
28
+ "compendium-mcp": "bin/run.js"
28
29
  },
29
30
  "files": [
30
31
  "bin/",
@@ -33,14 +34,15 @@
33
34
  "LICENSE"
34
35
  ],
35
36
  "scripts": {
36
- "prepack": "node npm/scripts/check-wrapper.js"
37
+ "prepack": "node npm/scripts/check-wrapper.js",
38
+ "prepare": "node npm/scripts/link-bins.js"
37
39
  },
38
40
  "optionalDependencies": {
39
- "compendium-mcp-darwin-arm64": "0.1.0",
40
- "compendium-mcp-darwin-x64": "0.1.0",
41
- "compendium-mcp-linux-x64": "0.1.0",
42
- "compendium-mcp-linux-arm64": "0.1.0",
43
- "compendium-mcp-win32-x64": "0.1.0"
41
+ "compendium-mcp-darwin-arm64": "0.1.2",
42
+ "compendium-mcp-darwin-x64": "0.1.2",
43
+ "compendium-mcp-linux-x64": "0.1.2",
44
+ "compendium-mcp-linux-arm64": "0.1.2",
45
+ "compendium-mcp-win32-x64": "0.1.2"
44
46
  },
45
47
  "preferUnplugged": true
46
48
  }