# 🛡️ 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.
## 🎯 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](https://docs.astral.sh/uv/).
```bash
# 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".
```json
{
"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:
```markdown
# 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.
```json
{
"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
```mermaid
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
```bash
# 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
