# 1. Clone and install
git clone https://github.com/kofi-sketch/pii-anonymizer-mcp.git
cd pii-anonymizer-mcp
npm install

# 2. Verify it works
npm test

✓ Detected 6 PII items
✓ anonymize_text works
✓ deanonymize_text works
✓ All tests passed

{
  "mcpServers": {
    "pii-anonymizer": {
      "command": "node",
      "args": ["/absolute/path/to/pii-anonymizer-mcp/server.js"]
    }
  }
}

{
  "mcpServers": {
    "pii-anonymizer": {
      "command": "node",
      "args": ["/absolute/path/to/pii-anonymizer-mcp/server.js"]
    }
  }
}

{
  "mcp": {
    "servers": {
      "pii-anonymizer": {
        "command": "node",
        "args": ["/absolute/path/to/pii-anonymizer-mcp/server.js"]
      }
    }
  }
}

node server.js

Input:  "Hi, I'm John Smith. SSN: 123-45-6789. Email: john@example.com"
Output: "Hi, I'm [PERSON_NAME_1] [PERSON_NAME_2]. SSN: [SSN]. Email: [EMAIL]"

{
  "[PERSON_NAME_1]": "John",
  "[PERSON_NAME_2]": "Smith",
  "[SSN]": "123-45-6789",
  "[EMAIL]": "john@example.com"
}

Input:  "[PERSON_NAME_1]'s account has been updated" + entityMap
Output: "John's account has been updated"

{ "names": ["Satoshi", "Nakamoto", "kraken_admin_42", "ProjectPhoenix"] }

{
  "patterns": [
    { "regex": "EMP-\\d{6}", "label": "Employee ID", "placeholder": "EMPLOYEE_ID" },
    { "regex": "PROJ-[A-Z]{3}-\\d{4}", "label": "Project Code", "placeholder": "PROJECT_ID" },
    { "regex": "TICKET-\\d+", "label": "Support Ticket", "placeholder": "TICKET_ID" }
  ]
}

1. User pastes sensitive text into AI chat
2. AI calls anonymize_text → gets clean text + entity map
3. AI processes the sanitized text (summarize, classify, extract, translate, etc.)
4. AI calls deanonymize_text → restores originals in the output
5. User gets the result with real data intact

# Pipe text
echo "John Smith, SSN 123-45-6789" | node cli.js
# → [PERSON_NAME_1] [PERSON_NAME_2], SSN [SSN]

# Scrub a file, save entity map for later
node cli.js --file ticket.txt -o clean.txt --map map.json

# Restore originals after AI processing
node cli.js --restore --file ai-response.txt --map map.json

# Full JSON output (anonymized text + entity map + stats)
node cli.js --file data.txt --json

# Use custom org dictionary
node cli.js --config kraken-pii.json --file logs.txt

# Only run specific detectors
node cli.js --detectors email,credit_card,ssn --file data.csv

# Stats only
node cli.js --stats --file data.txt

# Scan a file
node scan.js --file ticket.txt

# ⚠ ticket.txt: 6 PII items found
#   PERSON_NAME (2)
#     → J***
#     → S****
#   SSN (1)
#     → ***6789
#   CREDIT_CARD (1)
#     → ***0366
#   Severity: HIGH

# Show context around each finding
node scan.js --file ticket.txt --verbose

# JSON report
node scan.js --file data.csv --json

# CI/CD gate — exit code 0=clean, 1=PII found
node scan.js --file output.txt -q || echo "BLOCKED: PII detected"

# Batch scan a directory
find ./logs -name "*.txt" -exec node scan.js --file {} -q \;

{
  "names": ["Jesse Powell", "internal_admin_42"],
  "nameFiles": ["employees.txt", "contractors.csv"],
  "patterns": [
    { "regex": "EMP-\\d{6}", "label": "Employee ID", "placeholder": "EMPLOYEE_ID" },
    { "regex": "TICKET-\\d+", "label": "Support Ticket", "placeholder": "TICKET_ID" }
  ]
}

┌─────────────────────────────────────────────────────┐
│                   AI Client (Claude, Cursor, etc.)   │
│                                                      │
│  "Get support tickets from Superset,                 │
│   summarize them, but scrub PII first"               │
└──────┬──────────────────────────┬────────────────────┘
       │                          │
       ▼                          ▼
┌──────────────┐          ┌──────────────────┐
│  Superset    │          │  PII Anonymizer  │
│  MCP Server  │          │  MCP Server      │
│  (your data) │          │  (scrubs PII)    │
└──────────────┘          └──────────────────┘

# Superset export → scrub → feed to AI
superset export --query 42 | pii-anonymize -o clean.csv --map map.json

# Scan any data source for PII without changing it
cat database_dump.csv | pii-scan

# CI/CD: block deploys that leak PII
pii-scan --file api-response.json -q || exit 1

┌─────────────┐     stdio (JSON-RPC)     ┌──────────────────┐
│  MCP Client  │ ◄──────────────────────► │  pii-anonymizer  │
│  (Claude,    │                          │  server.js       │
│   Cursor,    │    anonymize_text()      │  engine.js       │
│   VS Code)   │    deanonymize_text()    │  (all local)     │
└─────────────┘    list_detectors()       └──────────────────┘
                                                   │
                                            No network calls
                                            No external APIs
                                            No data storage

# Build
docker build -t pii-anonymizer .

# Pipe text through the container
echo "John Smith, SSN 123-45-6789" | docker run -i pii-anonymizer

# Scrub a file (mount it in)
docker run -i pii-anonymizer < ticket.txt > clean.txt

# JSON output
echo "John Smith, SSN 123-45-6789" | docker run -i pii-anonymizer cli.js --json

# Read-only scan
echo "John Smith, SSN 123-45-6789" | docker run -i pii-anonymizer scan.js

# MCP server mode (for AI client integration)
docker run -i pii-anonymizer server.js

# With custom config (mount your config file)
docker run -i -v /path/to/pii-config.json:/app/pii-config.json pii-anonymizer

# CI/CD gate — exit code 1 if PII found
echo "some text" | docker run -i pii-anonymizer scan.js -q || echo "BLOCKED"