{
  "markdown": "# SecuRedact MCP\n\n<!-- mcp-name: io.github.GigantesHJI/securedact-mcp -->\n\n[![PyPI](https://img.shields.io/pypi/v/securedact-mcp)](https://pypi.org/project/securedact-mcp/)\n[![Python](https://img.shields.io/pypi/pyversions/securedact-mcp)](https://pypi.org/project/securedact-mcp/)\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE.md)\n\n**SecuRedact** is a local-first privacy and security layer for AI agents and AI\nworkflows. It detects and protects sensitive data — personal data / PII,\nGDPR-sensitive information, credentials, API keys, tokens, secrets, and\nsensitive files — before that data reaches models, tools, files, or external\ndestinations.\n\nSecuRedact MCP is the Apache-2.0 open-source MCP server and reusable Python\nprivacy engine. It detects sensitive text, applies versioned policies, redacts\nlocally, and validates residual output before marking sanitized content\napproved.\n\n> MCP mode does not automatically intercept every prompt. The host must invoke\n> the tool and send only `sanitized_text` when `status == \"ok\"`; a misconfigured\n> or malicious MCP host can bypass that ordinary MCP workflow. Provider-native\n> enforced hooks are separate integration assets: when a supported provider\n> invokes such a hook at its prompt lifecycle boundary, it can apply the same\n> deterministic decision before normal model processing. See [SecuRedact\n> Enforced](docs/enforced.md).\n\n## Why SecuRedact\n\nAI agents increasingly read files, call tools, and send prompts to external\nmodels. That exposes PII, credentials, and sensitive documents unless something\nchecks the data first. SecuRedact is a privacy and security control for AI\nworkflows:\n\n- **Local-first** — all detection, redaction, and policy evaluation run on your\n  machine. No network listener by default, no telemetry, no provider calls.\n- **PII / GDPR detection** — names, emails, IBANs, identifiers, and\n  special-category data are detected and pseudonymized or redacted.\n- **Secret & credential protection** — API keys, tokens, and passwords are\n  detected and blocked from leaving your environment.\n- **Filesystem protection** — reads are defended against traversal/symlink\n  escapes and blocked from protected paths such as `.env`.\n- **AI Agent Privacy Firewall** — enforced hooks for Claude Code and Gemini CLI\n  run the same local decision before a prompt, model call, or tool action\n  proceeds.\n- **Network / egress awareness** — outbound tool calls are classified\n  (internal/external/unknown) so policy can require approval or block egress.\n\nSecuRedact helps reduce exposure of sensitive data; it is not a guarantee of\ncompliance or a claim that every leak is prevented. See\n[Limitations](#security-and-limitations).\n\n## HIPAA Safe Harbor (0.5.0)\n\nSecuRedact 0.5.0 adds a HIPAA Safe Harbor mechanical-de-identification aid for\n`45 CFR 164.514(b)(2)` text processing. It builds on the existing deterministic\ndetection stack and adds an 18-category Safe Harbor mapping, US-specific identifiers\n(SSN with area/group/serial validation, US ZIP/ZIP+4, health-plan beneficiary,\naccount numbers, ages over 89, VIN-format vehicle identifiers, fax), and an optional\nvalidated Flair PERSON-only gate for Category A (Names).\n\nUse `engine.hipaa_safe_harbor(text)` or the `HIPAA_SAFE_HARBOR_POLICY` policy. This is\na mechanical aid, **not** a compliance certification: it cannot satisfy the\nactual-knowledge prong (`164.514(b)(2)(ii)`) or replace Expert Determination\n(`164.514(b)(1)`). See\n[docs/hipaa-safe-harbor-profile.md](docs/hipaa-safe-harbor-profile.md) and\n[docs/hipaa-safe-harbor-gap-analysis.md](docs/hipaa-safe-harbor-gap-analysis.md).\n\n## Quick start\n\nInstall from PyPI and run the guided setup (Windows):\n\n```powershell\npy -3.12 -m pip install \"securedact-mcp[ml]\"\nsecuredact-mcp setup\n```\n\nLinux / macOS:\n\n```bash\npython3.12 -m pip install \"securedact-mcp[ml]\"\nsecuredact-mcp setup\n```\n\nProtect a piece of text in seconds (deterministic-only demo, no model needed):\n\n```python\nimport os\n\nos.environ[\"SECUREDACT_REQUIRE_FLAIR\"] = \"0\"  # deterministic detectors only\nfrom securedact_core import RedactionRequest, SecuredactEngine\n\nengine = SecuredactEngine.from_environment()\nresult = engine.prepare(\n    RedactionRequest(\n        text=\"Contact alex@example.test, IBAN NL91ABNA0417164300\",\n        policy=\"strict_external_ai\",\n    )\n)\nprint(result.status)  # \"ok\"\nprint(result.sanitized_text)  # \"Contact [EMAIL_1], IBAN [IBAN_1]\"\n```\n\nReproducible synthetic security demos: [`docs/distribution/security-demo.md`](docs/distribution/security-demo.md).\n\n## Safe default workflow\n\nUse `prepare_for_external_ai` for normal external-AI preparation:\n\n```json\n{\n  \"text\": \"Contact alex@example.test\",\n  \"policy\": \"strict_external_ai\",\n  \"language\": \"auto\",\n  \"response_mode\": \"minimal\"\n}\n```\n\nApproved response:\n\n```json\n{\n  \"schema_version\": \"1\",\n  \"status\": \"ok\",\n  \"sanitized_text\": \"Contact [EMAIL_1]\",\n  \"counts\": {\"email\": 1},\n  \"policy\": \"strict_external_ai\",\n  \"policy_version\": 1,\n  \"policy_digest\": \"...\",\n  \"reason_codes\": []\n}\n```\n\n`review_required` and `blocked` responses never contain approved\n`sanitized_text`. Minimal responses contain no original text, raw entity values,\nmapping, exception body, stack trace, model path, or restoration handle unless\n`restore_capable` was explicitly selected.\n\n## Architecture and trust boundary\n\n```mermaid\nflowchart LR\n    H[\"MCP host\"] --> M[\"Securedact MCP\"]\n    M --> D[\"deterministic detectors\"]\n    M --> C[\"contextual detectors\"]\n    D --> P[\"policy engine\"]\n    C --> P\n    P --> R[\"redactor\"]\n    R --> V[\"residual validator\"]\n    V --> O[\"approved sanitized output\"]\n    O --> W[\"host-controlled downstream workflow\"]\n    H -. \"host may bypass MCP\" .-> W\n```\n\nThe server has no provider clients, OpenAI-compatible proxy, reverse proxy,\nwebsite, desktop chatbot, provider credentials, or provider-specific forwarding.\nSee [ADR 0001](docs/adr/0001-mcp-server-product-boundary.md) and the\n[threat model](docs/threat-model.md).\n\n## Tools\n\n| Tool | Intended use | Sensitive-response behavior |\n|---|---|---|\n| `prepare_for_external_ai` | Recommended complete safe workflow | Minimal by default |\n| `analyze_text` | Lower-level local analysis/review | Minimal; offsets in `review`; raw values only in enabled debug mode |\n| `redact_text` | Lower-level compatibility operation | Minimal by default; explicit `legacy` mode is sensitive and deprecated |\n| `restore_text` | Consume a local opaque session | Single-use by default; direct mappings require explicit trusted legacy mode |\n| `create_safe_copy` | Write approved `.txt`/`.md` content under one configured root | Returns no mapping or absolute path |\n| `securedact_read_file` | Safely read a local file and return only sanitized text | Blocks protected paths before reading; rejects traversal/symlink/binary; `minimal` by default |\n\nResponse modes are `minimal`, `review`, `debug`, and `restore_capable`. Debug is\ndisabled unless the process was started with\n`SECUREDACT_ENABLE_DEBUG_RESPONSES=1`; an MCP request cannot enable it. In-memory\nrestoration sessions use cryptographic random handles, bounded capacity,\nexpiration, concurrency protection, and single-use consumption. Process exit\ndestroys all sessions.\n\nSee [MCP tools](docs/mcp-tools.md), [response privacy](docs/privacy-model.md), and\n[restoration sessions](docs/restoration-sessions.md).\n\n## Installation\n\nPython `>=3.12,<3.13` is supported.\n\nFor a normal installation from PyPI:\n\n```powershell\npy -3.12 -m pip install \"securedact-mcp[ml]\"\nsecuredact-mcp setup\n```\n\nOn Linux or macOS, use `python3.12 -m pip install \"securedact-mcp[ml]\"`;\n`python -m pip install \"securedact-mcp[ml]\"` is also appropriate when `python`\nalready selects a supported 3.12 environment.\n\n`setup` checks the package, Python and ML dependencies, inspects local model\nstate, offers the existing consent-based model installer, runs the existing\noffline verifier, and offers the packaged Claude Code and Gemini CLI\nintegrations when those hosts are detected. It uses the providers' official\nplugin/extension commands and is safe to rerun. It does not call a provider\nmodel API, accept provider trust automatically, or download a contextual model\nunless the user explicitly selects model setup and accepts the existing\nupstream prompt.\n\nManual model commands remain available for advanced or unattended operation:\n\n```powershell\nsecuredact-mcp install\nsecuredact-mcp models verify\nsecuredact-mcp\n```\n\nThe last command starts a local `stdio` server. Standard output is reserved for\nMCP protocol messages. `securedact-mcp setup --non-interactive` reports state\nwithout implying upstream acceptance or configuring a new provider. Use\n`--host claude`, `--host gemini`, or `--host all` for targeted interactive\nprovider setup.\n\n### Developer/source installation\n\nTo work from a reviewed source checkout instead:\n\n```powershell\ngit clone https://github.com/GigantesHJI/securedact-mcp.git\ncd securedact-mcp\npython -m pip install \".[ml]\"\nsecuredact-mcp setup\n```\n\nNo model checkpoint is included in the repository or wheel, and startup never\ndownloads one. Securedact does not redistribute these model weights. Upstream\nmodel weights retain their own licenses and are not relicensed by Apache-2.0.\nSee [model installation](docs/model-installation.md) and [third-party\nlicenses](docs/third-party-licenses.md).\n\nDeterministic-only local development must be explicitly selected:\n\n```powershell\n$env:SECUREDACT_REQUIRE_FLAIR = \"0\"\nsecuredact-mcp\n```\n\nProduction defaults to requiring contextual capability and fails closed while a\nconfigured model is missing, loading, corrupt, or unavailable.\n\n## Host packages\n\nTested configuration assets and safe-workflow instructions are under\n`integrations/` for Codex, Cursor, and Windsurf. The automated MCP client harness\nvalidates server startup, tool listing, calls, minimal response shape, stdout\nintegrity, and shutdown. It does not prove that a real host invokes the tool for\nevery prompt. See the [compatibility evidence](docs/compatibility.md).\n\nThe repository is also a Gemini CLI extension root: `gemini extensions install\nhttps://github.com/GigantesHJI/securedact-mcp` can install the hooks. The\n`gemini-cli-extension` topic and a release whose tag tree contains the root\nmanifest are required for that path to resolve; without `pip install\n\"securedact-mcp[ml]\"` and the local models the installed hooks do not enforce\nanything. See [SecuRedact Enforced](docs/enforced.md).\n\n## Policies and Python API\n\nBuilt-ins include `default`, `strict_external_ai`, `gdpr`, `identifiers_only`,\nand `review_all_contextual`; compatibility policies remain available. Local\norganization policy files load only from the controlled policy directory, use a\nstrict declarative schema, and cannot disable fail-closed invariants. Unknown,\nduplicate, oversized, malformed, or symlinked policies fail closed.\n\n```python\nfrom securedact_core import RedactionRequest, SecuredactEngine\n\nengine = SecuredactEngine.from_environment()\nresult = engine.prepare(\n    RedactionRequest(\n        text=\"Contact alex@example.test\",\n        policy=\"strict_external_ai\",\n    )\n)\n```\n\n`from_environment()` preserves the contextual-model requirement. Standalone\ndeterministic development requires `SECUREDACT_REQUIRE_FLAIR=0`; applications may\nalso inject tested detector implementations. See [public API](docs/public-api.md)\nand [policies](docs/policies.md).\n\n## Reproducible development\n\nThe committed `uv.lock` resolves runtime, ML, development, benchmark, and\nsecurity extras for Python 3.12.\n\n```powershell\nuv sync --frozen --extra dev --extra benchmark\nuv run python scripts\\verify.py\n```\n\nNever use real personal information, private documents, credentials, customer\nlogs, or model weights in tests, issues, screenshots, fixtures, or pull requests.\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Evaluation and performance\n\n```powershell\nuv run python -m securedact_eval quality --mode deterministic --gate `\n  --thresholds benchmarks\\thresholds.json `\n  --baseline benchmarks\\baselines\\quality-deterministic.json\nuv run python -m securedact_eval performance --mode deterministic\n```\n\nThe versioned synthetic corpus reports exact and relaxed span precision, recall,\nF1, false-positive and false-negative rates, per-entity/language/domain/split\nresults, action/category accuracy, and bootstrap recall intervals. True negatives\nare document-level negative examples, not token-level safety. The GDPR-related\nsuite is detection evaluation, not legal compliance certification. Real Flair\nand GPU benchmarks require an explicitly configured local model and are not\nordinary CI. See [benchmarking](docs/benchmarking.md).\nThe [benchmark framework](benchmarks/README.md) documents local data tiers and large profiles;\nthe [migration plan](docs/benchmark-migration.md) defines its future extraction boundary. For a\nfailure before GitHub executes repository steps, use the\n[CI troubleshooting decision tree](docs/ci-troubleshooting.md). Local success does not replace a\nrequired GitHub check.\n\n## Security and limitations\n\n- No prompt, finding, mapping, restoration handle, secret, model input, or\n  restored output is logged by application code.\n- Deterministic and contextual detection can miss novel, ambiguous, or\n  adversarial disclosure; coreference and universal obfuscation resistance are\n  not claimed.\n- Review offsets let a trusted local client with the original input reconstruct\n  a value; keep review responses local.\n- Host behavior and downstream provider behavior are outside the trust boundary.\n- Repository security settings documented in files still require administrator\n  verification.\n\nReport vulnerabilities privately using [SECURITY.md](SECURITY.md). Do not put\nvulnerability details or real data in a public issue.\n\n## License\n\nOriginal repository source and documentation are licensed under the\n[Apache License 2.0](LICENSE.md). Copyright attribution is recorded in\n[NOTICE](NOTICE). Third-party dependencies and model weights retain their own\nlicenses.\n",
  "bytes": 14033,
  "sha": "6a85b7e506e232bbeb50500b541b412d5a56c4bb941b1509447d961cebce983a",
  "repo_slug": "giganteshji/securedact-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_giganteshji_securedact_mcp_50e791bc/readme"
}