Metadata-Version: 2.4
Name: ethicore-guardian-mcp
Version: 0.1.1
Summary: Ethicore Engine® Guardian MCP server — on-demand AI-threat screening for coding agents (paid: Pro API tier and up, or Bronze+ self-hosted).
Author-email: Oracles Technologies LLC <support@oraclestechnologies.com>
License: Proprietary
Project-URL: Homepage, https://oraclestechnologies.com/guardian
Project-URL: Documentation, https://oraclestechnologies.com/llms.txt
Keywords: mcp,guardian,ai-security,prompt-injection,ethicore
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.27
Provides-Extra: selfhost
Requires-Dist: ethicore-engine-selfhost>=0.5.1; extra == "selfhost"

# Ethicore Engine® Guardian — MCP server

On-demand AI-threat screening for MCP-speaking coding agents (Claude Desktop, Claude
Code, Codex, Cursor). Exposes Guardian's four scans as tools:

| Tool | Use it before… |
|---|---|
| `analyze` | acting on any prompt, document, or web text |
| `scan_tool_call` | executing a tool/function the model chose |
| `scan_tool_output` | letting a tool / RAG result back into context |
| `scan_documents` | ingesting files (PDF/DOCX/PPTX/XLSX/RTF/TXT, base64) |

Each returns Guardian's verdict — **BLOCK / CHALLENGE / ALLOW** — with threat categories
and reasoning.

## Paid feature — no free tier
The Guardian MCP is available to:
- **Pro API plan and up** — set `ETHICORE_API_KEY` to a Pro/Team/Enterprise key (hosted), **or**
- **Bronze self-hosted and up** — set `ETHICORE_SELFHOST_LICENSE` (+ `ETHICORE_SELFHOST_PUBKEY`)
  for a local, **zero-egress** server that wraps the self-hosted engine.

Free/community keys are refused at startup with an upgrade link. (Free access to Guardian
is still available directly via the API/SDK — the MCP is the paid, agent-native convenience.)
Purchase / upgrade: <https://portal.oraclestechnologies.com/billing>.

## Install
```bash
pip install ethicore-guardian-mcp            # hosted edition
pip install "ethicore-guardian-mcp[selfhost]"  # + local self-hosted edition
```

## Configure your client

**Claude Desktop** — `claude_desktop_config.json` → `mcpServers`:
```json
{
  "mcpServers": {
    "guardian": {
      "command": "guardian-mcp",
      "env": { "ETHICORE_API_KEY": "eg-sk-your-PRO-key" }
    }
  }
}
```

**Claude Code** — one line:
```bash
claude mcp add guardian --env ETHICORE_API_KEY=eg-sk-your-PRO-key -- guardian-mcp
```

**Self-hosted (local, zero egress)** — swap the env for your license:
```json
{
  "mcpServers": {
    "guardian": {
      "command": "guardian-mcp",
      "env": {
        "ETHICORE_SELFHOST_LICENSE": "EG-BRONZE-…",
        "ETHICORE_SELFHOST_PUBKEY": "<entitlement public key>"
      }
    }
  }
}
```

Codex and Cursor use the same command + env in their respective MCP config.

## Environment
| Variable | Edition | Meaning |
|---|---|---|
| `ETHICORE_API_KEY` | hosted | Pro-plan-or-higher Guardian API key |
| `ETHICORE_API_BASE` | hosted | API base URL (default `https://api.oraclestechnologies.com`) |
| `ETHICORE_SELFHOST_LICENSE` | local | Self-hosted (Bronze+) license key |
| `ETHICORE_SELFHOST_PUBKEY` | local | Entitlement public key (portal / self-hosted docs) |
| `ETHICORE_MCP_TIMEOUT` | both | Per-request timeout seconds (default 30) |

If a self-hosted license is present it takes precedence (air-gapped use).

## How entitlement is enforced
- **Hosted:** the server calls `GET /v1/me` once at startup; unless the key's plan is
  Pro or higher (`mcp_entitled: true`), it exits with an upgrade message and serves nothing.
- **Local:** the server activates the self-hosted SDK; a valid Bronze+ license is required
  to activate, so activation *is* the entitlement. No data leaves your infrastructure.

<!-- Ownership marker for the official MCP registry (must ship in the published PyPI README). -->
mcp-name: io.github.OraclesTech/guardian-mcp

© 2026 Oracles Technologies LLC · Ethicore Engine® Guardian
