pseudonym-mcp

# pseudonym-mcp

Local pseudonymisation tools for LLM workflows — replace detected PII with opaque tokens before you hand text to a cloud LLM, then restore those tokens afterward.

[![npm version](https://img.shields.io/npm/v/pseudonym-mcp?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/pseudonym-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-ffd60a?style=flat-square)](LICENSE)
[![Node 18+](https://img.shields.io/badge/node-18%2B-339933?logo=node.js&logoColor=white&style=flat-square)](#)
[![GDPR-aligned](https://img.shields.io/badge/GDPR-aligned-0070f3?style=flat-square)](#gdpr--ai-compliance)
[![Local detection](https://img.shields.io/badge/detection-local-brightgreen?style=flat-square)](#)
[![Offline NER](https://img.shields.io/badge/NER-local%20%2F%20offline-blue?style=flat-square)](#)

Expose MCP tools (`mask_text` and `unmask_text`) that your client or agent can call as an explicit privacy step. The server detects PII locally, replaces it with opaque tokens, and keeps the token mapping in memory for later restoration.

It is a **defense-in-depth measure**, not a compliance silver bullet. Read the [Limitations](#limitations) and [GDPR & AI Compliance](#gdpr--ai-compliance) sections before assuming this stack does more than it does.

## What you get

- **Multi-language PII detection**: Built-in support for English (SSN, credit cards, US phone) and Polish (PESEL, IBAN, Polish phone). New **heuristic language detection** (`detectLanguage()`) infers the language from text content — `--lang` remains the authoritative override but is no longer the only input.
- **Hybrid NER engine**: Regex for structured PII (SSN, credit cards, IBAN, email, phone) + local Ollama LLM for unstructured entities (names, organisations).
- **Local-detection architecture**: Detection and substitution happen on your machine when the MCP tool is called. The cloud LLM call still happens (that's the point) — but it can see tokens instead of detected PII when your workflow uses the masked output.
- **Session-keyed mapping store**: Tokens like `[PERSON:1]` map back to originals in an isolated, per-request session. Multiple round-trips preserve token coherence.
- **Unmask workflow support**: `mask_text` returns `auto_unmask` for clients that want to honor that preference, but this server does not intercept arbitrary LLM responses automatically.
- **Flexible engines**: Run `regex` only (no Ollama required), `llm` only, or `hybrid` (default).
- **Strict validation**: SSN area-number validation, credit card Luhn checksum, PESEL checksum — all configurable.
- **Graceful degradation**: If Ollama is unavailable, the regex phase still runs and no exception is thrown.
- **MCP-native**: Works with Claude Code, Claude Desktop, Cursor — any MCP-compatible client.

## ❌ Without / ✅ With

❌ **Without pseudonym-mcp:**

- Prompt: `"John Smith, SSN 123-45-6789, card 4111 1111 1111 1111"` → sent verbatim to the LLM provider
- Every name, ID number, and credit card in your prompt is processed and potentially logged by the provider
- A breach at the provider's end exposes those values in cleartext
- Sending personal data to a non-EU LLM provider without further safeguards raises GDPR Article 44 questions you'll need to answer

✅ **With pseudonym-mcp used before the cloud call:**

- The same prompt can become `"[PERSON:1], SSN [SSN:1], card [CREDIT_CARD:1]"` when you call `mask_text` first
- The LLM reasons about structure and content without seeing those detected values in cleartext
- The response can be locally de-tokenised with `unmask_text` before reaching the user
- Detected direct identifiers are no longer shipped upstream — though structure, dates, indirect references, and any missed PII still are

This is a meaningful reduction in cleartext PII exposure. It is **not** "no personal data leaves your machine" — see [Limitations](#limitations).

## GDPR & AI Compliance

pseudonym-mcp is relevant to compliance work, but it is a **technical control**, not a compliance product. Whether you are compliant with any specific regulation depends on your full stack, your role (controller/processor), your contracts, your DPIA, and your jurisdiction.

### Why this matters

The EU **General Data Protection Regulation (GDPR)** classifies names, national ID numbers (like SSN or PESEL), bank account numbers (IBAN), email addresses, credit card numbers, and phone numbers as **personal data** under Article 4(1). Sending this data to a cloud LLM provider constitutes **processing** under Article 4(2). Pseudonymisation is explicitly recognised under Art. 4(5) as a risk-reduction measure — but, critically, **pseudonymised data is still personal data** (Recital 26).

| GDPR Article | Obligation                           | Where pseudonym-mcp helps                                                                  | Where it doesn't                                                                |
| ------------ | ------------------------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| Art. 5(1)(c) | **Data minimisation**                | Strips detected direct identifiers before transmission                                     | Doesn't minimise context, structure, or undetected PII                          |
| Art. 25      | **Privacy by design and by default** | Provides a technical layer that fits into a privacy-by-design architecture                 | Architecture and policy decisions are still your responsibility                 |
| Art. 32      | **Security of processing**           | Recognised technical measure under Recital 83 (pseudonymisation)                           | One control among many; doesn't replace access control, logging, encryption     |
| Art. 44      | **Transfers to third countries**     | Reduces the cleartext PII you transfer                                                     | Pseudonymised personal data is still personal data — transfer rules still apply |
| Art. 4(5)    | **Pseudonymisation** definition      | The mapping store is opaque to the cloud LLM; re-identification requires the local session | Re-identification is possible from context for anyone with side knowledge       |

> **The honest bottom line:** pseudonymisation under GDPR Art. 4(5) is **not** anonymisation. The data remains personal data in your system, and Art. 44 transfer obligations are not switched off just because you tokenised the name field.

### AI Act alignment

The EU **AI Act** places additional requirements on high-risk AI systems that process personal data. Using pseudonym-mcp as an intermediary layer can:

- Support data minimisation in your AI system's data flows.
- Help document a technical control for transparency and human-oversight requirements.
- Align with the principle of **technical robustness and safety** (Art. 15) by limiting cleartext PII exposure.

It does not change your AI Act risk classification on its own — classification is a function of use-case and deployment context, not of the masking step in front of the model.

### US & international applicability

The tool is also relevant outside the EU, with the same caveats:

- **CCPA / CPRA** (California) — reduces personal information sent to third-party processors; doesn't change controller/business obligations or consumer rights.
- **HIPAA** (US healthcare) — pseudonymised PHI is still PHI under HIPAA. Using this tool does **not** eliminate the need for a BAA with your cloud LLM provider if you're a covered entity or business associate. It can be part of a defensible safeguard posture; it cannot substitute for one.
- **PCI DSS** (payment industry) — Luhn-validated detection reduces the chance card numbers ride in cleartext to an LLM. It is one control; PCI scope, segmentation, and storage rules are separate concerns.
- **SOC 2** — useful evidence of a technical control limiting PII exposure. Auditors will look at the full picture, not just this layer.
- **PIPEDA** (Canada), **LGPD** (Brazil), **POPIA** (South Africa) — all require appropriate safeguards for cross-border personal data transfers. This tool is a relevant safeguard, not a substitute for the legal basis of the transfer.

### Sector-specific applicability

| Sector             | Relevant regulation                      | PII types commonly handled            |
| ------------------ | ---------------------------------------- | ------------------------------------- |
| Healthcare         | GDPR + HIPAA + national health data laws | Patient names, SSN, diagnoses         |
| Banking & Finance  | GDPR + PCI DSS + PSD2 + DORA             | Credit cards, IBAN, SSN, PESEL        |
| HR & Recruitment   | GDPR Art. 9 (special categories)         | Names, national IDs, contact details  |
| Legal              | GDPR + attorney–client privilege         | Names, case numbers, personal details |
| Insurance          | GDPR + Solvency II                       | Personal identifiers, health data     |
| Public Sector (US) | CCPA + state privacy laws                | SSN, driver's license numbers         |
| Public Sector (PL) | GDPR + UODO + KRI                        | PESEL, NIP, REGON                     |

In every row of this table, pseudonym-mcp is a useful **building block**. None of those regimes can be satisfied by a masking tool alone.

## How it works

```
Your App / Claude Desktop
        │
        │  explicit mask_text tool call with PII
        ▼
┌─────────────────────────┐
│      pseudonym-mcp      │
│                         │
│  Phase 1: Pattern NER   │  ← 46 rules: national IDs, tax numbers,
│                         │    IBAN, VAT, cards, wallets, devices
│                         │    scored, checksum-verified, context-aware
│  Phase 2: Ollama NER    │  ← PERSON, ORG  (local LLM)
│  MappingStore (session) │  ← [TAG:N] ↔ original value
└────────────┬─────────