🛡️ Edit Math Supervisor (MCP Server)

An implementation of the Edit Approval State Machine (EASM)

A stateful gatekeeper for AI-driven code editing

Overview

This project implements a Model Context Protocol (MCP) server that acts as an architectural gatekeeper between an AI coding agent and the file system.

Its purpose is simple:

An AI is not allowed to edit code unless it has demonstrated awareness of the consequences and obtained explicit human approval.

The server enforces this rule procedurally, not heuristically.

---

Why this exists

Modern AI coding assistants can generate and apply code changes faster than humans can reliably reason about their impact.

This creates a dangerous asymmetry:

• the AI can act immediately
• the human can only review after the fact

In practice, this leads to:

• silent breaking changes
• accidental dependency violations
• refactors without understanding downstream effects

This project explores a different model.

The AI must stop. Explain. Ask. And wait.

Only then is it allowed to modify code.

---

🧠 Philosophy: Architectural Control over AI Action

This project is intentionally not focused on making AI “smarter”.

Instead, it explores a different question:

What architectural constraints are required when an AI system is allowed to act on real code?

Most AI coding tools optimize for fluency and speed. This project optimizes for procedural awareness.

The core assumption is simple: AI systems do not lack intelligence —
they lack structural incentives to pause, explain, and verify.

The Edit Approval State Machine introduces such a structure.

It forces the AI to:

• stop before acting
• externalize its assumptions
• acknowledge dependencies
• wait for explicit human intent

In this model, the human provides intent and responsibility. The AI provides execution and analysis.

The result is not “better code generation”, but controlled code modification.

---

The core idea: Edit Approval State Machine (EASM)

At the heart of this server is the Edit Approval State Machine —
a security and control pattern for AI-driven code edits.

Each edit target exists in one of three states:

• NONE
  No approval. Editing is forbidden.

• PENDING
  Dependencies have been analyzed.
  The system is waiting for explicit human confirmation.

• APPROVED
  Permission granted.
  A single safe edit is allowed.

State transitions are enforced by the server. The AI cannot skip steps, self-approve, or persist approval silently.

---

Human confirmation token

For any edit that is potentially non-trivial — for example:

• detected dependencies
• renaming
• declared breaking changes

the server requires an explicit human confirmation token.

By default, this token is the literal string: ок

The token:

• must come from the user
• is validated by the server
• cannot be generated or assumed by the AI on first pass

This creates a hard human-in-the-loop boundary.

---

What this project is (and is not)

This project is:

• a procedural safety layer for AI coding agents
• a stateful MCP server enforcing edit discipline
• an experiment in AI control, not AI intelligence

This project is not:

• ❌ a linter
• ❌ a static analyzer
• ❌ a sandbox
• ❌ a code correctness verifier

The goal is not to prove code correctness.

The goal is to prevent unreviewed action.

---

Supported analysis

The server performs lightweight dependency extraction using:

• Python AST (ast)
• Tree-sitter for JavaScript, TypeScript, and HTML

The analysis is intentionally conservative and incomplete. It is used to force awareness and explanation, not to model full semantics.

---

Threat model

This project assumes:

• AI agents optimize for task completion speed
• AI agents may skip reasoning steps if not explicitly blocked
• silent failures are more dangerous than slow workflows

As a result, the system is designed to fail closed.

---

Typical workflow

1. AI requests dependency analysis for a target
2. Server returns detected dependencies and revokes edit access
3. AI explains risks and plan to the user
4. User explicitly confirms by typing ok
5. Server grants approval for a single edit
6. Approval is reset after commit

Any deviation resets the process.

---

Origin

This project and the Edit Approval State Machine (EASM) pattern were created by Annenkov Yuriy in 2025.

The goal was to explore architectural safeguards for AI-assisted software development, especially in environments where correctness and trust matter.

---

🆕 What's New in v1.5.0

• Python Support: Native AST parsing for Python files.
• HTML Support: Dependency detection in <script> tags and event handlers.
• 2-Step Handshake: New security mechanism. The server now requires a specific token ('ok') to confirm dangerous edits, preventing the AI from "hallucinating" user consent.
• Renaming Detection: Automatically triggers Strict Mode if a function signature changes.

---

✨ Key Features

• Polyglot AST Parsing: Accurate dependency detection for JavaScript, TypeScript, Python, and HTML.
• 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, the server forces it to stop and ask the user for confirmation using a secure handshake protocol.
• Smart Filtering: Automatically ignores standard language methods (e.g., .map(), print()) 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, the server puts the request in PENDING state and demands user 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/yrannkv/mcp-edit-math.git
   cd mcp-edit-math
   

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

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

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"]
       }
     }
   }
   

⚡ Quick Start (via uvx)

If you use uv, you can run the server directly without cloning the repo:

{
  "mcpServers": {
    "edit-math": {
      "command": "uvx",
      "args": ["mcp-edit-math"]
    }
  }
}

---

🤖 System Prompt (Required)

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

=== 🛡️ EDIT MATH PROTOCOL (v1.5.0) ===
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)`.
   - **REQUIRED:** Provide `file_path` (absolute or relative) to scope the security check.
   - Determine `language` ("js", "ts", "html", "python") based on file extension.

2. 🎫 GET TICKET: Call `calculate_integrity_score`.
   - **REQUIRED:** Provide `file_path` matching the scan step.
   - **REQUIRED:** Provide `proposed_header` to check for renaming.
   - **If server returns "STOP. INTERVENTION REQUIRED":**
     a. STOP generating immediately.
     b. Present the plan/conflicts to the user.
     c. ASK: "Do you approve? (Type 'ok')"
     d. **CRITICAL:** END YOUR TURN. Do not simulate user response.
     e. When user replies "ok", call `calculate_integrity_score` again with `confirmation_token='ok'`.

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

☕ Support the Project

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

• EVM (Ethereum / Base / BNB): 0x2D7CDf70F44169989953e4cfA671D0E456fBe465
• Solana: CGG9JouoxAs5Lja948h8ktn3CxLmbVmH1ocxPLEPCfVx
• Bitcoin: bc1q30u6rsyu8gx3urcf20p36npgj4uc2aan7k5ntn

---

License: Apache-2.0 Author: Annenkov Yuriy