Skip to main content
Glama
senior-sde-mcp-guard

senior-sde-mcp-guard

by amirmadani

šŸ›”ļø Senior SDE MCP Guard

Universal AST Gatekeeper & Architectural Guardrail for AI Coding Agents (Antigravity, Cursor, Claude Code, Kiro)

Python 3.10+ License: MIT MCP Compatible

Senior SDE MCP Guard is a high-performance, cross-platform Abstract Syntax Tree (AST) gatekeeper that prevents AI agents from generating messy, unmaintainable, or anti-pattern code. It acts as an active Senior Staff Software Engineer auditing file writes before they land in your codebase.


🌟 Why Senior SDE Guard?

AI coding assistants (Antigravity, Cursor, Claude Code, Kiro) are incredible at writing fast code, but often produce architectural smells:

  • āŒ God Classes (300+ lines of bloated code dumping all responsibilities into one file)

  • āŒ Parameter Bloat (functions taking 7–10 arguments instead of structured DTO objects)

  • āŒ Deep Control Nesting (The "Arrow Anti-Pattern" of nested if/for/try loops)

  • āŒ Silent Error Swallowing (except: pass or empty catch blocks)

  • āŒ Hardcoded Secrets (Accidentally writing API keys or tokens into source files)

Senior SDE MCP Guard executes deterministic AST analysis in < 10 milliseconds at $0.00 cost, rejecting bad architectural edits and forcing the AI agent to refactor immediately.


Related MCP server: mcp-edit-math

šŸš€ Installation & Setup

1. Install Package

Install via pip (or run directly with uvx):

pip install senior-sde-mcp-guard

āš™ļø How to Activate in Antigravity

You can activate the Senior SDE Guard in Antigravity either Per-Project or Globally Across All Projects.

Add a .agents/AGENTS.md file to the root of your project directory:

  1. Create directory .agents/ in your project root.

  2. Create file .agents/AGENTS.md with these instructions:

# Project Rules for Antigravity

## Senior SDE Gatekeeper Rule
Whenever creating or editing code files in this workspace:
1. After editing or creating any `.py` file, execute the Senior SDE check:
   `python -m senior_sde_guard.cli check <file_path>`

2. If any AST violations are reported (e.g. Class size > 300 lines, Function lines > 60, Parameter count > 5, bare exceptions, or missing type hints), immediately refactor the code to fix all reported violations before completing the task.

Option B: Global Activation Across All Projects (System-Wide)

To make Antigravity enforce the Senior SDE Guard automatically across every project on your computer without adding .agents to every folder:

  1. Open your global user configuration directory:

    • Windows: C:\Users\<YourUsername>\.gemini\config\

    • macOS/Linux: ~/.gemini/config/

  2. Create or edit the AGENTS.md file in that folder: C:\Users\<YourUsername>\.gemini\config\AGENTS.md

  3. Add the following rule:

# Global Rules for Antigravity

## Senior SDE Gatekeeper Rule (Global)
Whenever creating or editing code files in any workspace:
1. After editing or creating any `.py` file, execute the Senior SDE check:
   `python -m senior_sde_guard.cli check <file_path>`

2. If any AST violations are reported, immediately refactor the code to fix all reported violations before completing the task.

Now Antigravity will automatically check and enforce Senior SDE standards on every codebase you work on!


āš™ļø Activation in Cursor, Claude Code, & Kiro (MCP Mode)

Add senior-sde-guard to your mcp.json or claude_desktop_config.json:

{
  "mcpServers": {
    "senior-sde-guard": {
      "command": "uvx",
      "args": ["senior-sde-mcp-guard", "serve"]
    }
  }
}

šŸ“‹ Customizing Rules (.gatekeeper.yaml)

Place a .gatekeeper.yaml in your project root to customize your team's architectural thresholds:

version: 1
strict_mode: true

rules:
  # Maintainability & Complexity (Pragmatic Enterprise Defaults)
  max_file_lines: 600
  max_class_lines: 300
  max_function_lines: 60
  max_function_params: 5
  max_cyclomatic_complexity: 12
  max_nesting_depth: 4

  # Reliability & Security
  block_bare_except: true
  block_silent_errors: true
  block_wildcard_imports: true
  detect_secrets: true
  require_type_hints: true

šŸ› ļø CLI Usage

You can also run the guardrail manually or via pre-commit hooks:

# Audit a single file
senior-sde-guard check src/services/order_service.py

Sample Output on Rejection:

āŒ [Senior SDE Gatekeeper REJECTED] File 'src/services/order_service.py' failed 3 quality check(s):

  • Line 42 [max_class_lines]: Class 'OrderManager' is 380 lines long (Max allowed: 300). Split responsibilities into sub-modules.
  • Line 115 [max_function_params]: Function 'process_order' has 7 parameters (Max allowed: 5). Pass a configuration object or dataclass.
  • Line 180 [block_bare_except]: Bare 'except:' statement detected. Catch specific exception classes.

āš ļø ACTION REQUIRED: Refactor the code to fix these architectural issues before writing to disk.

šŸ“„ License

Licensed under the MIT License. Built by Amir Madani.

Available Tools

2 tools
audit_fileA

Reads an existing workspace file from disk and audits it against Senior SDE AST rules.

Inputs: file_path (required). Returns: result

check_code_qualityA

Audits code against Senior Staff Software Engineer AST rules (Class size, Complexity, Parameter count, Type hints, Secret leakage, Bare exceptions).

Inputs: code_content (required), file_path. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 2 tools

    Disambiguation4/5

    The two tools are distinct in their input: check_code_quality presumably audits code provided directly, while audit_file reads a file from disk. However, both perform the same core action (auditing against AST rules), causing minor potential for confusion if the input types are not obvious.

    Naming Consistency5/5

    Both tool names follow a clear verb_noun pattern (check_code_quality, audit_file). The verbs are different but semantically similar, and the structure is consistent, making the naming predictable and easy to parse.

    Tool Count3/5

    With only two tools, the server feels thin for its stated purpose of code quality auditing. It covers direct code and files, but the minimal count suggests a limited scope that may not handle broader workflows.

    Completeness3/5

    The domain is code quality auditing, and the tools cover auditing code snippets and files. However, there is no tool to list or retrieve the AST rules, adjust audit scope (e.g., directories), or provide remediation guidance, leaving notable gaps in the workflow.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Provides real-time policy enforcement for AI coding agents by intercepting and validating their actions against organizational standards like naming conventions, security policies, and compliance rules before execution. Prevents violations through immediate feedback and auto-correction suggestions.
      5
      -
    • A
      license
      C
      quality
      D
      maintenance
      Architectural Gatekeeper for AI coding. Prevents "tunnel vision" bugs by forcing the AI to verify dependencies (via AST parsing) before editing files. Supports JavaScript & TypeScript. Blocks unsafe edits until the AI proves it understands the impact
      3
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Stops your AI from re-introducing bugs, leaking provider keys, or weakening tests. Bug fixes become permanent regression guards; blocked mistakes become AI lessons the agent reads and learns from before its next edit.
      6
      2
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI coding assistants to analyze codebases locally before generating code, reducing duplication and enforcing architecture boundaries.
      1
      3
      MIT