## ✨ Key Features

* **Zero-Cost Local Critic:** Offload heavy code review iterations to your local GPU via LM Studio without spending cloud tokens.
* **Sub-Millisecond AST Sentinel:** Catches syntax errors and dangerous runtime calls (`eval`, `exec`, `os.system`, `subprocess`) before wasting GPU cycles.
* **Deterministic Contract:** Enforces structured outputs (`APPROVED` vs `REJECTED` with specific line feedback) so the agent automatically refactors code without human intervention.
* **Dual Data Sink (DPO Flywheel):**
  * **SQLite (`audit_history.db`):** Tracks duration, categories, and metrics.
  * **Per-Audit JSON (`audit_logs/`):** Stores individual audit records to easily build DPO / Fine-tuning datasets from paired rejected/approved attempts.

---

## 🚀 Quick Start

### 1. Prerequisites
* Python 3.10+
* [LM Studio](https://lmstudio.ai/) running an OpenAI-compatible Local Server (`http://localhost:1234/v1`)
* [Antigravity](https://github.com) or any MCP-compatible client

2. Installation

```bash
# Clone the repository
git clone [https://github.com/xTanThaix/mcp-local-auditor.git](https://github.com/xTanThaix/mcp-local-auditor.git)
cd mcp-local-auditor

# Set up virtual environment
python -m venv .venv

# Activate virtual environment
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

### 3. Register MCP Server
Open your Antigravity MCP config file:
* **Windows:** `%USERPROFILE%\.gemini\config\mcp_config.json`
* **macOS / Linux:** `~/.gemini/config/mcp_config.json`

Add the server definition inside `mcpServers`:

```json
{
  "mcpServers": {
    "lmstudio-auditor": {
      "command": "D:\\Hucdeline\\.venv\\Scripts\\python.exe",
      "args": ["D:\\Hucdeline\\auditor_bridge.py"]
    }
  }
}
```
> **Note:** Replace `D:\\Hucdeline` with your actual project directory path.

---

### 4. Configure LM Studio
1. Open **LM Studio** and load any instruction-tuned coding model (e.g., `Qwen-2.5-Coder`, `DeepSeek-Coder`, `Llama-3`).
2. Go to the **Local Server** (Developer) tab.
3. Set Port to `...(e.g.,1234)` and click **Start Server**.

---

## 🤖 Agent Loop Setup (Custom Rule / Skill)

Add the following rule to your Antigravity Agent (`mcp-studio-loop`):

```markdown
# Mandatory MCP Code Audit Protocol
Every time code is generated or refactored, you MUST invoke the `audit_submission` tool:
- Arguments: `task_goal`, `output_content`, `strict_rules`
- If STATUS == "REJECTED": Read `ACTIONABLE_FEEDBACK`, refactor the code, and re-submit.
- If STATUS == "APPROVED": Output the final solution to the user.
- Maximum retry limit: 5 attempts before breaking loop.
```

4. Configure LM Studio
Open LM Studio and load any instruction-tuned coding model (e.g., Qwen-2.5-Coder, DeepSeek-Coder, Llama-3).

Go to the Local Server tab.

Set Port to xxxx and click Start Server.

🤖 Agent Loop Setup (Custom Rule / Skill)
Add the following rule to your Antigravity Agent (mcp-studio-loop):

Markdown
# Mandatory MCP Code Audit Protocol
Every time code is generated or refactored, you MUST invoke the `audit_submission` tool:
- Arguments: `task_goal`, `output_content`, `strict_rules`
- If STATUS == "REJECTED": Read `ACTIONABLE_FEEDBACK`, refactor the code, and re-submit.
- If STATUS == "APPROVED": Output the final solution to the user.
- Maximum retry limit: 5 attempts before breaking loop.
🧪 Testing
Run the included Pytest suite to verify AST checks, SQLite migrations, and mock responses:

Bash
pytest test_auditor.py -v

## 📸 Real-World Audit in Action (Example Usage / Usage Example)

Here is an example of `MCP Local Auditor` rejecting an unoptimized code path with actionable feedback, prompting the coding agent to self-heal and re-verify:
Example Usage: After the tests pass, audit each modified file one by one using the "lmstudio-auditor" tool.

<img width="1007" height="805" alt="355a4b51-1d4c-4e9c-8a74-38247be83340" src="https://github.com/user-attachments/assets/17bc3ed9-92e3-4de6-93a0-553a5ef20e7e" />

💖 Support & Donations
If this project saved you API costs and helped streamline your local LLM workflow, consider supporting development:

Ko-fi: [https://ko-fi.com/xtanthaix](https://ko-fi.com/xtanthaix)

GitHub Sponsors: Click the Sponsor button on this repository

📄 License
MIT License. Free for open-source and commercial use.