# 🛡️ Senior SDE MCP Guard

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

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)

**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`):

```bash
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:

```markdown
# 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:

```markdown
# 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`:

```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:

```yaml
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:

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

### Sample Output on Rejection:

```text
❌ [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](LICENSE). Built by [Amir Madani](https://github.com/amirmadani).