🛡️ Senior SDE MCP Guard

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

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.

---

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

Option A: Per-Project Activation (Recommended)

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.