
<img align="center" width="197" height="240" alt="Puli-Icon" src="https://github.com/user-attachments/assets/f8c608c3-17d5-4274-a494-98c16b0a77c2" />

# 🛡️ The Puli Guardian MCP

### Puli Reviewer
is a proactive security and stability guardrail for your 
AI coding agents (Claude Code, Cursor, Antigravity, etc.). 
It prevents production breakages by confronting proposed 
code changes with a massive, real-time database of global 
incidents, edge cases, and security breaches.

**Stop production errors before they happen.**

Puli acts as a real-time bridge between your local development and global production insights. It doesn't just check syntax—it checks reality.
* **Real-time Intelligence:** Connects to a live DB of global incidents.
* **Agent Native:** Built specifically for the MCP ecosystem.
* **IP Protection:** Choose between BYOK or zero-retention cloud.

[How do I install it?](#install)

## 🚀 How it Works

Whenver your coding agent attempts to modify your codebase, <br>
Puli:

1.  **Analyzes the Context:**<br>
Queries the agent to understand the intent of<br>
the change.

2.  **Cross-References Failures:**<br>
Matches the code against a live-updated DB<br>
of real-world production errors and business-flow<br>
disruptions.

4.  **Stress Tests:**<br>
Forces the agent to account for specific edge<br>
cases before the code is ever committed.<br><br>


---

<a id="install"></a>
## ⚙️ Installation & Setup

### 1. Configure the MCP Server
Add the following to your coding agent's configuration (e.g., `claude_desktop_config.json` or your IDE's MCP settings):

```json
{
  "mcpServers": {
    "puli-viewer": {
      "command": "uvx",
      "args": ["--from", "puli-mcp-server@latest", "puli-reviewer"],
      "env": {
        "BYO_OPENAI_API_KEY": "Optional* - <your-key-if-using-byok>",
        "BYO_GOOGLE_API_KEY": "Optional* - <your-key-if-using-byok>",
        "BYO_ANTHROPIC_API_KEY": "Optional* - <your-key-if-using-byok>"
      }
    }
  }
}
```

* Provide at lease one API key

### 2. Add Agent Rules

To ensure your agent utilizes the guardrail for every change, add our rules file to your project:

* **For Cursor:** Create a file at `.cursor/rules/puli-reviewer.md` and paste the content from [our rules template here](https://drive.google.com/file/d/1e2qbVHWiT6zAE2VYYVbXrydT8iRz1HlH/view?usp=sharing).

---

## 🛡️ Privacy & Security
We prioritize your IP security, Operations run locally on your station and no code is shared with our cloud.

We support two distinct working modes:

| Mode | Data Privacy |
| :--- | :--- |
| When OpenAI API key provided. | **Local Only.** We pass embedded vectors to be used for extracting DB patterns. |
| When no OpenAI API key provided. | **Zero Retention.** We embedd the semantical meanning of your code change in our cloud. Nothing is ever logged or stored. |
