Blind Auditor - MCP Server

1# 🛡️ Blind Auditor - MCP Server
2 
3"Code -> audit -> amend -> audit again -> pass."
4 
5Blind 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.
6 
7## 🧠 Core Philosophy: Thinking Isolation
8 
9Traditional AI coding is often "generate and output," which allows errors and biases to slip through. Blind Auditor introduces a middle layer:
10 
111.  **Intercept**: When the Agent wants to output code, it must first submit it to Blind Auditor.
122.  **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.
133.  **Audit**: In this isolated context, the Agent must scan the generated code line by line against the predefined `rules.json`.
144.  **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.
15 
16## 🎯 Key Features
17 
18- **🛡️ Zero Trust Architecture**: Default distrust of the Agent's initial draft; it must pass an audit.
19- **💰 Zero Extra Cost**: Reuses the host IDE's current session model, requiring no additional API Key.
20- **⚖️ Bias Removal**: Forces a perspective switch via Prompt injection to break generation inertia.
21- **📏 Strict Compliance**: Hard-codes team code standards (`rules.json`) into the generation process, which is more effective than simple Prompts.
22- **🔄 Auto-Fix Loop**: Automatically triggers a "fix-resubmit" loop upon audit failure until compliance is met or the maximum retry count is reached.
23 
24---
25 
26## 🚀 Quick Start
27 
28### 1. Prerequisites
29 
30This project requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
31 
32```bash
33# Install uv (if not already installed)
34curl -LsSf https://astral.sh/uv/install.sh | sh
35 
36# Enter project directory
37cd blind-auditor
38 
39# Install dependencies (automatically creates virtual environment)
40uv sync
41```
42 
43### 2. Configure Audit Rules (`rules.json`)
44 
45Create or edit `rules.json` in the project root. This is the auditor's "Rulebook".
46 
47```json
48{
49  "project_name": "MyCoreProject",
50  "strict_mode": true,
51  "max_retries": 3,
52  "rules": [
53    {
54      "id": "SEC-001",
55      "severity": "CRITICAL",
56      "description": "Strictly prohibit hardcoding any API Keys, passwords, or sensitive Tokens.",
57      "weight": 50
58    },
59    {
60      "id": "PERF-001",
61      "severity": "WARNING",
62      "description": "Avoid database queries or IO operations inside loops.",
63      "weight": 15
64    },
65    {
66      "id": "STYLE-001",
67      "severity": "PREFERENCE",
68      "description": "Use snake_case for variable names.",
69      "weight": 5
70    }
71  ]
72}
73```
74 
75**Configuration Fields**:
76- `severity`:
77    - `CRITICAL`: Fatal error. If found, the audit fails immediately. Usually carries a high penalty.
78    - `WARNING`: Warning. Moderate penalty; accumulation can lead to failure.
79    - `PREFERENCE`: Style preference. Low penalty.
80- `weight`: The penalty points deducted when this rule is violated (Total score: 100).
81 
82### 3. Configure IDE (Antigravity / Cursor / Windsurf)
83 
84#### Step A: Add System Prompt (Critical)
85 
86To ensure the Agent knows it must use this tool, add the following instruction to your `.cursorrules` or IDE System Prompt settings:
87 
88```markdown
89# Blind Auditor Protocol
90**CRITICAL INSTRUCTION**:
91You are integrated with the **Blind Auditor MCP**.
92Whenever you generate code for a user request, you **MUST NOT** output the code block directly to the user.
93 
94**Execution Protocol**:
951.  **Draft**: Generate the code internally in your thought process.
962.  **Submit**: Call the `submit_draft` tool with your code and language.
973.  **Obey**: The tool will return a strict "Audit Instruction". You MUST follow it exactly to audit your own code.
984.  **Finalize**: Only when the tool returns "✅ AUDIT PASSED" can you display the final code to the user.
99 
100**Prohibited**:
101- Do NOT output code blocks before passing the audit.
102- Do NOT skip the audit step for "simple" changes.
103```
104 
105#### Step B: Configure MCP Server
106 
107Add the following to your MCP client configuration file (e.g., `claude_desktop_config.json` or IDE settings):
108 
109**Note**: Replace `/path/to/your/blind-auditor` with the actual absolute path where you cloned this repository.
110 
111```json
112{
113  "mcpServers": {
114    "blind-auditor": {
115      "command": "uv",
116      "args": ["run", "--directory", "/path/to/your/blind-auditor", "blind-auditor"]
117    }
118  }
119}
120```
121 
122---
123 
124## 🔧 Tool Details
125 
126### 1. `submit_draft`
127Submit a code draft.
128- **Input**: `code` (content), `language` (programming language)
129- **Behavior**: Locks the session and returns mandatory audit instructions.
130 
131### 2. `submit_audit_result`
132Submit your audit conclusion.
133- **Input**:
134    - `passed` (bool): Whether you believe it passed.
135    - `issues` (list): List of issues found.
136    - `score` (int): Score from 0-100.
137- **Behavior**:
138    - If `score < 80`, forces `passed=False`.
139    - If passed, unlocks the code.
140    - If failed, increments retry count and requires the Agent to fix and resubmit.
141 
142### 3. `reset_session`
143Resets the state and clears the retry count.
144 
145---
146 
147## 🔁 Workflow Diagram
148 
149```mermaid
150graph TD
151    User["User Request"] --> Agent
152    Agent["Agent Generates Draft"] -->|1. submit_draft| MCP
153    MCP -->|2. Inject Audit Instructions| Agent
154    
155    subgraph Isolation ["Thinking Isolation"]
156        Agent -->|3. Self-Review| Agent
157        Agent -->|4. submit_audit_result| MCP
158    end
159    
160    MCP -->|5. Verdict| Decision{"Passed?"}
161    
162    Decision -->|No - Issues Found| Retry["Retry Count +1"]
163    Retry -->|Limit Not Reached| Fix["Agent Fixes Code"]
164    Fix -->|Resubmit| Agent
165    
166    Decision -->|Yes - Score >= 80| Final["✅ Output Final Code"]
167    
168    Retry -->|Limit Reached| Force["⚠️ Force Output - With Warning"]
169```
170 
171## ❓ Troubleshooting
172 
173**Q: The Agent always outputs code directly without calling tools.**
174A: 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".
175 
176**Q: Why does it fail even if I give the code 100 points?**
177A: 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.
178 
179**Q: Which programming languages are supported?**
180A: 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`.
181 
182---
183 
184## 🛠️ Development Guide
185 
186```bash
187# Run server
188uv run blind-auditor
189 
190# Or run directly with Python module
191uv run python -m src.main
192 
193# Debug mode (output to stderr)
194# View print statements in src/main.py
195```
196 
197## 📄 License
198 
199MIT License
200