CorpusGate

MarkItDownとMCPを利用した、LLM対応のプライベート文書ゲートウェイ。

文書コンテンツを第三者のサービスへ送信することなく、AIツール向けにプライベート文書の変換・インデックス化・取得を実現します。

CorpusGateは、個人やチームが自らのインフラ上で文書への制御されたAIツールアクセスを必要とする場合に使える、汎用のセルフホスト型Document MCP Serverです。MarkItDownが対応ファイルを再利用可能なMarkdownに変換します。ゲートウェイはそのMarkdownをチャンク化してインデックスを作成し、MCPはサーバーが強制するバジェット（上限）の範囲内で、関連する出典付きチャンクのみを返します。

セルフホスティングにより、元の文書、生成されたMarkdown、クエリ、メタデータ、インデックスをすべて運用者の管理下に置けます。トークン削減はMarkItDown単独によるものではなく、制限付き取得とチャンク選択によって実現されます。このプロジェクトは、チャットボットでも、LLM回答生成ツールでも、契約分析製品でも、SaaSプラットフォームでも、ユーザー向け文書パネルでもありません。

特徴

• Microsoft MarkItDownによるPDF、DOCX、PPTX、XLSX、TXT、Markdown、HTMLの変換。

• 永続的なMarkdownキャッシュ、トークンを考慮して見出しを維持するチャンク、SHA-256による重複排除。

• 軽量なデフォルト構成でのSQLite FTS5/BM25語彙検索。

• オプションのCPU専用多言語セマンティック検索と、ローカル埋め込みを使ったRRFハイブリッド取得。

• ソース/位置メタデータ、カーソル、重複排除、近傍制限を備えた制限付きMCP応答。

• REST APIキー認証とMCP Bearer認証、安全なUUID保存、パス/シンボリックリンク保護、レート制限、構造化されたコンテンツ安全なログ。

• 高堅牢化したDocker Composeデプロイ（AMD64/ARM64、Oracle Cloud、Tailscale、Caddy HTTPS対応）。

• セットアップヘルパー、運用コマンド（doctor/scan/reindex/backup）、バージョン管理されたSQLiteスキーマ、CI。

Related MCP server: knowledge-base

動作の仕組み

REST upload or read-only inbox scan
        │
        ├─ type, signature, size, path, and free-space validation
        ├─ UUID storage + SHA-256 ── unchanged? ── reuse cached/indexed record
        │
        └─ MarkItDown ──> persistent Markdown ──> token-aware chunks
                                                   │
                              ┌────────────────────┴────────────────────┐
                              │                                         │
                    SQLite FTS5 / BM25                      optional local embeddings
                              │                                  + private Qdrant
                              └────────────────────┬────────────────────┘
                                                   │
                               ranking → dedup → token/char budget → MCP

パーサー、ストレージ、リポジトリ、チャンキング、埋め込み、ベクターストア、取得のコントラクトは、シングルサーバー製品を分散システムにせずにインターフェースの背後に保持されます。文書は一次データソースであり続け、Markdownとベクターインデックスは再構築できます。

対応フォーマット

暗号化、破損、スキャン画像のみ、またはコンバータ非対応のファイルは、他の文書への処理を止めずに安全に失敗します。

クイックスタート

要件：Docker Compose v2とOpenSSLを備えたDocker Engine。ホストにPythonは不要です。

git clone https://github.com/mustafa0zdemir/corpusgate.git
cd corpusgate
./corpusgate init
./corpusgate up
curl --fail http://127.0.0.1:8000/health
./corpusgate doctor

./corpusgate init は、persistent/inboxフォルダを作成し、.env が存在する場合を除いて .env.example をコピーし、ランダムなREST/MCP認証情報を画面に表示せずに生成し、Docker/Composeと選択したポートをチェックして、Composeを検証します。既存の .env を上書きすることはありません。

同等の手動フローは、.env.example を .env にコピーし、両方の認証情報プレースホルダーを異なる openssl rand -hex 32 の値に置き換え、documents/ を作成して、docker compose up -d を実行します。.env をコミットしないでください。

オプションのローカル・セマンティック/ハイブリッド取得も、初期化後の1操作で有効化できます:

./corpusgate init --semantic
./corpusgate up --semantic

最初のセマンティック起動時には、モデルを永続キャッシュにダウンロードし、その後、内部Dockerネットワーク上のQdrantとともにゲートウェイをオフラインで起動します。以降の起動時は、モデルとベクターの両ボリュームを再利用します。語彙検索のみのインストールでは、どちらのセマンティック・コンポーネントもインストールも実行もされません。

ドキュメントの追加

最もシンプルな運用ワークフローは、読み取り専用のホスト受信ボックスを使うものです:

cp examples/documents/* documents/
./corpusgate scan
./corpusgate list-documents

スキャンでは、非表示/システム/一時ファイル、未対応タイプ、ディレクトリ、シンボリックリンクをスキップします。入力ファイルは documents/ に残り、UUIDのプライベートコピーが永続的なソースボリュームに保存されます。lexical→semantic/hybrid→MCPの完全なチュートリアルは、合成デモ を参照してください。

AIツールがモデルコンテキストにファイルのバイト列を入れずに呼び出せる単一ファイルのワークフローとして、実行中のREST APIへローカルファイルを直接ストリーミングできます（curl が必要）:

./corpusgate upload /absolute/path/to/document.pdf

このコマンドはRESTキーを CORPUSGATE_CLIENT_API_KEY、CORPUSGATE_API_KEY、またはローカルの .env から読み取り、それを表示せず、リダイレクトや非晒しのリモートHTTPを拒否し、APIのアップロードメタデータのみを返します。リモートのプライベートサーバーには、--url https://YOUR-NODE.YOUR-TAILNET.ts.net を指定します。

RESTアップロードはアプリケーションからも利用できます:

export CORPUSGATE_CLIENT_API_KEY='value-from-your-env'
curl --fail -X POST http://127.0.0.1:8000/api/v1/documents \
  -H "X-API-Key: ${CORPUSGATE_CLIENT_API_KEY}" \
  -F 'file=@examples/documents/private-network-guide.md'

RESTは /api/v1/documents 以下で、ページング対応のメタデータ、Markdown、チャンク、語彙検索、削除も提供しています。インタラクティブなOpenAPIドキュメントは /docs にあり、保護された操作には引き続き X-API-Key が必要です。

MCPクライアントの接続

リモートエンドポイントは https://YOUR_PRIVATE_OR_PUBLIC_HOST/mcp で、すべてのMCPリクエストには次のものが必要です:

Authorization: Bearer YOUR_MCP_TOKEN

推奨されるプライベートルートはTailscale Serveです。公開用の代替はCaddy HTTPSです。どちらの場合もゲートウェイのポートはホストのループバックにバインドされたままです。検証済みのフィールドマッピング、Inspectorコマンド、Tailscale/HTTPSの例、トラブルシューティングはMCP接続ガイド にあります。検証されていないクライアント固有のJSONラッパーをコピーしたり、トークンをソースコード管理に保存したりしないでください。

MCPツール

取得項目には常に、document_id、document_name、chunk_id、heading、position、関連度/順位フィールド、制限付きの content、content_length、取得モードのメタデータが含まれます。空検索では空の items リスト、適用済みバジェット、メトリクス、カーソルなしが返ります。無効なモードやフィルタ、文書ID、上限超えの値は制御されたツールエラーを返します。アップロードと削除はRESTのみです。

推奨フロー:

AI tool → search_document(query, top_k=3, max_tokens=600)
        → ranked chunks + source positions + actual retrieval mode
        → optional bounded get_document_section

語彙検索、セマンティック検索、ハイブリッドの検索

• lexical は本番デフォルトです。見出しに重み付けられたBM25を備えるSQLite FTS5が、外部サービスなしの正確な識別子とフレーズを保持します。

• semantic は、構成可能な多言語CPUモデルでクエ感想やチャンクをローカルに埋め込み、ベクターを専用の Qdrant に保存します。

• hybrid は、独立した語彙順位とセマンティック順位をReciprocal Rank Fusionで結合します。重複チャンクは一度だけ返し、語彙の完全一致を取りこぼすこともありません。

• lexical_fallback は、セマンティック/ハイブリッドが要求されたのに、局所モデル、ベクターストア、インデックスが利用不能で、フォールバックが有効なとき報告されます。

既定モデルはApache-2.0ライセンスの sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2。 CPU上でFastEmbed/ONNX を通して使われます。モデルの差し替え、オフライン転送、再インデックスの規則、測定値、ノードメモリの目安は semantic search にあります。メソッド名のアドレス構造を省略しない。

トークン最適化

MarkItDownは様々な形式のファイルを取得しやすいMarkdownに統一する働きですが、単独でトークンを減らすことはありません。ゲートウェイは、変換を一度だけキャッシュし、チャンクの順位付け、重複除去、top_k、max_chars、見積もり max_tokens の制限、近傍の制限、長い結果セットのページングによって、返すコンテ These to ensure it utilizes brackets: As in the original text, keep: informational.

トークン数はローカル環境で決定? しかし、静的に定められた推定値であり、プロバイダー固有の設定的トークナイザではありません。再利用可能な合成測定とその範囲は、retrieval report にあります。特定の TKA 全体の省略はしていない。

トークン数はワーストケースのローカルな概算であり、プロバイダが請求するトークナイザーザとは異なります。再試行可能な合成評価 i.e., 実験の定義・範囲は retrieval-evaluation-2026-08-24.md に詳細されています。どのべつの全体的削減速度も主張していません。

トークン数はローカルで決定論的に推定されたもので、提供元の課金トークナイザではありません。再現できる合成測定とその対象範囲は、探索評価レポート に説明しています。普遍的な削減率を満足するものはありません。

セキュリティとプライバシー

• テレ測、文書テキスト、クエリテキスト、クラウドエンベーディングAPI、必須LLMプロバイダーなし。

• ソースファイルはUUIDパスに保存し、ファイル名のパストラバーサル、絶対パス、シンボリックリンク逃げ道、隠し/一時ファイル、MIME/署名の不一致、アーカイブの展開、アップロードサイズ、ディスク不足を検査。

• RESTはAPIキーによる認証、リモートMCPは竜saltedキー（例としてBulldog）は環境またはDockerの秘密によって定数時間比較のBearerトークンを使用。複数の現行・過去トークンでローテーション可能。

• 構造化ログには許容された操作のメタデータのみ含まれ、文書の中身、資格情報、全体クエリ、クライアントから見えるスタックトレースは含まれない。

• ゲートウェイコンテナはroot非、権限なし、no-new-privileges、読み込み専用ルート、明示的可書きボリュール/tmpfs、リソース/ログの制限。

• 標準のComposeは 127.0.0.1:8000 のみ公開。Qdrantは内部専用。公開展開にはCaddy TLSが必要です。Bearer認証・レート・レスポンスの制限を守ります。

保存データは、本人確認付きUUIDソースコピー、生成Markdown、SQLiteメタデータ/チャンク/FTS、オプションのローカルベクトル/モデルキャッシュ、バックアップ、運用者設定です。データを消去するには、まずRESTューブで文書を削除し、明示的なバックアップとシャットダウンの後に永続ボリュールを削除してください。非公開の脆弱情報は、SECURITY.md を参照してください。

Oracle Cloudでのデプロイ

推奨されるOracle Ubuntu環境では、アプリをループバックにバインドし、tailnet限定HTTPSにはTailscale Serveを使用します。ドメインが必要な場合は、Caddy の public プロフィールを説明しています。Oracle Security Lists/NSG では、TCP 8000、Qdrant 6333を一般に公開してはなりません。

VMの準備、AMD64/Ampere ARM64ノート、Dockerのインストール、ファイルシステムの所有、シークআরিক，ファイアウォール，Tailscale/Caddy，ログ，更新，バックアップと復元，トラブルシューティングは Oracle deployment guide にあります。

設定

すべてのアプリケーションの環境変数、標準値、要件、レンジ、例，セキュリティ設定は、設定仕様 と .env.example にまとめられています。起動時には、欠落・短すぎる認証情報、無効なポート/パス、成立しないチャンク/バジェット準拠、非対応ス, retrieval modes、無効なセマンティック・ベクターストアの設定について、値を公開せずにエラーとして拒否されます。

運用コマンド:

./corpusgate version
./corpusgate status
./corpusgate doctor
./corpusgate mcp-smoke
./corpusgate upload /absolute/path/to/document.pdf
./corpusgate scan
./corpusgate reindex
./corpusgate reindex --semantic
./corpusgate list-documents --limit 20 --offset 0

バックアップとリストア

./corpusgate backup
./corpusgate restore /backups/corpusgate-backup-TIMESTAMP.tar.gz --confirm-restore

Restore は現在の永続データを置き換えるため、本番環境では明示的な確認フラグと、停止したライターが必要です。バックアップには、プライベートソースストレージ、Markdown キャッシュ、トランザクショナルにコピーされた SQLite データベース、マニフェスト、シークレットを含まない設定例が含まれます。.env とトークンファイルは、別の暗号化されたシークレットバックアップに保存してください。ベクタデータはチャンクから再構築できます。

更新とロールバック

現在のバージョンを確認し、バックアップし、レビュー済みのタグ/イメージを選択し、バージョン管理された冪等なマイグレーションを実行し、再起動して ready/MCP を確認し、検証が完了するまでバックアップを保持します。新しい互換性のないアプリケーションで作成されたデータベースは、黙って変更されるのではなく拒否されます。

正確なコマンドと安全なロールバック/復元手順は 更新とロールバック にあります。通常の更新中に docker compose down -v を実行しないでください。

このリポジトリには、手動かつ承認制の GHCR ワークフローも含まれています。Stable tag、moving minor、latest の挙動は コンテナ公開ポリシー で定義されています。このスプリントではまだイメージは公開されていません。

トラブルシューティング

• ./corpusgate doctor: 設定、ストレージ権限、SQLite/スキーマ、ディスク、オプションのモデル/ベクタ状態、サービスの準備状態、バージョンを、シークレットを出力せずに検証します。

• 401: REST の X-API-Key または MCP の Authorization: Bearer を使用してください。それ以外の資格情報タイプは使用しないでください。

• ホスト拒否: 正確な Tailscale/ドメインホストを CORPUSGATE_ALLOWED_HOSTS に追加し、ゲートウェイを再作成してください。

• 507: ディスク空き領域を確保するか、予約済みディスクしきい値を見直してから、取り込みを再試行してください。

• lexical_fallback: モデルキャッシュと Qdrant の健全性を確認してください。字句検索は引き続き利用できます。

• 変換失敗: サポート対象の拡張子、MIME/シグネチャ、UTF-8/Office アーカイブの整合性、サイズ、暗号化、PDF にテキストが含まれるかを確認してください。

• ログ: ./corpusgate logs --tail=100。共有する前に出力をサニタイズしてください。

イシューを起票する前に、SUPPORT.md とデプロイメント固有のトラブルシューティングガイドを参照してください。

互換性

テストされていないプラットフォームは、サポート対象として提示されません。成果物を公開する前に、リリースチェックリスト を確認してください。

制限事項

• 単一ノードの SQLite は、高可用性データベースでもマルチライター型データベースでもありません。

• 0.1.0 ではアップロード変換は同期です。サイズが大きいドキュメントでは、クライアント/プロキシのタイムアウト延長が必要になる場合があります。

• OCR、クラウドストレージアダプター、ユーザーアカウント、UI、回答生成、リランカー、ファインチューニング、SaaS コントロールプレーンはありません。

• 近似トークン予算は、特定の LLM のトークナイザーと異なる場合があります。

• セマンティックモデルのダウンロードには、キャッシュをオフラインで転送しない限り、一時的なアウトバウンドアクセスが必要です。

ロードマップ

• シングルノードユーザーに Redis を必須にすることなく、バックグラウンド変換ジョブを実現します。

• 既存のインターフェースの背後で実装する、オプションの PostgreSQL/pgvector とオブジェクトストレージアダプター。

• さらなるコンバータメタデータの抽出と、オペレーター制御の OCR アダプター。

• 署名付きリリース、SBOM/provenance、クロスアーキテクチャとアップグレードフィクスチャの拡充。

コントリビューション

CONTRIBUTING.md を読み、CODE_OF_CONDUCT.md に従い、テストを追加し、合成された非機密のフィクスチャのみを使用してください。セキュリティレポートは、公開イシューではなく、SECURITY.md の非公開ルートを使用してください。

ライセンス

CorpusGate は既存の MIT License の下で提供されています。サードパーティライブラリとオプションの組み込みモデルには、それぞれのライセンスが適用されます。