CloakMCP

Your secrets stay home. The AI only sees tags.

Local-first secret sanitization before LLM exposure — works with any LLM, includes first-class Claude Code integration

See It Work • Features • Quick Start • Claude Code Integration • Demo • Security • Documentation

See It Work

Every time you paste code into an LLM, your secrets go with it:

private static final String API_KEY  = "sk_live_51Jd9RealKeyGoesHere";
private static final String DB_PASS  = "P@ssw0rd-Pr0duction!";
private static final String AWS_KEY  = "AKIAIOSFODNN7REALKEY1";

CloakMCP intercepts — automatically, invisibly — before the LLM ever sees your code:

 YOUR MACHINE                              LLM (Claude, Codex, Copilot…)
 ────────────                              ──────────────────────────────

 API_KEY = "sk_live_51Jd9RealKey"          API_KEY = "TAG-d7182d9e703d"
 DB_PASS = "P@ssw0rd-Pr0duction!"         DB_PASS = "TAG-a6c0cd73627c"
 AWS_KEY = "AKIAIOSFODNN7REALKEY1"         AWS_KEY = "TAG-f63caf98581a"

The LLM understands the code perfectly — it just can't see the secrets:

 You → LLM:      "Which variable stores the database password?"

 LLM:            "DB_PASS on line 27 stores the credential TAG-a6c0cd73627c.
                  It's used in the JDBC connection to the PostgreSQL instance."

 You → CloakMCP: cloak unpack

 Result:          TAG-a6c0cd73627c → P@ssw0rd-Pr0duction!   ← restored locally

The LLM identified the right variable, understood the architecture, explained the data flow — but the actual password never left your machine. One command brings it back. This works with Claude, Copilot, Codex, Gemini, local Ollama models — any LLM that reads your code.

With Claude Code, the entire cycle is automatic via hooks: secrets vanish at session start, reappear at session end. Zero human intervention.

Overview

CloakMCP is a local-first, deterministic sanitizer that removes or neutralizes secrets (emails, IPs, URLs, tokens, API keys, SSH keys, JWTs) before your text/code reaches any LLM — Claude, GitHub Copilot, OpenAI Codex, Gemini, or local models via Ollama. The core CLI (cloak pack/unpack/scan/sanitize) is LLM-agnostic; a dedicated Claude Code integration provides automatic session-level protection via hooks and an MCP tool server.

What makes CloakMCP different

Feature	CloakMCP	ggshield / gitleaks	SOPS	DIY Scripts
Detect secrets	Yes	Yes	No	Yes
Reversible redaction	Yes	No	No	No
LLM-optimized workflow	Yes	No	No	No
MCP tool server	Yes (6 tools)	No	No	No
IDE hook integration	Yes (Claude Code auto pack/unpack)	No	No	No
Deterministic tags	Yes (HMAC-based)	No	No	Varies
Local-only vault	Yes	No	No (cloud KMS)	Varies
Directory pack/unpack	Yes	No	No	No
Encrypted storage	Yes (AES-128 Fernet)	No	Yes (cloud KMS)	Varies
IDE integration	Yes (VS Code)	Yes	No	No

Key Capabilities

LLM-agnostic: Core CLI works with any LLM workflow — no vendor lock-in
Local-first: All operations run on your machine — no cloud dependencies
Reversible: Deterministic tagging allows safe restoration via encrypted vaults
Batch processing: Pack/unpack entire codebases with one command
Policy-driven: Configure detection rules via YAML (regex, entropy, IPs, URLs)
Group policies: Hierarchical policy inheritance (company → team → project)
Auditable: Every operation logged to audit/audit.jsonl
Claude Code integration: Hooks automate pack/unpack at session boundaries; 6 MCP tools for in-session use

Claude Code Integration

CloakMCP's core CLI is LLM-agnostic. This section describes the first-class integration with Claude Code, which automates the pack/unpack lifecycle through hooks and exposes tools via the Model Context Protocol (MCP). For other LLMs, use cloak pack / cloak unpack manually or in your own scripts.

CloakMCP integrates with Claude Code through two complementary mechanisms:

1. Hooks — Automatic Session Protection

When Claude Code starts a session, CloakMCP automatically packs all files. When it ends, it automatically unpacks. Zero manual steps.

 Claude Code starts  →  SessionStart hook  →  cloak pack   (secrets → tags)
 Claude works on code →  MCP tools available (6 tools)
 Claude Code exits   →  SessionEnd hook    →  cloak unpack (tags → secrets)

Install (cross-platform, no bash required):

cloak install                          # secrets-only profile (default)
cloak install --profile hardened       # + Bash safety guard + read guard
cloak install --dry-run                # preview without changes

Configuration (.claude/settings.local.json — auto-generated by cloak install):

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{"type": "command", "command": "cloak hook session-start"}]
    }],
    "SessionEnd": [{
      "hooks": [{"type": "command", "command": "cloak hook session-end"}]
    }],
    "UserPromptSubmit": [{
      "hooks": [{"type": "command", "command": "cloak hook prompt-guard"}]
    }],
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{"type": "command", "command": "cloak hook guard-write"}]
    }]
  }
}

The UserPromptSubmit guard scans every user message for secrets — blocking critical/high and warning on medium/low. The PreToolUse guard scans content Claude tries to write — and denies if raw secrets appear in generated code. The hardened profile adds a Read|Grep|Glob guard that blocks access to backup directories and session state files.

2. MCP Tool Server — 6 Tools

CloakMCP exposes tools via the Model Context Protocol. The recommended approach uses the FastMCP-based cloak serve command (stdio by default, optional SSE/streamable-http). Any MCP-compatible client (Claude Code, Claude Desktop, or custom agents) discovers them automatically:

Tool	Description
`cloak_scan_text`	Scan text for secrets (returns matches without modifying)
`cloak_pack_text`	Replace secrets with vault tags in text
`cloak_unpack_text`	Restore vault tags to original secrets
`cloak_vault_stats`	Get vault statistics (total secrets, unique tags)
`cloak_pack_dir`	Pack entire directory
`cloak_unpack_dir`	Unpack entire directory

Configuration (.mcp.json):

{
  "mcpServers": {
    "cloakmcp": {
      "type": "stdio",
      "command": "cloak",
      "args": ["serve"]
    }
  }
}

Note: cloak serve auto-discovers .cloak/policy.yaml (set via cloak policy use). You can also pass --policy <path> explicitly.

Network transport (SSE on port 8766):

cloak serve --transport sse --port 8766

Note: cloak serve requires the optional MCP dependency: pip install cloakmcp[mcp]. The legacy cloak-mcp-server entry point (raw JSON-RPC) remains available without extra dependencies.

Features

Detectors

Type	Examples	Action
AWS keys	`AKIA`, `ASIA`	block
JWT tokens	3-part base64	pseudonymize
SSH private keys	PEM blocks	replace
X.509 certificates	PEM blocks	block
Email addresses	with whitelist support	replace_with_template
URLs	HTTP/HTTPS (internal)	pseudonymize
IP addresses	IPv4/IPv6 with CIDR whitelists	pseudonymize
High-entropy strings	base64-like tokens	redact
Custom regex	user-defined patterns	configurable

Actions

Action	Behavior	Reversible
`block`	Refuse to process (exit with error)	—
`redact`	Replace with `<REDACTED:rule_id>`	No
`pseudonymize`	Replace with HMAC-based token (`TAG-xxxxxxxxxxxx`)	Yes (vault)
`hash`	Replace with SHA-256 hash	No
`replace_with_template`	Custom template (e.g., `<EMAIL:{hash8}>`)	No
`allow`	Keep unchanged (whitelist)	—

CLI Commands

Command	Description
`cloak scan --policy POL --input FILE`	Scan file, log detections (no modification)
`cloak sanitize --policy POL --input FILE --output OUT`	Sanitize a single file (one-shot)
`cloak pack --policy POL --dir DIR`	Replace secrets by deterministic tags across directory
`cloak unpack --dir DIR`	Restore original secrets from local vault
`cloak policy validate --policy POL`	Validate policy file (including inheritance chain)
`cloak policy show --policy POL`	Show merged policy after inheritance resolution
`cloak policy use <path>`	Set per-project policy (copies to `.cloak/policy.yaml`); `--show`, `--clear`, `--link`, `--force`
`cloak policy reload`	Reload policy mid-session (G2): re-resolve, update pinned hash, print diff
`cloak sanitize-stdin --policy POL`	Sanitize text from stdin to stdout (pipe helper)
`cloak repack --dir DIR --policy POL`	Incremental re-pack: scan new/changed files only
`cloak verify --dir DIR`	Post-unpack verification: scan for residual tags
`cloak status --dir DIR`	Session diagnostics: state, manifest, delta, vault, tags, backups, audit
`cloak restore --dir DIR`	Restore secrets from vault (default) or `--from-backup --force`
`cloak hook <event>`	Hook handler for Claude Code integration (session-start, session-end, guard-write, guard-read, prompt-guard, safety-guard, audit-log)
`cloak install`	Cross-platform hook installer; `--profile`, `--method cli\|copy\|symlink`, `--policy`, `--dry-run`, `--uninstall`
`cloak hooks-path`	Print path to bundled hook scripts; `--format sh\|py\|cli` (toolbox discovery contract)
`cloak doctor`	Installation health check: platform, hook method, policy, vault state
`cloak key wrap`	Wrap key with passphrase (Tier 0 → Tier 1); requires `CLOAK_PASSPHRASE`
`cloak key unwrap`	Unwrap key back to raw format (Tier 1 → Tier 0)
`cloak backup migrate`	Encrypt legacy plaintext backups; `--dry-run`, `--quarantine`
`cloak backup prune`	Remove old backups; `--ttl 30d`, `--keep-last 10`, `--apply`, `--include-legacy`
`cloak serve`	FastMCP server: stdio (default), SSE, or streamable-http transport
`cloak serve --check`	Validate MCP server configuration and exit
`cloak --version`	Print CloakMCP version
`cloak-mcp-server`	Legacy MCP tool server (JSON-RPC 2.0 over stdio)

Live Demo

The demo/ directory contains a realistic Spring Boot banking microservice with 10+ fake secrets across 3 config files. Four demo scripts showcase different aspects:

LLM Demo — The Highlight

Packs the code, asks a real LLM to explain it, proves the AI understands the logic without seeing secrets:

cd demo && bash llm_demo.sh              # auto-detect (Ollama / Claude)
cd demo && bash llm_demo.sh --ollama     # force local Ollama
cd demo && bash llm_demo.sh --claude     # force Claude Code CLI

Sample output — Qwen2.5-coder explains cloaked banking code

▶ Asking Ollama (qwen2.5-coder:14b) to explain the cloaked code...

  This class simulates a high-value transfer workflow in a banking service.
  It initiates the transfer by performing risk and compliance checks,
  creating a transfer intent, signing it, and calling a payment gateway.
  The process involves persisting data to a database, sending confirmation
  emails, notifying operations via a webhook, and archiving an audit trail.

The LLM understood 8 workflow steps, compliance logic, and integrations
— zero real credentials seen.

MCP Protocol Demo

Shows CloakMCP as an MCP tool server with raw JSON-RPC protocol:

cd demo && bash mcp_demo.sh              # raw JSON-RPC protocol (5 steps)
cd demo && bash mcp_demo.sh --claude     # + full hook lifecycle with live LLM

With --claude, demonstrates the complete transparent lifecycle:

SessionStart hook fires → cloak pack (automatic)
An LLM explains the cloaked code — sees only TAG-xxxx tokens
SessionEnd hook fires → cloak unpack (automatic)

Other Demos

cd demo && bash transcript.sh            # screenshot-friendly before/after (6 phases)
cd demo && bash run_demo.sh              # interactive 5-act presentation

Full demo documentation: See demo/README.md

Quick Start

New to CloakMCP? See the full Quickstart Guide with FAQ, compatibility matrix, and troubleshooting.

1. Install

From PyPI (recommended):

pipx install cloakmcp              # isolated install, cloak available globally
# or
pip install cloakmcp               # into current environment
pip install cloakmcp[mcp]          # optional: enables cloak serve (FastMCP)

From source (development):

git clone https://github.com/ovitrac/CloakMCP.git && cd CloakMCP
pip install -e ".[mcp]"

Vault keys are auto-generated on first use — no manual key setup required.

2. Set Policy (Recommended)

# Set per-project policy (persists in .cloak/policy.yaml)
cloak policy use examples/mcp_policy.yaml

# Verify
cloak policy use --show

3. Pack / Unpack (Works with Any LLM)

# Pack: replace secrets with tags (vaulted, reversible)
cloak pack --policy examples/mcp_policy.yaml --dir . --prefix TAG

# Now safe to share with any LLM — secrets replaced with TAG-xxxxxxxxxxxx
# Vault stored in ~/.cloakmcp/vaults/

# Unpack: restore original secrets
cloak unpack --dir .

4. Claude Code Setup (Optional)

If you use Claude Code, the pack/unpack cycle is fully automated via hooks:

# The repo already includes .mcp.json and .claude/hooks/
# Just start Claude Code in the project directory:
claude

# CloakMCP hooks fire automatically:
#   SessionStart → pack (secrets hidden)
#   SessionEnd   → unpack (secrets restored)

Security Architecture

How CloakMCP Protects Your Secrets

graph TB
    subgraph "Your Local Machine"
        A[Original Code<br/>with Secrets] -->|cloak pack| B[Packed Code<br/>with Tags]
        B --> C[Git Repository]
        A -->|secrets extracted| D[Encrypted Vault<br/>~/.cloakmcp/vaults/]
        D -.encryption key.-> E[Encryption Key<br/>~/.cloakmcp/keys/]
    end

    subgraph "Shared with LLM"
        C -->|safe to share| F[Claude/Codex<br/>sees only tags]
    end

    subgraph "Restoration"
        F -->|modified code| G[Code with Tags]
        G -->|cloak unpack| H[Original Code<br/>secrets restored]
        D -.decryption.-> H
    end

    style D fill:#ffcccc, color:#000000
    style E fill:#ffcccc, color:#000000
    style F fill:#ccffcc, color:#000000
    style H fill:#ccccff, color:#000000

Why LLMs Cannot Access Secrets

The sequence below shows the automated Claude Code hook flow. For other LLMs, the developer runs cloak pack / cloak unpack manually — the security properties are identical.

sequenceDiagram
    participant Dev as Developer
    participant Cloak as CloakMCP
    participant Vault as Encrypted Vault<br/>(~/.cloakmcp/)
    participant LLM as LLM (any)

    Note over Dev,Cloak: cloak pack (or SessionStart hook)
    Dev->>Cloak: cloak pack --dir .
    Cloak->>Cloak: Scan for secrets
    Cloak->>Vault: Store secret → TAG mapping (encrypted)
    Cloak->>Dev: Files now contain tags (TAG-xxxx)

    Dev->>LLM: Work on tagged code
    Note over LLM: LLM sees: TAG-a6c0cd73627c<br/>NOT: P@ssw0rd-Pr0duction!

    LLM->>Dev: Modified code (tags preserved)
    Note over Dev,Cloak: cloak unpack (or SessionEnd hook)
    Dev->>Cloak: cloak unpack --dir .
    Cloak->>Vault: Retrieve secret for each TAG
    Vault->>Cloak: Decrypted secrets
    Cloak->>Dev: Files restored with original secrets

Vault Architecture

~/.cloakmcp/
├── keys/
│   └── <project-slug>.key        # Fernet encryption key (AES-128, 600 perms)
├── vaults/
│   └── <project-slug>.vault      # Encrypted JSON mapping {TAG → secret}
└── backups/
    └── <project-slug>/           # Pre-redaction backups (auto-cleaned on session end)
        └── <timestamp>.enc       # Encrypted backup (Fernet + HKDF-derived key)

Backups can be restored with cloak restore --from-backup --backup-id <timestamp> --force.

Slug: 16-character SHA-256 prefix of project's absolute path
Encryption: AES-128 via cryptography.Fernet
Permissions: 0600 (owner read/write only)
Portability: Copy .key and .vault to share between machines

Security Properties

Vault is local-only — Never uploaded to git, cloud, or LLM
HMAC-based tags — Tags use HMAC-SHA256 with vault key; cannot reverse without vault key
Brute-force resistant — Even with tag and candidate secret, attacker needs vault key to verify
Encryption protects vault — Even if vault file leaks, attacker needs encryption key
Keys are separate — Vault + key both required for decryption

Protection Boundaries

Core protection (any LLM workflow):

Boundary	Protected?	Mechanism
Files on disk	Yes	`cloak pack` / `cloak unpack` (manual or scripted)
Clipboard / copy-paste	No	Use `cloak sanitize-stdin` before pasting sensitive content
Secret inference by LLM	No	Fundamental: no local filter can prevent model reasoning

Claude Code hooks (when installed — see SECURITY.md for details):

Boundary	Protected?	Mechanism
Session lifecycle	Yes	`SessionStart` / `SessionEnd` hooks automate pack/unpack
Write/Edit tool calls	Yes	`guard-write` hook denies high-severity secrets
Read/Grep/Glob access	Yes	`guard-read` hook blocks access to backups & session files (hardened)
Bash commands	Yes	`safety-guard` hook blocks dangerous commands
User prompts	Mitigated	`prompt-guard` hook blocks/warns (if installed)
Backup exfiltration	Yes	Backups stored in `~/.cloakmcp/backups/`, outside project tree
Chat after prompt	No	Prompt guard scans user input, not model responses

Tip: Pipe text through cloak sanitize-stdin --policy examples/mcp_policy.yaml before pasting. Use vault tags (TAG-xxxxxxxxxxxx) when referring to credentials.

Why no output filtering? In the Claude Code integration, the conversation operates entirely in tag-space by design. See SECURITY.md for the full rationale.

Data Flow Comparison

Without CloakMCP

graph LR
    A[Code with Secrets] -->|sent directly| B[LLM Provider]
    B -->|logged forever| C[Provider Database]
    style C fill:#ffcccc

Risk: Secrets permanently stored on provider servers

With CloakMCP

graph LR
    A[Code with Secrets] -->|hooks / cloak pack| B[Code with Tags]
    B -->|safe to send| C[LLM Provider]
    C -->|only sees tags| D[Provider Database]
    A -.secrets stay local.-> E[Encrypted Vault<br/>~/.cloakmcp/]
    style E fill:#ccffcc
    style D fill:#ccffcc

Protection: Only meaningless tags reach provider

Common Questions

Q: Can someone with my git repo see my secrets? A: No. Git only contains tags like TAG-2f1a8e3c9b12. The vault is in ~/.cloakmcp/ on your machine.

Q: What if I lose my vault key? A: Secrets are unrecoverable. Keep backups of ~/.cloakmcp/keys/ in a secure location.

Q: Can LLMs guess secrets from tags? A: No. Tags are HMAC-SHA256 signatures (keyed with your vault key) truncated to 12 hex chars. Without your ~/.cloakmcp/keys/, reversing tags is cryptographically infeasible.

Q: Does this work with any LLM? A: Yes. CloakMCP's core CLI (cloak pack/unpack/scan/sanitize) is LLM-agnostic — it works with Claude, Copilot, Codex, Gemini, local Ollama models, or any LLM that reads your code. The Claude Code integration (hooks + MCP) adds automatic session-level protection but is not required.

Configuration

Policy File (`mcp_policy.yaml`)

version: 1

globals:
  default_action: redact
  audit:
    enabled: true
    path: ./audit/audit.jsonl
  pseudonymization:
    method: hmac-sha256
    secret_key_file: ./keys/mcp_hmac_key

detection:
  - id: aws_access_key
    type: regex
    pattern: '\b(AKIA|ASIA)[A-Z0-9]{16}\b'
    action: block
    severity: high

  - id: jwt_token
    type: regex
    pattern: '\b[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+\b'
    action: pseudonymize

  - id: email
    type: regex
    pattern: '(?i)[a-z0-9_.+-]+@[a-z0-9-]+\.[a-z0-9.-]+'
    action: replace_with_template
    template: '<EMAIL:{hash8}>'
    whitelist: ['*@example.com']

  - id: high_entropy_token
    type: entropy
    min_entropy: 4.5
    min_length: 20
    action: redact

Enterprise Policy Profile

For production environments with additional provider coverage:

cloak pack --policy examples/mcp_policy_enterprise.yaml --dir .

Profile	File	Rules	Coverage
Default	`mcp_policy.yaml`	10	AWS, GCP, SSH, PEM, JWT, email, IP, URL, entropy
Enterprise	`mcp_policy_enterprise.yaml`	26	Default + GitHub, GitLab, Slack, Stripe, npm, Heroku, Twilio, SendGrid, Azure, PKCS#8, generic password/secret patterns

The enterprise profile inherits from the default via inherits: [mcp_policy.yaml]. Provider-specific rules use context-gated detection where needed (e.g., Heroku UUID requires HEROKU prefix to avoid false positives).

`.mcpignore` File

Controls which files are skipped during pack/unpack (similar to .gitignore):

# Binaries and build artifacts
*.pyc
*.so
dist/
build/
__pycache__/

# Virtual environments
.venv/
node_modules/

# Media
*.png
*.jpg
*.pdf

# Already sensitive
audit/
keys/
.git/

Environment Variables

Variable	Default	Description
`CLOAK_POLICY`	`examples/mcp_policy.yaml`	Path to the YAML policy file used by hooks
`CLOAK_PREFIX`	`TAG`	Tag prefix for pack operations (e.g., `TAG`, `SEC`, `KEY`)
`CLOAK_STRICT`	(unset)	Set to `1` to treat medium-severity matches as blocking (hooks escalate warn → deny/block)
`CLOAK_PROMPT_GUARD`	(enabled)	Set to `off` to disable the UserPromptSubmit hook entirely
`CLOAK_AUDIT_TOOLS`	(unset)	Set to `1` to enable Tier 2 tool metadata logging (hashed file paths)
`CLOAK_REPACK_ON_WRITE`	(unset)	Set to `1` to auto-repack files after Write/Edit tool calls. Adds latency per write.
`CLOAK_FAIL_CLOSED`	(unset)	Set to `1` to deny writes and refuse sessions when no policy is found (recommended for regulated environments)
`CLOAK_PASSPHRASE`	(unset)	Passphrase for Tier 1 key wrapping (scrypt). When set, new keys are wrapped and existing wrapped keys are unlocked automatically

Group Policies

New in v0.3.2+: Hierarchical security policies that cascade from company → team → project.

graph TB
    A[Company Baseline<br/>~/.cloakmcp/policies/company-baseline.yaml] --> B[Backend Team Policy<br/>~/.cloakmcp/policies/team-backend.yaml]
    A --> C[Frontend Team Policy<br/>~/.cloakmcp/policies/team-frontend.yaml]
    B --> D[Project Policy<br/>examples/my-project-policy.yaml]

    style A fill:#ffcccc
    style B fill:#ccffcc
    style D fill:#ccccff

Policies share detection rules, NOT vault keys
Each project maintains its own unique vault key
Later policies override earlier ones (same rule ID)
Cycle detection prevents circular inheritance

# Validate policy chain
cloak policy validate --policy examples/my-project-policy.yaml

# Show merged policy after inheritance
cloak policy show --policy examples/my-project-policy.yaml --format yaml

Full guide: See docs/GROUP_POLICY_IMPLEMENTATION.md

VS Code Integration

Shortcut	Action
`Ctrl+Alt+S`	Sanitize current file (preview)
`Ctrl+Alt+A`	Scan current file (audit only)

Full guide: See docs/VSCODE_MANUAL.md

API Server (Optional)

CloakMCP includes an optional FastAPI server for real-time sanitization:

openssl rand -hex 32 > keys/mcp_api_token
uvicorn cloakmcp.server:app --host 127.0.0.1 --port 8765

Endpoint	Method	Description
`/health`	GET	Server status and policy hash
`/sanitize`	POST	Sanitize text (modify secrets)
`/scan`	POST	Scan text (audit only)

All endpoints require Bearer token authentication. Server binds to 127.0.0.1 only.

Testing

pip install -e ".[test]"

# Run all tests (401 passing)
pytest

# Run with coverage
pytest --cov=cloakmcp --cov-report=term

Test suite: 401 tests across 10 test files covering unit tests, integration tests, API tests, hook tests, MCP server tests, enterprise policy tests, backup encryption, key wrapping, backup lifecycle, cross-platform hooks, idempotency, and Windows platform guards.

Project Structure

CloakMCP/
├── cloakmcp/                      # Main package (16 modules, ~4,200 LOC)
│   ├── __init__.py
│   ├── actions.py                 # Action engine (redact, pseudonymize, etc.)
│   ├── audit.py                   # Audit logging
│   ├── cli.py                     # CLI entry point (scan, sanitize, pack, unpack, hook, install)
│   ├── dirpack.py                 # Directory pack/unpack walker
│   ├── fastmcp_server.py          # FastMCP server (cloak serve, 6 tools)
│   ├── filepack.py                # Text-level pack/unpack with overlap dedup
│   ├── hooks/                     # Claude Code hooks package (v0.12.0)
│   │   ├── __init__.py            # Hook handlers (session, guard-write, prompt-guard, etc.)
│   │   └── __main__.py            # python -m cloakmcp.hooks entrypoint
│   ├── installer.py               # Cross-platform hook installer (cloak install)
│   ├── mcp_server.py              # MCP tool server (JSON-RPC 2.0 over stdio)
│   ├── normalizer.py              # Text normalization
│   ├── policy.py                  # Policy engine (YAML, inheritance, merging)
│   ├── scanner.py                 # Secret detectors (regex, entropy, IP, URL, email)
│   ├── server.py                  # FastAPI REST server (localhost)
│   ├── storage.py                 # Vault encryption (Fernet AES-128, scrypt key wrapping)
│   └── utils.py                   # Utilities (hashing, encoding)
├── tests/                         # Test suite (401 tests, 10 files)
│   ├── conftest.py                # Autouse fixture for ~/.cloakmcp/ artifact cleanup
│   ├── test_comprehensive.py      # Full feature tests
│   ├── test_api.py                # API endpoint tests
│   ├── test_filepack.py           # Pack/unpack round-trip tests
│   ├── test_hooks.py              # Claude Code hook tests (session, guard, repack)
│   ├── test_mcp_server.py         # MCP server protocol tests
│   ├── test_policy_enterprise.py  # Enterprise policy profile tests
│   ├── test_backup_encryption.py  # HKDF backup encryption tests
│   ├── test_key_wrapping.py       # Tier 1 scrypt key wrapping tests
│   ├── test_backup_lifecycle.py   # Backup migrate/prune tests
│   ├── test_cross_platform_hooks.py # Cross-platform hook installer tests
│   └── test_smoke.py              # Basic smoke test
├── docs/                          # Developer documentation
│   ├── QUICKSTART.md              # First-time setup, FAQ, compatibility
│   ├── QUICKREF.md                # Cheat sheet (all CLI commands)
│   ├── SERVER.md                  # Server configuration and security model
│   ├── VSCODE_MANUAL.md           # Complete VS Code integration guide
│   ├── GROUP_POLICY_IMPLEMENTATION.md  # Group policy inheritance details
│   └── THREAT_MODEL.md            # Threat model and security analysis (v0.12.0)
├── cloakmcp/scripts/              # Bundled installer + hooks (included in PyPI wheel)
│   ├── install_claude.sh          # Legacy bash installer (use cloak install instead)
│   ├── hooks/                     # 7 .sh + 7 .py hook scripts (cross-platform)
│   └── settings/                  # Settings templates (hooks-cli.json, hooks-hardened.json, etc.)
├── demo/                          # Live demo (Spring Boot banking service)
│   ├── llm_demo.sh                # LLM demo (Ollama / Claude)
│   ├── mcp_demo.sh                # MCP protocol + hook lifecycle demo
│   ├── transcript.sh              # Screenshot-friendly before/after
│   ├── run_demo.sh                # Interactive 5-act presentation
│   └── src/                       # Fake banking microservice (3 config files)
├── examples/                      # Example policies
│   ├── mcp_policy.yaml            # Default policy (10 rules)
│   ├── mcp_policy_enterprise.yaml # Enterprise policy (26 rules, inherits default)
│   └── policies/                  # Group policy examples (inheritance)
├── api/                           # REST Client examples
│   └── requests.http              # VS Code REST Client test file
├── assets/                        # Project assets (logo, media)
├── audit/                         # Audit log output directory
├── deploy/                        # Deployment configurations
│   └── mcp-local.service          # Systemd unit (localhost only)
├── keys/                          # Local keys (gitignored contents)
├── .claude/                       # Claude Code integration (runtime, gitignored)
├── .mcp.json                      # MCP server discovery for Claude Code
├── .vscode/                       # VS Code integration (tasks, keybindings)
├── .mcpignore                     # Pack/unpack exclusion patterns
├── pyproject.toml                 # Package metadata (v0.13.1)
├── pytest.ini                     # Pytest configuration
├── CHANGELOG.md                   # Full release history
├── SECURITY.md                    # Security policy and disclosure
├── CONTRIBUTING.md                # Contribution guidelines
├── AUTHORS.md                     # Project authorship
├── LICENSE                        # MIT License
└── README.md                      # This file

Documentation

Document	Description
`README.md`	This file (overview and quick start)
`docs/QUICKSTART.md`	First-time setup, compatibility matrix, FAQ
`docs/QUICKREF.md`	Cheat sheet for daily use (all CLI commands)
`CHANGELOG.md`	Full release history (Keep a Changelog format)
`demo/README.md`	Live demo guide (4 scripts, LLM + MCP)
`docs/SERVER.md`	Server configuration and security model
`docs/VSCODE_MANUAL.md`	Complete VS Code integration guide
`docs/GROUP_POLICY_IMPLEMENTATION.md`	Group policy inheritance details
`docs/THREAT_MODEL.md`	Threat model and security analysis
`SECURITY.md`	Security policy, Claude Code hook security model, disclosure
`CONTRIBUTING.md`	Contribution guidelines
`tests/README.md`	Test suite documentation

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

# Development setup (from source)
git clone https://github.com/ovitrac/CloakMCP.git && cd CloakMCP
pip install -e ".[test]"

# Code quality
black cloakmcp/ tests/
mypy cloakmcp/
bandit -r cloakmcp/
pytest -v

Commit convention: type(scope): description (e.g., feat(hooks): add guard-write handler)

Changelog

See CHANGELOG.md for the full release history.

Latest: v0.13.1 — PyPI/pipx install recommended (v0.13.0: Windows hardening, v0.12.0: cross-platform hooks)

License

MIT License — see LICENSE.

Authors

Olivier Vitrac — Design & Implementation — Adservio Innovation Lab

See AUTHORS.md for the full list of contributors.

Links

Repository: https://github.com/ovitrac/CloakMCP
Issues: https://github.com/ovitrac/CloakMCP/issues
Documentation: DeepWiki
License: MIT

"Any LLM may read, refactor, or reason on tagged data — but none can unmask what the vault keeps safe."

Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 45 Commits
.github/workflows		.github/workflows
.vscode		.vscode
api		api
assets		assets
cloakmcp		cloakmcp
demo		demo
deploy		deploy
docs		docs
examples		examples
tests		tests
.gitignore		.gitignore
.mcp.json		.mcp.json
.mcpignore		.mcpignore
AUTHORS.md		AUTHORS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini

Folders and files

Latest commit

History

Repository files navigation

CloakMCP

Your secrets stay home. The AI only sees tags.

See It Work

Overview

What makes CloakMCP different

Key Capabilities

Claude Code Integration

1. Hooks — Automatic Session Protection

2. MCP Tool Server — 6 Tools

Features

Detectors

Actions

CLI Commands

Live Demo

LLM Demo — The Highlight

MCP Protocol Demo

Other Demos

Quick Start

1. Install

2. Set Policy (Recommended)

3. Pack / Unpack (Works with Any LLM)

4. Claude Code Setup (Optional)

Security Architecture

How CloakMCP Protects Your Secrets

Why LLMs Cannot Access Secrets

Vault Architecture

Security Properties

Protection Boundaries

Data Flow Comparison

Without CloakMCP

With CloakMCP

Common Questions

Configuration

Policy File (mcp_policy.yaml)

Enterprise Policy Profile

.mcpignore File

Environment Variables

Group Policies

VS Code Integration

API Server (Optional)

Testing

Project Structure

Documentation

Contributing

Changelog

License

Authors

Links

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Policy File (`mcp_policy.yaml`)

`.mcpignore` File

Packages