compaction-mcp

A portable MCP stdio server that brings Claude Code's /compact lifecycle to any MCP host — GitHub Copilot (VS Code), Claude Desktop, or a custom local-LLM agent loop (e.g. Qwen-Coder via Ollama).

It exposes context compaction as tools/resources/prompts so the agent can: gauge context pressure, summarize accumulated history into a dense block (a real inference call, not truncation), re-hydrate live files from disk, persist session-long rules and a verification ledger across the compact_boundary, and run PreCompact/PostCompact hooks.

See SPEC.md for the full protocol design and the host/server responsibility split, ENTERPRISE.md for deploying under GitHub Copilot Enterprise (org policy gates, MCP registry, in-tenant summarizer, distribution), and runbooks/ for step-by-step operational guides for each strategy (offload, recall, compact, re-seed, auto-compact, hooks/ledger).

Why a server can't just "do" /compact

In Claude Code, /compact is host-level — the CLI owns the context window. An MCP server doesn't. So this server provides the mechanism (summarize, re-hydrate, persist, snapshot ledger) and returns a compacted context block; the host installs that block as its new ground truth and discards pre-boundary history. Read §1 of the spec first.

Install

npm install
npm run build      # → dist/index.js

Configuration (env)

Var	Default	Purpose
COMPACTION_SUMMARIZER	direct	direct | sampling | auto (§6 of spec)
COMPACTION_LLM_BASE_URL	http://localhost:11434/v1	OpenAI-compatible endpoint (Ollama)
COMPACTION_LLM_MODEL	qwen2.5-coder:14b	summarizer model
COMPACTION_LLM_API_KEY	—	optional bearer token
COMPACTION_LLM_HEADERS	—	JSON of extra request headers (Azure api-key, gateway/tenant headers); overrides Bearer
COMPACTION_MODE	passthrough	passthrough (host owns history) | store (server holds it)
COMPACTION_STATE_DIR	~/.compaction-mcp/sessions	session + ledger persistence
COMPACTION_ALLOWED_ROOTS	cwd	colon-separated roots for file re-hydration
COMPACTION_HOOKS	—	path to hooks JSON (see examples/hooks.example.json)
COMPACTION_HOOKS_ENABLED	true	set false to disable all hook execution
COMPACTION_TOKEN_BUDGET	128000	default window size when host doesn't declare one
COMPACTION_AUTO	false	auto-compact on ingest when pressure ≥ nowPct (store mode only)
COMPACTION_RECALL_MODE	auto	auto | embed | lexical — recall ranking strategy
COMPACTION_EMBED_MODEL	—	embeddings model for semantic recall (e.g. nomic-embed-text); enables embed
COMPACTION_EMBED_BASE_URL	= LLM base URL	OpenAI-compatible /embeddings endpoint

Manual vs auto

The server is manual by default — it only acts when a tool is called. context_status tells you when to compact, but the host decides.

For deterministic auto behavior, use COMPACTION_MODE=store + COMPACTION_AUTO=true: turn_add then checks pressure after each turn and, once it crosses the compact-now threshold, runs compaction inline and returns the block under autoCompacted. Your agent loop just installs autoCompacted whenever it's present. Passthrough mode stays manual (the server doesn't hold continuous history).

Summarizer choice (important)

• direct works on every host (incl. Copilot) — the server calls the LLM itself. Point it at Ollama for fully local operation.
• sampling needs a sampling-capable host (Claude Desktop). Copilot does not support sampling — don't use it there.
• auto uses sampling if the client offers it, else falls back to direct.

Host setup

GitHub Copilot (VS Code) — .vscode/mcp.json

Copilot is tools-only, so use passthrough mode + direct summarizer (Ollama):

{
  "servers": {
    "compaction": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/compaction-mcp/dist/index.js"],
      "env": {
        "COMPACTION_SUMMARIZER": "direct",
        "COMPACTION_LLM_BASE_URL": "http://localhost:11434/v1",
        "COMPACTION_LLM_MODEL": "qwen2.5-coder:14b",
        "COMPACTION_MODE": "passthrough",
        "COMPACTION_ALLOWED_ROOTS": "${workspaceFolder}"
      }
    }
  }
}

Then instruct Copilot (e.g. in .github/copilot-instructions.md): when the conversation grows long, call context_compact with the recent history as transcript, then continue from the returned summary + rehydratedFiles + persistentRules.

No Ollama? (Copilot-only) Copilot doesn't lend its model to MCP servers (no sampling), so direct must point at some OpenAI-compatible endpoint. Easiest for a Copilot user is GitHub Models (free, OpenAI-compatible) — see examples/vscode-mcp.github-models.json. It uses VS Code's inputs to prompt for a GitHub token (scope models: read) once and store it encrypted. Any other OpenAI-compatible provider (OpenAI, OpenRouter, Groq, …) works the same way — just change COMPACTION_LLM_BASE_URL / COMPACTION_LLM_MODEL.

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "compaction": {
      "command": "node",
      "args": ["/abs/path/compaction-mcp/dist/index.js"],
      "env": { "COMPACTION_SUMMARIZER": "auto" }
    }
  }
}

auto lets Claude Desktop run the summary via sampling (same model, no extra infra).

Enterprise (internal LLM gateway)

Point direct at your company's OpenAI-compatible gateway (LiteLLM, Portkey, Kong/Cloudflare AI Gateway, or Azure OpenAI fronted by one) so code + transcripts stay in-tenant. Non-Bearer auth goes in COMPACTION_LLM_HEADERS (e.g. Azure's {"api-key": "..."}). See examples/vscode-mcp.enterprise-gateway.json. Raw Azure OpenAI isn't drop-in (its URL is /openai/deployments/{d}/chat/completions?api-version=…), so front it with a gateway rather than pointing the server at it directly.

On a Copilot Enterprise/Business plan there are also org-policy gates that block MCP unless an admin opts in — see ENTERPRISE.md for the full deployment guide.

Custom local-LLM agent loop (full control)

Use COMPACTION_MODE=store: feed each message through turn_add, poll context_status, and call context_compact (no transcript arg) when it returns compact-soon/compact-now.

Tool surface

context_status, context_compact, context_trim, context_clear, turn_add, handoff_brief, read_offloaded, offload_store, offload_fetch, recall, files_track, files_untrack, files_rehydrate, rules_set, rules_append, rules_get, ledger_record, ledger_query, ledger_snapshot.

Resources: compaction://session/{id}, compaction://rules/{id}, compaction://ledger/{id}, compaction://summary/{id}/{boundaryId}, compaction://handoff/{id}, compaction://blob/{handle}.

Keeping the window small: offloading

Re-seed recovers after the window is big; offloading keeps it small in the first place. Instead of dumping a full file or command output into chat, read_offloaded / offload_store stash it and return a short digest + handle; the agent pulls the full body (or a line slice) via offload_fetch only when needed. On Copilot this only helps if the agent uses read_offloaded instead of the native file-read tool. See SPEC.md §10B.

On hosts with their own retrieval (e.g. Augment), add recall { query }: it searches the ledger + offloaded blobs for already-known facts/content so the agent doesn't re-pull the same files. Instruct the agent to recall before querying the codebase. Ranking is semantic when COMPACTION_EMBED_MODEL is set (e.g. Ollama nomic-embed-text), else lexical; auto falls back gracefully. See SPEC.md §10C.

Reclaiming tokens on Copilot: re-seed

On Copilot (passthrough), context_compact produces a great summary but doesn't shrink the live window — the server can't evict the host's messages, so the summary is additive. The way to actually reclaim tokens is re-seed: compact → open a new chat → seed it from handoff_brief → continue. A new chat starts with an empty window.

handoff_brief returns the seed (rules + latest summary + ledger + files to re-open) and always writes it to disk (and to outPath, e.g. .compaction/handoff.md), so a new chat can attach the file even if MCP is blocked for the account. See SPEC.md §10A.

Typical loop (passthrough)

1. rules_set — pin session-long rules (survive every boundary).
2. files_track — list active files to re-hydrate.
3. …work… ledger_record whenever something is verified.
4. context_status → compact-soon? → context_compact { transcript, preserve }.
5. Install the returned block; drop everything before boundary. Continue.

Status

v0.1 scaffold — stub logic is wired end-to-end and typechecks; replace the token estimator (§ estimateTokens) with a real tokenizer and harden hook sandboxing before production. Roadmap in SPEC.md §13.