🚀 MCP Server for Document Processing

🚀 ドキュメント処理用 MCP サーバー

🔗 Model Context Protocol（MCP）について

Model Context Protocol（MCP） は、AI アシスタントが外部のツールやデータソースにアクセスできるようにするため、Anthropic が作成した新しい標準です。このプロトコルにより、AI モデルはこの MCP サーバーのような専門サービスに接続し、トレーニングデータの範囲を超えて能力を拡張できます。

MCP 標準を実装することで、このサーバーは AI アシスタントが独自のドキュメントコレクションから情報を検索・取得できるようにし、固有のコンテンツでナレッジベースを効果的に拡張します。

🧠 最新情報で LLM の知識を拡張

この Model Context Protocol（MCP）サーバーを使用すると、大規模言語モデルの最大の制約のひとつである知識のカットオフを克服できます。独自の MCP サーバーを作成することで、以下に関する最新情報を AI アシスタントに提供できます。

• 最新のフレームワークのドキュメント：LLM のトレーニングデータに含まれていないコンテンツを利用できます（React 19、Angular 17、Vue 3.4 以降など）。
• プライベートなコードベース：独自のコードパターンや構造を AI アシスタントが理解できるよう支援します。
• 技術仕様：新しい API、プロトコル、ツールに関するドキュメントをインポートします。

推奨データソース：

• FireCrawl.dev：ドキュメントサイトのスクレイピングに便利な強力なツール
• GitHub の公式リポジトリ：README とドキュメントをダウンロードします
• 技術ブログとチュートリアル：重要な記事を Markdown ファイルとして保存します

🏗️ アーキテクチャ

システムは次の 2 つの主要コンポーネントで構成されています。

1. 📝 処理パイプライン：Markdown ファイルとテキストファイルを読み込み、チャンクに分割して埋め込みを生成し、ベクトルデータベースに保存します。
2. 🔌 MCP サーバー：処理済みのコンテンツを MCP ツール経由で公開し、AI アシスタントが関連情報を検索・取得できるようにします。

💡 使用例

最新のフレームワークドキュメントで AI の知識を更新

# Scrape latest React 19 docs using FireCrawl.dev
# Place the saved markdown files in the data/ directory
# Run the pipeline to process the documentation
# Now ask your AI assistant about React 19 features!

プライベートなコードベースのドキュメントを使用

# Export your API documentation as markdown
# Place the markdown files in the data/ directory
# Run the pipeline to process
# Now your AI assistant can help debug issues with your specific APIs!

✅ 前提条件

• Docker：Windows または Mac 用の Docker Desktop、または Linux 用の Docker Engine
• OpenAI API キー（任意）：代わりに無料のローカル埋め込みを使用できます
• MCP に対応した AI アシスタント：Roo やその他の互換性のあるアシスタントなど

🛠️ セットアップ

1. このリポジトリをクローンします。

   git clone https://github.com/donphi/mcp-server.git
   cd mcp-server
   

2. 設定を記述した .env ファイルを作成します。

   # Copy the example file
   cp .env.example .env
   
   # Edit the file with your settings
   nano .env
   

   Windows では、メモ帳を使って .env ファイルを編集できます。

3. Markdown（.md）ファイルとテキスト（.txt）ファイルを data/ ディレクトリに配置します。

⚙️ 設定

.env ファイルの環境変数を使用して、MCP サーバーを設定できます。

# API Keys
OPENAI_API_KEY=your_openai_api_key_here  # Optional - can use free local embeddings instead
ANTHROPIC_API_KEY=your_anthropic_api_key_here  # Optional

# Pipeline Configuration
CHUNK_SIZE=800                 # Size of text chunks
CHUNK_OVERLAP=120              # Overlap between chunks (in tokens)
BATCH_SIZE=10                  # Batch size for embedding generation
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2  # Model to use (see options below)
SUPPORTED_EXTENSIONS=.md,.txt,.pdf,.docx,.doc  # Comma-separated list of supported file extensions

# Server Configuration
CLAUDE_MODEL=claude-3-7-sonnet-20240307  # Claude model to use
MAX_RESULTS=10                 # Maximum number of results to return
USE_ANTHROPIC=true             # Whether to use Anthropic API for responses

# Paths
DATA_DIR=/data                 # Directory containing input files
OUTPUT_DIR=/output             # Directory for output files
DB_PATH=/db                    # Directory for vector database
CONFIG_PATH=/config/server_config.json  # Path to server configuration file

📊 埋め込みモデル

このシステムは、テキストをベクトル表現に変換するため、複数の埋め込みモデルに対応しています。

無料モデル（API キー不要）

これらのモデルは Docker コンテナ内でローカルに実行され、API キーは不要です。

• sentence-transformers/all-MiniLM-L6-v2：文や短い段落のエンコード用に設計されたコンパクトなモデルです。効率的な埋め込みを生成し、高速な検索タスクに適しています。

• BAAI/bge-m3：複数の検索機能に対応し、100 を超える言語と最大 8192 トークンの入力をサポートする汎用性の高いモデルです。包括的な検索タスクに最適です。

• Snowflake/snowflake-arctic-embed-m：高品質な検索性能を実現するよう最適化されたモデルで、精度と推論速度のバランスに優れています。

有料モデル（OpenAI API キーが必要）

• text-embedding-3-small：高い品質を保ちながら、速度とコスト効率を重視して最適化されています。
• text-embedding-3-large：最高品質の埋め込みを生成します（より高価です）。

パイプラインを実行すると、使用するモデルを選択するよう求められます。OpenAI API キーがない場合、システムは無料のローカルモデルを自動的に使用します。

🚀 使用方法

🔄 ファイルの処理

ファイルを処理して埋め込みを生成するには、次のコマンドを実行します。

docker-compose build pipeline
docker-compose run pipeline

Windows の場合は、Docker Desktop のインストール後に、コマンドプロンプトまたは PowerShell でこれらのコマンドを実行できます。

実行すると、次の処理が行われます。

• 埋め込みモデルを選択するよう求められます
• 必要に応じてパッケージがインストールされます
• data/ ディレクトリ内にある、サポート対象のすべてのファイルが読み込まれます
• コンテンツが処理され、チャンクに分割されます
• 埋め込みが生成されます
• 埋め込みがベクターデータベースに保存されます（db/ ディレクトリ内に chroma.sqlite3 ファイルが作成されます）

⚠️ 重要な次の手順： ファイルを処理した後、サーバーを実行する前に、必ずサーバーをビルドしてください。次のセクションを参照してください。

🔧 MCP サーバーのビルド

必須の手順： ドキュメントを処理した後、サーバーを実行する前に、サーバーコンポーネントをビルドする必要があります。

docker-compose build server

Windows ユーザーへの注意： MCP サーバーを実行する前に、この手順を行うことが重要です。サーバーイメージをビルドせずにサーバーを実行しようとすると、「invalid reference format」エラーが発生します。

Linux/macOS 用の更新された実行スクリプトは、サーバーイメージが存在しない場合に自動的にビルドします。ただし、パフォーマンスを向上させ、サーバーの初回実行時に予期しない遅延が発生しないよう、手動でビルドすることをおすすめします。

🔌 MCP 対応の AI アシスタントへの接続

⚠️ 再確認： MCP サーバーへの接続を設定する前に、次の手順が完了していることを確認してください。

1. パイプラインをビルドします（docker-compose build pipeline）
2. パイプラインを実行します（docker-compose run pipeline）
3. サーバーをビルドします（docker-compose build server）— この手順は重要ですが、見落とされることがよくあります！

MCP サーバーを AI アシスタントで設定する必要があります。設定を生成するスクリプトを用意しています。

macOS/Linux の場合：

1. セットアップスクリプトに実行権限を付与して、実行します。

   chmod +x setup-mcpServer-json.sh
   ./setup-mcpServer-json.sh
   

2. 正しい設定を含む mcp-config.json ファイルが作成されます。

3. AI アシスタントに設定を追加します。

Windows の場合：

1. setup-mcpServer-json.bat ファイルをダブルクリックするか、コマンドプロンプトから実行します。

   setup-mcpServer-json.bat
   

2. 正しい設定を含む mcp-config.json ファイルが作成されます。

3. AI アシスタントに設定を追加します。

Windows ユーザーへの重要なお知らせ： run-mcp-server.bat ファイルは、Docker Compose を一貫して使用するように更新されました。これにより、一部の Windows ユーザーに発生していた「invalid reference format」エラーが解消されます。それでもこの問題が発生する場合は、このリポジトリの最新バージョンのバッチファイルを使用していることを確認してください。

例：Roo の設定

AI アシスタントとして Roo を使用する場合：

1. お使いのプラットフォームに適したセットアップスクリプトを実行し、設定ファイルを生成します
2. Roo のサイドバーにある「MCP Server」ボタン／タブをクリックします
3. 「Enable MCP Servers」の切り替えを有効にします
4. 「Edit MCP Settings」をクリックします
5. mcp-config.json ファイルの内容全体をコピーして貼り付けます
6. 設定を保存します

🧩 MCP サーバーの使用

設定が完了すると、MCP に対応した AI アシスタントで MCP サーバーを使用できます。Roo のような対応アシスタントでは、次の 2 つの方法で使用できます。

1. 自動モード（autoQuery: true の場合）：通常どおり質問すると、AI がベクターデータベースを自動的に検索し、関連情報を確認します。

   例：「React 19 の主な機能は何ですか？」

2. ツールの明示的な使用：特定のツールを使うよう AI に直接依頼します。

   例：「search_content ツールを使って、React 19 Compiler に関する情報を見つけてください。」

🧰 MCP ツール

MCP サーバーでは、次のツールを利用できます。

• 📚 read_md_files：ファイルを処理して取得します。パラメーター：file_path（特定のファイルまたはディレクトリへのパス。省略可能）
• 🔍 search_content：処理済みのコンテンツ全体を検索します。パラメーター：query（必須の検索クエリ）
• 📋 get_context：コンテキスト情報を取得します。パラメーター：query（必須のコンテキストクエリ）、window_size（取得するコンテキスト項目数。省略可能）
• 🏗️ project_structure：プロジェクト構造に関する情報を提供します。パラメーターはありません。
• 💡 suggest_implementation：実装案を生成します。パラメーター：description（実装する内容の説明。必須）

📄 対応ファイル形式

デフォルトでは、次のファイル形式に対応しています。

• Markdown ファイル（.md）
• テキストファイル（.txt）
• PDF ファイル（.pdf）
• Word 文書（.docx、.doc）

.env ファイルで環境変数 SUPPORTED_EXTENSIONS を設定すると、対応するファイル拡張子を追加できます。

🔄 動作モード

MCP サーバーは、次の 2 つのモードで動作します。

1. 🤖 フル処理モード：Anthropic API キーが設定され、USE_ANTHROPIC が true に設定されている場合、サーバーは取得したコンテキストに基づいて Claude で応答を生成します。

2. 📋 コンテキスト取得モード：Anthropic API キーが設定されていない場合、または USE_ANTHROPIC が false に設定されている場合、サーバーは関連するコンテキストの取得と返却のみを行います。クライアント（AI アシスタントなど）は、そのコンテキストを独自の LLM で処理できます。

📁 プロジェクト構造

mcp-server/
├── Dockerfile.pipeline
├── Dockerfile.server
├── docker-compose.yml
├── requirements.pipeline.txt
├── requirements.server.txt
├── README.md
├── .env.example
├── run-mcp-server.sh       # For macOS/Linux
├── run-mcp-server.bat      # For Windows
├── setup-mcpServer-json.sh # Setup script for macOS/Linux
├── setup-mcpServer-json.bat # Setup script for Windows
├── enhanced_chunking.py
├── inspect_chunks.py
├── run_chunk_analysis.sh
├── setup_enhanced_chunking.sh
├── visualize_chunks.py
├── restart_server.sh
├── chunk_analysis/         # Tools for analyzing chunking methods
│   ├── docker_entrypoint.sh
│   ├── docker-compose.yml
│   ├── Dockerfile
│   ├── inspect_chunks.py
│   ├── README.md
│   ├── run_tests.sh
│   ├── semi_interactive_chunking.py
│   └── test_chunking.py
├── src/
│   ├── pipeline.py
│   ├── server.py
│   └── utils/
│       ├── __init__.py
│       ├── chunking.py
│       ├── embedding.py
│       └── vector_db.py
├── config/
│   ├── pipeline_config.json
│   └── server_config.json
├── data/
│   └── README.md
├── output/
│   └── .gitkeep
└── db/
    └── .gitkeep

❓ トラブルシューティング

• Docker が見つからない：Docker がインストールされ、実行中であることを確認してください。docker --version で確認できます。
• 「Invalid reference format」エラー：このよくあるエラーは、次の 2 つの原因で発生することがあります。
  1. ビルド手順の未実行：サーバーイメージをビルドする前に、MCP サーバーを実行しようとしました。サーバーを実行する前に、必ず docker-compose build server を実行してください。
  2. Docker と Docker Compose の混在：Windows のバッチファイルは、一貫して Docker Compose を使用するように更新されています。それでもこのエラーが発生する場合は、このリポジトリの最新バージョンのバッチファイルを使用していることを確認してください。
• API キーの問題：ご心配には及びません。API キーなしで、無料のローカル埋め込みモデルを使用できます。
• sentence-transformers パッケージが見つからない：無料モデルを選択すると、必要なパッケージはシステムによって自動的にインストールされます。
• Chroma データベースが見つからない：まずパイプラインを実行して、ドキュメントを処理してください。
• 接続の問題：MCP の設定にあるパスが、実行スクリプトの正しい場所を指していることを確認してください。
• Windows のパスの問題：Windows でパスに問題が発生する場合は、JSON 設定内のパスに二重のバックスラッシュ（\\）を使用してください。
• 埋め込みモデルの不一致：サーバーはデータベースの作成に使用されたモデルを自動的に検出し、検索にも同じモデルを使用します。

ドキュメントのチャンク分割に関する問題

チャンク分割の不一致

ファイル間でチャンク分割に一貫性がない場合、次の原因が考えられます。

• ドキュメントタイプ検出システムが以前の判定を記憶している
• spaCy の依存関係が不足している
• 設定ファイルと環境変数が競合している

解決方法：

• パイプラインは実行ごとにドキュメントタイプの記憶を自動的にリセットします
• spaCy がインストールされていることを確認してください：pip install spacy && python -m spacy download en_core_web_md
• .env ファイルと設定ファイルの内容に一貫性があることを確認してください

PDF の処理

次の場合、PDF が適切にチャンク分割されないことがあります。

• PDF にテキストではなく、スキャン画像が含まれている
• PDF の書式が複雑である
• 必要な依存関係が不足している

解決方法：

• パイプラインでは、診断機能を強化して PDF の処理を改善しています
• スキャンした PDF では、事前に OCR 処理を行うことを検討してください
• PyPDF をインストールしてください：pip install pypdf

🔬 高度な設定

高度なユースケースでは、パイプラインとサーバーをカスタマイズできます。

• カスタム埋め込み関数：独自の埋め込みロジックを作成します
• ドキュメントタイプの分類：ドキュメントタイプの検出方法を変更します
• チャンク化の動作：特定のニーズに合わせてチャンク化のパラメーターを調整します
• チャンク分析：/chunk_analysis のテストツールを使って、標準的なチャンク化方法と拡張されたチャンク化方法を比較します。

  # First build the Docker container
  cd chunk_analysis
  docker-compose build
  
  # Then run the tests
  ./run_tests.sh
  

チャンク化戦略

パイプラインでは、ドキュメントの種類に応じて次のチャンク化戦略を使用します。

• 科学論文：セクションごとに分割し、参考文献を保持します
• 財務ドキュメント：表と数値のセクションを保持します
• 技術ドキュメント：コードブロックと例を保持します
• 物語文：spaCy NLP による意味的な境界を使用します
• 一般：セクション見出しと意味的な区切りを使ったバランスの取れた方法です

利用可能な場合、すべてのドキュメントタイプで、チャンク化の推奨方法として spaCy を使用します。

📄 ライセンス

MIT

---

donphi が ❤️ を込めて作成しました