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.

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.7.

Then wire your IDE (Cursor snippet below). Run gate_init once per workspace. Doctor: npx --package=@gatemcp/cli@0.5.7 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).

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.7.

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`

gate_session_stats mixes path-filtered persistent cache totals with process-wide counters for the MCP instance. See prior release notes for the exact field split.

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.7 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
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.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
Latest commit History 38 Commits
.agents/plugins		.agents/plugins
.gate-mcp		.gate-mcp
.github/workflows		.github/workflows
.planning		.planning
assets		assets
demo		demo
plugins/gatemcp		plugins/gatemcp
scripts		scripts
src		src
test-fixtures		test-fixtures
vscode-extension		vscode-extension
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Measure and reduce context without hiding fidelity failures.

Why developers use Gate

What it does — four layers

Get started (60 seconds)

Tools

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

Folders and files

Latest commit

History

Repository files navigation

Measure and reduce context without hiding fidelity failures.

Why developers use Gate

What it does — four layers

Get started (60 seconds)

Tools

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