PDF リーダー MCP サーバー (@sylphlab/pdf-reader-mcp)

単一の柔軟なツールを使用して、プロジェクトのコンテキスト内で PDF ファイルから安全に情報 (テキスト、メタデータ、ページ数) を読み取り、抽出する機能を AI エージェント (Cline など) に提供します。

インストール

npm の使用（推奨）

MCP ホスト環境またはプロジェクトに依存関係としてインストールします。

pnpm add @sylphlab/pdf-reader-mcp # Or npm install / yarn add

npxを使用するように MCP ホスト (例: mcp_settings.json ) を構成します。

{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "npx",
      "args": ["@sylphlab/pdf-reader-mcp"],
      "name": "PDF Reader (npx)"
    }
  }
}

(ホストがターゲットプロジェクトに正しいcwdを設定していることを確認してください)

Dockerの使用

イメージをプルします:

docker pull sylphlab/pdf-reader-mcp:latest

コンテナを実行するように MCP ホストを構成し、プロジェクトディレクトリを/appにマウントします。

{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/project:/app", // Or use "$PWD:/app", "%CD%:/app", etc.
        "sylphlab/pdf-reader-mcp:latest"
      ],
      "name": "PDF Reader (Docker)"
    }
  }
}

ローカルビルド（開発用）

クローン: git clone https://github.com/sylphlab/pdf-reader-mcp.git
インストール: cd pdf-reader-mcp && pnpm install
ビルド: pnpm run build
MCP ホストを構成する:
{ "mcpServers": { "pdf-reader-mcp": { "command": "node", "args": ["/path/to/cloned/repo/pdf-reader-mcp/build/index.js"], "name": "PDF Reader (Local Build)" } } }
(ホストがターゲットプロジェクトに正しいcwdを設定していることを確認してください)

クイックスタート

サーバーが MCP ホストで実行され、構成されていると仮定します。

MCP リクエスト (ローカル PDF からメタデータとページ 2 のテキストを取得):

{
  "tool_name": "read_pdf",
  "arguments": {
    "sources": [
      {
        "path": "./documents/my_report.pdf",
        "pages": [2]
      }
    ],
    "include_metadata": true,
    "include_page_count": false, // Default is true, explicitly false here
    "include_full_text": false // Ignored because 'pages' is specified
  }
}

予想される応答スニペット:

{
  "results": [
    {
      "source": "./documents/my_report.pdf",
      "success": true,
      "data": {
        "page_texts": [
          { "page": 2, "text": "Text content from page 2..." }
        ],
        "info": { ... },
        "metadata": { ... }
        // num_pages not included as requested
      }
    }
  ]
}

このプロジェクトを選択する理由

**🛡️ 安全:**ファイルアクセスをプロジェクトのルートディレクトリに厳密に制限します。
**🌐 柔軟性:**ローカル相対パスとパブリック URL の両方を処理します。
**🧩 統合:**単一のread_pdfツールで複数の抽出ニーズ (全文、特定のページ、メタデータ、ページ数) に対応します。
**⚙️ 構造化された出力:**エージェントが解析しやすい予測可能な JSON 形式でデータを返します。
🚀 簡単な統合: npxまたは Docker を介して MCP 環境内でシームレスに使用できるように設計されています。
**✅ 堅牢:**信頼性の高い解析にはpdfjs-distを使用し、入力検証には Zod を使用します。

パフォーマンス上の利点

サンプル PDF で Vitest を使用した初期ベンチマークでは、さまざまな操作が効率的に処理されていることが示されています。

シナリオ	1秒あたりの操作数（Hz）	相対速度
存在しないファイルの処理	約12,933	最速
全文を見る	約5,575
特定のページを取得（ページ 1）	約5,329
特定のページを取得する（ページ 1 と 2）	約5,242
メタデータとページ数を取得する	約4,912	最も遅い

(hz が高いほどパフォーマンスは向上します。結果は PDF の複雑さと環境によって異なる場合があります。)

詳細と今後の計画については、パフォーマンスドキュメントを参照してください。

特徴

PDF ファイルから全文コンテンツを読み取ります。
特定のページまたはページ範囲からテキストコンテンツを読み取ります。
PDF メタデータ (作成者、タイトル、作成日など) を読み取ります。
PDF の合計ページ数を取得します。
1 回のリクエストで複数の PDF ソース (ローカルパスまたは URL) を処理します。
定義されたプロジェクトルート内で安全に動作します。
MCP 経由で構造化された JSON 出力を提供します。
npm および Docker Hub から利用できます。

デザイン哲学

このサーバーは、コンテキストの制限によるセキュリティ、構造化データ転送による効率性、そしてAIエージェントのワークフローへの容易な統合を可能にするシンプルさを重視しています。堅牢なpdfjs-distライブラリを活用し、依存関係を最小限に抑えることを目指しています。

完全な設計哲学のドキュメントを参照してください。

他のソリューションとの比較

直接ファイルアクセス（多くの場合不可能）や汎用ファイルシステムツールと比較して、このサーバーはPDFに特化した解析機能を提供します。外部CLIツール（例： pdftotext ）とは異なり、構造化された出力を備えた安全で統合されたMCPインターフェースを提供し、AIエージェントの信頼性と使いやすさを向上させます。

完全な比較ドキュメントを参照してください。

今後の計画（ロードマップ）

ドキュメント:
- すべてのドキュメントセクション (ガイド、API、設計、比較) を完成させます。
- TypeDoc の問題を解決し、API ドキュメントを生成します。
- さらに多くの例と高度な使用パターンを追加します。
- ドキュメントサイトに PWA サポートとモバイル最適化を実装します。
- ドキュメントサイトに共有ボタンと成長指標を追加します。
ベンチマーク:
- さまざまな PDF ファイル (サイズ、複雑さ) を使用して包括的なベンチマークを実施します。
- メモリ使用量を測定します。
- URL とローカルファイルのパフォーマンスを比較します。
コア機能:
- 非常に大きな PDF ファイルの潜在的な最適化を検討します。
- 画像や注釈を抽出するためのオプションを調査します (長期的)。
テスト:
- 可能な場合は、テスト範囲を 100% に増やします。
- 実行可能になったらランタイムテストを追加します。

ドキュメント

詳細な使用方法、API リファレンス、ガイドについては、完全なドキュメントの Web サイト(展開時にリンクが更新されます) をご覧ください。

コミュニティとサポート

バグを見つけた場合や機能のリクエストがある場合は、 GitHub Issuesで問題を報告してください。
**貢献してみませんか？**貢献を歓迎します！ CONTRIBUTING.mdをご覧ください。
**スターとウォッチ:**このプロジェクトが役に立つと思われる場合は、 GitHubのリポジトリに ⭐ スターを付けて 👀 ウォッチし、サポートを示して最新情報を入手してください。

ライセンス

このプロジェクトはMIT ライセンスに基づいてライセンスされています。

PDF Reader MCP Server

Integrations