Gate-MCP

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.

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.

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

Related MCP server: Smart Context MCP

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      │
                     └──────────────────────────────┘

Recommended workflow

1. gate_init — health, graphify path, cache kind

2. gate_graph_query (graphify_map or symbol search) — navigate before full reads

3. gate_compress_file (signature or structure) — hydrate only what you need

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

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.

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

{
  "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).

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 — ~/.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

Compression-oriented tools include originalTokens / optimizedTokens / savingsPercent where applicable. When output grows, expanded: true and savings stay 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:

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

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

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

Agent compatibility matrix

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.

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

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

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

Uninstall

1. Remove the gatemcp / user-gatemcp entry from your IDE MCP config

2. Optional: delete the cache DB (GATE_CACHE_DB or <project>/.gate-mcp/)

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

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

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.

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.

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

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.