Metadata-Version: 2.5
Name: ocultar-mistral-mcp
Version: 0.3.0
Summary: Zero-egress PII protection for Mistral Le Chat workflows via MCP stdio
Project-URL: Repository, https://github.com/ocultar-dev/ocultar
License: AGPL-3.0-only
Keywords: france,gdpr,le-chat,mcp,mistral,pii,privacy,rgpd,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 — Mistral Le Chat MCP Extension

Zero-egress PII protection for Mistral Le Chat workflows.
Runs entirely in your infrastructure — no data ever leaves your environment.

Optimised for French and EU compliance: SIRET/SIREN, IBAN, RGPD Article 25, CNIL requirements.

## Tools

| Tool | Description |
|------|-------------|
| `refine_text` | Redacts PII / DCP before sending text to Le Chat. Returns clean text + token map. |
| `reveal_tokens` | De-tokenizes tokens back to plaintext (auditor-only, requires `OCULTAR_AUDITOR_TOKEN`). |
| `register_entity` | Registers a canonical PII entity and its variants so they resolve to the same token across sessions (auditor-only, requires `OCULTAR_AUDITOR_TOKEN`). |
| `list_entities` | Lists all registered PII entities (auditor-only, requires `OCULTAR_AUDITOR_TOKEN`). |
| `seed_entities` | Bulk-registers PII entities, e.g. from a CRM roster (auditor-only, requires `OCULTAR_AUDITOR_TOKEN`). |
| `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). |

## Prerequisites

- Ocultar Refinery running locally:
  ```bash
  docker compose up
  ```
- Python 3.10+

## Installation

```bash
pip install ocultar-mistral-mcp
```

Or with `uvx` (no install needed):
```bash
uvx ocultar-mistral-mcp
```

## Mistral Le Chat Configuration

In Mistral Le Chat, open **Settings → Tools → MCP Servers** and add:

```json
{
  "mcpServers": {
    "ocultar-pii": {
      "command": "ocultar-mistral-mcp",
      "env": {
        "OCULTAR_URL": "http://localhost:4141",
        "OCULTAR_API_KEY": "your-api-key"
      }
    }
  }
}
```

Or with `uvx` (no prior install required):

```json
{
  "mcpServers": {
    "ocultar-pii": {
      "command": "uvx",
      "args": ["ocultar-mistral-mcp"],
      "env": {
        "OCULTAR_URL": "http://localhost:4141",
        "OCULTAR_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `OCULTAR_URL` | Yes | URL of your local Ocultar Refinery (default: `http://localhost:4141`) |
| `OCULTAR_API_KEY` | No | Bearer token for Refinery auth |
| `OCULTAR_AUDITOR_TOKEN` | No | Enables `reveal_tokens`, `register_entity`, `list_entities`, `seed_entities` — must match `OCU_AUDITOR_TOKEN` on the server |
| `OCULTAR_SOMBRA_URL` | No | URL of your local Ocultar Sombra gateway (default: `http://localhost:8086`) |
| `OCULTAR_SOMBRA_TOKEN` | No | Enables `sombra_query` — Sombra rejects requests with no Bearer token |

## Usage

Once connected, Le Chat will automatically call `refine_text` before processing sensitive data. You can also invoke it explicitly:

> "Avant de traiter ce texte, filtre les DCP : Jean Dupont, jean.dupont@banque.fr, IBAN FR76 3000 6000 0112 3456 7890 189"

Le Chat returns:
```json
{
  "cleanText": "[NAME_a1b2c3d4e5f6a7b8], [EMAIL_9c8f7a1b2d3e4f50], IBAN [IBAN_7f3e9a2b1c4d5e60]",
  "tokenMap": {
    "[NAME_a1b2c3d4e5f6a7b8]": "NAME",
    "[EMAIL_9c8f7a1b2d3e4f50]": "EMAIL",
    "[IBAN_7f3e9a2b1c4d5e60]": "IBAN"
  }
}
```

For authorized workflows that need to restore PII after AI processing:

> "Reveal these tokens: [EMAIL_9c8f7a1b2d3e4f50], [IBAN_7f3e9a2b1c4d5e60]"

This call is recorded in the immutable Ed25519-signed audit log.

## Why This Matters for French Enterprises

Sending customer data to any external AI API — including Mistral's cloud — without redaction constitutes a RGPD violation under Article 25 (Privacy by Design). The CNIL has issued enforcement guidance specifically targeting AI pipeline data flows.

Ocultar ensures that:
- No raw PII ever reaches Le Chat's API endpoint
- SIRET, SIREN, IBAN, and French address formats are detected and tokenized
- Every vault access is logged in a tamper-evident, Ed25519-signed audit trail
- You remain the data controller — Ocultar is a local processor under your full control

## Security Model

- `refine_text` is safe to expose to any Le Chat session
- `reveal_tokens` requires `OCULTAR_AUDITOR_TOKEN` and every call is logged with actor, timestamp, and Ed25519 signature
- The Refinery vault uses AES-256-GCM with HKDF-SHA256 key derivation — tokens are useless without the master key
- If the Refinery is unreachable, both tools fail closed — raw PII is never forwarded

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