document-scanner

@guardbee/mcp-document-scanner

🇬🇧 English | 🇹🇷 Türkçe

一个 MCP 服务和命令行工具，可在文档交给大模型之前，找出其中的个人数据和凭据——包括 PDF、屏幕截图和扫描页面。代理或 DLP 中的文本检查会将 PDF 附件或图像视为不透明数据块；此软件包可以读取其中的内容：首先读取 PDF 文本层，再对图像和不含文本的 PDF 页面进行 OCR（支持土耳其语和英语）。

默认关闭遥测。启用 GUARDBEE_TELEMETRY=1 后，会发送服务、工具、成功状态、耗时和简短参数值（例如文件路径）；较长的字符串以及 content、token 或 password 等字段会替换为占位符。请参阅 @guardbee/mcp-telemetry。

document ──► type from the bytes (PDF, PNG, JPEG, GIF, WebP, BMP, TIFF, text)
              │
              ├─ PDF page with a text layer ──► text
              ├─ PDF page without one ─────► render (@napi-rs/canvas) ──► OCR (tesseract.js)
              └─ image ─────────────────────► OCR (tesseract.js)
                                                 │
                     guard-core detectors ◄──────┘  TC Kimlik No, VKN, IBAN, card (checksums),
                                                    passport, SGK, MERSİS, birth date, address,
                                                    e-mail, KEP, phone, 22+ credential formats

安装

npx -y @guardbee/mcp-document-scanner scan ./contracts      # text layers only
npm i -g @guardbee/mcp-document-scanner tesseract.js @napi-rs/canvas   # with OCR

OCR 为可选功能：tesseract.js 用于读取图像，@napi-rs/canvas（预构建，无需编译器）用于渲染扫描版 PDF 页面，以供 OCR 读取。没有这些依赖时，扫描器仍会读取每个 PDF 文本层，并指出无法读取的页面或图像。Tesseract 首次使用时会将 tur 和 eng 语言数据（约 10 MB）下载到 ~/.cache/guardbee/tessdata（或 $XDG_CACHE_HOME/guardbee/tessdata），绝不会下载到工作目录。离线使用：将 <lang>.traineddata 放入一个文件夹，并传入 --lang-path。

MCP 工具

工具	功能
scan_document	扫描文件，或文件夹中的所有 PDF 和图像
scan_base64	扫描以 base64 提供的字节（附件、工具返回的图像）；类型根据字节内容确定
list_detectors	列出将运行的个人数据和凭据检测器

{ "mcpServers": { "documents": { "command": "npx", "args": ["-y", "@guardbee/mcp-document-scanner"] } } }

命令行

guardbee-document-scanner scan <file|folder> [--format=text|json|sarif] [--fail-on=any|critical|high|medium|low|none]
                               [--no-ocr] [--lang=tur,eng] [--lang-path=<dir>] [--cache-path=<dir>] [--include=ip_address,plate_tr]
                               [--max-pages=50] [--max-files=500] [--text]

⚠️  Found 3 item(s) in 1 document(s) (812ms)
   Critical: 0  High: 2  Medium: 1  Low: 0

contracts/acme.pdf (pdf, 2 page(s) read)
  [HIGH] tc_kimlik (personal) — page 1, pdf-text: 10*******46
  [HIGH] iban (personal) — page 2, pdf-ocr: TR************26
  [MEDIUM] email (personal) — page 2, pdf-ocr: al***********om

发现结果只显示首尾字符。--format=sarif 会生成 SARIF 2.1.0 格式的结果，并将页面作为行号，以供 GitHub Code Scanning 使用。当发现达到或超过 --fail-on 指定级别的内容时，退出码为 1。

在安全代理中使用

@guardbee/mcp-security-proxy 使用此软件包处理 interceptors.documents：在模型看到工具结果和资源数据块中的图像及嵌入式 PDF 之前，会先对其进行扫描；包含个人数据或凭据的文档将被拦截（block）或记录（warn）。

interceptors:
  documents: { enabled: true, action: block, ocr: true, maxBytes: 26214400 }

限制

• 类型根据字节内容确定，不依据文件名或 MIME 类型。
• 默认每份文档最多 25 MB、50 页（maxBytes、--max-pages）。
• OCR 质量取决于扫描质量；模糊的照片可能漏掉数字，导致校验和检查失败——此类值不会报告，因此宁可不报，也不误报。
• 不检测姓名、签名和手写内容。

许可证

MIT

反馈

有疑问、想法或发现误报？请在 GitHub Discussions 中发起讨论，或提交 issue。如果 GuardBee 对你有帮助，在代码库上点一个 ⭐，有助于其他人发现它。