A
licenseNot graded
qualityD
maintenanceA 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
securedact-mcp
by GigantesHJI
SecuRedact MCP
SecuRedact es una capa de privacidad y seguridad local-first para agentes de IA y flujos de trabajo de IA. Detecta y protege datos sensibles — datos personales / PII, información sensible según GDPR, credenciales, claves de API, tokens, secretos y archivos sensibles — antes de que esos datos lleguen a modelos, herramientas, archivos o destinos externos.
SecuRedact MCP es el servidor MCP de código abierto bajo Apache-2.0 y el motor de privacidad reutilizable en Python. Detecta texto sensible, aplica políticas versionadas, redacta localmente y valida la salida residual antes de marcar el contenido saneado como aprobado.
El modo MCP no intercepta automáticamente cada prompt. El host debe invocar la herramienta y enviar solo
sanitized_textcuandostatus == "ok"; un host MCP mal configurado o malicioso puede omitir ese flujo MCP normal. Los hooks forzados nativos del proveedor son activos de integración separados: cuando un proveedor compatible invoca dicho hook en el límite del ciclo de vida del prompt, puede aplicar la misma decisión determinista antes del procesamiento normal del modelo. Consulte SecuRedact Enforced.
Por qué SecuRedact
Los agentes de IA cada vez leen más archivos, llaman a herramientas y envían prompts a modelos externos. Eso expone PII, credenciales y documentos sensibles a menos que algo verifique los datos primero. SecuRedact es un control de privacidad y seguridad para flujos de trabajo de IA:
Local-first — toda la detección, redacción y evaluación de políticas se ejecutan en su máquina. Sin listener de red por defecto, sin telemetría, sin llamadas a proveedores.
Detección de PII / GDPR — nombres, correos electrónicos, IBANs, identificadores y datos de categorías especiales se detectan y se seudonimizan o redactan.
Protección de secretos y credenciales — claves de API, tokens y contraseñas se detectan y se bloquean para que no salgan de su entorno.
Protección del sistema de archivos — las lecturas están protegidas contra escapes de traversal/symlink y se bloquean rutas protegidas como
.env.Firewall de privacidad para agentes de IA — los hooks forzados para Claude Code y Gemini CLI ejecutan la misma decisión local antes de que un prompt, una llamada al modelo o una acción de herramienta continúe.
Conciencia de red / egress — las llamadas a herramientas salientes se clasifican (internas/externas/desconocidas) para que la política pueda requerir aprobación o bloquear el egress.
SecuRedact ayuda a reducir la exposición de datos sensibles; no es una garantía de cumplimiento ni una afirmación de que se previene cada fuga. Consulte Limitaciones.
Related MCP server: phi-redact-mcp
Inicio rápido
Instale desde PyPI y ejecute la configuración guiada (Windows):
py -3.12 -m pip install "securedact-mcp[ml]"
securedact-mcp setupLinux / macOS:
python3.12 -m pip install "securedact-mcp[ml]"
securedact-mcp setupProteja un fragmento de texto en segundos (demo solo determinista, sin necesidad de modelo):
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]"Demostraciones de seguridad sintéticas reproducibles: docs/distribution/security-demo.md.
Flujo de trabajo seguro por defecto
Use prepare_for_external_ai para la preparación normal para IA externa:
{
"text": "Contact alex@example.test",
"policy": "strict_external_ai",
"language": "auto",
"response_mode": "minimal"
}Respuesta aprobada:
{
"schema_version": "1",
"status": "ok",
"sanitized_text": "Contact [EMAIL_1]",
"counts": {"email": 1},
"policy": "strict_external_ai",
"policy_version": 1,
"policy_digest": "...",
"reason_codes": []
}Las respuestas review_required y blocked nunca contienen sanitized_text aprobado. Las respuestas mínimas no contienen texto original, valores de entidades sin procesar, mapeo, cuerpo de excepción, traza de pila, ruta de modelo o identificador de restauración a menos que se haya seleccionado explícitamente restore_capable.
Arquitectura y límite de confianza
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" .-> WEl servidor no tiene clientes de proveedores, proxy compatible con OpenAI, proxy inverso, sitio web, chatbot de escritorio, credenciales de proveedores ni reenvío específico de proveedores. Consulte ADR 0001 y el modelo de amenazas.
Herramientas
Herramienta | Uso previsto | Comportamiento de respuesta sensible |
| Flujo de trabajo seguro completo recomendado | Mínimo por defecto |
| Análisis/revisión local de nivel inferior | Mínimo; desplazamientos en |
| Operación de compatibilidad de nivel inferior | Mínimo por defecto; el modo |
| Consumir una sesión opaca local | De un solo uso por defecto; los mapeos directos requieren modo legacy confiable explícito |
| Escribir contenido aprobado | No devuelve mapeo ni ruta absoluta |
| Leer un archivo local de forma segura y devolver solo texto saneado | Bloquea rutas protegidas antes de leer; rechaza traversal/symlink/binario; |
Los modos de respuesta son minimal, review, debug y restore_capable. La depuración está deshabilitada a menos que el proceso se haya iniciado con SECUREDACT_ENABLE_DEBUG_RESPONSES=1; una solicitud MCP no puede habilitarla. Las sesiones de restauración en memoria usan identificadores aleatorios criptográficos, capacidad limitada, expiración, protección de concurrencia y consumo de un solo uso. La salida del proceso destruye todas las sesiones.
Consulte Herramientas MCP, privacidad de respuestas y sesiones de restauración.
Instalación
Se admite Python >=3.12,<3.13.
Para una instalación normal desde PyPI:
py -3.12 -m pip install "securedact-mcp[ml]"
securedact-mcp setupEn Linux o macOS, use python3.12 -m pip install "securedact-mcp[ml]"; python -m pip install "securedact-mcp[ml]" también es apropiado cuando python ya selecciona un entorno 3.12 compatible.
setup verifica el paquete, las dependencias de Python y ML, inspecciona el estado del modelo local, ofrece el instalador de modelos existente basado en consentimiento, ejecuta el verificador offline existente y ofrece las integraciones empaquetadas de Claude Code y Gemini CLI cuando se detectan esos hosts. Usa los comandos oficiales de plugin/extensión de los proveedores y es seguro volver a ejecutarlo. No llama a una API de modelo de proveedor, no acepta confianza de proveedor automáticamente ni descarga un modelo contextual a menos que el usuario seleccione explícitamente la configuración del modelo y acepte el prompt ascendente existente.
Los comandos manuales de modelo siguen disponibles para operación avanzada o desatendida:
securedact-mcp install
securedact-mcp models verify
securedact-mcpEl último comando inicia un servidor stdio local. La salida estándar está reservada para mensajes de protocolo MCP. securedact-mcp setup --non-interactive informa el estado sin implicar aceptación ascendente ni configurar un nuevo proveedor. Use --host claude, --host gemini o --host all para configuración interactiva dirigida del proveedor.
Instalación para desarrolladores / desde el código fuente
Para trabajar desde un checkout de código fuente revisado en su lugar:
git clone https://github.com/GigantesHJI/securedact-mcp.git
cd securedact-mcp
python -m pip install ".[ml]"
securedact-mcp setupNo se incluye ningún checkpoint de modelo en el repositorio ni en el wheel, y el inicio nunca descarga uno. Securedact no redistribuye estos pesos de modelo. Los pesos de modelo ascendentes conservan sus propias licencias y no se vuelven a licenciar bajo Apache-2.0. Consulte instalación de modelos y licencias de terceros.
El desarrollo local solo determinista debe seleccionarse explícitamente:
$env:SECUREDACT_REQUIRE_FLAIR = "0"
securedact-mcpLa producción por defecto requiere capacidad contextual y falla de forma cerrada mientras un modelo configurado falta, se está cargando, está corrupto o no está disponible.
Paquetes de host
Los activos de configuración probados y las instrucciones de flujo de trabajo seguro están en integrations/ para Codex, Cursor y Windsurf. El arnés automatizado de cliente MCP valida el inicio del servidor, el listado de herramientas, las llamadas, la forma mínima de respuesta, la integridad de stdout y el apagado. No demuestra que un host real invoque la herramienta para cada prompt. Consulte la evidencia de compatibilidad.
El repositorio también es una raíz de extensión de Gemini CLI: gemini extensions install https://github.com/GigantesHJI/securedact-mcp puede instalar los hooks. El tema gemini-cli-extension y una versión cuyo árbol de etiquetas contenga el manifiesto raíz son necesarios para que esa ruta se resuelva; sin pip install "securedact-mcp[ml]" y los modelos locales, los hooks instalados no aplican nada. Consulte SecuRedact Enforced.
Políticas y API de Python
Los integrados incluyen default, strict_external_ai, gdpr, identifiers_only y review_all_contextual; las políticas de compatibilidad siguen disponibles. Los archivos de política de organización local se cargan solo desde el directorio de políticas controlado, usan un esquema declarativo estricto y no pueden deshabilitar invariantes de fallo cerrado. Las políticas desconocidas, duplicadas, sobredimensionadas, malformadas o con symlink fallan de forma cerrada.
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() conserva el requisito de modelo contextual. El desarrollo determinista independiente requiere SECUREDACT_REQUIRE_FLAIR=0; las aplicaciones también pueden inyectar implementaciones de detectores probadas. Consulte API pública y políticas.
Desarrollo reproducible
El uv.lock confirmado resuelve extras de runtime, ML, desarrollo, benchmark y seguridad para Python 3.12.
uv sync --frozen --extra dev --extra benchmark
uv run python scripts\verify.pyNunca use información personal real, documentos privados, credenciales, registros de clientes o pesos de modelo en pruebas, issues, capturas de pantalla, fixtures o pull requests. Consulte CONTRIBUTING.md.
Evaluación y rendimiento
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 deterministicEl corpus sintético versionado informa precisión de span exacta y relajada, recall, F1, tasas de falsos positivos y falsos negativos, resultados por entidad/idioma/dominio/división, precisión de acción/categoría e intervalos de recall bootstrap. Los verdaderos negativos son ejemplos negativos a nivel de documento, no seguridad a nivel de token. El conjunto relacionado con GDPR es evaluación de detección, no certificación de cumplimiento legal. Los benchmarks reales de Flair y GPU requieren un modelo local configurado explícitamente y no son CI ordinario. Consulte benchmarking. El marco de benchmark documenta los niveles de datos locales y los perfiles grandes; el plan de migración define su límite de extracción futuro. Para un fallo antes de que GitHub ejecute los pasos del repositorio, use el árbol de decisión de solución de problemas de CI. El éxito local no reemplaza una verificación de GitHub requerida.
Seguridad y limitaciones
Ningún prompt, hallazgo, mapeo, identificador de restauración, secreto, entrada de modelo o salida restaurada se registra mediante código de aplicación.
La detección determinista y contextual puede omitir divulgación novedosa, ambigua o adversarial; no se afirma resistencia a la correferencia ni a la ofuscación universal.
Los desplazamientos de revisión permiten que un cliente local confiable con la entrada original reconstruya un valor; mantenga las respuestas de revisión locales.
El comportamiento del host y el comportamiento del proveedor posterior están fuera del límite de confianza.
La configuración de seguridad del repositorio documentada en archivos aún requiere verificación por parte del administrador.
Reporte vulnerabilidades de forma privada usando SECURITY.md. No ponga detalles de vulnerabilidad ni datos reales en un issue público.
Licencia
El código fuente y la documentación originales del repositorio están bajo la Licencia Apache 2.0. La atribución de derechos de autor se registra en NOTICE. Las dependencias de terceros y los pesos de modelo conservan sus propias licencias.
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'.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Free text to inspect locally for sensitive content. Processing is on this machine only; the original text is never modified or transmitted. | |
| policy | No | Named analysis policy controlling which detectors and entity types apply. Defaults to 'default'. Common values include 'default'; other policies may be registered in your environment. An unknown name returns a policy_not_found error. | default |
| response_mode | No | Level of detail returned. 'minimal' returns only status and entity-type counts; 'review' additionally returns a 'findings' list with spans and entity types; 'debug' additionally returns 'debug_details' (only when debug responses are enabled). Defaults to 'minimal'. | minimal |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool read-only and idempotent, and the description adds valuable context: the original text is not modified, no sanitized representation is returned, processing is local, and response modes change the output. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured into overview, usage guidance, and return contract. It is slightly longer than minimal but every sentence earns its place, and the core purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only analysis tool, the description is complete: it covers what it does, when to use it, alternatives, side-effect behavior, response modes, and return shape. The output schema also exists, so the description does not need to over-explain returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds extra value by clarifying response_mode behavior and the policy_not_found error case, going beyond the schema without repeating it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Inspect text locally and report detected sensitive content without producing sanitized output.' This immediately distinguishes it from redaction/export tools and makes the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use the tool ('when you need to understand what PII, secrets, or credentials are present... but do not need redacted text') and names alternatives for other needs: prepare_for_external_ai, create_safe_copy, and restore_text. This gives an agent clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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'.
| Name | Required | Description | Default |
|---|---|---|---|
| policy | No | Named redaction policy applied before writing. Defaults to 'strict_external_ai'. An unknown name returns a policy_not_found error. | strict_external_ai |
| content | Yes | Text to sanitize locally and write to disk. Processed on this machine; never transmitted. | |
| filename | Yes | Bare target filename (no directory components) ending in '.txt' or '.md'. The file is created inside the configured Safe Copies directory; an existing file is never overwritten. |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by disclosing concrete side effects: writes to SECUREDACT_SAFE_COPY_DIR, never modifies the supplied content, never overwrites existing files, requires a bare '.txt' or '.md' filename, and blocks/reports 'blocked' on unconfigured directory, invalid filename, or policy failure. It also specifies the return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short paragraphs are used: purpose in the first sentence, usage guidance in the second, and side effects/return in the third. Every sentence earns its place and the description is front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the side-effecting nature of the tool, the description covers the operation, side effects, blocking/failure conditions, and return format. Combined with the rich output schema and annotations, an agent has all necessary information to invoke it correctly and safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters with detailed descriptions (100% coverage), so the description's restatements such as 'content is not modified' and 'bare target filename' add little new meaning. The baseline of 3 applies; the description does not need to compensate for missing schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Sanitize text locally and write the approved result to a new file in the Safe Copies directory.' It explicitly contrasts this with in-memory sanitization and names sibling tools for alternative use cases, so an agent can distinguish it immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit 'Use this when' condition (need a sanitized on-disk copy for storage, handoff, or archival) and names three sibling tools with their respective conditions: prepare_for_external_ai for sanitized text only, analyze_text for inspection-only, and restore_text for reversing a prior session. This is clear decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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').
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Free text to inspect and sanitize locally before it is sent to an external AI service. All processing happens on this machine; this tool never transmits the text to any provider. | |
| policy | No | Named redaction policy controlling which entity types are masked or blocked. Defaults to 'strict_external_ai'. Common values include 'strict_external_ai' and 'default'; other policies may be registered in your environment. An unknown name returns a policy_not_found error. | strict_external_ai |
| language | No | Hint for the contextual detection language. One of 'auto' (detect automatically), 'en', or 'nl'. Defaults to 'auto'. | auto |
| response_mode | No | Amount of detail returned. 'minimal' returns only the approved result and counts; 'review' adds per-detection findings for human review; 'debug' adds engine internals (only when debug responses are enabled); 'restore_capable' additionally returns a local restoration_session for later trusted restore_text. Defaults to 'minimal'. | minimal |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows the safety profile. The description adds valuable context: it explicitly states that the tool does not transmit text externally and that processing is local. It also discloses that unknown policy names return a policy_not_found error and describes the response structure (status field with values). This goes beyond annotations to explain operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is focused and well-structured. It opens with a clear directive and then alternates between contrasts and return-format details. Every sentence adds value, and the return format is clearly specified. It loses one point for being slightly longer than necessary, but it is still quite efficient with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is moderately complex with 4 optional parameters and an output schema, so the description does not need to explain return values in detail. It covers key aspects: what it does, when to use it, distinctions from siblings, policy parameter semantics, and the response_mode conditional field. It does not mention rate limits or auth, but given the annotations indicate a safe read-only operation and the schema is fully documented, a 4 is appropriate for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds significant parameter semantics beyond the schema: it explains the 'policy' parameter with default value and common values, warns about unknown policies causing errors; it clarifies 'response_mode' values including 'restore_capable' and mentions the conditional 'restoration_session' field in the output. It also explains 'language' options globally. This enriches parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a clear directive: 'Use this before sending user-supplied or potentially sensitive text to an external AI service.' It specifies the action ('inspects and sanitizes'), the resource ('text'), and the local scope ('does not transmit the text externally'). It names its siblings and contrasts with them, making it easy to distinguish from alternatives like analyze_text and redact_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use it ('before sending... to an external AI service') and what it is not for. It enumerates alternative tools by name and explains their different purposes: '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.' This gives clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Free text to redact locally. Processing is on this machine; nothing is transmitted externally. | |
| policy | No | Named redaction policy controlling which entity types are masked or blocked. Defaults to 'default'. Common values include 'default' and 'strict_external_ai'; other policies may be registered. An unknown name returns a policy_not_found error. | default |
| response_mode | No | Normal modes behave like prepare_for_external_ai: 'minimal', 'review', and 'debug' return the approved result with increasing detail. The special value 'legacy' returns raw local-review redaction internals (including a mapping that reveals original values) under deprecation_code 'legacy_sensitive_response'; it must never be sent to an external service. Defaults to 'minimal'. | minimal |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the annotations, noting that normal modes return the same approved result as prepare_for_external_ai and that 'legacy' mode returns sensitive local-review details under a deprecation_code and must never be sent externally. This complements the readOnlyHint and idempotentHint annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized and front-loaded with the most critical routing guidance: prefer prepare_for_external_ai. Each paragraph earns its place, covering normal modes, legacy mode caveats, and return behavior without unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and the annotations cover read-only, idempotent, non-destructive behavior, the description provides sufficient context for selecting and invoking the tool correctly. It explains when to use it, what modes exist, and the sensitive nature of legacy output, leaving no critical gap for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all parameters well. The description reinforces the response_mode semantics and legacy sensitivity but does not add substantial new meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies redact_text as a lower-level redaction entry point and contrasts it with prepare_for_external_ai, stating that it performs the same local sanitization in normal modes. It also specifies the distinct 'legacy' mode purpose, making its role unambiguous relative to sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells agents to prefer prepare_for_external_ai for normal outbound workflows and to use redact_text only when needing the lower-level compatibility path or 'legacy' mode for local review. This gives clear when-to-use and when-not-to-use guidance, directly addressing the main alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Text containing SecuRedact placeholders (or a prior protected representation) to restore. Processed locally; never transmitted. | |
| mapping | No | Legacy direct mapping from placeholder token to original value. Supplying this bypasses the session vault and immediately reveals the original sensitive values. It is only honored when 'trusted_local_review' is true and 'restoration_session' is omitted. | |
| restoration_session | No | Opaque session token previously returned by SecuRedact (for example from prepare_for_external_ai with response_mode 'restore_capable'). It identifies the trusted local vault entry used to reverse protection and recover the original values. Required unless you supply 'mapping' together with trusted_local_review. | |
| trusted_local_review | No | Explicit acknowledgment that you are in a trusted local review context and accept that restoration reveals original sensitive values. Required (true) to use the 'mapping' form. It has no effect on the 'restoration_session' form. |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations carry almost no signal (all hints false), so the description bears full responsibility for behavioral disclosure, and it delivers: local-only processing, that restored values are raw PII/secrets never to be transmitted, that the mapping form bypasses the session vault, and the exact response contract (status, restored_text, reason_codes). This goes well beyond what the annotations provide and directly informs safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded and the structure flows from what-it-does to when-to-use to security boundary to return format. It is somewhat longer than necessary — the mapping/trusted_local_review constraint is stated both in the description and in the schema — but the repeated security warnings are justified given the sensitivity of restored data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and 100% parameter coverage, the description needs only to add selection and safety context, which it does thoroughly. An agent has everything needed to decide when to call it, which parameters to supply, what security posture to assume, and what the response will contain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3; the description raises it by explaining the two mutually exclusive invocation forms (restoration_session vs mapping + trusted_local_review) and adding the security consequence of the mapping form. It adds semantic cohesion among the parameters that the schema's individual field descriptions do not provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Reverse a prior SecuRedact protection step') and clearly frames the operation as trusted-local reconstruction. It also differentiates itself from the key sibling by explicitly naming prepare_for_external_ai as the tool for the opposite direction, so an agent can disambiguate without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage conditions are explicit: call it only after receiving a restoration_session from a prior SecuRedact step, never to sanitize data, and never on text not previously protected. It names the alternative tool (prepare_for_external_ai) and states the exact precondition ('restore_capable'), leaving no ambiguity about when this tool applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Local filesystem path to read. It is resolved and defended against path traversal, symlink/UNC escapes, and oversized or binary content (FW-011/012/013); sensitive paths are blocked before any file content is read. | |
| policy | No | Named redaction policy applied to the file contents. Defaults to 'strict_external_ai'. An unknown name returns a policy_not_found error. | strict_external_ai |
| max_bytes | No | Optional cap on the number of bytes read from the file. When omitted, the engine's configured size limit applies. |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A4.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful context beyond those: side effects ('reads a file from local disk and never transmits it'), defense ordering ('Sensitive paths and escapes are blocked before any file content is read'), and return safety ('sanitized_text is safe to forward'). This aligns with and complements the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then usage guidance, then side effects. It is moderately sized and each sentence earns its place, though the three-paragraph structure could be tightened slightly without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is an output schema, and the description still gives a concise summary of return fields (status, path, sanitized_text) and edge cases (blocked/ok). It covers when to use the tool, alternatives, side effects, and defense guarantees. With schema and annotations carrying the rest, nothing an agent needs to invoke or react to this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (path, policy, max_bytes) already described with details about defenses and defaults. The description adds no additional parameter-level semantics, so the baseline of 3 is appropriate—it doesn't degrade or enhance schema-provided meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: 'Safely read a local file and return only its sanitized (PII/secrets removed) text.' It explicitly differentiates from siblings by naming prepare_for_external_ai and create_safe_copy, so an agent can distinguish it without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use: '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.' It also provides concrete when-not and alternatives: 'If the content is already in memory, use prepare_for_external_ai; for a sanitized file on disk, use create_safe_copy.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
6 tool updates
v0.4.2- Changed
analyze_text3 fields changed- added
Input schema / properties / policy / descriptionAdded value: +"Named analysis policy controlling which detectors and entity types apply. Defaults to 'default'. Common values include 'default'; other policies may be registered in your environment. An unknown name returns a policy_not_found error." - added
Input schema / properties / response_mode / descriptionAdded value: +"Level of detail returned. 'minimal' returns only status and entity-type counts; 'review' additionally returns a 'findings' list with spans and entity types; 'debug' additionally returns 'debug_details' (only when debug responses are enabled). Defaults to 'minimal'." - added
Input schema / properties / text / descriptionAdded value: +"Free text to inspect locally for sensitive content. Processing is on this machine only; the original text is never modified or transmitted."
- Changed
create_safe_copy3 fields changed- added
Input schema / properties / content / descriptionAdded value: +"Text to sanitize locally and write to disk. Processed on this machine; never transmitted." - added
Input schema / properties / filename / descriptionAdded value: +"Bare target filename (no directory components) ending in '.txt' or '.md'. The file is created inside the configured Safe Copies directory; an existing file is never overwritten." - added
Input schema / properties / policy / descriptionAdded value: +"Named redaction policy applied before writing. Defaults to 'strict_external_ai'. An unknown name returns a policy_not_found error."
- Changed
prepare_for_external_ai4 fields changed- added
Input schema / properties / language / descriptionAdded value: +"Hint for the contextual detection language. One of 'auto' (detect automatically), 'en', or 'nl'. Defaults to 'auto'." - added
Input schema / properties / policy / descriptionAdded value: +"Named redaction policy controlling which entity types are masked or blocked. Defaults to 'strict_external_ai'. Common values include 'strict_external_ai' and 'default'; other policies may be registered in your environment. An unknown name returns a policy_not_found error." - added
Input schema / properties / response_mode / descriptionAdded value: +"Amount of detail returned. 'minimal' returns only the approved result and counts; 'review' adds per-detection findings for human review; 'debug' adds engine internals (only when debug responses are enabled); 'restore_capable' additionally returns a local restoration_session for later trusted restore_text. Defaults to 'minimal'." - added
Input schema / properties / text / descriptionAdded value: +"Free text to inspect and sanitize locally before it is sent to an external AI service. All processing happens on this machine; this tool never transmits the text to any provider."
- Changed
redact_text3 fields changed- added
Input schema / properties / policy / descriptionAdded value: +"Named redaction policy controlling which entity types are masked or blocked. Defaults to 'default'. Common values include 'default' and 'strict_external_ai'; other policies may be registered. An unknown name returns a policy_not_found error." - added
Input schema / properties / response_mode / descriptionAdded value: +"Normal modes behave like prepare_for_external_ai: 'minimal', 'review', and 'debug' return the approved result with increasing detail. The special value 'legacy' returns raw local-review redaction internals (including a mapping that reveals original values) under deprecation_code 'legacy_sensitive_response'; it must never be sent to an external service. Defaults to 'minimal'." - added
Input schema / properties / text / descriptionAdded value: +"Free text to redact locally. Processing is on this machine; nothing is transmitted externally."
- Changed
restore_text4 fields changed- added
Input schema / properties / mapping / descriptionAdded value: +"Legacy direct mapping from placeholder token to original value. Supplying this bypasses the session vault and immediately reveals the original sensitive values. It is only honored when 'trusted_local_review' is true and 'restoration_session' is omitted." - added
Input schema / properties / restoration_session / descriptionAdded value: +"Opaque session token previously returned by SecuRedact (for example from prepare_for_external_ai with response_mode 'restore_capable'). It identifies the trusted local vault entry used to reverse protection and recover the original values. Required unless you supply 'mapping' together with trusted_local_review." - added
Input schema / properties / text / descriptionAdded value: +"Text containing SecuRedact placeholders (or a prior protected representation) to restore. Processed locally; never transmitted." - added
Input schema / properties / trusted_local_review / descriptionAdded value: +"Explicit acknowledgment that you are in a trusted local review context and accept that restoration reveals original sensitive values. Required (true) to use the 'mapping' form. It has no effect on the 'restoration_session' form."
- Added
securedact_read_file
5 tool updates
v0.2.0- Changed
analyze_text1 field changed- added
Input schema / properties / response_modeAdded value: +{ + "default": "minimal", + "title": "Response Mode", + "type": "string" +}
- Changed
create_safe_copy1 field changed- changed
Input schema / properties / policy / defaultPrevious value: -"default"New value: +"strict_external_ai"
- Added
prepare_for_external_ai - Changed
redact_text1 field changed- added
Input schema / properties / response_modeAdded value: +{ + "default": "minimal", + "title": "Response Mode", + "type": "string" +}
- Changed
restore_text11 fields changed- removed
Input schema / properties / mapping / additionalPropertiesRemoved value: -{ - "type": "string" -} - added
Input schema / properties / mapping / anyOfAdded value: +[ + { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + { + "type": "null" + } +] - added
Input schema / properties / mapping / defaultAdded value: +null - removed
Input schema / properties / mapping / typeRemoved value: -"object" - added
Input schema / properties / restoration_sessionAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Restoration Session" +} - added
Input schema / properties / trusted_local_reviewAdded value: +{ + "default": false, + "title": "Trusted Local Review", + "type": "boolean" +} - changed
Input schema / requiredPrevious value: -[ - "text", - "mapping" -]New value: +[ + "text" +] - added
Output schema / additionalPropertiesAdded value: +true - removed
Output schema / propertiesRemoved value: -{ - "result": { - "title": "Result", - "type": "string" - } -} - removed
Output schema / requiredRemoved value: -[ - "result" -] - changed
Output schema / titlePrevious value: -"restore_textOutput"New value: +"restore_textDictOutput"
4 tool updates
v0.1.0- First observed
analyze_text - First observed
create_safe_copy - First observed
redact_text - First observed
restore_text
TDQS
A4.5/5.0
Scored across 6 tools
Disambiguation4/5
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.
Naming Consistency4/5
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.
Tool Count5/5
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.
Completeness4/5
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
ActivitySlowing
ResponsivenessNo recent community issues
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
- AlicenseAqualityCmaintenanceAn MCP server that redacts PII/PHI from text before it ever reaches an LLM — self-hosted, fail-closed, and HIPAA-aware.322 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.8576 npm-