Crate sqz_mcp 

sqz-mcp

MCP (Model Context Protocol) context-compression server and proxy for AI coding agents. A thin adapter over sqz_engine that compresses tool results before they enter the model’s context window: deterministic, no LLM calls, offline, and every compressed result is recoverable byte-exact.

Works with any MCP client: Claude Code, Cursor, Windsurf, Cline, Gemini CLI, Kiro, OpenCode, Codex CLI, Zed, Copilot CLI. sqz init (from the sqz-cli crate) registers it for every client it finds. Published on the official MCP Registry as io.github.ojuschugh1/sqz.

Tools

Tool	Purpose
sqz_read_file	Read a file faithfully; a repeat read of unchanged content returns a ~13-token §ref:HASH§, a re-read after a small edit returns a line-level delta. Output is capped at 256 KB, cut on a line boundary, with continue_with_offset in the header
sqz_grep	Literal or regex search, path:lineno:text output, capped at max_matches hits and 100 KB; lines over 400 chars are clipped around the hit
sqz_list_dir	Directory listing that skips .git, node_modules, target, dist, build, vendor; capped at 1000 entries
compress	Run arbitrary text through the full sqz pipeline (per-command formatters, log folding, JSON compaction, session dedup)
passthrough	Return text unchanged (escape hatch for models that cannot parse §ref§ tokens)
expand	Resolve a §ref:HASH§ token or hex prefix to the original bytes
sqz_recall	Full-text search over everything sqz has compressed in past sessions

The read, grep and list tools are lossless: their savings come from the dedup cache, not from dropping content. When a size cap cuts output the header says so.

Proxy: compress any other MCP server

sqz-mcp proxy -- <upstream command...> wraps a stdio MCP server and, on the way back to the client, compresses tools/call text results, compacts tools/list descriptions, and injects an sqz_expand tool for recovery. --lazy-tools shortens every description to one sentence and adds an sqz_tool_help tool that serves the full documentation on demand; --no-desc keeps descriptions verbatim; --no-cache disables dedup refs. Error results, non-text content and every client-to-server message pass through untouched. See proxy.

Running the server

sqz-mcp                                   # stdio, the default for MCP clients
sqz-mcp --transport sse --port 3002       # SSE for network use
sqz-mcp --preset-dir ~/.sqz/presets       # hot-reloaded .toml presets
sqz-mcp proxy --lazy-tools -- npx -y @modelcontextprotocol/server-github

Set SQZ_DB_PATH to keep the dedup cache and stats per project instead of in ~/.sqz/sessions.db.

MCP protocol

• initialize — returns server capabilities
• tools/list — returns registered tools (optionally filtered by intent; with an intent parameter the built-in ToolSelector ranks tools by similarity and returns the top matches)
• tools/call — dispatches to the tools above

Further reading

• MCP context compression guide
• Quality benchmark: compression ratio vs information preservation
• How to stop AI coding agents from re-reading the same files
• Repository

Modules

proxy

MCP compression proxy: wrap any upstream MCP server and compress its tool responses through the sqz engine.

Structs

McpServer

MCP server that wraps SqzEngine and exposes tool calls over stdio or SSE.

ToolCallRequest

An incoming MCP tool-call request. Contains the tool ID, input arguments, and an optional intent string for tool filtering.

ToolCallResponse

The result of processing an MCP tool call. Includes the compressed output and before/after token counts so the caller can see the savings.

Enums

McpTransport

Transport mode for the MCP server.

Functions

default_tool_definitions

Returns the default set of MCP tool definitions registered at startup.