Metadata-Version: 2.4
Name: onewolf-mcp
Version: 0.2.0
Summary: OneWolf AI Security - MCP Server (Model Context Protocol)
Author: OneWolf Team
License: MIT
Project-URL: Homepage, https://github.com/onewolf-ai/onewolf-guard
Keywords: ai-security,mcp,model-context-protocol,llm-guard
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp<3,>=2.0
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"

# OneWolf MCP Server

OneWolf AI Security tools exposed via the [Model Context Protocol](https://modelcontextprotocol.io).

Provides 6 security tools and 2 resources to MCP-compatible clients (Cursor, Claude Desktop, MCP Inspector, custom agents).

## Tools

| Tool | Category | Purpose |
|---|---|---|
| `analyze_prompt` | text | Detect prompt injection, jailbreak, PII, toxic content, secrets |
| `filter_output` | text | Sanitize LLM responses (mask PII, redact credentials, filter toxicity) |
| `scan_document` | document | Scan files for threats, PII, malicious content (Fenrir Shield) |
| `rag_pre_check` | rag | Validate user query before vector retrieval (exfiltration/injection) |
| `rag_post_check` | rag | Sanitize retrieved documents before LLM context |
| `rag_ingest_check` | rag | Analyze documents before knowledge-base ingestion (anti-poisoning) |

## Resources

| URI | Returns |
|---|---|
| `guard://health` | API health status (filtered — no internal topology) |
| `guard://capabilities` | Available tools and resources |

## Installation

```bash
pip install -e .
```

Or for development:

```bash
pip install -e ".[dev]"
```

Python 3.10+ required.

## Configuration

Set these environment variables in your MCP client config:

| Variable | Required | Default | Description |
|---|---|---|---|
| `ONEWOLF_API_KEY` | yes | — | Your OneWolf API key |
| `ONEWOLF_URL` | no | `http://localhost:8001` | Backend API URL |
| `ONEWOLF_TIMEOUT` | no | `30` | Request timeout in seconds (text/RAG). Document scan uses 60s. |

## Setup — Cursor

Edit `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):

```json
{
  "mcpServers": {
    "onewolf-guard": {
      "command": "python",
      "args": ["-m", "onewolf_mcp"],
      "env": {
        "ONEWOLF_API_KEY": "your-api-key",
        "ONEWOLF_URL": "http://localhost:8001"
      }
    }
  }
}
```

Restart Cursor or toggle the server off/on in Settings → MCP. You should see "6 tools, 2 resources enabled".

## Setup — Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "onewolf-guard": {
      "command": "python",
      "args": ["-m", "onewolf_mcp"],
      "env": {
        "ONEWOLF_API_KEY": "your-api-key",
        "ONEWOLF_URL": "http://localhost:8001"
      }
    }
  }
}
```

Restart Claude Desktop.

## Setup — MCP Inspector (testing)

```bash
npx @modelcontextprotocol/inspector python -m onewolf_mcp
```

Set environment variables in the Inspector UI before connecting.

## Limits and timeouts

- **Text input** (analyze_prompt, filter_output, rag_pre_check): max 10,000 chars
- **Document size** (scan_document, rag_ingest_check): max 50 MB (decoded base64)
- **RAG docs** (rag_post_check): max 50 documents per call
- **Timeout** (text/RAG): 30s default (`ONEWOLF_TIMEOUT`)
- **Timeout** (document scan): 60s

## Error handling

All tools return JSON. On failure, the response has an `error` field:

| `error` | Meaning |
|---|---|
| `invalid_input` | Bad arguments (empty, oversized, invalid base64) |
| `invalid_response` | API returned malformed response (fail-closed) |
| `connection_failed` | Backend unreachable — check `ONEWOLF_URL` |
| `timeout` | Backend did not respond in time |
| `request_failed` | Generic HTTP error |
| `api_error` | API returned 4xx/5xx (auth, rate limit, etc.) |

## Latency baseline

Measured against a healthy local backend (n=20 per tool, all values in ms):

| Tool | Cold (1st call) | Warm p50 | Warm p95 |
|---|---|---|---|
| `analyze_prompt` | 1040 | 49 | 54 |
| `filter_output` | 48 | 44 | 48 |
| `scan_document` | 1265 | 52 | 68 |
| `rag_pre_check` | 431 | 53 | 68 |
| `rag_post_check` | 423 | 54 | 62 |
| `rag_ingest_check` | 91 | 56 | 72 |

**Mean warm p50: 51ms — Mean warm p95: 62ms**

Cold-call latency is dominated by backend cache miss + ML model warmup (Cerberus/Fenrir). Warm latency reflects steady-state performance with backend caches warm.

Note: a true cold-start of the entire backend stack (Docker container boot + ML model load) takes ~18-30s and is not captured here.

See `tests/baseline_latency.py` for the benchmark script.

## Testing

```bash
pytest tests/
```

69 tests covering: input validation, fail-closed behavior, API error mapping, contract alignment with backend (route names, field names), and a stdio smoke that drives the server as a real subprocess over the MCP protocol.

## License

MIT
