document-scanner

@guardbee/mcp-document-scanner

🇬🇧 英語 | 🇹🇷 トルコ語

LLM に渡す前に、PDF、スクリーンショット、スキャンしたページなどのドキュメント内にある個人データや認証情報を検出する MCP サーバー兼 CLI です。プロキシや 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 を使用し、スキャンした PDF ページのレンダリングには @napi-rs/canvas（プリビルド済みで、コンパイラーは不要）を使用します。これらがなくても、スキャナーはすべての 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"] } } }

CLI

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 を指定すると、GitHub Code Scanning 用にページを行として扱う SARIF 2.1.0 を出力します。--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 が役に立った場合は、リポジトリに ⭐ を付けていただけると、ほかの人にも見つけてもらいやすくなります。