code-context-gate

An MCP server that acts as a context-aware code retrieval broker for AI coding agents. It sits between the agent and your codebase, enforcing backpressure so the agent never receives more context than it can use.

---

Why use it?

Without a gate, AI agents call raw grep/find/cat on source files. On a large codebase that means:

• A single broad search returns 800 lines from 60 files — flooding the context window
• Irrelevant comments, tests, and vendored code push the signal out of the model's attention
• There is no token budget, no relevance ranking, and no guidance on how to narrow a bad query

code-context-gate solves this with four disciplined tools that rank, gate, and budget every result before it reaches the agent. Over-broad queries get a structured refine refusal with a per-directory hit distribution and actionable suggestions — so the next call is deterministic.

Scenario	Without gate	With gate
Broad search ("auth")	800 hits across 60 files, full context dump	Refusal with distribution; agent narrows to src/auth/ in one round-trip
Large codebase (500+ files)	Agent reads several wrong files before finding the right one	locate returns the 3 most relevant paths
Cross-file relationships	Must read every candidate file to infer callers	explore returns the call chain directly
Path traversal	No protection	resolveSafe() hard-blocks any path outside project root

Relationship to codebase-memory-mcp

code-context-gate can connect to a graph backend (codebase-memory-mcp or codegraph) for semantic symbol lookup and architecture overviews. But the gate's core value — ranking, backpressure, token budgeting, block expansion — is its own, independent of any graph backend. Even with --graph-backend none, it outperforms raw file access on any codebase where result volume is a concern.

codebase-memory-mcp     ← semantic understanding (what code MEANS)
        ↑ consumed by
code-context-gate       ← budget discipline (HOW MUCH reaches the agent)
        ↑ consumed by
AI agent

---

How it works

Every tool call flows through the same pipeline:

Tool call (locate / read / explore / search)
  └─ Dispatcher         — routes by query shape (symbol → graph, phrase → merge, pattern → fileio)
       ├─ Graph adapter  — codebase-memory-mcp or codegraph (optional)
       └─ FileIO adapter — async line-by-line file scan with gitignore support
            └─ Shaper   — BM25 lexical scoring + kind weighting → ranked ResultItem[]
                 └─ Gatekeeper — enforces maxFiles / maxHits / maxTokens / minRelevance
                      └─ OkEnvelope  (results fit budget)
                      └─ RefineEnvelope  (too broad — includes distribution + suggestions)

Query shape routing in the dispatcher:

Query shape	Example	Strategy
Symbol (single word)	OrderHandler	Graph first → FileIO fallback on miss
Phrase (has spaces)	payment retry logic	FileIO + graph merged, deduped by file:line
Pattern (regex chars)	retry.*count	FileIO regex scan only

---

Installation

npx code-context-gate --project-root /path/to/your/project

Or install globally:

npm install -g code-context-gate
code-context-gate --project-root .

---

MCP Configuration

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json or Claude Code .mcp.json):

{
  "mcpServers": {
    "code-context-gate": {
      "command": "npx",
      "args": ["code-context-gate", "--project-root", "/path/to/project"]
    }
  }
}

With a graph backend

{
  "mcpServers": {
    "code-context-gate": {
      "command": "npx",
      "args": [
        "code-context-gate",
        "--project-root", "/path/to/project",
        "--graph-backend", "codebase-memory-mcp"
      ]
    }
  }
}

---

CLI flags

Flag	Default	Description
--project-root	(see below)	Root directory to search within
--config	(none)	Path to a JSON config file
--graph-backend	codebase-memory-mcp	codebase-memory-mcp, codegraph, or none
--debug	false	Write structured JSON logs to stderr

Project root resolution order

1. --project-root CLI flag
2. CODE_CONTEXT_GATE_ROOT environment variable
3. process.cwd() — the working directory of the process that launched the server

For stdio-mode MCP clients (Claude Code CLI, Cursor, etc.) option 3 already points at the correct project root. For GUI clients (Claude Desktop) set the env var in your MCP config:

{
  "mcpServers": {
    "code-context-gate": {
      "command": "npx",
      "args": ["code-context-gate"],
      "env": { "CODE_CONTEXT_GATE_ROOT": "/path/to/your/project" }
    }
  }
}

---

Tools

locate — find where something lives

Returns file paths and line ranges only — no source bodies. Use first, before read.

{ "query": "OrderHandler", "kind": "definition", "scope": "src/" }

Parameter	Type	Description
query	string	Symbol name or concept
kind	definition | reference | any	Filter by result kind (default: any)
scope	string	Subdirectory to restrict the search
max_results	number	Override the default hit cap

read — get the actual source

Reads a symbol by name or an explicit file:start-end range. Block-expands to enclosing function/class boundaries. Size-bounded so a single call never dumps an entire file.

{ "target": "OrderHandler.handle" }
{ "target": "src/payments/OrderHandler.ts:142-179", "expand": false }
{ "target": "src/config.ts" }

Parameter	Type	Description
target	string	Symbol name or file:start[-end]
expand	boolean	Expand to enclosing block (default: true)
max_tokens	number	Token budget for the response

search — keyword or regex search

The sanctioned replacement for grep. Always ranked, gated, and token-budgeted.

{ "pattern": "PathDeniedError", "scope": "src/" }
{ "pattern": "export.*function", "regex": true, "max_hits": 20 }

Parameter	Type	Description
pattern	string	Keyword or regex pattern
regex	boolean	Treat pattern as regex (default: false)
scope	string	Subdirectory to restrict the search
exclude	string[]	Subdirectories to skip
max_hits	number	Override the default hit cap
max_tokens	number	Token budget for snippets
force	boolean	Bypass gating (use sparingly)

explore — understand structure and relationships

Answers structural questions: callers, callees, dependencies, blast radius, architecture overview. Requires a graph backend for full results; falls back to a file scan summary when no graph is available.

{ "question": "what calls resolveSafe", "anchor": "resolveSafe", "relation": "callers" }
{ "question": "overview of the payments module", "relation": "overview" }
{ "question": "what would break if I change UserSession", "relation": "impact" }

Parameter	Type	Description
question	string	Natural-language structural question
anchor	string	Symbol to anchor the query
relation	callers | callees | dependencies | impact | overview | auto	Relationship type (default: auto)

---

Backpressure

When a query is too broad, tools return a refine envelope instead of overwhelming the agent:

{
  "status": "refine",
  "reason": "breadth",
  "summary": { "totalFound": 340, "files": 48, "estTokens": 28000, "topScore": 0.21 },
  "distribution": [
    { "dir": "src/auth", "hits": 120 },
    { "dir": "src/core", "hits": 80 }
  ],
  "suggestions": [
    { "action": "narrow_scope", "arg": "src/auth", "wouldYield": 120 },
    { "action": "use_force", "hint": "Set force:true to bypass gating" }
  ],
  "refusalCount": 1
}

Refusal reasons:

Reason	Condition
breadth	Unique files > maxFiles (default 25)
volume	Hit count > maxHits (120) or estimated tokens > absoluteMaxTokens (24 000)
relevance	Top BM25 score below minRelevance (0.35)
compound	Two or more of the above

Deadlock cap: after maxRefusals (default 3) consecutive refusals, the gate opens automatically.
Compound margin: single-axis near-misses within 15% of a threshold pass through without refusal.

---

Config file

Place a JSON file anywhere and pass it with --config:

{
  "gates": {
    "maxFiles": 25,
    "maxHits": 120,
    "maxTokens": 6000,
    "minRelevance": 0.35
  },
  "scan": {
    "excludeDirs": ["node_modules", "dist", ".git"],
    "respectGitignore": true
  }
}

Full config schema (all fields optional — shown with defaults):

{
  "gates": {
    "maxFiles": 25,
    "maxHits": 120,
    "maxTokens": 6000,
    "minRelevance": 0.35,
    "compoundMargin": 0.15
  },
  "limits": {
    "maxRefusals": 3,
    "absoluteMaxTokens": 24000
  },
  "estimation": {
    "charsPerToken": 3.5
  },
  "scoring": {
    "weights": {
      "kind": 0.30,
      "lexical": 0.25,
      "proximity": 0.20,
      "shape": 0.15,
      "recency": 0.10
    }
  },
  "backend": {
    "graph": "codebase-memory-mcp"
  },
  "scan": {
    "excludeDirs": ["node_modules", "dist", "build", "target", ".venv", "vendor", ".git"],
    "respectGitignore": true
  }
}

---

Logging

All tool activity is written as newline-delimited JSON to code-context-gate.log in the project root. Pass --debug to also stream logs to stderr.

Log events

Event	Source	Key fields	What it tells you
tool_call	server.ts	tool, args	Every inbound MCP tool call with its arguments
dispatch	dispatcher.ts	query, shape, graphAvailable	Query shape classification and whether graph is reachable
fileio_scan	fileio.ts	scope, patternType	When a file walk starts, what directory and pattern type (string|regex)
graph_search	graph.ts	backend, count	Graph search completed; how many results the backend returned
graph_search_error	graph.ts	backend, error	Graph search failed silently (previously swallowed)
graph_architecture	graph.ts	backend, hasResult	Architecture call completed and whether a non-empty summary was returned
graph_architecture_error	graph.ts	backend, error	Architecture call failed
dispatch_result	dispatcher.ts	strategy, count	Final strategy used (graph_symbol, fileio_only, fileio+graph_merged, etc.) and total hits
dispatch_graph_miss	dispatcher.ts	query, shape	Graph returned 0 results for a symbol query; falling back to FileIO
gate	server.ts	tool, pass, reason	Gate decision — passed or refused, and why
tool_result	server.ts	tool, returned, estTokens	How many results were returned and their estimated token cost
tool_error	server.ts	tool, error	Unhandled tool exception

Reading the log

A typical symbol lookup with graph hit:

{"ts":"...","event":"tool_call","tool":"locate","args":{"query":"resolveSafe","kind":"definition"}}
{"ts":"...","event":"dispatch","query":"resolveSafe","shape":"symbol","graphAvailable":true}
{"ts":"...","event":"graph_search","backend":"codebase-memory-mcp","count":2}
{"ts":"...","event":"dispatch_result","query":"resolveSafe","strategy":"graph_symbol","count":2}
{"ts":"...","event":"gate","tool":"locate","pass":true,"reason":null}
{"ts":"...","event":"tool_result","tool":"locate","returned":2}

A broad search that triggers a refusal:

{"ts":"...","event":"tool_call","tool":"search","args":{"pattern":"export"}}
{"ts":"...","event":"dispatch","query":"export","shape":"symbol","graphAvailable":true}
{"ts":"...","event":"graph_search","backend":"codebase-memory-mcp","count":148}
{"ts":"...","event":"dispatch_result","query":"export","strategy":"graph_symbol","count":148}
{"ts":"...","event":"gate","tool":"search","pass":false,"reason":"breadth"}
{"ts":"...","event":"tool_result","tool":"search","returned":0}

---

Source structure (src/)

File	Role
cli.ts	Entry point — parses CLI flags, loads config, starts the server
server.ts	MCP server — registers the four tools, wires dispatch → shape → gate → respond
dispatcher.ts	Routes queries by shape to graph and/or FileIO; merges and deduplicates results
shaper.ts	BM25 lexical scoring + kind weighting → ranked ResultItem[]; trim() for token budgeting
gatekeeper.ts	Enforces backpressure limits; returns RefineEnvelope with distribution and suggestions on failure
config.ts	Zod-validated config loader; resolves project root from flag → env var → CWD
logger.ts	Append-only JSON line logger to code-context-gate.log; never crashes the server on write failure
types.ts	Shared types and Zod input schemas for all four tools
adapters/fileio.ts	Filesystem adapter — scan(), readLines(), expandBlock(), resolveSafe()
adapters/graph.ts	Graph adapters — CodebaseMemoryAdapter, CodegraphAdapter, NullAdapter; createGraphAdapter() factory

Result scoring

Each result gets a composite score before ranking:

score = kindScore × 0.30 + BM25lexical × 0.25 + graphScore × 0.45

Kind weights:

Kind	Weight
definition	1.0
call, reference	0.7
unknown	0.5
test	0.3
comment, string	0.2

---

Graph backends

Backend	Launch command	Adapter
codebase-memory-mcp	npx -y codebase-memory-mcp --project-root <root>	CodebaseMemoryAdapter — calls search_code and get_architecture
codegraph	npx -y codegraph <root>	CodegraphAdapter — calls search and architecture
none	(not launched)	NullAdapter — FileIO only, all tools still work

Both graph backends are optional. Without one, all four tools work using FileIO only.

---

Agent Instructions (CLAUDE.md)

This repo ships a CLAUDE.md that Claude Code and compatible agents load automatically. It routes all code discovery through code-context-gate and prohibits direct calls to lower-level tools like codebase-memory-mcp.

When an agent session starts it first probes code-context-gate with a lightweight locate call:

• Server responds → the four tools are used for all code access
• Server unavailable → the agent stops and prompts the user to enable code-context-gate or re-enable the cbm-session-reminder fallback hook

Re-enabling the fallback hook

If you want agents to fall back to raw codebase-memory-mcp calls when code-context-gate is not running, add to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      { "matcher": "startup", "hooks": [{ "type": "command", "command": "~/.claude/hooks/cbm-session-reminder" }] },
      { "matcher": "resume",  "hooks": [{ "type": "command", "command": "~/.claude/hooks/cbm-session-reminder" }] },
      { "matcher": "clear",   "hooks": [{ "type": "command", "command": "~/.claude/hooks/cbm-session-reminder" }] },
      { "matcher": "compact", "hooks": [{ "type": "command", "command": "~/.claude/hooks/cbm-session-reminder" }] }
    ]
  }
}

---

Requirements

• Node.js 20+
• No native build tools required

---

License

MIT © 2026 wisdom rock — see LICENSE for full text.