compaction-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| COMPACTION_AUTO | No | auto-compact on ingest when pressure ≥ nowPct (store mode only) (default: false) | |
| COMPACTION_MODE | No | passthrough | store (default: passthrough) | |
| COMPACTION_HOOKS | No | path to hooks JSON | |
| COMPACTION_LLM_MODEL | No | summarizer model (default: qwen2.5-coder:14b) | |
| COMPACTION_STATE_DIR | No | session + ledger persistence (default: ~/.compaction-mcp/sessions) | |
| COMPACTION_SUMMARIZER | No | direct | sampling | auto (default: direct) | |
| COMPACTION_EMBED_MODEL | No | embeddings model for semantic recall | |
| COMPACTION_LLM_API_KEY | No | optional bearer token | |
| COMPACTION_LLM_HEADERS | No | JSON of extra request headers | |
| COMPACTION_RECALL_MODE | No | auto | embed | lexical (default: auto) | |
| COMPACTION_LLM_BASE_URL | No | OpenAI-compatible endpoint (default: http://localhost:11434/v1) | |
| COMPACTION_TOKEN_BUDGET | No | default window size when host doesn't declare one (default: 128000) | |
| COMPACTION_ALLOWED_ROOTS | No | colon-separated roots for file re-hydration (default: cwd) | |
| COMPACTION_HOOKS_ENABLED | No | set false to disable all hook execution (default: true) | |
| COMPACTION_EMBED_BASE_URL | No | OpenAI-compatible /embeddings endpoint (default: = LLM base URL) |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| context_statusC | Report context pressure and a compaction recommendation (ok | compact-soon | compact-now | at-limit). |
| context_compactA | Summarize accumulated history into a dense block, snapshot the ledger, re-hydrate tracked files, and run Pre/PostCompact hooks. Returns the compacted context block to install as new ground truth. |
| context_trimB | Remove low-value/duplicate tool output without an inference call. Store mode only. |
| context_clearC | Hard reset turns and boundaries. Keeps rules and ledger by default. |
| handoff_briefA | Produce a small, self-contained brief (rules + latest summary + verification ledger + active files) to START A FRESH CHAT with. This is how you actually reclaim tokens on hosts that own their window (e.g. Copilot): open a new chat and seed it with this brief. Always written to disk too, so a new chat can attach the file even if MCP is unavailable. |
| turn_addC | Append a message to the server-held transcript. Store mode only. When COMPACTION_AUTO=true and pressure crosses the compact-now threshold, compaction fires automatically and the compacted block is returned under |
| files_trackA | Mark files to silently re-read from disk on every compaction. |
| files_untrackB | Stop re-hydrating the given files. |
| files_rehydrateB | Read tracked (or given) files from disk and return current contents. |
| read_offloadedA | Read a file from disk and OFFLOAD it: returns a short digest (preview + structural outline + line/byte counts) and a handle, instead of dumping the full contents into the window. Prefer this over a normal file read for large files. Fetch the full body only when needed via offload_fetch or the compaction://blob/{handle} resource. |
| offload_storeA | Stash large text (command output, grep results, logs, API payloads) as a blob and return a digest + handle instead of putting it all in the window. |
| offload_fetchA | Retrieve a blob's full content, or a 1-indexed inclusive line slice. Use the smallest slice that answers the question to keep the window small. |
| recallA | Search the verification ledger + offloaded blobs for already-known facts and content. CALL THIS BEFORE querying the codebase / context engine: a cached fact or a known blob line range avoids pulling whole files back into the window (token saver, esp. on hosts with their own retrieval like Augment). Semantic ranking when embeddings are configured, else lexical. Returns ledger hits + blob hits with line ranges (use with offload_fetch). |
| rules_setA | Replace the CLAUDE.md-equivalent rules that survive every boundary. |
| rules_appendC | Append a rule that survives every boundary. |
| rules_getB | Return the current persistent rules. |
| ledger_recordA | Append an entry to the verification ledger (maker/checker). Survives compaction; verified results are copied verbatim into summaries. |
| ledger_queryB | Filter ledger entries by claim substring and/or result. |
| ledger_snapshotB | Return the full current ledger (used at boundaries for re-injection). |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| compaction_summarize | The summarization instruction used by context_compact. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 19 tools
The tools cover distinct actions across context, files, offloading, rules, and ledger. Some close concepts (context_compact vs context_trim, handoff_brief vs context_compact, recall vs ledger_query) have subtle differences that require careful reading, but the descriptions disambiguate them. Overall, each tool has a specific role.
Most tools follow a resource_verb pattern (context_*, files_*, offload_*, rules_*, ledger_*), but a few outliers like read_offloaded and recall break this pattern. The prefix grouping is helpful and consistent within subgroups, making the set mostly predictable despite a few deviations.
At 19 tools, the set is on the heavier side. While each tool serves a distinct need across multiple subdomains (context, handoff, files, offload, rules, ledger), the number is above the typical 3-15 sweet spot, giving it a sense of bloat. A more focused server could combine some tools or drop rarely used ones.
The set covers the full lifecycle of context management: status, compact, trim, clear, handoff, turn recording, file tracking, offloading, recall, rules, and ledger. Missing operations include offload deletion and explicit restoration of compacted blocks, but these are minor and workarounds exist. Overall the surface is comprehensive.