🛡️ Edit Math Supervisor (MCP Server)

Architectural Gatekeeper for AI Coding Assistants.

Edit Math Supervisor is an advanced Model Context Protocol (MCP) server that acts as a Stateful Gatekeeper for AI coding assistants (Claude Desktop, Roo Code, Cline, Lingma).

It prevents "Tunnel Vision" by forcing the AI to verify code dependencies before editing. Unlike simple linters, this server physically blocks file saving until the AI proves that the changes are safe.

---

✨ Key Features

• AST Parsing (Tree-sitter): Accurate dependency detection for JavaScript and TypeScript. Understands classes, nested functions, and this context.
• Stateful Gatekeeper: The server tracks verification status. The commit_safe_edit tool returns ⛔ ACCESS DENIED if the Integrity Score is not 1.0.
• Interactive Conflict Resolution: If the AI detects breaking changes or cannot verify an external dependency, the server forces it to ask the user for permission before proceeding.
• Smart Filtering: Automatically ignores standard language methods (e.g., .map(), console.log) to keep the focus on your business logic.

🚀 The "#editmath" Protocol

The server enforces a strict workflow:

1. 🔍 SCAN: The AI scans the target function using AST.
2. 🎫 TICKET: The AI verifies dependencies. If conflicts exist, it must ask the user for confirmation.
3. 💾 COMMIT: Only with a valid ticket (or user override) can the AI save changes.

📦 Installation

1. Clone the repository:

   git clone https://github.com/your-username/mcp-edit-math.git
   cd mcp-edit-math
   

2. Install dependencies: Note: Specific versions are recommended for stability.

   pip install mcp tree-sitter==0.21.3 tree-sitter-javascript==0.21.0 tree-sitter-typescript==0.21.0
   

3. Configure your MCP Client: Add this to your configuration file (e.g., claude_desktop_config.json):

   {
     "mcpServers": {
       "edit-math": {
         "command": "python",
         "args": ["/absolute/path/to/mcp-edit-math/mcp_edit_math.py"]
       }
     }
   }
   

🤖 System Prompt (Required)

Add this to your AI's Custom Instructions or .cursorrules to activate the protocol:

=== 🛡️ EDIT MATH PROTOCOL ===
Trigger: When user types "#editmath".

You are operating under a strict safety protocol. Direct file editing is FORBIDDEN.
Follow this sequence precisely:

1. 🔍 SCAN: Call `scan_dependencies(code, target_function)`.
   - Determine `language` ("js", "ts") based on file extension.

2. 🎫 GET TICKET: Call `calculate_integrity_score`.
   - **If server returns "STRICT MODE INTERVENTION":**
     a. STOP. Do not proceed.
     b. ASK THE USER: Explain the plan/conflicts and ask "Do you approve?".
     c. WAIT for the user's "Yes".
     d. RE-CALL `calculate_integrity_score` with `user_confirmed=True`.

3. 💾 COMMIT: Call `commit_safe_edit`.
   - If you need to force a commit (e.g., for unverified external libs), ask the user first, then use `force_override=True`.

### 🧘‍♀️ Philosophy: The Meta-Project

This project is a result of **pure Vibecoding**.

It was built *by* an AI, *for* AIs.
I realized that while AI coding is powerful, it lacks architectural awareness. So, I directed **Google Gemini** to build its own "Supervisor" — a tool that forces it to pause, think, and verify dependencies before writing code.

It is a self-correcting mechanism for the AI-assisted development era.

<a id="donate"></a>
## ☕ Support the Project

If this tool saved you time or prevented a bug, you can support the development via crypto:

*   **EVM (Ethereum / Base / BNB):** `0x13cA48D52bd7bB4f12Daa39730299b21c6DaA566`
*   **Solana:** `3TPUjSQ77GaCESp1Dugt8AjQJaD51jHAtckEQNLuWd83`
*   **Bitcoin:** `bc1qsles2ylewztk5297hnmfqwmjt2lk9qgchd78at`

---
License: Apache-2.0
Author: Annenkov Yuriy
**Co-authored with:** Google Gemini