Metadata-Version: 2.4
Name: puli-plg
Version: 0.1.45
Summary: 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.
License-File: public_docs/LICENSE
Requires-Python: <3.15,>=3.10
Requires-Dist: anthropic>=0.40.0
Requires-Dist: google-auth>=2.0.0
Requires-Dist: google-genai>=1.0.0
Requires-Dist: mcp[cli]>=0.1.0
Requires-Dist: openai>=1.0.0
Requires-Dist: puli-embedding-client>=0.2.3
Requires-Dist: pydantic-ai>=0.0.18
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.1
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown


<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. |
