🛡️ diff-sentinel

Autonomous Open-Source Maintainer Sentinel & Model Context Protocol (MCP) Server

Lightweight AST & Unified Git Diff Analyzer, Security Secret Scanner, Breaking Change Detector, GitHub Action, and AI Maintainer Companion.

⚡ Overview

Maintaining high-velocity open-source repositories is exhausting:

• PR reviews accumulate faster than maintainers can review them.

• Leaked credentials, API tokens, and dangerous runtime patterns slip through manual reviews.

• Subtle breaking API changes (e.g. modified function signatures, removed public exports) break downstream packages.

• PRs modify complex production logic without updating test coverage.

diff-sentinel is built from the ground up for open-source maintainers and AI coding agents (such as Claude Code, OpenAI Codex, and Cursor). It provides deep, sub-millisecond AST-level patch inspection, automated risk scoring (0–100), security vulnerability detection, issue triage, and an official Model Context Protocol (MCP) server interface.

Related MCP server: Smart Git MCP Server & CLI

🌟 Key Features

• 🚀 Sub-Millisecond Unified Diff Parsing: Accurately parses hunk headers, added/deleted lines, renames, and calculates blast radius across codebases.

• 🔍 AST-Level Breaking Change Detection: Identifies removed public exports, altered parameter signatures, and type narrowing across TypeScript, JavaScript, Python, and Go.

• 🔐 Deep Secret & Vulnerability Scanner: Intercepts OpenAI keys, Anthropic keys, AWS IAM tokens, GitHub PATs, private cryptographic keys, and unsafe APIs (eval, shell injection, SQL concatenation).

• 🎯 Multi-Factor PR Risk Engine: Generates a composite risk score (0 to 100), letter grade (A through F), and determines isSafeToMerge based on churn, sensitive path impact, and test coverage gaps.

• 🤖 Model Context Protocol (MCP) Server: Native stdio JSON-RPC 2.0 server allowing AI assistants (Claude Desktop, Claude Code, OpenAI agents) to audit diffs, scan secrets, and triage issues directly.

• 📋 Automated Issue Triager: Classifies incoming GitHub issues into categories (bug, feature, security, documentation), checks for minimal reproduction steps, and suggests triage labels.

• 📦 Semantic Changelog Generator: Parses Conventional Commits and automatically suggests SemVer version bumps (major, minor, patch) formatted in Keep-a-Changelog Markdown.

• ⚙️ GitHub Action Ready: Drop-in composite action (action.yml) to guard PRs directly in CI/CD pipelines.

📐 Architecture

flowchart TD
    A[Git Diff / PR Patch] --> B[Diff Parser Engine]
    B --> C[AST Signature Analyzer]
    B --> D[Security & Secret Scanner]
    B --> E[Blast Radius & Churn Counter]
    
    C --> F[Multi-Factor Risk Engine]
    D --> F
    E --> F
    
    F --> G[Maintainer Report & Grade]
    
    subgraph Interfaces
        H[CLI Tool: diff-sentinel]
        I[GitHub Action Runner]
        J[Model Context Protocol Server]
    end
    
    G --> H
    G --> I
    G --> J
    
    J <--> K[Claude Code / Claude Desktop]
    J <--> L[OpenAI Codex / Custom Agents]

🚀 Quick Start

1. Run via CLI

# Analyze git diff from latest commit
git diff HEAD~1 | diff-sentinel diff

# Run strict audit (fails CI if high risk or secrets are found)
git diff HEAD~1 | diff-sentinel diff --strict

# Output machine-readable JSON for automated pipelines
diff-sentinel diff pr.patch --json

2. Triage an Issue

diff-sentinel triage "Crash on startup when parsing malformed diff" issue_body.md

3. Generate Semantic Release Changelog

git log -n 20 --oneline | diff-sentinel changelog 1.2.0

4. Audit Repository Hygiene

diff-sentinel audit .

🤖 Model Context Protocol (MCP) Integration

diff-sentinel ships with a native Model Context Protocol server. This allows AI assistants like Claude Code, Claude Desktop, and Cursor to execute repository audits and diff reviews autonomously.

Configure Claude Desktop (claude_desktop_config.json)

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "diff-sentinel": {
      "command": "node",
      "args": [
        "--experimental-strip-types",
        "/absolute/path/to/diff-sentinel/src/cli.ts",
        "mcp"
      ]
    }
  }
}

Available MCP Tools

🐙 GitHub Action Setup

Add diff-sentinel directly into your GitHub repository to gate every pull request:

Create .github/workflows/sentinel-review.yml:

name: Pull Request Sentinel Audit

on:
  pull_request:
    branches: [main, master]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run diff-sentinel
        uses: your-username/diff-sentinel@v1
        with:
          base-ref: ${{ github.base_ref }}
          strict: true

🧪 Testing

diff-sentinel contains a 100% native test suite running via Node's built-in test runner without any external runtime dependencies:

npm test

🤝 Contributing

We love contributions! Please read our Contributing Guide and review our Code of Conduct.

📄 License

Licensed under the Apache License, Version 2.0. See LICENSE for details.