Skip to main content
Glama
Blind-Auditor-MCP

Blind-Auditor-MCP

by Sim-xia

🛡️ Blind Auditor - MCP Server

"Code -> audit -> amend -> audit again -> pass."

Blind Auditor is a mandatory code auditing system built on the MCP (Model Context Protocol). It uses a unique "Thinking Isolation" mechanism to force AI Agents to enter an independent "audit phase" and self-review their code before outputting the final result.

🧠 Core Philosophy: Thinking Isolation

Traditional AI coding is often "generate and output," which allows errors and biases to slip through. Blind Auditor introduces a middle layer:

  1. Intercept: When the Agent wants to output code, it must first submit it to Blind Auditor.

  2. Isolate: Blind Auditor does not return the result immediately. Instead, it injects a mandatory system instruction, forcing the Agent to pause its current persona and switch to a "Ruthless Auditor" role.

  3. Audit: In this isolated context, the Agent must scan the generated code line by line against the predefined rules.json.

  4. Release: The code is unlocked and returned to the user only when the audit score meets the threshold (default > 80) and there are no Critical issues.

Related MCP server: MeshMind

🎯 Key Features

  • 🛡️ Zero Trust Architecture: Default distrust of the Agent's initial draft; it must pass an audit.

  • 💰 Zero Extra Cost: Reuses the host IDE's current session model, requiring no additional API Key.

  • ⚖️ Bias Removal: Forces a perspective switch via Prompt injection to break generation inertia.

  • 📏 Strict Compliance: Hard-codes team code standards (rules.json) into the generation process, which is more effective than simple Prompts.

  • 🔄 Auto-Fix Loop: Automatically triggers a "fix-resubmit" loop upon audit failure until compliance is met or the maximum retry count is reached.


🚀 Quick Start

1. Prerequisites

This project requires Python 3.10+ and uv.

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Enter project directory
cd blind-auditor

# Install dependencies (automatically creates virtual environment)
uv sync

2. Configure Audit Rules (rules.json)

Create or edit rules.json in the project root. This is the auditor's "Rulebook".

{
  "project_name": "MyCoreProject",
  "strict_mode": true,
  "max_retries": 3,
  "rules": [
    {
      "id": "SEC-001",
      "severity": "CRITICAL",
      "description": "Strictly prohibit hardcoding any API Keys, passwords, or sensitive Tokens.",
      "weight": 50
    },
    {
      "id": "PERF-001",
      "severity": "WARNING",
      "description": "Avoid database queries or IO operations inside loops.",
      "weight": 15
    },
    {
      "id": "STYLE-001",
      "severity": "PREFERENCE",
      "description": "Use snake_case for variable names.",
      "weight": 5
    }
  ]
}

Configuration Fields:

  • severity:

    • CRITICAL: Fatal error. If found, the audit fails immediately. Usually carries a high penalty.

    • WARNING: Warning. Moderate penalty; accumulation can lead to failure.

    • PREFERENCE: Style preference. Low penalty.

  • weight: The penalty points deducted when this rule is violated (Total score: 100).

3. Configure IDE (Antigravity / Cursor / Windsurf)

Step A: Add System Prompt (Critical)

To ensure the Agent knows it must use this tool, add the following instruction to your .cursorrules or IDE System Prompt settings:

# Blind Auditor Protocol
**CRITICAL INSTRUCTION**:
You are integrated with the **Blind Auditor MCP**.
Whenever you generate code for a user request, you **MUST NOT** output the code block directly to the user.

**Execution Protocol**:
1.  **Draft**: Generate the code internally in your thought process.
2.  **Submit**: Call the `submit_draft` tool with your code and language.
3.  **Obey**: The tool will return a strict "Audit Instruction". You MUST follow it exactly to audit your own code.
4.  **Finalize**: Only when the tool returns "✅ AUDIT PASSED" can you display the final code to the user.

**Prohibited**:
- Do NOT output code blocks before passing the audit.
- Do NOT skip the audit step for "simple" changes.

Step B: Configure MCP Server

Add the following to your MCP client configuration file (e.g., claude_desktop_config.json or IDE settings):

Note: Replace /path/to/your/blind-auditor with the actual absolute path where you cloned this repository.

{
  "mcpServers": {
    "blind-auditor": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/your/blind-auditor", "blind-auditor"]
    }
  }
}

🔧 Tool Details

1. submit_draft

Submit a code draft.

  • Input: code (content), language (programming language)

  • Behavior: Locks the session and returns mandatory audit instructions.

2. submit_audit_result

Submit your audit conclusion.

  • Input:

    • passed (bool): Whether you believe it passed.

    • issues (list): List of issues found.

    • score (int): Score from 0-100.

  • Behavior:

    • If score < 80, forces passed=False.

    • If passed, unlocks the code.

    • If failed, increments retry count and requires the Agent to fix and resubmit.

3. reset_session

Resets the state and clears the retry count.


🔁 Workflow Diagram

graph TD
    User["User Request"] --> Agent
    Agent["Agent Generates Draft"] -->|1. submit_draft| MCP
    MCP -->|2. Inject Audit Instructions| Agent
    
    subgraph Isolation ["Thinking Isolation"]
        Agent -->|3. Self-Review| Agent
        Agent -->|4. submit_audit_result| MCP
    end
    
    MCP -->|5. Verdict| Decision{"Passed?"}
    
    Decision -->|No - Issues Found| Retry["Retry Count +1"]
    Retry -->|Limit Not Reached| Fix["Agent Fixes Code"]
    Fix -->|Resubmit| Agent
    
    Decision -->|Yes - Score >= 80| Final["✅ Output Final Code"]
    
    Retry -->|Limit Reached| Force["⚠️ Force Output - With Warning"]

❓ Troubleshooting

Q: The Agent always outputs code directly without calling tools. A: Check if the System Prompt is configured correctly. You must explicitly tell the Agent "Do NOT output code directly". You can also manually remind it in the chat: "Please audit via Blind Auditor first".

Q: Why does it fail even if I give the code 100 points? A: Check if any CRITICAL rules in rules.json were triggered. Current logic mainly relies on the score passed by the Agent, but if passed is True while score < 80, the system will force a rejection.

Q: Which programming languages are supported? A: Theoretically, all languages are supported. Blind Auditor itself does not parse code syntax but relies on the Agent's understanding to match descriptions in rules.json.


🛠️ Development Guide

# Run server
uv run blind-auditor

# Or run directly with Python module
uv run python -m src.main

# Debug mode (output to stderr)
# View print statements in src/main.py

📄 License

MIT License

Available Tools

4 tools
reset_sessionB

Reset the current audit session.

Inputs: no named parameters. Returns: result

submit_audit_resultD

Submit the audit result.

Inputs: passed (required), issues (required), score. Returns: result

submit_draftC

Submit a code draft for audit.

Inputs: code (required), language. Returns: result

update_rulesA
Update audit rules configuration.

Args:
	action: Operation to perform - "add", "remove", "update", or "list"
	rule_id: Rule identifier (required for add/remove/update)
	severity: Rule severity level - "CRITICAL", "WARNING", or "PREFERENCE" (for add/update)
	description: Rule description (for add/update)
	weight: Point deduction weight 0-100 (for add/update)

Returns:
	Status message with operation result

Examples:
	# List all rules
	update_rules(action="list")
	
	# Add a new rule
	update_rules(
		action="add",
		rule_id="SEC-001",
		severity="CRITICAL",
		description="No hardcoded API keys",
		weight=50
	)
	
	# Remove a rule
	update_rules(action="remove", rule_id="SEC-001")
	
	# Update a rule
	update_rules(
		action="update",
		rule_id="SEC-001",
		description="Updated description"
	)

Inputs: action (required), rule_id, severity, description, +1 more. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: reset_session handles session management, submit_audit_result and submit_draft handle different submission types (final results vs. code drafts), and update_rules handles rule configuration. The tools target different resources and actions, making misselection unlikely.

    Naming Consistency4/5

    Three tools follow a consistent verb_noun pattern (reset_session, submit_audit_result, submit_draft), while update_rules also fits this pattern but uses a different verb style ('update' vs. 'reset'/'submit'). The naming is mostly consistent with only minor deviation in verb choice.

    Tool Count5/5

    With 4 tools, this is well-scoped for an audit server. Each tool earns its place by covering core audit workflow stages: session management, rule configuration, draft submission, and result submission. The count is neither too sparse nor bloated for the domain.

    Completeness4/5

    The toolset covers the essential audit lifecycle: configure rules, submit drafts, submit results, and manage sessions. A minor gap exists in lacking a tool to retrieve or review audit results/history, but agents can work around this using the existing submission tools. Core workflows are well-supported.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers