GitHub - Dukeabaddon/Gate-MCP: Local MCP server that compresses AI-coding context by 89% before it hits the LLM. 5-layer compression (schema/nav/AST/JSON/OCR), 99.1% symbol-recall fidelity, works in every MCP-aware IDE.

Measure and reduce context without hiding fidelity failures.

Gate-MCP — local context compression gateway for AI coding assistants

Gate sits between your agent and the expensive parts of an MCP turn: tool schemas, file bodies, JSON tool results, and screenshots. It compresses what you ask it to, caches unchanged work in SQLite, and labels every savings number with an honest billingScope. Opt-in only — Gate does not intercept editor Read / Bash.

Problem	With Gate-MCP
Fat `tools/list` every turn	Default catalog mode: ~6 tools + `gate_invoke`
Full-file reads for navigation	AST signatures / bounded structure
Re-reading unchanged files	SQLite dedup cache (required `better-sqlite3`)
Huge JSON tool responses	TOON tables when the shape fits
Screenshots eating the window	OCR text or downscale via `gate_optimize_image`

Website · Install · Demo · Benchmarks · Agents · Architecture · Security · Changelog

Token savings are a receipt — fidelity is the product. Gate reports originalTokens / optimizedTokens / savingsPercent on compression tools, forces expanded: true (and 0% “savings”) when output grows, and scopes metrics as billingScope: "tool_payload_only" so nobody mistakes tool JSON size for Cursor billed usage.

See it in action:

Compress
AST signatures with measured %

Navigate
Graph dependents → signature compress

Stats
Measured session tokens + cache

_{Recorded Cursor + Gate MCP demos · silent loop GIFs in assets/.}

Why developers use Gate

Schema budget first — catalog mode attacks the tax every MCP turn pays before you read a single file
Measured, not vibed — compression tools return real BPE counts; inflation is never sold as savings
Navigate then hydrate — symbol graph + optional graphify bridge before full Read
Durable cache — SQLite/WAL dedup across IDE restarts (fail-closed unless you opt into memory)
Local-only — no cloud, no telemetry, path jail under GATE_PROJECT_ROOT

Saves you tokens? Give it a star — it helps others find Gate.

What it does — four layers

Architecture detail: ARCHITECTURE.md.

                        ┌──────────────────────────┐
                        │    YOUR AI ASSISTANT      │
                        │  (Cursor / Claude Code /  │
                        │   Windsurf / Antigravity) │
                        └─────────┬────────────────┘
                                  │
                     ┌────────────▼────────────────┐
                     │           gatemcp            │
                     │  L0  Catalog tool surface    │
                     │  L1  Graph navigation        │
                     │  L2  File compression        │
                     │  L3  Response cleaning       │
                     │  L4  SQLite persistence      │
                     └──────────────────────────────┘

Layer	Job
L0 Schema	`GATE_TOOL_MODE=catalog` (default): `gate_help`, `gate_init`, compress/graph/stats, `gate_invoke`. Set `full` to list every tool.
L1 Graph	In-process tree-sitter symbol graph + optional `graphify-out` bridge (`graphify_map` / `search` / `hubs`). HTML export via `export_html` / `gatemcp graph-html`.
L2 Compress	`gate_compress_file` depths: `signature` / `structure` / `summary` / `full`. Image OCR/downscale.
L3 Clean	`gate_clean_response` TOON; optional MCP proxy (`GATE_ENABLE_PROXY=1`).
L4 Persist	Required `better-sqlite3` WAL DB for dedup + `gate_memory`.

Recommended workflow

gate_init — health, graphify path, cache kind
gate_graph_query (graphify_map or symbol search) — navigate before full reads
gate_compress_file (signature or structure) — hydrate only what you need
gate_session_stats — measured tool-payload work

gate_help with tool: "recommended_stack" is the agent-facing playbook.

What Gate compresses — and what it does not

Gate only shrinks results of Gate tool calls. It is a tool your agent chooses to call, not a filter on the whole conversation.

Gate reduces	Gate does not touch
`tools/list` schema size (catalog mode)	Your prompts and chat history
File views returned by `gate_compress_file`	The editor's built-in `Read` / `Grep` / terminal output
Graph answers from `gate_graph_query`	Rules, system prompt, attached files
Re-reads of unchanged files (SQLite dedup)	Model output — generated code and replies
JSON passed to `gate_clean_response`	Other MCP servers (unless routed through the opt-in proxy)
Images passed to `gate_optimize_image`	Your provider bill — see `billingScope` below

What this means in practice:

If the agent never calls a Gate tool, savings are zero. Add a rule telling your agent to use gate_compress_file before full reads.
An agent footer such as Savings: n/a means no Gate compression ran that turn. It does not mean Gate is broken. Run gate_init to confirm health.
Gate cannot shrink code generation. Smaller input context leaves more room for output, but the output itself is the model's.

Get started (60 seconds)

better-sqlite3 is a required dependency. Install must allow its native build (and the other reviewed native packages below).

npm install -g --strict-allow-scripts \
  --allow-scripts=better-sqlite3,sharp,tesseract.js,tree-sitter,tree-sitter-bash,tree-sitter-c,tree-sitter-c-sharp,tree-sitter-cli,tree-sitter-cpp,tree-sitter-css,tree-sitter-go,tree-sitter-html,tree-sitter-java,tree-sitter-javascript,tree-sitter-json,tree-sitter-kotlin,tree-sitter-php,tree-sitter-python,tree-sitter-ruby,tree-sitter-rust,tree-sitter-svelte,tree-sitter-swift,tree-sitter-typescript,tree-sitter-vue,tree-sitter-yaml \
  @gatemcp/cli

Or without a global install:

npm exec --yes --strict-allow-scripts \
  --allow-scripts=better-sqlite3,sharp,tesseract.js,tree-sitter,tree-sitter-bash,tree-sitter-c,tree-sitter-c-sharp,tree-sitter-cli,tree-sitter-cpp,tree-sitter-css,tree-sitter-go,tree-sitter-html,tree-sitter-java,tree-sitter-javascript,tree-sitter-json,tree-sitter-kotlin,tree-sitter-php,tree-sitter-python,tree-sitter-ruby,tree-sitter-rust,tree-sitter-svelte,tree-sitter-swift,tree-sitter-typescript,tree-sitter-vue,tree-sitter-yaml \
  --package=@gatemcp/cli -- gatemcp

Package: @gatemcp/cli · binary: gatemcp · current: 0.5.8.

Then wire your IDE (Cursor snippet below). Run gate_init once per workspace. Doctor: npx --package=@gatemcp/cli@0.5.8 gatemcp doctor /abs/path/to/repo --strict.

Install from source

git clone https://github.com/Dukeabaddon/Gate-MCP.git
cd Gate-MCP
npm install --strict-allow-scripts \
  --allow-scripts=better-sqlite3,sharp,tesseract.js,tree-sitter,tree-sitter-bash,tree-sitter-c,tree-sitter-c-sharp,tree-sitter-cli,tree-sitter-cpp,tree-sitter-css,tree-sitter-go,tree-sitter-html,tree-sitter-java,tree-sitter-javascript,tree-sitter-json,tree-sitter-kotlin,tree-sitter-php,tree-sitter-python,tree-sitter-ruby,tree-sitter-rust,tree-sitter-svelte,tree-sitter-swift,tree-sitter-typescript,tree-sitter-vue,tree-sitter-yaml
npm run build
npm link

Cursor — .cursor/mcp.json

{
  "mcpServers": {
    "gatemcp": {
      "command": "gatemcp",
      "args": [],
      "env": {
        "GATE_PROJECT_ROOT": "/absolute/path/to/Documents",
        "GATE_CACHE_DB": "/absolute/path/to/Documents/.gate-mcp/cache.db",
        "GATE_TOOL_MODE": "catalog"
      }
    }
  }
}

Cursor may show the server as user-gatemcp — that is normal. Multi-repo: set GATE_PROJECT_ROOT to the trusted parent, pass per-call projectRoot to narrow (never widen).

Pin Node in mcp.json — fixes SQLite NODE_MODULE_VERSION errors

better-sqlite3 is a native module. It is compiled for the Node version that ran npm install. Your IDE may launch MCP servers with a different Node (nvm, Homebrew, Volta, or a GUI app PATH without your shell profile).

Symptoms:

Server fails to start, or gate_init / gate_session_stats shows persistentCache: false
Log line like was compiled against a different Node.js version using NODE_MODULE_VERSION 127. This version of Node.js requires NODE_MODULE_VERSION 137

Fix: point the IDE at the same Node binary that installed Gate. In the terminal where you installed it:

which node                                   # e.g. /Users/you/.nvm/versions/node/v22.21.1/bin/node
echo "$(npm root -g)/@gatemcp/cli/dist/main.js"

Then use both absolute paths:

{
  "mcpServers": {
    "gatemcp": {
      "command": "/Users/you/.nvm/versions/node/v22.21.1/bin/node",
      "args": ["/Users/you/.nvm/versions/node/v22.21.1/lib/node_modules/@gatemcp/cli/dist/main.js"],
      "env": {
        "GATE_PROJECT_ROOT": "/absolute/path/to/your/repo"
      }
    }
  }
}

Verify with the same Node: /path/to/node /path/to/dist/main.js doctor /absolute/path/to/your/repo --strict — cache_access must say SQLite write/reopen probe passed.

If you switch Node versions later, reinstall Gate under the new version (or keep the pin). Avoid GATE_ALLOW_MEMORY_CACHE=1 as a fix — it hides the problem and turns off persistent dedup.

Claude Code / Windsurf / Antigravity / VS Code / Codex

Claude Code — ~/.claude/mcp.json: { "mcpServers": { "gatemcp": { "command": "gatemcp", "args": [] } } }

Windsurf — ~/.codeium/windsurf/mcp_config.json: same mcpServers shape.

Antigravity — .antigravity/mcp.json with MCP_MODE=stdio and DISABLE_CONSOLE_OUTPUT=true.

VS Code Copilot — .vscode/mcp.json uses "servers" (not "mcpServers").

Codex plugin

codex plugin marketplace add Dukeabaddon/Gate-MCP && codex plugin add gatemcp@dukeabaddon-gate-mcp

Restart the thread after install. Plugin pins @gatemcp/cli@0.5.8.

Emergency only: GATE_ALLOW_MEMORY_CACHE=1 skips the startup SQLite module check (tests / broken hosts). Prefer fixing the native install.

Tools

Tool	What it does
`gate_init`	Health: graphify path, SQLite, toolMode, MCP slug hint
`gate_compress_file`	AST signatures / structure / summary / full
`gate_graph_query`	Symbol graph + graphify map/search/hubs + HTML export
`gate_session_stats`	Measured file/byte/token work + cache activity
`gate_help`	Full docs; `tool=recommended_stack`
`gate_invoke`	Catalog escape hatch: call any Gate tool by name
`gate_dedup_context`	Reference-only unchanged check / cache ops
`gate_memory`	Cross-session KV in SQLite
`gate_clean_response`	JSON → TOON
`gate_optimize_image`	OCR or downscale
`gate_proxy_tools` / `gate_proxy_call`	Opt-in downstream MCP compression
`gate_validate_compression`	LLM-in-the-loop quality score (mock for CI)

Compression-oriented tools include originalTokens / optimizedTokens / savingsPercent where applicable. When output grows, expanded: true and savings stay 0.

How to read savings metrics

Field	Meaning
`baseline`	`"file"` \| `"GRAPH_REPORT.md"` \| `"symbol_estimate"`
`billingScope`	`"tool_payload_only"` — not Cursor billed tokens
`expanded: true`	Output grew; `savingsPercent` forced to `0`

Reading `gate_session_stats`

The result has two groups of numbers with different scopes. Do not add them together.

Persistent cache — stored in SQLite, survives IDE restarts, filtered by projectRoot:

Field	Meaning
`persistentCache`	`true` = SQLite. `false` = in-memory fallback; run `gatemcp doctor --strict` (often a Node pin issue)
`cachePartition`	Canonical `GATE_PROJECT_ROOT` the DB belongs to (macOS shows `/private/var` for `/var`)
`projectRoot`	Path filter applied to the totals below
`totalEntries`	Files cached under that path
`totalHits`	Times an unchanged file was served from cache
`totalTokensSaved`	Cumulative raw-file tokens minus cached-view tokens on those hits
`topEntries`	Top 10 files by activity

This MCP process — reset when the server restarts, counts every repo the process served:

Field	Meaning
`files_considered` / `files_compressed`	Files Gate read / returned a smaller view for
`input_bytes` / `output_bytes`	Raw file bytes in vs tool-result bytes out
`estimated_tokens_before` / `estimated_tokens_after`	Same, as BPE token estimates
`cache_hits`	Dedup hits in this process
`elapsed_ms` / `session_elapsed_ms`	Gate processing time / server uptime

Labels on every result:

measurement_scope: "serialized_tool_result_excluding_mcp_envelope" — what was measured.
billingScope: "tool_payload_only" — not your Cursor / provider bill. Your bill also includes prompts, history, rules, other tools, and model output.

Example from one real session: estimated_tokens_before: 6622, estimated_tokens_after: 666 → Gate tool results were ~90% smaller than the raw files. That is the honest claim; it is not "90% off your bill".

Multi-repo / one global MCP

Setting	Guidance
`GATE_PROJECT_ROOT`	Trusted parent directory
`GATE_CACHE_DB`	SQLite file inside that parent
Per-call `projectRoot`	Active child repo; narrow-only
Omitting `projectRoot` on dedup `clear`	Wipes the entire partition

Supported IDEs & AI tools

Gate is a standard MCP server (stdio). There is no shell-hook / Hybrid mode — savings only land when the agent calls Gate tools (or you teach it via rules / AGENTS.md).

Mode	How it works	Best for
MCP	Agent calls `gate_*` tools	Any MCP client
Catalog	Small `tools/list` + `gate_invoke`	Default (recommended)
Full	Every tool listed	Debugging only

Agent compatibility matrix

Agent	MCP	Catalog	Setup
Cursor	●	●	`.cursor/mcp.json` → `gatemcp`
Claude Code	●	●	`~/.claude/mcp.json`
Codex	●	●	`codex plugin add gatemcp@…`
Windsurf	●	●	Windsurf MCP config
Antigravity	●	●	`.antigravity/mcp.json`
VS Code Copilot	●	●	`.vscode/mcp.json` (`servers`)
Cline / Roo / Continue / Zed	●	●	Generic stdio MCP
JetBrains / Neovim / Emacs	●	●	MCP-capable plugin + `gatemcp`

Any MCP-compatible client works. Hybrid shell interception is intentionally out of scope (see Architecture).

When to use (and when not to)

Great fit if you…

live in MCP-heavy agents (Cursor, Claude Code, Codex) and pay schema tax
work in medium/large repos and can navigate via graph → signature
want local, measurable compression without installing a full context OS

Skip it (or pair carefully) if you…

need transparent shell/git compression on every agent command → that is LeanCTX Hybrid territory
need an LLM request proxy that shrinks full chat history on the wire
never teach the agent to call Gate (opt-in = zero savings)

Demo

# After MCP is connected
# 1) gate_init
# 2) gate_compress_file { filePath: "src/main.ts", depth: "signature" }
# 3) gate_session_stats

# Regenerate README GIFs
python3 scripts/generate-readme-gifs.py

Illustrative compress call:

gate_compress_file({ filePath: "src/main.ts", depth: "signature" })
→ originalTokens: 2,664 · optimizedTokens: 191 · savingsPercent: 93%

Benchmarks

React figures below are from the v0.3.2 real-repo harness. They are not a universal or current-session guarantee. Rerun before publishing new marketing claims.

Test	Target	Result
React monorepo	`facebook/react` `packages/` — 2,080 files, 3.93M tokens	89% → 446k tokens
Symbol-recall fidelity	1,010 React files, 7,047 exports	99.1% (6,987/7,047)
Per-file perfect recall	1,010 React files	99.3% files at 100% recall
TOON fidelity	Round-trip fields/values	100% (17/17 · 15/15)
Scale	VS Code source (6,115 TS files)	3.2s build, 8ms queries

git clone --depth 1 https://github.com/facebook/react ~/demo/react
node dist/scripts/benchmark-real-repo.js ~/demo/react/packages --out report.md
node dist/scripts/fidelity-test.js ~/demo/react/packages

Modeled per-turn example (not a measurement)

Typical AI coding session (before):
  Tool schemas:     30,000 tokens
  File reads (5):   10,000 tokens
  JSON responses:    5,000 tokens
  Total:            45,000 tokens

With gatemcp (agent actually calls Gate):
  Tool schemas:      3,000 tokens  (catalog + gate_help)
  File reads (5):      600 tokens  (AST signatures)
  JSON responses:    1,500 tokens  (TOON)
  Total:             5,100 tokens

By the numbers

@gatemcp/cli@0.5.8 on npm — binary gatemcp
Catalog-first tool surface (schema anti-bloat)
12 tools (6 hot-path in catalog + long tail via gate_invoke)
20+ languages via tree-sitter / regex fallback
MIT · local-only · no telemetry
React bench: 89% payload reduction @ 99.1% symbol recall

Language support

Tier 1 — Core native	Tier 2 — Optional native
JS / TS / TSX, Python, Java, C#, C/C++, Go, Rust, HTML, CSS, JSON	PHP, Ruby, Kotlin, Bash, Swift

Regex fallback today: SQL, Scala, Markdown, Vue, Svelte, YAML (where native bindings do not load cleanly). See src/lib/astParser.ts.

Docs

Architecture (SSOT): ARCHITECTURE.md
Agent playbook: gate_help → recommended_stack
Proxy example: .gate-mcp/proxy-servers.example.json
Website: https://gate-mcp-site.vercel.app/

Privacy & security

No telemetry
Local process only — code never leaves your machine unless you call a remote MCP through the opt-in proxy
Path jail — tools restricted to GATE_PROJECT_ROOT (or startup cwd); per-call projectRoot may only narrow
Sensitive paths blocked — ~/.ssh, ~/.aws/credentials, /etc/passwd, etc.
Proxy off by default — GATE_ENABLE_PROXY=1 required after review
SQLite required — no silent memory fallback unless GATE_ALLOW_MEMORY_CACHE=1

Env var	Default	Purpose
`GATE_PROJECT_ROOT`	`process.cwd()`	Trusted path ceiling
`GATE_ALLOW_ANY_PATH`	`0`	Disable boundary (not recommended)
`GATE_MAX_FILES`	`5000`	Symbol graph file cap (hard 50000)
`GATE_MAX_FILE_BYTES`	`33554432`	Max compress input
`GATE_CACHE_DB`	`<root>/.gate-mcp/cache.db`	Dedup + memory DB
`GATE_TOOL_MODE`	`catalog`	`catalog` \| `full`
`GATE_ENABLE_PROXY`	`0`	Downstream MCP proxy

Uninstall

Remove the gatemcp / user-gatemcp entry from your IDE MCP config
Optional: delete the cache DB (GATE_CACHE_DB or <project>/.gate-mcp/)
Remove the package:

npm uninstall -g @gatemcp/cli
# or stop using npm exec --package=@gatemcp/cli

Codex: remove the plugin from the Codex UI / plugin list. Source installs: npm unlink -g from the clone if you used npm link.

Known limitations

Area	Behavior
Opt-in only	Zero savings if the agent never calls Gate — see what Gate compresses
Code generation	Model output is never compressed; Gate only shrinks tool results
Native SQLite	IDE must run the same Node that installed Gate — see Pin Node
gate graph vs graphify	Different graphs; use `graphify_*` for communities
Graph savings %	Symbol queries use a modeled baseline; `graphify_map` baselines the report file
Cursor MCP name	May appear as `user-gatemcp`
Proxy	Disabled until `GATE_ENABLE_PROXY=1`

Development

npm install   # with allow-scripts as above
npm run build
npm test
npm run qa
npm start     # MCP stdio

Node 20 and 22–26 (Node 21 unsupported by required better-sqlite3).

Star History

Changelog

v0.5.8 — dependency security fixes, end-user docs

Security. sharp 0.35.3 → 0.35.5 (libheif / librsvg advisories). Lockfile refresh clears transitive advisories in proxy-addr, ip-address, fast-uri, hono, and qs. npm audit --omit=dev reports 0.

Docs. What Gate compresses, reading gate_session_stats, and pinning Node for SQLite.

QA. macOS /var vs /private/var canonical-path fixes in test scripts. No tool behavior changes.

v0.5.7 — catalog mode, required SQLite, symbol HTML

Schema budget. Default GATE_TOOL_MODE=catalog lists six core tools plus gate_invoke. Shared Zod schemas validate direct calls and gate_invoke args.

SQLite policy. Fail-closed unless GATE_ALLOW_MEMORY_CACHE=1. Doctor reports the escape hatch and does not inherit it into its MCP child probe.

Symbol graph viz. queryType=export_html / gatemcp graph-html.

v0.5.6 — Codex plugin, doctor, measurable session statistics

projectRoot narrow-only on compress/dedup/session_stats; unified cache partition; billingScope="tool_payload_only"; gatemcp doctor; Codex marketplace plugin.

Earlier — v0.5.5 → v0.3.0

v0.5.5 — Honest metrics (expanded), gate_init, YAML structure mode, graphify stale warning.

v0.5.3 — Graphify bridge (graphify_hubs / search / map).

v0.5.2 — SQLite-backed gate_memory.

v0.5.1 — Tier-2 optional grammars + VS Code snippet pack + gate_validate_compression.

v0.5.0 — MCP proxy mode (gate_proxy_tools / gate_proxy_call).

v0.4.0 — Published as @gatemcp/cli; SQLite/WAL dedup.

v0.3.2 — React monorepo fidelity fixes; 89% reduction @ 99.1% recall.

v0.3.0 — Rename to gatemcp (npm collision with Gate.io).

Full historical detail remains in git history for those tags.

Contributing

Issues and PRs: https://github.com/Dukeabaddon/Gate-MCP/issues
Run npm run qa before opening a PR.

License

MIT — see LICENSE.

Website · GitHub · Issues

_{Built for developers who are tired of hitting rate limits — and of fake savings %.}

Name		Name	Last commit message	Last commit date
.agents/plugins		.agents/plugins
.gate-mcp		.gate-mcp
.github/workflows		.github/workflows
.planning		.planning
assets		assets
demo		demo
docs		docs
plugins/gatemcp		plugins/gatemcp
scripts		scripts
src		src
test-fixtures		test-fixtures
vscode-extension		vscode-extension
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
DELEGATE-PLAN.md		DELEGATE-PLAN.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Navigation Menu

Repository navigation

About

Repository files navigation

Measure and reduce context without hiding fidelity failures.

Why developers use Gate

What it does — four layers

What Gate compresses — and what it does not

Get started (60 seconds)

Tools

Reading `gate_session_stats`

Supported IDEs & AI tools

Agent compatibility matrix

When to use (and when not to)

Demo

Benchmarks

By the numbers

Language support

Docs

Privacy & security

Uninstall

Known limitations

Development

Star History

Changelog

Contributing

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Measure and reduce context without hiding fidelity failures.

Why developers use Gate

What it does — four layers

What Gate compresses — and what it does not

Get started (60 seconds)

Tools

Reading gate_session_stats

Supported IDEs & AI tools

Agent compatibility matrix

When to use (and when not to)

Demo

Benchmarks

By the numbers

Language support

Docs

Privacy & security

Uninstall

Known limitations

Development

Star History

Changelog

Contributing

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Reading `gate_session_stats`