How do I use code-context-gate?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@code-context-gate locate the UserService class in the auth module" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

code-context-gate

by wisdomrock

Overview Schema Related Servers Score Discussions

TypeScript

Local

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

Related MCP server: projscan

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

--project-root CLI flag
CODE_CONTEXT_GATE_ROOT environment variable
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

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

parecode
Developer Tools Code Analysis Coding Agents
BasilSkyWalk
A
license
A
quality
A
maintenance
An MCP server giving coding agents context-window-aware code search and safe, atomic multi-file edits — built to cut token usage on large codebases without sacrificing correctness.
Last updated 2026-07-20
3
68
5
MIT
projscan
Developer Tools Code Analysis Autonomous Agents
abhiyoheswaran1
A
license
-
quality
B
maintenance
An MCP server that provides AI coding agents with AST-accurate, context-budget-aware codebase querying, safety gates, and team policy integration via structured tools and a local plugin layer.
Last updated 2026-07-20
540
4
MIT
reflens
RAG Systems Code Analysis
cybertronayush
A
license
A
quality
B
maintenance
An MCP server that indexes reference repositories and provides tools for AI coding agents to retrieve lossless code context, enabling reasoning over codebases larger than the agent's context window.
Last updated 2026-07-02
8
2
Apache 2.0
contextsliver
Code Analysis Knowledge & Memory Developer Tools
DevMuneeb
A
license
-
quality
A
maintenance
An MCP server that indexes codebases into a local graph and provides on-demand context retrieval for AI coding agents, reducing token usage by tracking session history and delivering only relevant code subgraphs.
Last updated 2026-07-24
28
MIT

View all related MCP servers

Related MCP Connectors

ContextStream
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
gread
An MCP server that gives your AI access to the source code and docs of all public github repos
hithereiamaliff-mcp-nextcloud
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…

View all MCP Connectors

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/wisdomrock/code-context-gate'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

code-context-gate

Why use it?

Relationship to codebase-memory-mcp

How it works

Installation

MCP Configuration

With a graph backend

CLI flags

Project root resolution order

Tools

locate — find where something lives

read — get the actual source

search — keyword or regex search

explore — understand structure and relationships

Backpressure

Config file

Logging

Log events

Reading the log

Source structure (src/)

Result scoring

Graph backends

Agent Instructions (CLAUDE.md)

Re-enabling the fallback hook

Requirements

License

Maintenance

Resources

Looking for Admin?

Related MCP Servers

parecode

projscan

reflens

contextsliver

Related MCP Connectors

Latest Blog Posts

MCP directory API

`locate` — find where something lives

`read` — get the actual source

`search` — keyword or regex search

`explore` — understand structure and relationships

Source structure (`src/`)