Metadata-Version: 2.5
Name: ocultar-goose-mcp
Version: 0.3.0
Summary: Zero-egress PII protection for Goose AI workflows via MCP stdio
Project-URL: Repository, https://github.com/ocultar-dev/ocultar
License: AGPL-3.0-only
Keywords: gdpr,goose,mcp,pii,privacy,security,zero-egress
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

## Ocultar PII Refinery — Goose Extension

Zero-egress PII protection for Goose AI workflows.
Runs entirely in your infrastructure — no data leaves your environment.

### Prerequisites
- Ocultar running locally (see Quick Start below)
- Python 3.10+

### Quick Start — Docker

```bash
docker run --rm -p 4141:4141 \
  -e OCU_MASTER_KEY=<64-hex-chars> \
  -e OCU_SALT=<32-hex-chars> \
  -e OCU_AUDITOR_TOKEN=<your-secret-token> \
  ghcr.io/ocultar-dev/ocultar:latest -serve 4141
```

### Installation

```bash
pip install ocultar-goose-mcp
```

### Configuration in Goose
1. Open Goose settings
2. Add Extension → Command-line Extension
3. Name: `ocultar-pii`
4. Command: `ocultar-goose-mcp`
5. Environment:
   ```
   OCULTAR_URL=http://localhost:4141
   ```

### Usage
Ask Goose: `Refine this text before processing: [text with PII]`

Goose will call `ocultar-pii` which redacts PII locally before any further processing.
The tool returns the cleaned text with each PII value replaced by a deterministic token
(e.g. `[EMAIL_9c8f7a1b2d3e4f50]`).

### Available tools

| Tool | Description |
|---|---|
| `refine_text` | Redacts PII from text before AI processing |
| `sombra_query` | Asks a redacted question via the Ocultar Sombra gateway — redacts PII, routes to the chosen LLM, rehydrates the response. Requires `OCULTAR_SOMBRA_TOKEN` and Sombra running separately (`go run ./apps/sombra`). |

> **Note:** `reveal_tokens` (de-tokenization) and the Entity Registry tools
> (`register_entity`, `list_entities`, `seed_entities`) are intentionally
> omitted from this extension. They are auditor-only operations and not
> suitable for automated agent workflows. Use the Claude or Mistral MCP
> extension if you need them.

### Why local-only?
The zero-egress design means your sensitive data never leaves your infrastructure.
The MCP server runs on stdio — no network server, no remote calls, no supply chain attack surface.
If Ocultar is unreachable, the extension returns an error and withholds the raw text — it never
forwards unmasked data as a fallback.

## License

AGPLv3 — see [LICENSE](../../LICENSE). Commercial licensing available for organizations that cannot comply with AGPLv3's source-disclosure requirements — see [COMMERCIAL_LICENSE.md](../../COMMERCIAL_LICENSE.md).
