Skip to main content
Glama

MCP Git Sentinel πŸ›‘οΈ

CI License: MIT Python Version MCP Standard

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.


πŸ’‘ The Thesis: Agent Context Economics

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:

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

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

  3. 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: Semantic Cache MCP

πŸš€ The Solution: Architecture & Core Pillars

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  β”‚
                           β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

1. AST-Aware Semantic Change Outlines

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)

2. Zero-Overhead Shannon Entropy Secret Guard

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.

3. In-Memory 3-Way Merge Simulation (git merge-tree)

Simulates branch compatibility in-memory without checking out branches, modifying files, or creating dirty <<<<<<< HEAD conflict markers on disk.


πŸ› οΈ MCP Tools Exposed

Tool

Description

smart_diff

Generates token-budgeted, noise-filtered diffs with AST outlines and secret leak detection.

scan_secrets

Audits unstaged/staged changes specifically for high-entropy tokens and credential leaks.

inspect_branch

Inspects current branch topology, uncommitted counts, upstream divergence, and recent commits.

detect_conflicts

In-memory 3-way merge conflict check against a target branch (e.g. main).

estimate_context_cost

Analyzes working tree modifications and breaks down token usage and noise bloat file-by-file.


⚑ Quick Start

Installation

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

πŸ”Œ Configuration

1. Cursor / Windsurf (mcp.json)

{
  "mcpServers": {
    "git-sentinel": {
      "command": "python",
      "args": ["-m", "mcp_git_sentinel.cli"],
      "cwd": "${workspaceFolder}"
    }
  }
}

2. Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "git-sentinel": {
      "command": "python",
      "args": ["-m", "mcp_git_sentinel.cli"],
      "cwd": "/path/to/your/project"
    }
  }
}

3. OpenAI / Codex Agent CLI

codex --mcp-server "python -m mcp_git_sentinel.cli"

πŸ“Š Empirical Benchmarks: Agent Context Economics

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

πŸ§ͺ Testing & Quality Assurance

Run the comprehensive unit test suite:

pytest -v

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


πŸ“œ License

Distributed under the MIT License. Copyright (c) 2026 Sir-Lancelot-du-Lac-Dev.

Available Tools

5 tools
detect_conflictsA

Performs an in-memory 3-way merge simulation against a target branch to detect potential merge conflicts before merging.

Inputs: target_ref (required).

estimate_context_costB

Analyzes pending working tree changes and breaks down estimated LLM token consumption file-by-file.

Inputs: staged_only.

inspect_branchA

Inspects current Git branch topology, uncommitted file counts, upstream divergence, and recent commit history.

Inputs: no named parameters.

scan_secretsB

Audits Git diffs for accidental API key and high-entropy secret leaks using Shannon Entropy and credential signatures.

Inputs: staged_only.

smart_diffB

Generates a token-budgeted, noise-filtered semantic git diff with AST change outlines and secret leak detection.

Inputs: max_tokens, target_ref, staged_only, filter_noise, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 5 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

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

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Extracts minimal, relevant code context from multiple programming languages while analyzing diffs and optimizing imports to reduce token usage for AI assistants. Supports TypeScript/JavaScript, Python, Go, and Rust with token-aware caching.
      7
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP file cache for AI coding agents. Re-reading an unchanged file costs ~40 tokens instead of the whole file; a changed file comes back as a diff. Adds grep, BM25 search and glob over cached files, atomic edits with dry_run, and token-budgeted batch reads. One local daemon serves every client. No API keys, no GPU. Works with Claude Code, Cursor, VS Code, Codex and OpenCode.
      14
      79 PyPI
      3
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables LLMs to efficiently read, write, and refactor code using precise AST-based operations, reducing token usage and context window waste.
      25
      238 npm
      3
      MIT