Provides tools for interacting with local Git repositories, including token-budgeted and noise-filtered smart diffs, secret scanning of staged/unstaged changes, branch topology inspection, in-memory merge conflict detection, and context cost estimation for working tree changes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Git Sentinel scan my staged changes for secrets before I commit"
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.
A high-performance, zero-dependency Model Context Protocol (MCP) server engineered to solve Agent Context Economics: protecting LLM context windows from diff explosion, filtering repository noise, extracting AST semantic outlines, and intercepting accidental secret leakage before code reaches AI models.
In modern autonomous software engineering, AI Coding Agents (such as OpenAI Codex, Claude Code, Cursor, and Windsurf) rely on context windows as their primary working memory. However, traditional Git was built for human terminal readers and disk storage—not for token-metered neural attention windows.
This architectural mismatch creates three critical bottlenecks:
The Context Explosion Dilemma:
Updating a single package in package.json often dumps 10,000+ lines of lockfile diffs (package-lock.json, pnpm-lock.yaml, Cargo.lock), consuming 30,000 to 60,000 tokens in a single tool call. This causes immediate context exhaustion, slows generation, and costs dollars per query.
Attention Degradation (Needle in a Haystack):
When prompt context is inundated with minified bundles (.min.js), source maps (.map), and hash churn, LLMs lose sensitivity to critical business logic modifications and security regressions.
The Upstream Secret Leakage Hazard:
Agents analyzing unstaged code or automated PR workflows risk ingesting unmasked API keys (sk-..., ghp_..., AWS secrets) directly into model prompt logs.
Related MCP server: Ambiance MCP Server
mcp-git-sentinel sits as an intelligent semantic proxy between Git and your LLM Agent:
┌──────────────┐ JSON-RPC 2.0 / stdio ┌─────────────────────────────────┐ git cli ┌──────────────┐
│ AI Agent │ ◄────────────────────────────► │ mcp-git-sentinel │ ◄───────────────► │ Local Repo │
│ (Codex/MCP) │ │ (Zero External Runtime Deps) │ │ │
└──────────────┘ └────────────────┬────────────────┘ └──────────────┘
│
┌───────────────────────────┴───────────────────────────┐
│ │
┌─────────▼─────────┐ ┌─────────────────▼─────────┐ ┌────────▼────────┐
│ Noise Suppression │ │ Shannon Entropy Sentinel │ │ AST Semantic │
│ 14+ Lockfile types│ │ H(X) secret calculation │ │ Outline Parser │
│ Minified / Maps │ │ Pattern & Masking Engine │ │ Class/Def Sig │
└───────────────────┘ └───────────────────────────┘ └─────────────────┘Rather than dumping 500 lines of implementation diffs, mcp-git-sentinel parses Python, TypeScript, and Go AST signatures to tell the model what changed structurally before presenting diff lines:
[CLASS] class PaymentProcessor->[FUNC] def process(amount: float, currency: str)
Using pure information theory mathematics, the server computes character randomness in real time:
$$H(X) = -\sum_{i=1}^{n} P(x_i) \log_2 P(x_i)$$
Natural code registers between $2.0 - 3.5$. High-entropy strings ($H \ge 4.4$) and modern AI credentials (sk-proj-..., ghp_..., AWS keys) trigger an immediate 🚨 SECURITY ALERT and automatic masking before the diff ever leaves your machine.
git merge-tree)Simulates branch compatibility in-memory without checking out branches, modifying files, or creating dirty <<<<<<< HEAD conflict markers on disk.
Tool | Description |
| Generates token-budgeted, noise-filtered diffs with AST outlines and secret leak detection. |
| Audits unstaged/staged changes specifically for high-entropy tokens and credential leaks. |
| Inspects current branch topology, uncommitted counts, upstream divergence, and recent commits. |
| In-memory 3-way merge conflict check against a target branch (e.g. |
| Analyzes working tree modifications and breaks down token usage and noise bloat file-by-file. |
# Clone the repository
git clone git@github.com:Sir-Lancelot-du-Lac-Dev/mcp-git-sentinel.git
cd mcp-git-sentinel
# Install in editable mode
pip install -e .Or run directly without installation (uses only Python standard library):
python -m mcp_git_sentinel.climcp.json){
"mcpServers": {
"git-sentinel": {
"command": "python",
"args": ["-m", "mcp_git_sentinel.cli"],
"cwd": "${workspaceFolder}"
}
}
}claude_desktop_config.json){
"mcpServers": {
"git-sentinel": {
"command": "python",
"args": ["-m", "mcp_git_sentinel.cli"],
"cwd": "/path/to/your/project"
}
}
}codex --mcp-server "python -m mcp_git_sentinel.cli"To evaluate real-world token compression and latency overhead, mcp-git-sentinel includes a reproducible micro-benchmark (scripts/benchmark.py) simulating an enterprise repository diff: 9,070 lines (~915 KB) containing massive lockfile churn (package-lock.json), minified bundles, and core authentication services.
Metric | Raw Unfiltered Git Diff | MCP Git Sentinel (Optimized) | Compression & Efficiency |
Total Lines Evaluated | 9,070 lines | ~120 lines (Semantic diff + AST) | ~98.7% line reduction |
Estimated Context Tokens | ~267,814 tokens | ~1,203 tokens | 99.6% token savings 📉 |
End-to-End Latency | Baseline (I/O bound) | ~127.7 ms | Sub-second edge evaluation ⚡ |
Peak Working Memory | N/A | 3.11 MB | Negligible agent footprint 🧠 |
Noise Filtering | 0 files | 2 lockfiles/minified suppressed | 100% lockfile noise filtered |
Reproduce locally:
python scripts/benchmark.py
Run the comprehensive unit test suite:
pytest -vAll 18 unit tests run in < 2.5 seconds and validate cross-platform compatibility across Ubuntu, Windows, and macOS on Python 3.10, 3.11, and 3.12.
Distributed under the MIT License. Copyright (c) 2026 Sir-Lancelot-du-Lac-Dev.
Performs an in-memory 3-way merge simulation against a target branch to detect potential merge conflicts before merging.
| Name | Required | Description | Default |
|---|---|---|---|
| target_ref | Yes | Target branch or ref to test mergeability against (e.g. 'main', 'origin/main'). | main |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'In-memory simulation' productively discloses that nothing is mutated on disk, which is real value. But it omits prerequisites (must the target ref be fetched locally?), behavior on unknown refs, and what the result contains, so the disclosure is only partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence with zero redundant clauses; the purpose and the pre-merge framing land immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, non-mutating check this is close to sufficient. The one gap is that no output schema exists and the description doesn't indicate whether the tool returns a boolean, a conflict list, or per-file details, so a caller can't fully anticipate the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter at 100% schema coverage, so the schema already documents target_ref's meaning and examples. The description adds nothing parameter-specific, which matches the baseline 3 when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and mechanism (3-way merge simulation) and the concrete outcome (detect potential merge conflicts before merging), which clearly separates it from siblings like inspect_branch or smart_diff. It never names those siblings explicitly, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Before merging' implies the triggering workflow, giving an agent a usable usage cue. However, there is no explicit when-not guidance and no routing to alternatives such as smart_diff or inspect_branch for related pre-merge checks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyzes pending working tree changes and breaks down estimated LLM token consumption file-by-file.
| Name | Required | Description | Default |
|---|---|---|---|
| staged_only | No | Whether to analyze only staged changes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It implies a read-only analysis (no mutation language), and 'pending working tree changes' signals it reads the live working tree rather than commits. However, it says nothing about whether it's expensive to run, how tokens are estimated, or what the breakdown contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. Compact and easy to scan, though it borders on too terse for an analysis tool with no output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one optional boolean, full schema coverage), but there is no output schema and the description doesn't describe the shape of the file-by-file breakdown or what 'estimated token consumption' entails. An agent knows enough to invoke it but not what to expect back.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so staged_only is already documented. The phrase 'pending working tree changes' hints that the default scope includes unstaged work, loosely aligning with staged_only=false, but the description adds no further semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States specific verbs (analyzes pending working tree changes, breaks down estimated token consumption) with the level of granularity (file-by-file). It's clearly distinguishable from siblings like smart_diff or scan_secrets, though it doesn't explicitly say so.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to reach for this versus smart_diff or inspect_branch, and no mention of when the staged_only variant applies. The agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspects current Git branch topology, uncommitted file counts, upstream divergence, and recent commit history.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden; 'Inspects' signals a read-only operation and the facet list tells the agent what data surfaces. However it says nothing about prerequisites (must the working directory be a Git repo?), failure behavior outside a repo, cost/latency of walking commit history, or how much history 'recent' means.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence with no filler; the core action leads and the four returned facets follow as a compact list. Nothing could be cut without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully names the return categories, which is the key omission risk for a zero-param tool. What remains uncovered is environmental scope (does it need a repo path or specific checkout, how much commit history, behavior when not in a Git repo), which keeps it short of a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4 — there is nothing for the description to disambiguate and no schema-documented inputs to compensate for. The description correctly implies a parameterless snapshot of the current branch context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Uses a specific verb ('Inspects') with a specific resource ('current Git branch') and enumerates exactly what facets it covers: topology, uncommitted file counts, upstream divergence, and recent commit history. That resource scope is unmistakably distinct from the siblings (smart_diff, scan_secrets, detect_conflicts, estimate_context_cost), so an agent can route without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The enumerated facets imply when the tool is useful (whenever you need a branch-state snapshot), but there is no explicit 'use this when…' guidance, no exclusions, and no mention of the sibling tools or when one of them would be the better choice. Usage is inferable but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audits Git diffs for accidental API key and high-entropy secret leaks using Shannon Entropy and credential signatures.
| Name | Required | Description | Default |
|---|---|---|---|
| staged_only | No | Whether to audit only staged changes (default: false). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, yet it says nothing about whether the scan is read-only, what it does when a leak is found (report vs. block), how it behaves on large diffs, or what the findings look like. The disclosure of detection methodology (entropy + signature matching) is the only added behavioral context and is thin on its own.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence with the action, target and technique in that order; no filler or redundancy. It is appropriately sized for a one-parameter scan tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description should at least indicate what a scan yields (findings list, pass/fail, exit gating) and which diff scope is examined. The technique mention gives partial coverage, but return shape and failure semantics are left entirely unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter staged_only is fully documented in the schema (100% coverage, default and meaning included), so the schema does the work. The description only says 'Git diffs' generically and never reinforces the staged-vs-working-tree distinction, so it adds no meaning beyond the schema — baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (audits), resource (Git diffs), target (API key and high-entropy secret leaks) and method (Shannon Entropy and credential signatures). An agent can distinguish this from siblings like smart_diff or detect_conflicts by domain, though the description never explicitly names or contrasts them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to call this (pre-commit review, CI gate, ad-hoc audit) and no mention of alternatives or when not to use it. The agent must infer the trigger condition entirely from the tool name and the word 'audits'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generates a token-budgeted, noise-filtered semantic git diff with AST change outlines and secret leak detection.
| Name | Required | Description | Default |
|---|---|---|---|
| max_tokens | No | Strict token ceiling for the diff output (default: 4000). | |
| target_ref | No | Git revision or branch to diff against (e.g. 'HEAD~1', 'origin/main'). Defaults to working tree diff. | |
| staged_only | No | Whether to only diff staged files (git diff --cached). | |
| filter_noise | No | Whether to automatically discard lockfiles and generated assets (default: true). | |
| scan_secrets | No | Whether to scan for high-entropy credentials and API keys (default: true). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden, and it does disclose concrete traits: a strict token ceiling, noise filtering of lockfiles/generated assets, and secret scanning. However, it says nothing about the result payload structure, truncation behavior when the budget is exceeded, or failure modes for invalid refs — notable gaps for a tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence that front-loads the core output type before listing modifiers; nothing is wasted. It is adjective-heavy ('token-budgeted, noise-filtered, semantic'), which costs a little readability but not correctness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All parameters are optional, so an agent can invoke the tool with no arguments and the description makes clear the defaults are sane. The main missing piece is what the returned diff/outline looks like and how it degrades past the token ceiling, which matters given there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with all five parameters including defaults fully documented, so the schema does the heavy lifting. The description's phrases ('token-budgeted', 'noise-filtered', 'secret leak detection') only loosely mirror max_tokens, filter_noise, and scan_secrets without adding syntax or interaction detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource ('Generates ... semantic git diff') and enumerates its distinctive features: token budgeting, noise filtering, AST change outlines, and secret leak detection. It stops short of distinguishing the tool from siblings like scan_secrets, whose surface the 'secret leak detection' phrase partially overlaps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use, when-not-to-use, or alternative routing guidance. An agent cannot tell from this description whether to call smart_diff or the sibling scan_secrets for a credential check, or whether estimate_context_cost is preferable for pure budget planning.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0detect_conflictsestimate_context_costinspect_branchscan_secretssmart_diffScored across 5 tools
Two clear overlaps muddy selection: smart_diff advertises 'secret leak detection' and 'token-budgeted' output, which is exactly what scan_secrets and estimate_context_cost do respectively. inspect_branch and detect_conflicts are distinct, but an agent must guess whether to call smart_diff or the specialized scanners.
Four of five tools follow a clean verb_noun snake_case pattern (inspect_branch, scan_secrets, detect_conflicts, estimate_context_cost). smart_diff breaks the pattern with an adjective_noun form, a minor but visible deviation.
Five tools is well-scoped for a pre-commit/pre-merge git inspection server, and each tool maps to a distinct workflow step (branch state, diff, secrets, conflicts, cost). No filler tools.
The read-only 'sentinel' surface is solidly covered: branch state, diff, secret audit, conflict simulation, and token cost. Minor gaps exist in that findings are purely diagnostic with no follow-up action (e.g. staging, ignoring paths, or diffing arbitrary commit ranges).
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Guardian agent for AI coding: four frontier models review risky diffs and commits before they ship.
Change-aware CI validation and affected-test guidance for coding agents.
Git-backed platform for skills, tools, and context for AI agents
