PDF Text Extractor MCP

PDF Text Extractor MCP

extract_pdf_text というツールを1つだけ公開する、ローカルの STDIO MCP サーバーです。PDF.js で埋め込みテキストを読み取り、スキャンされたページでは英語／ドイツ語の OCR にフォールバックし、文書内の順序でページ単位の段落を返します。React アプリ、HTTP サーバー、API キー、PDF のアップロードは不要です。

Node.js 22.19 以降と npm（node と npx が PATH 上にあること）が必要です。

公開パッケージを実行する

バージョン 0.1.1 は npm で公開されています。 リポジトリをクローンしたり、React アプリを起動したりせずに実行できます。

npx -y [email protected]

プロセスは標準入力で MCP クライアントからの接続を待ちます。対話型プロンプトはありません。 通常、クライアントがこのコマンドを自動で起動します。

VS Code の設定

.vscode/mcp.json に次の内容を記述し、VS Code の MCP コントロールからサーバーを起動して、エージェントのチャットでツールを有効にします。

{
  "servers": {
    "pdf-text-extractor": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

ローカルの開発ビルドを使用する場合は、ローカルでビルドした後に "command": "node" および "args": ["/absolute/path/to/pdf-text-extractor/mcp/dist/index.js"] を指定します。ほかのクライアントでは、トップレベルのキーとして servers ではなく mcpServers を使用する場合があります。そのクライアントの設定形式に従ってください。

クライアントにローカルの PDF を抽出するよう依頼するか、次の引数で extract_pdf_text を呼び出します。

{ "file_path": "/absolute/path/to/contract.pdf" }

Windows で JSON を使用する場合は、C:\\Users\\you\\contract.pdf のような絶対パスを指定します。 パスは MCP サーバーを実行しているマシン上のものです。

結果の仕様

成功した呼び出しでは、isError: false、JSON テキストコンテンツブロック、および structuredContent 内の同じオブジェクトが返されます。

{
  "success": true,
  "text": "First page text\n\nSecond page text",
  "page_count": 2,
  "pages_without_text": [],
  "pages": [
    {
      "page_number": 1,
      "method": "embedded",
      "text": "First page text",
      "paragraphs": ["First page text"],
      "warnings": []
    },
    {
      "page_number": 2,
      "method": "ocr",
      "text": "Second page text",
      "paragraphs": ["Second page text"],
      "warnings": []
    }
  ],
  "warnings": []
}

ファイルまたは抽出のエラーでは、isError: true と { "success": false, "text": "", "error": "PDF file was not found." } が返されます。 引数が不足している場合や型が正しくない場合は、抽出の実行前に SDK が MCP ツールエラーとして拒否します。

元の text、page_count、pages_without_text フィールドも引き続き利用できます。 text は空でないページを空行でつなぎます。各ページの text は paragraphs を空行でつなぎ、段落内の改行を保持します。 page_number と pages_without_text は、1 始まりのページ番号を使用します。 method は embedded、ocr、またはテキストを抽出できず OCR に失敗した場合は none です。OCR の試行が完了したもののテキストが見つからなかった場合は、警告とともに ocr を報告します。 トップレベルの warnings には、ページ番号を付けたページの警告が重複して含まれます。 success: true は PDF の処理が完了したことを示します。部分的な結果については警告を確認してください。

PDF ヘッダーを持つ通常の .pdf ファイルのみ受け付けます。サイズ上限は 25 MiB です。 ファイルが見つからない、読み取れない、無効である、サイズ超過である、またはパスワードで保護されている場合はエラーになります。サーバーはファイルを変更せずに読み取り、シェルコマンドを実行せず、抽出のためのネットワークリクエストも行いません。診断情報は stderr に出力され、stdout は MCP メッセージ用に確保されています。PDF の内容がログに記録されることはありません。

制限事項

ヘッダーとフッターしかないページを含め、本文テキストが埋め込まれていないページには OCR が使用されます。 本文テキストが 40 文字未満で、画像も含まれるページにも OCR が使用されます。 OCR が成功すると、ヘッダーの重複を避けるため、ページに埋め込まれたテキストが OCR 結果に置き換えられます。 OCR が失敗するか、テキストを返さない場合は、埋め込まれたテキストが保持され、警告が返されます。テキストがないままのページは pages_without_text に表示されます。

英語とドイツ語の言語モデルはビルド時にバンドルされます。抽出にネットワーク接続、モデルのダウンロード、書き込み可能なモデルキャッシュは不要です。OCR ワーカーは必要な場合にのみ起動し、文書全体で再利用された後、終了します。OCR 入力は最大で PDF の 2.5 倍のスケールでレンダリングされ、1 ページあたり 800 万ピクセルを上限とします。エンジンの起動を含み、PDF のレンダリングを除く OCR 認識には、ページあたり 60 秒の制限時間があります。ワーカーが失敗またはタイムアウトした場合は終了され、残りのページでは埋め込まれたテキストが警告とともに保持されます。

埋め込まれたテキストは、位置に基づいて行と段落にグループ化されます。基本的な表の読みやすさを確保するため、大きな水平方向の空白は | で表されます。OCR では、Tesseract の段落検出と単語の位置情報を使用します。これらは読みやすさを高めるためのヒューリスティックであり、意味を考慮した表の抽出や複雑なレイアウト解析ではありません。複数列、回転、手書き、または画質の低いスキャンページでは、順序やテキストが正しくない場合があります。スキャンされた本文の上に埋め込まれたテキストが十分にあるページでは、OCR が実行されないことがあります。OCR の信頼度が低い場合は警告が生成されますが、信頼度が高くても正確さが保証されるわけではありません。 サイズ制限は入力バイト数を制限するものであり、PDF の展開や処理にかかる時間は制限しません。サーバーは OS ユーザーがアクセスできる任意の PDF を読み取ることができ、ディレクトリのサンドボックスはありません。テキストは MCP クライアントに返され、データの取り扱いにはクライアント側の設定が適用されます。

開発

リポジトリのルートから実行します。

npm ci --prefix mcp
npm run build --prefix mcp
node mcp/dist/index.js

CLI は独立したパッケージであるため、インストールしても React はインストールされません。 Tesseract.js と、ネイティブの Node canvas 依存関係が含まれています。@napi-rs/canvas がサポートするプラットフォームを使用し、npm がプラットフォーム用バイナリをインストールできるようにしてください（オプションの依存関係を省略しないでください）。開発用モデルパッケージはビルド時に dist/tessdata/ にコピーされるため、利用者に開発用依存関係は不要です。 このパッケージ独自のロックファイルにより、再現可能なビルドが実現します。ルートアプリのコマンドに変更はありません。

ブラウザーサービスとこの CLI は、src/shared/ にあるランタイムに依存しない同じ抽出コアを使用します。これには、ページ処理、埋め込まれたテキストの読み取り、スキャン検出、OCR フォールバック、段落、表の空白調整、警告が含まれます。ブラウザーと Node のアダプターは、それぞれ独自のファイルアクセス、PDF.js のセットアップ、レンダリング制限、OCR ワーカー管理を維持します。ブラウザーの既存の結果インターフェースと、このツールの JSON コントラクトは維持されます。 ビルドでは生成された出力をクリーンアップし、コンパイル済みの dist/shared/ モジュールを tarball に含めます。ランタイム利用者は、リポジトリの共有ソースファイルを必要としません。

MCP Inspector でのテスト

クローンやビルドをせずに公開済みパッケージをテストします。

npx -y @modelcontextprotocol/[email protected] --cli npx -y [email protected] --method tools/list
npx -y @modelcontextprotocol/[email protected] --cli npx -y [email protected] --method tools/call --tool-name extract_pdf_text --tool-arg "file_path=/absolute/path/to/contract.pdf"

ブラウザー版 Inspector の場合：

npx -y @modelcontextprotocol/[email protected] npx -y [email protected]

Connect をクリックし、Tools を開いて、ローカル PDF のパスを指定して extract_pdf_text を実行します。 Inspector は開発用ツールであり、このパッケージのランタイム依存関係ではありません。

ローカルの開発ビルドを調べるには、ビルド後にリポジトリのルートから実行します。

npx -y @modelcontextprotocol/[email protected] --cli node mcp/dist/index.js --method tools/list
npx -y @modelcontextprotocol/[email protected] --cli node mcp/dist/index.js --method tools/call --tool-name extract_pdf_text --tool-arg "file_path=/absolute/path/to/contract.pdf"

自動テストとパッケージング

npm test --prefix mcp
cd mcp
npm pack

tar -tzf pdf-text-extractor-mcp-0.1.1.tgz で tarball の内容を確認します。 コンパイル済み JavaScript（OCR ワーカーを含む）、圧縮された両方の言語モデル、サードパーティの通知、この README、パッケージのメタデータが含まれています。ソースのチェックアウトを使わずに実行可能ファイルを検証するには、別のディレクトリにインストールします。

mkdir /tmp/pdf-mcp-install
cd /tmp/pdf-mcp-install
npm install /absolute/path/to/mcp/pdf-text-extractor-mcp-0.1.1.tgz
./node_modules/.bin/pdf-text-extractor-mcp

リポジトリのルートから、インストールした実行可能ファイルを対象に統合テストを実行します。

MCP_TEST_CLI=/tmp/pdf-mcp-install/node_modules/.bin/pdf-text-extractor-mcp npm test --prefix mcp

新しいバージョンを公開する

公開済みのバージョンは上書きできません。 次のリリースではバージョンを上げ、両方の README に記載された固定バージョンの例も更新してください。 プロジェクトのコードは MIT ライセンスで提供されています。パッケージには、著作権表示 © 2026 Prashant Bhatia が記載された LICENSE が含まれています。バンドルされている OCR モデルには Apache-2.0 ライセンスが適用されており、帰属表示は THIRD_PARTY_NOTICES.md と licenses/Apache-2.0.txt に記載されています。

mcp/ から実行します。

npm login --auth-type=web
npm version patch --no-git-tag-version
npm test
npm pack
npm publish --dry-run --access public
npm publish --access public --auth-type=web

上記の説明に従って、公開前にパッケージ化された成果物を確認し、テストしてください。公開には、2FA が有効になっているメンテナーの npm アカウントへのアクセスが必要です。npm から求められた場合は、ブラウザーでの承認を完了してください。リリースに向けて、バージョン、ロックファイル、ドキュメントの変更をコミットしてください。ビルドやテストによって自動的に公開されることはありません。ルートの React パッケージはプライベートのままなので、mcp/ から公開してください。

MCP Registry に公開する

レジストリ識別子は io.github.Prashant2204/pdf-text-extractor-mcp です。 package.json の mcpName は server.json の name と一致させる必要があります。server.json のパッケージバージョン、サーバーバージョン、npm パッケージバージョンは一致させてください。レジストリがメタデータを検証できるよう、先に npm パッケージを公開してください。

公式パブリッシャーを brew install mcp-publisher でインストールし、mcp/ から次を実行します。

mcp-publisher validate
mcp-publisher login github
mcp-publisher publish

求められたら、GitHub デバイス認証を完了してください。公開されたエントリーは、次のコマンドで確認できます。

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.Prashant2204/pdf-text-extractor-mcp"

レジストリにはメタデータが掲載され、npm はローカルの STDIO サーバーを配布します。 公式の公開ガイドを参照してください。

統合テストでは、STDIO を介して、画像のみの PDF ページ、ヘッダーとスキャンが混在するページ、空白ページ、埋め込みテキストのあるページに対し、英語とドイツ語の実際の OCR を実行します。 その他のテストでは、順序、表の空白、OCR のタイムアウト、画像検査または OCR アセットに障害が発生した場合の部分的な結果を確認します。上記のように、同じ統合テストをインストール済みの実行ファイルに対して実行することもできます。 バンドルされているモデルの帰属表示については、THIRD_PARTY_NOTICES.md を参照してください。

公式リファレンス

• SDK 最初のサーバー
• SDK STDIO トランスポート
• MCP Inspector
• VS Code MCP サーバー

実装は、安定版 @modelcontextprotocol/server 2.4.0 に対して検証済みで、McpServer.registerTool() と serveStdio() を使用しています。ブラウザーと MCP のパッケージはどちらも PDF.js 6.5.438 を使用します。