Pii Shield

🛡️ PII Shield

Anonymize documents before Claude sees them. Restore real data after analysis.

______________________________________________________________________

MCP服务器 克劳德桌面 它在本地读取您的文档，用占位符替换所有个人数据( , ``等），并仅将匿名文本发送给Claude。经过分析，PII Shield将原始数据还原到最终文档中——完全在您的计算机上。 PII从不进入API。

Document ──> [PII Shield on your machine] ──> anonymized text ──> [Claude analyzes] ──> [PII Shield restores] ──> Result
              John Smith  → 
                                                   
 → John Smith
              Acme Corp.  →                                                           → Acme Corp.

v2.0.2是一个完整的Node.js重写版本。 原始Python产品仍然可用——请参阅 v1怎么了？ 在......下面

特性

||功能|详细信息| |:-:|---------|---------| | 🔒 | API中的零PII | anonymize_file 读取机器上的文档并仅返回文件路径+会话id。Claude从磁盘读取匿名文件-PII从不输入API请求。 | | 🧠 | GLiNER零样本NER | knowledgator/gliner-pii-base-v1.0 结束 onnxruntime-node + @xenova/transformers （钉扎三元组1.22.0，确定性 npm ci).处理ALL-CAPS、域名、多语言文本。没有Python，就没有PyTorch。 | | 👤 | Human in the Loop评论 |MCP Apps的iframe UI直接在Claude Desktop中呈现。删除误报，添加遗漏的实体——所有事件都会自动更新，无需绕过本地主机浏览器。 | | 📄 | PDF+DOCX+纯文本 | .pdf, .docx （保留格式化+跟踪更改）， .txt, .md, .csv纯JS .docx 管道——无需安装Word/LibreOffice即可进行读取、编辑和恢复。 | | 🇪🇺 | 17个欧盟+英国模式识别器 |英国（NIN、NHS、护照、CRN、驾驶执照）、DE（税务ID、社会保障）、FR（NIR、CNI）、IT（财政代码、增值税）、ES（DNI、NIE）、CY（TIC、身份证）、欧盟范围（增值税、护照）——在通用包（电子邮件、电话、IBAN、信用卡、加密货币、美国身份证、医疗执照）之上。共33种实体类型。 | | 🔗 | 实体重复数据删除 |“Acme”→ `“Acme公司”→ “Acme公司”→ .规范形式选择一次；每个变体在去匿名化上都映射回相同的真实值。 | | 💾 | **跨会话去匿名化** |每个匿名 .docx 携带其 session_id 在Word自定义属性中。几周后，在一个全新的聊天中，将文件放入并 deanonymize_docx 从嵌入的id中恢复PII——无需记忆。 | | 📦 | **多文件会话** |将N个相关文档匿名化 session_id；相同的实体在文件之间共享相同的占位符。一 deanonymize_text / deanonymize_docx 呼叫可以在任何地方恢复PII。 | | 🤝 | **团队交接** | export_session(passphrase) 将映射+匿名文档打包成加密文件 .pii-session 存档（通过scrypt的AES-GCM）。同事跑步 import_session 使用密码短语，PII永远不会传输。 | | 📊 | **审核日志记录** |每个工具调用+响应都记录在本地 ~/.pii_shield/audit/mcp_audit.log`.NER引导跟踪、会话生命周期、删除stderr——所有这些都在磁盘上、可追加、网络外|

快速开始

先决条件

• 克劳德桌面 （任何最新版本）
• Windows或Linux:Claude Desktop提供了一个兼容的Node运行时环境。无需单独安装。
• macOS：macOS .mcpb 下面捆绑了自己的Node 24.15.0。无需单独安装。

无终端命令。无需提前下载模型。 PII Shield通过您首次匿名时出现的面板处理聊天中的模型安装。

第一步——下载人工制品

选择 .mcpb 对于您的操作系统和技能包：

步骤2——安装MCP扩展

克劳德桌面→ 设置→ 扩展→ 高级设置→ 安装扩展 → 选择你的 .mcpb.

在第一个工具调用PII Shield时运行 npm ci --ignore-scripts 安装一组固定的、确定性的运行时deps(onnxruntime-node, @xenova/transformers, gliner)进入 ~/.pii_shield/deps/installs//每台机器2-3分钟一次，之后立即进行。

第三步——上传技能

克劳德桌面→ 定制→ 技能→ + → 上传技能 → 选择 pii-contract-analyze.skill.

该技能精心策划端到端的合同匿名化+分析流程——克劳德用它来驱动 anonymize_file → HITL评论→ 分析→ deanonymize_docx 没有你把每一步都拼出来。

第四步——使用它

1. 在Claude Desktop中启动新对话
2. 选择 pii合同分析 技能
3. 连接文件夹 包含您的文档（单击文件夹图标）
4. 告诉克劳德你需要什么：

Analyze risks for the purchaser in contract.pdf and prepare a short memo

首次运行安装面板

当你第一次要求Claude匿名化任何东西时，PII Shield注意到NER模型还没有在磁盘上，并打开了一个 在聊天安装面板中。您看到两个按钮：

1. 下载型号 --打开默认浏览器，下载 gliner-pii-base-v1.0.zip （约634 MB）。浏览器处理传输（未签名的脚本没有Defender/SmartScreen问题）。
2. 安装下载的ZIP --PII Shield在您的Downloads/OneDrive/Desktop/Documents文件夹中查找ZIP，验证它，并将其原子提取到 ~/.pii_shield/models/，并重新初始化NER。匿名化会自动继续。

没有终端，没有脚本。后续运行将完全跳过该面板。

⚠️ 不要将文件直接附加到匿名化。 当你附加一个文件时，Claude Desktop会在API请求中发送其内容——Claude会在PII Shield处理之前看到原始数据。 连接文件夹 相反，Claude只获取文件路径并调用 anonymize_file 当地。

隐私架构

仅 文件路径 和 随机会话ID 流经API。所有匿名化和恢复都在本地进行。

Human in the Loop评论

匿名化后，Claude提供了一个直接在Claude Desktop中呈现的审核步骤，通过 MCP应用程序:

1. 克劳德打电话来 start_review --Claude Desktop在对话中打开一个面板
2. 完整文档 颜色编码实体高亮显示
3. 删除误报 --单击任何实体（删除所有引用）
4. 添加遗漏的实体 --选择文本，选择类型（添加所有引用）
5. 批准 --克劳德打电话来 apply_review_overrides，服务器会根据您的更正重新匿名

无需本地主机web服务器，无需绕过浏览器——UI是一个Vite单文件iframe，作为Claude Desktop的 ui:// MCP资源。

跨会话去匿名化

每个匿名 .docx PII Shield写带有它的 session_id Word内部自定义文档属性(docProps/custom.xml).稍后，在全新的聊天中，您可以：

1. 删除匿名 .docx 放入一个连接的文件夹中——不需要记住会话id，没有占位符的屏幕截图，什么都不需要。
2. 请Claude“恢复此文件中的PII。”
3. PII盾牌 deanonymize_docx 读取嵌入式 session_id，在中查找映射 ~/.pii_shield/mappings/，并将恢复的文件写入输入旁边。

地图实时发布于 ~/.pii_shield/mappings/ --根相同 models/, deps/，以及 audit/根目录在插件升级后仍然有效 /plugin remove 因为它在用户的主目录中，而不是Claude Desktop的每个插件的目录中 CLAUDE_PLUGIN_DATA （无论如何，MCPB插件都没有设置）。

基于时间的TTL由以下控制 PII_MAPPING_TTL_DAYS （默认值： 7天)--服务器会清理比启动时更早的映射。用它来处理更长久的事情(PII_MAPPING_TTL_DAYS=90等）通过克劳德桌面→ 扩展→ PII屏蔽→ 设置。如果在尝试去匿名化时缺少映射， deanonymize_docx 返回一个干净的错误，并提示 import_session （请参阅下面的团队切换），而不是默默地跳过实体。

平原 .txt / .md 输出没有嵌入元数据的地方，因此 deanonymize_text 工具采取 session_id 明确地作为一个论点。

多文件会话

将多个相关文档匿名化 session_id:

1. 第一通电话： anonymize_file(path_A) --服务器返回 session_id=SID123.
2. 第二次通话： anonymize_file(path_B, session_id="SID123") --PII Shield扩展了相同的映射。两个文件中的相同实体共享 相同的占位符 (Acme Corp. 成为 `` 两者都有）。
3. 您在Claude中编写了一份备忘录，其中混合了两个文件中的占位符。
4. 一 deanonymize_text(..., session_id="SID123") 调用备忘录可以恢复各地的个人身份信息。

这 pii-contract-analyze 当用户上传N≥2个文件并确认它们属于一个事项时，技能会自动驱动此操作。看 plugin/skills/pii-contract-analyze/references/bulk-mode.md 对于完整的决策树。

团队交接——导出/导入会话

如果同事需要在不共享个人身份信息的情况下处理相同的文档：

1. 你打 export_session(session_id, passphrase) --服务器将映射+匿名文档打包成加密文件 .pii-session 存档（AES-GCM，密钥通过scrypt从密码中导出）。
2. 发送给他们 .pii-session 文件（电子邮件、Slack、拇指驱动器——没有密码就没用了）。
3. 他们叫 import_session(path, passphrase) 在他们的机器上——地图就在他们的脚下 ~/.pii_shield/mappings/ 他们现在可以 deanonymize_docx 当地。

PII永远不会在运输过程中留下匿名文件。存档格式已进行版本控制(.pii-session v1），因此未来的模式更改将保持可读性。

MCP工具

技能模式

包括 pii-contract-analyze 技能支持：

检测到的实体类型

权威列表为 nodejs-v2/src/engine/entity-types.ts (SUPPORTED_ENTITIES).

NER基础 （ONNX运行时上的GLiNER零样本）： PERSON, ORGANIZATION, LOCATION, NRP

基于通用模式: EMAIL_ADDRESS, PHONE_NUMBER, URL, IP_ADDRESS, ID_DOC, CREDIT_CARD, IBAN_CODE, CRYPTO, MEDICAL_LICENSE

美国: US_SSN, US_PASSPORT, US_DRIVER_LICENSE

英国: UK_NHS, UK_NIN, UK_PASSPORT, UK_CRN, UK_DRIVING_LICENCE

欧盟范围: EU_VAT, EU_PASSPORT

特定国家: DE_TAX_ID, DE_SOCIAL_SECURITY, FR_NIR, FR_CNI, IT_FISCAL_CODE, IT_VAT, ES_DNI, ES_NIE, CY_TIC, CY_ID_CARD

总共33种类型（4种NER+29种基于图案）。

日志

发展

所有代码都存在于 nodejs-v2/。从该目录：

# Install exact-pinned dev deps
npm ci --ignore-scripts --legacy-peer-deps

# Type-check
node node_modules/typescript/bin/tsc --noEmit

# Build the thin .mcpb (Windows / Linux + darwin via platform overrides)
npm run build:plugin

# Also build the darwin-universal .mcpb (downloads Node 24.15.0 arm64 + x64)
npm run build:plugin:mac

# MCP protocol smoke test
npm run smoke

# Focused clean-install smoke for the sharp shim + transformers + gliner
npm run smoke:sharp-shim

Project structure

PII-Shield/
├── nodejs-v2/                                        # The product
│   ├── src/
│   │   ├── index.ts                                  # MCP tool handlers
│   │   ├── engine/ner-backend.ts                     # GLiNER + ONNX runtime boot
│   │   ├── docx/ pdf/ mapping/ audit/                # Document pipelines
│   │   └── portability/                              # session export/import
│   ├── plugin/
│   │   ├── build-plugin.mjs                          # thin .mcpb builder
│   │   ├── build-mac-binary.mjs                      # darwin-universal .mcpb builder (bundles Node 24.15.0)
│   │   └── skills/
│   │       ├── pii-contract-analyze/                 # canonical skill source (SKILL.md + references/*.md)
│   │       └── pii-contract-analyze.zip              # release artefact — auto-rebuilt from the source dir by build-plugin.mjs
│   ├── scripts/
│   │   ├── smoke-protocol.mjs                       # MCP protocol round-trip smoke
│   │   ├── smoke-setup-panel.mjs                    # Setup-panel + install-tool smoke
│   │   └── smoke-sharp-shim.mjs                     # Clean-install sharp-shim smoke
│   ├── manifest.json                                 # MCPB manifest (server.type=node)
│   └── package.json
├── .github/workflows/test.yml                        # Node CI (ubuntu + windows + macos, Node 18 + 20)
├── LICENSE
└── README.md

故障排除

v1怎么了？

v1.0.0是一个基于presidio+SpaCy+GLiNER/py构建的Python MCP服务器，作为 .dxt 捆绑。它仍然可用：

• 标签 v1.0.0 --固定源。
• 分支 python-legacy --Node.js重写前的完整树。

v2是一个完整的架构重置——Node.js，纯js .docx，MCP应用程序UI，精简 .mcpb --升级不会减少。

致谢

PII Shield建立在优秀的开源项目之上：

• onnxruntime节点 --CPU推理引擎。
• @xenova/transformers --ONNX Runtime之上的tokenizer+HF权重加载器。

作者

格里戈里 莫斯卡列夫 — 领英

许可证

麻省理工学院