obsify

让AI助手处理敏感文件，而原始值永远不会进入模型上下文。

obsify是一个本地、确定性的MCP服务器。前沿模型基于形状（模式、合成孪生、掩码反馈）进行推理，而确定性的本地代码处理实质内容，仅返回掩码后的聚合结果。无LLM调用，运行时无网络：检测基于正则表达式+校验和+字典+Presidio的本地NER。

它内置澳大利亚实体支持（ABN / ACN / TFN，校验和验证）和一个基于标签的路由层，使“助手何时应避免原始数据”成为一个确定性、强制执行的决策，而非主观判断。

诚实范围： run_on_real 在尽力而为的本地沙箱中执行模型编写的代码，并尽力而为地掩码其输出。它不是牢不可破的。在将其指向任何你无法承受泄露风险的内容之前，请阅读SECURITY.md。返回聚合结果。

为什么

将机密文档提供给托管LLM意味着实质内容离开了你的边界。通常的答案是“不使用LLM”或“信任提供商”。obsify采取了第三条路径——计算到数据：将代码带到数据处，而不是将数据带到模型处。

• 模型看到电子表格的模式，而不是其行。

• 模型针对合成孪生（伪造的值，真实的结构）进行开发。

• 模型的分析代码本地运行；仅返回掩码后的聚合输出。

前沿模型的推理能力得以保留。只是它对原始值的查看被移除了。

Related MCP server: Cloakbox

工具

支持的文档： PDF（文本+表格；复杂表格回退通过obsify[tables]），Excel .xlsx/.xlsm，以及Word .docx（段落+表格）。无法读取或不支持的文件会作为明确的注释/盲点呈现，绝不会静默丢弃。（尚无OCR——扫描/图像页面会被标记为低覆盖率，而非转录。）

已知实体掩码（可选）。 提供一个本地的.obsify.entities列表，包含要隐藏的名称；scan_pii / redact_text 确定性地捕获它们——以及NER遗漏的后缀/缩写变体（BRIGHTWATER HLDGS P/L 代表 Brightwater Holdings Pty Ltd）——作为KNOWN_ENTITY。该列表保持本地，永远不会进入模型上下文。参见docs/known_entities.md。

演示

使用官方的MCP Inspector 针对合成数据实时操作所有五个工具：

python -m obsify.make_corpus --out ./corpus_demo
npx @modelcontextprotocol/inspector obsify-mcp

对./corpus_demo/ledger.xlsx调用scan_pii，确认它仅返回类型/计数/位置——绝不包含值。参见docs/verifying.md。

试试看——合成语料库

生成一个伪造但逼真的语料库（全部合成；ABN/ACN/TFN经过校验和验证），涵盖所有三种格式，然后将工具指向它：

pip install "obsify[demo]"                 # reportlab, for the sample PDFs
python -m obsify.make_corpus --out ./corpus_demo

它会写入一个多工作表Excel分类账（数字误报雷区）、一个PDF聘书（散文+试算平衡表）和一个DOCX审计备忘录（段落+供应商表）。非常适合在不接触真实数据的情况下试用scan_pii / make_synthetic_twin。

安装并作为MCP服务器运行

需要Python 3.11+。obsify通过stdio与MCP通信——客户端将其作为本地子进程启动；没有任何内容远程托管。通过向客户端配置添加一个块，将其注册到任何支持MCP的客户端（Claude Desktop、Claude Code、Cursor、VS Code等）。

推荐——通过uvx零安装：

{ "mcpServers": { "obsify": { "command": "uvx", "args": ["obsify-mcp"] } } }

uvx从PyPI获取obsify并按需运行——无需永久安装。在首次运行时，obsify会下载spaCy NER模型（en_core_web_lg，约560 MB）一次并缓存；这会获取一个公共模型，不发送任何用户数据（设置OBSIFY_AUTO_DOWNLOAD=0可禁止此行为并自行安装模型）。后续运行即时完成且完全离线。

或者安装它（pip / pipx）：

pipx install obsify        # isolated, on PATH  (or: pip install obsify)

然后将客户端指向已安装的命令：

{ "mcpServers": { "obsify": { "command": "obsify-mcp" } } }

重启客户端，工具就会出现。可选附加组件：obsify[tables]（通过camelot + Ghostscript实现复杂表格PDF回退），obsify[compute]（pandas，在run_on_real代码中很方便）。

PATH陷阱（“服务器无法连接”的头号原因）： command 必须在客户端看到的PATH上可解析。GUI客户端可能不共享你的venv的PATH。修复方法：使用uvx/pipx（全局可解析），或提供绝对路径——"/path/to/.venv/bin/obsify-mcp"（macOS/Linux）或"C:\\path\\.venv\\Scripts\\obsify-mcp.exe"（Windows）。

从此仓库（在它发布到PyPI之前）：

pip install "git+https://github.com/Formative-Sum41/obsify.git"   # gets `obsify-mcp` + `obsify`

路由层——确定性，而非主观判断

“帮助我，但不要读取机密文件”的难点在于决定何时保护。obsify将该决策从模型中移出，放入环境：

1. .obsify.json ——一个标签清单，对路径进行分类（public / confidential / restricted）。

2. obsify.guard （作为python -m obsify.guard运行）——一个PreToolUse守卫，阻止直接读取带标签的文件（退出码2），并将助手重定向到scan_pii / make_synthetic_twin / run_on_real。

3. 一个约定（在CLAUDE.md中），使助手在遇到守卫之前优先使用obsify。

通过一个命令设置：

obsify init [--dir PATH] [--with-claude-md]

obsify init 设计为非破坏性——它只拥有一个文件，并为你提供其余部分的代码片段：

• .obsify.json ——obsify拥有此文件；init写入它（没有--force则永远不会覆盖）。

• .claude/settings.json ——你的文件：init 打印要粘贴的PreToolUse钩子块，从不编辑它（它运行代码，因此注册它是你的决定）。

• CLAUDE.md ——你的文件：约定是选择加入。默认打印；--with-claude-md 会追加一个标记包裹的、幂等的块，绝不会破坏你的内容。

完整约定：docs/obsify_routing.md。

检测如何保持精确

• 校验和验证的标识符。 ABN/ACN/TFN候选者由正则表达式提出，并由其官方校验和确认，因此随机数永远不会被报告为标识符。

• 需要上下文的ID。 仅当附近有标签词（“TFN”、“ABN”、“BSB”等）时，裸数字才被接受为ABN/ACN/TFN——这消除了数字分类账上顺序日记账ID的误报洪流。

• 无字母 / 带数字的NER抑制。 纯数字、金额、日期和字母数字代码不会被标记为名称/组织；真实的名称、电子邮件和地址（包含字母）不受影响。经过验证的无字母PII保持豁免：校验和ID（ABN/ACN/TFN/Medicare）、Luhn卡、有效IP、BSB相邻账户和电话号码（通过上下文或电话号码形状）——而小数点仍标记为金额，而非电话号码。

测量精度

obsify附带一个评分评估工具（eval/——带标签的合成语料库+答案键+针对发布版检测器的评分器，外加一个独立的第三方交叉检查）。合成语料库的总体指标：100%召回率（预期检测项），0个误报（在数字FP折磨表上，带有分组数字守卫），裸上下文门控ID被正确抑制。独立交叉检查与Microsoft presidio-research：EMAIL/IBAN 100%，PERSON 94%。

该工具证明了其价值——它发现了真实的缺陷，这些缺陷随后被修复： 信用卡和电话号码被数字噪声过滤器静默抑制（现在通过校验和验证/电话号码形状豁免），而Medicare、IP、出生日期、澳大利亚护照和驾照没有识别器（现已添加，通过校验和或上下文门控）。完整方法、数字和剩余已记录的差距（SWIFT/BIC，非DOB日期）：eval/README.md。

测试

pip install -e ".[dev]"
pytest tests/            # or run any file directly: python tests/test_obsify.py

十二个套件（73个测试），在CI上针对Linux + Windows / Python 3.11 + 3.12运行：

• mcp-protocol ——通过stdio启动真实服务器并与MCP通信（与Claude等客户端使用的路径相同）：确认所有五个工具都注册了有效的模式，并且调用通过JSON-RPC往返——包括scan_pii返回仅形状，端到端。

• checksums ——锚定到外部发布的ABN/ACN/TFN工作示例（有效和损坏），打破了生成器↔验证器的循环。

• obsify / twin / redaction ——隐私不变量：仅形状输出、无泄露孪生和失败关闭自检。

• precision ——误报抑制器在保留真实名称的同时消除数字分类账噪声。

• routing ——守卫的阻止/允许分类和obsify init的非破坏性契约。

• corpus ——合成PDF+Excel+DOCX语料库端到端：每种格式的检测、DOCX段落+表格提取以及每种格式的仅形状输出。

• evaluation ——作为回归门的评分工具（召回率、抑制、FP折磨、差距）。

• robustness ——优雅降级：损坏/过大/空/嵌套/不支持的输入永远不会崩溃，并且始终作为注释呈现。

• model / variants ——首次运行模型自动下载逻辑；verify_value_free背后的变体规范化。

有关交互式验证（MCP Inspector）和实时客户端最后一英里检查，请参见docs/verifying.md。

许可证

MIT——参见LICENSE。