securedact-mcp
SecuRedact MCP
SecuRedact 是面向 AI 代理和 AI 工作流的本地优先隐私与安全层。它能在数据到达模型、工具、文件或外部目标之前,检测并保护敏感数据——个人数据 / PII、GDPR 敏感信息、凭据、API 密钥、令牌、机密和敏感文件。
SecuRedact MCP 是 Apache-2.0 开源 MCP 服务器和可复用的 Python 隐私引擎。它检测敏感文本,应用版本化策略,在本地进行脱敏,并在将净化内容标记为已批准之前验证残余输出。
MCP 模式不会自动拦截每个提示。宿主必须调用该工具,并且仅在
status == "ok"时发送sanitized_text;配置错误或恶意的 MCP 宿主可以绕过这种普通的 MCP 工作流。提供商原生的强制钩子是单独的集成资产:当受支持的提供商在其提示生命周期边界调用此类钩子时,它可以在正常模型处理之前应用相同的确定性决策。参见 SecuRedact Enforced。
为什么选择 SecuRedact
AI 代理越来越多地读取文件、调用工具并向外部模型发送提示。除非先检查数据,否则这会暴露 PII、凭据和敏感文档。SecuRedact 是 AI 工作流的隐私和安全控制:
本地优先 — 所有检测、脱敏和策略评估都在您的机器上运行。默认无网络监听、无遥测、无提供商调用。
PII / GDPR 检测 — 姓名、电子邮件、IBAN、标识符和特殊类别数据均被检测并伪匿名化或脱敏。
机密与凭据保护 — API 密钥、令牌和密码均被检测并阻止离开您的环境。
文件系统保护 — 读取操作可防御路径遍历/符号链接逃逸,并阻止访问受保护路径(如
.env)。AI 代理隐私防火墙 — 针对 Claude Code 和 Gemini CLI 的强制钩子在提示、模型调用或工具操作继续之前运行相同的本地决策。
网络 / 出口感知 — 出站工具调用被分类(内部/外部/未知),以便策略可以要求批准或阻止出口。
SecuRedact 有助于减少敏感数据的暴露;它不保证合规性,也不声称能防止每一次泄露。参见 限制。
Related MCP server: phi-redact-mcp
快速开始
从 PyPI 安装并运行引导式设置(Windows):
py -3.12 -m pip install "securedact-mcp[ml]"
securedact-mcp setupLinux / macOS:
python3.12 -m pip install "securedact-mcp[ml]"
securedact-mcp setup在几秒钟内保护一段文本(仅确定性演示,无需模型):
import os
os.environ["SECUREDACT_REQUIRE_FLAIR"] = "0" # deterministic detectors only
from securedact_core import RedactionRequest, SecuredactEngine
engine = SecuredactEngine.from_environment()
result = engine.prepare(
RedactionRequest(
text="Contact alex@example.test, IBAN NL91ABNA0417164300",
policy="strict_external_ai",
)
)
print(result.status) # "ok"
print(result.sanitized_text) # "Contact [EMAIL_1], IBAN [IBAN_1]"可复现的合成安全演示:docs/distribution/security-demo.md。
安全默认工作流
对于正常的外部 AI 准备,使用 prepare_for_external_ai:
{
"text": "Contact alex@example.test",
"policy": "strict_external_ai",
"language": "auto",
"response_mode": "minimal"
}已批准的响应:
{
"schema_version": "1",
"status": "ok",
"sanitized_text": "Contact [EMAIL_1]",
"counts": {"email": 1},
"policy": "strict_external_ai",
"policy_version": 1,
"policy_digest": "...",
"reason_codes": []
}review_required 和 blocked 响应绝不包含已批准的 sanitized_text。最小响应不包含原始文本、原始实体值、映射、异常体、堆栈跟踪、模型路径或恢复句柄,除非显式选择了 restore_capable。
架构与信任边界
flowchart LR
H["MCP host"] --> M["Securedact MCP"]
M --> D["deterministic detectors"]
M --> C["contextual detectors"]
D --> P["policy engine"]
C --> P
P --> R["redactor"]
R --> V["residual validator"]
V --> O["approved sanitized output"]
O --> W["host-controlled downstream workflow"]
H -. "host may bypass MCP" .-> W服务器没有提供商客户端、OpenAI 兼容代理、反向代理、网站、桌面聊天机器人、提供商凭据或提供商特定的转发。参见 ADR 0001 和 威胁模型。
工具
工具 | 预期用途 | 敏感响应行为 |
| 推荐的完整安全工作流 | 默认最小化 |
| 较低级别的本地分析/审查 | 最小化; |
| 较低级别的兼容性操作 | 默认最小化;显式 |
| 使用本地不透明会话 | 默认单次使用;直接映射需要显式受信任的旧模式 |
| 在一个配置的根目录下写入已批准的 | 不返回映射或绝对路径 |
| 安全读取本地文件并仅返回净化文本 | 在读取前阻止受保护路径;拒绝路径遍历/符号链接/二进制;默认 |
响应模式为 minimal、review、debug 和 restore_capable。除非进程以 SECUREDACT_ENABLE_DEBUG_RESPONSES=1 启动,否则调试被禁用;MCP 请求无法启用它。内存中的恢复会话使用加密随机句柄、有界容量、过期时间、并发保护和单次使用消费。进程退出会销毁所有会话。
安装
支持 Python >=3.12,<3.13。
对于从 PyPI 的正常安装:
py -3.12 -m pip install "securedact-mcp[ml]"
securedact-mcp setup在 Linux 或 macOS 上,使用 python3.12 -m pip install "securedact-mcp[ml]";当 python 已经选择受支持的 3.12 环境时,python -m pip install "securedact-mcp[ml]" 也是合适的。
setup 检查包、Python 和 ML 依赖,检查本地模型状态,提供现有的基于同意的模型安装程序,运行现有的离线验证器,并在检测到这些宿主时提供打包的 Claude Code 和 Gemini CLI 集成。它使用提供商的官方插件/扩展命令,并且可以安全地重新运行。它不会调用提供商模型 API、自动接受提供商信任,也不会下载上下文模型,除非用户显式选择模型设置并接受现有的上游提示。
手动模型命令仍可用于高级或无人值守操作:
securedact-mcp install
securedact-mcp models verify
securedact-mcp最后一个命令启动本地 stdio 服务器。标准输出保留用于 MCP 协议消息。securedact-mcp setup --non-interactive 报告状态,而不暗示上游接受或配置新提供商。使用 --host claude、--host gemini 或 --host all 进行有针对性的交互式提供商设置。
开发者/源码安装
要从已审查的源码检出工作,请改为:
git clone https://github.com/GigantesHJI/securedact-mcp.git
cd securedact-mcp
python -m pip install ".[ml]"
securedact-mcp setup仓库或 wheel 中不包含模型检查点,启动时也从不下载。Securedact 不重新分发这些模型权重。上游模型权重保留其自己的许可证,并且不会由 Apache-2.0 重新许可。参见 模型安装 和 第三方许可证。
必须显式选择仅确定性的本地开发:
$env:SECUREDACT_REQUIRE_FLAIR = "0"
securedact-mcp生产环境默认要求上下文能力,并在配置的模型缺失、加载中、损坏或不可用时以失败关闭。
宿主包
integrations/ 下提供了针对 Codex、Cursor 和 Windsurf 的测试配置资产和安全工作流说明。自动化 MCP 客户端测试工具验证服务器启动、工具列表、调用、最小响应形状、stdout 完整性和关闭。它不证明真实宿主会为每个提示调用该工具。参见 兼容性证据。
该仓库也是 Gemini CLI 扩展根:gemini extensions install https://github.com/GigantesHJI/securedact-mcp 可以安装钩子。该路径需要 gemini-cli-extension 主题和包含根清单的发布标签树;如果没有 pip install "securedact-mcp[ml]" 和本地模型,安装的钩子不会强制执行任何内容。参见 SecuRedact Enforced。
策略和 Python API
内置策略包括 default、strict_external_ai、gdpr、identifiers_only 和 review_all_contextual;兼容性策略仍然可用。本地组织策略文件仅从受控策略目录加载,使用严格的声明式模式,并且不能禁用失败关闭不变量。未知、重复、过大、格式错误或符号链接的策略会失败关闭。
from securedact_core import RedactionRequest, SecuredactEngine
engine = SecuredactEngine.from_environment()
result = engine.prepare(
RedactionRequest(
text="Contact alex@example.test",
policy="strict_external_ai",
)
)from_environment() 保留上下文模型要求。独立的确定性开发需要 SECUREDACT_REQUIRE_FLAIR=0;应用程序也可以注入经过测试的检测器实现。参见 公共 API 和 策略。
可复现开发
已提交的 uv.lock 为 Python 3.12 解析运行时、ML、开发、基准测试和安全扩展。
uv sync --frozen --extra dev --extra benchmark
uv run python scripts\verify.py切勿在测试、问题、截图、夹具或拉取请求中使用真实的个人信息、私人文档、凭据、客户日志或模型权重。参见 CONTRIBUTING.md。
评估与性能
uv run python -m securedact_eval quality --mode deterministic --gate `
--thresholds benchmarks\thresholds.json `
--baseline benchmarks\baselines\quality-deterministic.json
uv run python -m securedact_eval performance --mode deterministic版本化合成语料库报告精确和宽松的跨度精确率、召回率、F1、假阳性和假阴性率、按实体/语言/领域/拆分的结果、动作/类别准确率以及引导召回区间。真阴性是文档级别的负例,而不是令牌级别的安全性。GDPR 相关套件是检测评估,不是法律合规认证。真实的 Flair 和 GPU 基准测试需要显式配置的本地模型,并且不是普通的 CI。参见 基准测试。 基准测试框架 记录了本地数据层级和大型配置文件;迁移计划 定义了其未来的提取边界。对于在 GitHub 执行仓库步骤之前发生的失败,请使用 CI 故障排除决策树。本地成功不能替代必需的 GitHub 检查。
安全与限制
应用程序代码不会记录任何提示、发现、映射、恢复句柄、机密、模型输入或恢复输出。
确定性和上下文检测可能会遗漏新颖、模糊或对抗性的披露;不声称具有共指和通用混淆抵抗能力。
审查偏移量允许拥有原始输入的受信任本地客户端重建值;请将审查响应保留在本地。
宿主行为和下游提供商行为不在信任边界内。
文件中记录的仓库安全设置仍需要管理员验证。
使用 SECURITY.md 私下报告漏洞。请勿在公共问题中放置漏洞详细信息或真实数据。
许可证
原始仓库源码和文档根据 Apache License 2.0 许可。版权归属记录在 NOTICE 中。第三方依赖和模型权重保留其自己的许可证。
Available Tools
6 toolsanalyze_textARead-onlyIdempotent
Inspect text locally and report detected sensitive content without producing sanitized output.
Use this when you need to understand what PII, secrets, or credentials are present (counts, entity types, and, with review/debug modes, positions) but do not need redacted text for transmission. The original text is not modified and no sanitized representation is returned. For a policy-approved, ready-to-send result use prepare_for_external_ai; for a sanitized file use create_safe_copy; for reversing a prior local session use restore_text.
Returns a JSON object with 'status' ('ok', 'review_required', or 'blocked'), 'policy', 'policy_version', 'policy_digest', 'counts' (entity-type tallies), and, when response_mode is 'review' or 'debug', a 'findings' list. 'debug' additionally returns 'debug_details'.
Inputs: text (required), policy, response_mode. Returns: object
create_safe_copyA
Sanitize text locally and write the approved result to a new file in the Safe Copies directory.
Use this when you need a sanitized on-disk copy (for storage, handoff, or archival) rather than an in-memory sanitized string. For the sanitized text only, use prepare_for_external_ai; for inspection-only use analyze_text; for reversing a prior session use restore_text.
Side effects: a new file is written to the directory set by SECUREDACT_SAFE_COPY_DIR. The supplied 'content' is not modified and no existing file is overwritten. The filename must be a bare '.txt' or '.md' basename (no path separators or directory traversal). The operation blocks and reports 'blocked' if the directory is unconfigured, the filename is invalid, or policy blocks the content.
Returns a JSON object with 'status' ('ok' or 'blocked'), 'filename', and 'counts'.
Inputs: content (required), filename (required), policy. Returns: object
prepare_for_external_aiARead-onlyIdempotent
Use this before sending user-supplied or potentially sensitive text to an external AI service.
SecuRedact inspects and sanitizes the text locally and returns the policy-approved representation; this tool does not transmit the text externally. It is the recommended default for outbound AI workflows. Use analyze_text for inspection-only classifications, redact_text for the lower-level compatibility path, create_safe_copy when a sanitized file is required, and restore_text only to reverse a prior local session in a trusted context.
Returns a JSON object with 'status' ('ok', 'review_required', or 'blocked'), 'sanitized_text' (present only when approved), 'counts', 'policy', and optionally 'restoration_session' (when response_mode is 'restore_capable').
Inputs: text (required), policy, language, response_mode. Returns: object
redact_textARead-onlyIdempotent
Direct/lower-level redaction entry point; prefer prepare_for_external_ai for normal outbound workflows.
In its normal modes this performs the same local sanitization as prepare_for_external_ai and returns the approved result, so most agents should call prepare_for_external_ai instead. Use redact_text when you specifically need this lower-level compatibility path, or the 'legacy' mode for local review of raw redaction internals. The 'legacy' mode returns potentially sensitive local-review details and is never selected by default.
Returns, for normal modes, the same approved result as prepare_for_external_ai (status, sanitized_text, counts). For 'legacy' mode it returns a result with deprecation_code 'legacy_sensitive_response' containing local-review redaction data.
Inputs: text (required), policy, response_mode. Returns: object
restore_textA
Reverse a prior SecuRedact protection step in a trusted, local-only context.
Use this ONLY after you previously received a restoration_session from SecuRedact (for example from prepare_for_external_ai with response_mode 'restore_capable') and now need to reconstruct the original text locally for trusted review. Restoration can reveal the original sensitive values (PII, secrets, credentials); it is a trusted-local operation, not a step to prepare data for external transmission. Never call it to sanitize or prepare text for an external AI; for that use prepare_for_external_ai. Never call it on text you did not previously protect with SecuRedact.
Security boundary: all processing is local and nothing leaves the machine. The 'mapping' form requires trusted_local_review=true and exposes raw originals, so its output must never be transmitted. Returns a JSON object with 'status' ('ok' or 'blocked'), 'restored_text' (present only on success), and 'reason_codes' describing any failure.
Inputs: text (required), mapping, restoration_session, trusted_local_review. Returns: object
securedact_read_fileARead-onlyIdempotent
Safely read a local file and return only its sanitized (PII/secrets removed) text.
Use this when you must ingest a local file's contents for use with an external AI but want path-traversal, size, and binary defenses plus sanitization applied first. If the content is already in memory, use prepare_for_external_ai; for a sanitized file on disk, use create_safe_copy.
Side effects: reads a file from local disk and never transmits it. Sensitive paths and escapes are blocked before any file content is read. The returned 'sanitized_text' is safe to forward.
Returns a JSON object with 'status' ('ok' or 'blocked'), 'path', and 'sanitized_text' (present only when approved).
Inputs: path (required), policy, max_bytes. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Most tools have clearly distinct outputs (in-memory text, file write, file read, inspection, restoration), but prepare_for_external_ai and redact_text perform identical sanitization in normal modes, with redact_text explicitly deferring to prepare_for_external_ai. This creates a potential misselection point despite the helpful cross-references.
The majority of tools follow a clean verb_noun pattern (analyze_text, redact_text, restore_text, create_safe_copy). prepare_for_external_ai and securedact_read_file deviate with a prepositional phrase and a brand prefix, but the overall naming remains readable and predictable.
Six tools is well within the ideal scope for a focused sanitization server. Each tool maps to a distinct workflow step, and none feel extraneous enough to bloat the surface.
The set covers the core lifecycle: inspection, in-memory sanitization, safe file output, safe file input, and session restoration. Minor gaps exist around policy management and the redundant redact_text path, but there are no critical dead ends for the stated purpose.
Maintenance
Related MCP Connectors
MCP gateway: one connection for your AI apps, with tool policies, PII redaction and audit logs.
MCP server for detecting and redacting PII (Personally Identifiable Information) in PDF documents.
Zero-secret MCP gateway for AI agents: risk-scored, audited calls with human-in-the-loop approval.
Scan prompts for injection attacks, redact PII, and audit LLM SDK usage from any MCP client
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA local, containerized MCP server that uses a local LLM to sanitize documents by removing or transforming PII before content is sent to public LLM services.MIT
- AlicenseAqualityCmaintenanceAn MCP server that redacts PII/PHI from text before it ever reaches an LLM — self-hosted, fail-closed, and HIPAA-aware.321 PyPIMIT
- AlicenseAqualityDmaintenanceMCP server providing on-prem PII detection and anonymization tools (scan and is_sensitive) for AI agents, ensuring data stays local.4MIT

omitly-mcpofficial
FlicenseAqualityBmaintenanceMCP server for local, verifiable PDF redaction. Enables AI agents to find sensitive regions, locate text, redact PDFs on-device, verify redaction and tamper-evidence seals, and generate PDFs—without uploading confidential documents.8365 npm-