Local RAG MCP Server
ローカル PC またはサーバー上の共有フォルダにある文書ファイルを AI から自然言語で検索できる MCP (Model Context Protocol) サーバー です。
PDF・Word・Excel・PowerPoint・画像・ソースコードなど多様なファイルを自動変換してベクトルインデックス化し、Ollama の埋め込みモデルを使用したセマンティック検索 (RAG) を提供します。CLINE などの MCP 対応クライアントから利用できます。
> 📋 更新履歴は CHANGELOG.md を参照してください。
> [!NOTE]
> 【重要】Ollama v0.17.x系における glm-ocr の不具合について
> かつて Ollama v0.17.0 〜 v0.17.5 までのバージョンにおいて、glm-ocr モデルを使用した際の OCR 結果が異常(空白等)になる問題が発生していましたが、Ollama v0.17.6 以降でこの問題は修正されています。
>
> 現在最新の Ollama を使用していれば問題ありませんが、もし v0.17.0 〜 v0.17.5 をお使いの場合は、v0.17.6 以上へのアップデートを推奨します。
機能一覧
| 機能 | 説明 |
|---|---|
| 文書変換 | PDF・DOCX・XLSX・PPTX・画像 → Markdown 変換(OCR対応) |
| ハイブリッド検索 | ベクトル検索 (Dense) と BM25 (Sparse) を組み合わせた高精度検索 |
| リランキング | FlashRank による検索結果の再評価・最適化 |
| アクセス制御 (ACL) | API キーによるルートフォルダ単位の検索権限管理 |
| 差分同期 | 更新ファイルのみ再インデックス(mtime + 内容ハッシュ管理) |
| ハッシュベースOCRスキップ | 内容が変わっていないファイルのOCR処理をスキップ |
| コンテキスト制限 | 巨大ドキュメント(1MB超)の自動圧縮・LLMコンテキスト上限を超えない制御 |
| SSE / Stdio 両対応 | CLINE (SSE) や stdio MCP クライアントどちらでも利用可能 |
アーキテクチャ概要```mermaid
flowchart TD
subgraph UserSide["👤 ユーザー側"]
Client["🖥️ MCPクライアント<br/>(CLINE 等)"]
end
subgraph ServerSide["⚙️ サーバー側 (Local RAG MCP Server)"]
Server["server.py<br/>MCPサーバー<br/>(SSE / stdio)"]
RAG["rag_engine.py<br/>RAGエンジン"]
Chroma[("ChromaDB<br/>ベクトルDB<br/>(Dense検索)")]
BM25[("BM25インデックス<br/>(Sparse検索)")]
FlashRank["FlashRank<br/>リランキングモデル"]
ModelCache[("models/flashrank_cache/<br/>モデルキャッシュ")]
Ollama_Embed["Ollama<br/>埋め込みモデル"]
Converter["file_converter.py<br/>文書変換エンジン"]
OCR_Ollama["Ollama<br/>glm-ocr (OCR)"]
OCR_Paddle["PaddleOCR"]
UpdateIdx["update_index.py<br/>インデックス更新スクリプト<br/>(手動 / cron / タスクスケジューラー)"]
Docs["📁 ソース文書<br/>(PDF / DOCX / 画像 等)"]
end
Client <-->|"MCP Protocol<br/>(検索 / ツール実行 / 応答)"| Server
Server <--> RAG
RAG <--> Chroma
RAG <--> BM25
RAG <--> Ollama_Embed
RAG <--> FlashRank
FlashRank <--> ModelCache
RAG <--> Converter
Converter <-->|"ocr_engine"| OCR_Ollama
Converter <-->|"ocr_engine"| OCR_Paddle
Docs --> RAG
UpdateIdx -->|"差分 / フル再構築"| RAG
RAG -->|"ハイブリッド検索結果"| FlashRank
FlashRank -->|"リランキング済み結果"| Server
# 🔧 管理者向けガイド
## 1. 必要環境
- Python 3.10 以上
- Ollama(ローカル実行)
- 埋め込みモデル(例: `nomic-embed-text-v2-moe:latest`)
- OCR モデル(例: `glm-ocr:latest`)
## 2. インストール```bash
# 1. リポジトリを任意のフォルダに配置
# 2. 仮想環境を作成して有効化
python -m venv venv
venv\Scripts\activate # Windows
# source venv/bin/activate # Linux / macOS
# 3. 依存パッケージをインストール
pip install -r requirements.txt
2.1 OCRエンジンの選択
本システムは2種類のOCRエンジンをサポートしています:
| OCRエンジン | 特徴 | インストール |
|---|---|---|
| Ollama glm-ocr(デフォルト) | Ollamaサーバー経由でOCR実行。追加インストール不要。GPUはOllama側で管理。 | なし(Ollamaにglm-ocrモデルをプルするのみ) |
| PaddleOCR(オプショナル) | ローカル実行のOCRライブラリ。Ollamaに依存せず動作可能。 | 別途インストール必要 |
Ollama glm-ocrを使用する場合(デフォルト)```bash
Ollamaにglm-ocrモデルをプル
ollama pull glm-ocr:latest
`config.json`で以下のように設定:```json
{
"ocr_engine": "ollama",
"ocr_model": "glm-ocr:latest"
}
PaddleOCRを使用する場合(オプショナル)
PaddleOCRはオプショナルな依存関係です。使用する場合は以下の手順でインストールしてください。
CPU版のインストール(推奨):```bash
pip install paddlepaddle paddleocr
**GPU版のインストール(上級者向け)**:```bash
pip install paddlepaddle-gpu paddleocr
> [!WARNING]
> GPU版の導入は特定のDLL (cudnn64_8.dll, zlibwapi.dll) の手動配置が求められるため上級者向けです。どうしてもGPU版を利用したい場合は、PADDLE_GPU_SETUP.md の手順に従って個別にセットアップを行ってください。
config.jsonで以下のように設定:```json
{
"ocr_engine": "paddleocr",
"paddleocr_use_gpu": false
}
> [!TIP]
> PaddleOCRがインストールされていない状態で`ocr_engine: "paddleocr"`を設定した場合、自動的にOllama glm-ocrにフォールバックします。
## オフライン環境へのインストール
ネットワークに接続されていないUbuntu端末へのインストール方法を提供しています。
### Dockerイメージ方式(推奨)
Dockerイメージを使用して、環境を完全にパッケージングできます。```bash
# Windows側(オンライン環境)
.\scripts\export-docker-image.ps1 -IncludeModels
# Ubuntu側(オフライン環境)
./scripts/import-docker-image.sh
docker-compose up -d
自己完結型パッケージ方式
Python環境が不要なスタンドアロンバイナリを生成できます。```bash
ビルド
python build-standalone.py --clean
詳細な手順は docs/OFFLINE_INSTALL.md を参照してください。
### Docker環境でのユーティリティ実行
Docker環境では、以下のコマンドでユーティリティを実行できます:```bash
# インデックスの手動更新
docker-compose exec mcp-server python update_index.py
# サーバーの停止(通常は docker-compose stop を使用)
docker-compose exec mcp-server python stop.py
3. 初期設定
config.json
config.json を自分の環境に合わせて編集してください。```json
{
"source_docs_dir": "C:\path\to\your\documents",
"docs_dir": "converted_docs",
"embedding_model": "nomic-embed-text-v2-moe:latest",
"ocr_engine": "paddleocr",
"ocr_model": "glm-ocr:latest",
"extra_text_extensions": [".conf", ".ini", ".env", ".log"],
"paddleocr_use_gpu": false,
"ollama_base_url": "http://localhost:11434",
"db_dir": "./chroma_db",
"collection_name": "mcp_rag_collection",
"search_settings": {
"hybrid_search_enabled": true,
"reranking_enabled": true,
"flashrank_model": "ms-marco-MultiBERT-L-12",
"flashrank_cache_dir": "models/flashrank_cache",
"flashrank_offline_mode": false
},
"context_management": {
"detail_level": "auto",
"max_context_tokens": 128000,
"max_document_tokens": 12000,
"max_search_result_tokens": 8000,
"summary_model": null,
"ollama_base_url": null
}
}
| キー | 説明 |
|------|------|
| `source_docs_dir` | 元文書フォルダの**絶対パスまたは相対パス**(server.py からの相対) |
| `docs_dir` | 変換済み Markdown の保存先(相対パス) |
| `embedding_model` | Ollama の埋め込みモデル名 |
| `ocr_engine` | OCRエンジン(`ollama` または `paddleocr`) |
| `ocr_model` | PDF/画像の OCR に使う Ollama モデル名 (ocr_engine が ollama の場合) |
| `extra_text_extensions` | テキストとしてそのまま読み込む追加の拡張子リスト(例: `[".conf", ".env"]`) |
| `paddleocr_use_gpu` | PaddleOCR実行時にGPUを使用するかどうか (`true` または `false`) |
| `ollama_base_url` | Ollama の API エンドポイント |
| `db_dir` | ChromaDB の保存先(相対パス) |
| `collection_name` | ChromaDB コレクション名 |
| `search_settings` | 検索エンジンに関する詳細設定(以下参照) |
| `context_management` | 巨大ドキュメントのコンテキスト制限設定(以下参照) |
### search_settings の詳細
| パラメータ | 説明 |
|------------|------|
| `hybrid_search_enabled` | ハイブリッド検索(ベクトル検索 + BM25)を有効にするか (`true`/`false`) |
| `reranking_enabled` | FlashRank によるリランキングを有効にするか (`true`/`false`) |
| `flashrank_model` | 使用する FlashRank モデル名 |
| `flashrank_cache_dir` | FlashRank モデルの保存先ディレクトリ |
| `flashrank_offline_mode` | オフラインモードを有効にするか (`true`/`false`) |
### context_management の詳細
| パラメータ | 説明 |
|------------|------|
| `detail_level` | ドキュメント詳細度: `"auto"`(デフォルト、上限超過時のみ圧縮) / `"summary"`(常に圧縮) / `"full"`(常に全文) |
| `max_context_tokens` | LLMのコンテキスト上限トークン数(デフォルト: 128000) |
| `max_document_tokens` | `get_document_content` の最大返却トークン数(デフォルト: 12000) |
| `max_search_result_tokens` | `search_documents` の最大返却トークン数(デフォルト: 8000) |
| `summary_model` | LLM要約用のOllamaモデル名(オプション。`null` の場合は構造ベース圧縮のみ使用) |
| `ollama_base_url` | 要約専用の別OllamaサーバーURL(オプション。`null` の場合はデフォルトの `ollama_base_url` を使用) |
#### 巨大ドキュメント(1MB超)の扱いについて
本サーバーは **1MB超の単一Markdownファイル** など、巨大ドキュメントに対して自動的にコンテキスト制限を適用します。
**仕組み:**
1. `get_document_content` や `search_documents` の返却時に、トークン数を自動カウント
2. 設定された上限(`max_document_tokens` / `max_search_result_tokens`)を超える場合、Markdownの見出し構造を尊重して段階的に圧縮
3. 圧縮時は「先頭文 + 重要キーワード文 + 末尾文」を残し、省略部分は `get_document_content(path=..., section=...)` で詳細取得可能と明示
**後方互換性:**
- `config.json` に `context_management` が未設定の場合、`detail_level: "auto"` で動作(上限内なら全文返却、超過時のみ圧縮)
- 通常サイズのドキュメント(数KB〜数百KB)は従来通り全文返却
#### FlashRank オフライン運用について
インターネット接続がない環境でリランキング機能を使用する場合は、以下の手順でセットアップを行ってください。
**推奨モデル:**
- デフォルト: `ms-marco-MultiBERT-L-12`(軽量・高速)
**フォルダ構成:**```
models/
└── flashrank_cache/
└── ms-marco-MultiBERT-L-12/
├── tokenizer.json
├── tokenizer_config.json
├── special_tokens_map.json
└── *.onnx (モデルファイル)
オフラインモードの設定手順:
-
モデルのダウンロード(オンライン環境で実行)
- インターネット接続のある環境でサーバーを起動し、初回の検索を実行すると自動的にモデルがダウンロードされます
- または、手動でモデルファイルを上記フォルダ構成で配置します -
オフラインモードの有効化
-config.jsonでflashrank_offline_mode: trueを設定します
- これにより、インターネット接続を試みずにローカルのモデルファイルを使用します -
動作確認
- オフライン環境でサーバーを起動し、検索が正常に動作することを確認してください
ドキュメントフォルダの構成
本サーバーの基本的な運用思想は、既存の共有フォルダをドキュメントフォルダ(source_docs_dir)として設定することです。ユーザーは普段通りに共有フォルダへファイルを追加・更新・削除できます。セキュリティは OS(Windows / Linux)のフォルダアクセス権で管理します。
source_docs_dir 直下に ルートフォルダ を作成し、その中に文書を格納してください。
> [!IMPORTANT]
> ルートフォルダ名は英語を推奨します。
> 日本語フォルダ名も使用できますが、CLINE からデフォルト検索スコープを設定する際に URL への記載が必要になります。詳細は「ユーザー向け:CLINE への接続設定」を参照してください。```
documents/ ← source_docs_dir
├── Public/ ← ルートフォルダ(誰でもアクセス可)
│ └── manual.pdf
├── Group A/ ← グループA専用
│ └── design_spec.docx
└── Group B/ ← グループB専用
└── report.xlsx
### acl.json(検索アクセス権限の設定)
`acl.json` は **「API キーとルートフォルダのアクセス権限のマッピング」** を管理します。フォルダへの OS 権限とは独立した検索権限の設定です。```json
{
"_comment": "MCPサーバーのグループアクセス制御設定ファイル。",
"_default": {
"name": "Public",
"allowed_roots": ["Public"]
},
"your-api-key-here": {
"name": "Group A",
"allowed_roots": ["Group A", "Public"]
}
}
| エントリ | 説明 |
|---|---|
_default |
API キー未設定で接続した場合に適用される権限 |
"キー文字列" |
そのキーを提示したクライアントが検索可能なルートフォルダを定義 |
> [!TIP]
> 複数の API キーを指定可能
> x-api-key ヘッダーや URL クエリパラメータには、カンマ区切りで複数の API キー(例: key1,key2)を指定できます。この場合、指定されたすべてのキーに紐づく allowed_roots がマージ(和集合)され、複数のグループの文書を横断的に検索できるようになります。
> API キーは推測されにくいランダムな文字列を使用してください(例: openssl rand -hex 32 で生成)。
注意: acl.json の変更はサーバー再起動まで反映されません。
3.4. 初回インデックスの作成
サーバーを初めて起動する前に、ドキュメントのインデックスを作成(データベース登録)する必要があります。サーバーの起動だけでは自動的にインデックスは作成されません。
以下のコマンドを実行して、ドキュメントのインデックスを作成してください。```bash
ドキュメントの同期(初回・差分更新)
python update_index.py
初回はドキュメントの量に応じて時間がかかる場合があります(特に OCR が必要な場合)。この処理が完了してから、次の「4. サーバーの起動・停止」へ進んでください。
## 4. サーバーの起動・停止
### 起動(SSE モード・CLINE などの HTTP クライアント向け)```bash
python server.py --transport sse --port 8000
起動(stdio モード・MCP 標準入出力クライアント向け)```bash
python server.py --transport stdio
### 停止```bash
python stop.py
または、サーバーを起動したターミナルで Ctrl+C を押してください。
5. バックグラウンド常駐(本番運用)
Ubuntu / Linux(systemd)
systemd サービスとして登録すると、OS 起動時に自動起動・クラッシュ時に自動再起動されます。
サービスファイルの作成```bash
sudo nano /etc/systemd/system/local-rag-mcp.service
以下の内容を貼り付けてください(パスは実際の環境に合わせてください)。```ini
[Unit]
Description=Local RAG MCP Server
After=network.target
[Service]
Type=simple
User=your-username
WorkingDirectory=/home/your-username/local-rag-mcp-server
ExecStart=/home/your-username/local-rag-mcp-server/venv/bin/python server.py --transport sse --port 8000
Restart=on-failure
RestartSec=5
StandardOutput=append:/home/your-username/local-rag-mcp-server/server.log
StandardError=append:/home/your-username/local-rag-mcp-server/server.log
[Install]
WantedBy=multi-user.target
サービスの有効化と起動```bash
sudo systemctl daemon-reload
sudo systemctl enable local-rag-mcp # OS起動時に自動起動
sudo systemctl start local-rag-mcp # 今すぐ起動
sudo systemctl status local-rag-mcp # 状態確認
#### 操作コマンド```bash
sudo systemctl stop local-rag-mcp # 停止
sudo systemctl restart local-rag-mcp # 再起動
journalctl -u local-rag-mcp -f # リアルタイムログ確認
Windows(タスクスケジューラー)
PowerShell で以下を実行します(管理者権限で実行してください)。```powershell
サーバーをログイン時に自動起動
$action = New-ScheduledTaskAction -Execute "D:\tools\local-rag-mcp-servr\venv\Scripts\python.exe"
-Argument "server.py --transport sse --port 8000" `
-WorkingDirectory "D:\tools\local-rag-mcp-servr"
$trigger = New-ScheduledTaskTrigger -AtLogOn
Register-ScheduledTask -TaskName "LocalRagMCPServer" -Action $action -Trigger $trigger
-RunLevel Highest -Force
## 6. インデックスの自動更新
インデックス更新はサーバーを停止せずに実行できます。深夜など負荷の低い時間帯に自動実行することを推奨します。
> **補足**: インデックス更新中もサーバーはリクエストを受け付け続けます。更新完了後に新しいドキュメントが検索対象になります。
### 手動更新```bash
# 差分更新(通常はこちら)
python update_index.py
# 強制フル再構築
python update_index.py --force
Ubuntu / Linux(cron で毎日深夜2時に自動実行)```bash
crontab -e
以下の行を追加します。```cron
0 2 * * * cd /home/your-username/local-rag-mcp-servr && ./venv/bin/python update_index.py >> server.log 2>&1
Windows(タスクスケジューラーで毎日深夜2時に自動実行)```powershell
$action2 = New-ScheduledTaskAction -Execute "D:\tools\local-rag-mcp-servr\venv\Scripts\python.exe"
-Argument "update_index.py" `
-WorkingDirectory "D:\tools\local-rag-mcp-servr"
$trigger2 = New-ScheduledTaskTrigger -Daily -At "02:00"
Register-ScheduledTask -TaskName "LocalRagIndexUpdate" -Action $action2 -Trigger $trigger2
-RunLevel Highest -Force
### 6.1 ハッシュベースOCRスキップと .source_hashes.json の仕様
OCR処理は時間がかかるため、本システムでは `.source_hashes.json` を用いて元ファイルの内容に変更がない(ハッシュ値が同一)場合はOCR処理を自動的にスキップします。
#### `.source_hashes.json` の仕様と生成場所
- **自動生成(通常運用時)**
`update_index.py` などによるインデックス更新時、RAGエンジンが各ドキュメントのハッシュ値を計算し、`config.json` で指定した `db_dir`(デフォルトは `chroma_db`)直下の `.source_hashes.json` に自動保存・更新します。
- **手動生成(移行用)**
すでに Markdown に変換済みの環境において、次回以降の不要なOCR処理を避けるため、事前にハッシュファイルのみを一括生成することができます。```bash
python _generate_source_hashes.py
```
- **生成場所の整合性**
自動生成(`update_index.py`)の場合も、手動生成(`_generate_source_hashes.py`)の場合も、**全く同じ場所(`db_dir` 配下の `.source_hashes.json`)** に生成されます。そのため手動生成を行っても、ソースコードからは正常に参照・比較が行われ、OCRスキップが正しく機能します。
## 7. ファイル監視による自動インデックス更新(上級者向け)
`file_watcher.py` は `watchdog` ライブラリを使ってソースフォルダを常時監視し、ファイルの追加・更新・削除・移動を検知すると **即座にインデックスを更新**するスクリプトです。
### 起動方法```bash
# サーバーとは別のターミナルで起動
python file_watcher.py
⚠️ リスクと注意事項
> [!WARNING]
> file_watcher.py の使用には以下のリスクがあります。十分に理解した上でご利用ください。
| リスク | 説明 |
|---|---|
| 高負荷 | ファイルが頻繁に更新される環境では OCR / 埋め込み処理が連続して走り続け、CPU・メモリを大量消費します |
| DB競合 | update_index.py や CLINE 経由の update_index ツールと同時に実行すると、ChromaDB への書き込みが競合する可能性があります |
| 誤削除の伝播 | ファイルの誤削除をそのまま検知してインデックスからも即座に削除します。元に戻すにはファイルを復元後に update_index.py の再実行が必要です |
| プロセス管理 | stop.py は server.py のみを停止します。file_watcher.py は別途 Ctrl+C で停止してください |
推奨運用
- 更新頻度が低い環境:
update_index.pyの定期実行(cron / タスクスケジューラー)を推奨します - リアルタイム反映が必要な環境:
file_watcher.pyの使用を検討できますが、上記リスクを踏まえた上でご利用ください
8. トラブルシューティング
Ollama に接続できない
- Ollama が起動しているか確認:
ollama list config.jsonのollama_base_urlが正しいか確認
ChromaDB の初期化エラー
データベースが破損している場合は自動的に再作成されます。手動で削除したい場合は chroma_db/ フォルダを削除してください。
PDF の文字が認識されない / OCR が空白出力になる
画像型 PDF の場合は OCR モデルが使用されます。config.json の ocr_model に適切なマルチモーダルモデルを指定してください。
Ollama v0.17.x で glm-ocr を使用している場合
> [!NOTE]
> Ollama v0.17.0 〜 v0.17.5 において glm-ocr モデルに非互換の不具合が確認されていましたが、この問題は Ollama v0.17.6 以降で修正されました。
対処法:
- Ollama のバージョンを v0.17.6 以上にアップデートしてください。
- アップデートが困難な場合は、OCR エンジンを "paddleocr" に切り替えるか、Ollama を v0.16.3 にダウングレードしてください。
なお、file_converter.py は OCR 出力が明らかに異常な場合(空文字・極端に短い出力・同一文字の繰り返しなど)を自動検出し、OCR 失敗として空のテキストを返すよう対応しています。ログに OCR validation failed: のメッセージが出た場合は、Ollama のアップデートをご検討ください。
バックスラッシュパスのデータが残っている
Windows 環境の旧データが残っている場合は以下を実行してください。```bash
python _cleanup_db.py
### インデックスロックエラー
同時に複数のインデックス更新が走った場合に発生します。しばらく待ってから再試行してください。
---
# 👤 ユーザー向けガイド
## CLINE への接続設定
管理者から提供された URL・API キーを CLINE の MCP サーバー設定に追加してください。
### stdio モード(ローカル実行・推奨)
サーバーをローカルで直接起動する場合は `stdio` モードを使用します。SSEモードと異なり、HTTPサーバーを起動する必要がなく、セキュリティ的にも安全です。```json
{
"mcpServers": {
"local-rag": {
"command": "python",
"args": ["server.py", "--transport", "stdio"],
"cwd": "D:\\tools\\local-rag-mcp-server",
"env": {
"MCP_API_KEY": "your-api-key-here",
"DEFAULT_ROOTS": "Group A",
"DEFAULT_CATEGORIES": ""
}
}
}
}
| 環境変数 | 説明 |
|---|---|
MCP_API_KEY |
acl.json に定義した API キー |
DEFAULT_ROOTS |
デフォルトで検索するルートフォルダ(カンマ区切りで複数指定可) |
DEFAULT_CATEGORIES |
デフォルトで検索するサブフォルダ(カンマ区切りで複数指定可) |
> [!TIP]
> Windowsパスを指定する場合、環境変数では D:/tools/documents のようにフォワードスラッシュを使用するか、D:\\tools\\documents のようにバックスラッシュを2つ重ねてください。本サーバーは自動的にフォワードスラッシュに正規化します。
SSE モード(HTTP経由)
SSEモードを使用する場合は、以下のように URL とヘッダーを設定します。
フォルダ名が英語の場合(推奨)
x-roots / x-categories ヘッダーにフォルダ名を直接記載できます。```json
{
"mcpServers": {
"local-rag": {
"url": "http://localhost:8000/sse",
"headers": {
"x-api-key": "your-api-key-here",
"x-roots": "Group A",
"x-categories": ""
}
}
}
}
### フォルダ名に日本語を使っている場合
通常、HTTP ヘッダーに日本語を含めると文字化け(Mojibake)が発生しますが、本サーバーは **CLINE から送られる日本語ヘッダーを自動的にデコードして復元する機能**を備えています。
そのため、多くの場合で特段の配慮なく `x-roots` 等に日本語を記載できます。
> [!TIP]
> もしヘッダーでの指定で正しく動作しない場合は、**URL のクエリパラメータ**に記載することでより確実に設定可能です。
| 目的 | クエリパラメータ | 例 |
|------|----------------|-----|
| ルートフォルダ指定 | `roots=` | `?roots=グループA` |
| サブフォルダ指定 | `categories=` | `?categories=カテゴリA` |
| 複数指定 | カンマ区切り | `?categories=カテゴリA,カテゴリB` |
```json
{
"mcpServers": {
"local-rag": {
"url": "http://localhost:8000/sse?categories=カテゴリA,カテゴリB",
"headers": {
"x-api-key": "your-api-key-here"
}
}
}
}
| パラメータ / ヘッダー | 説明 | 日本語対応 |
|---|---|---|
x-api-key (ヘッダー) |
acl.json に定義した API キー |
― |
x-roots (ヘッダー) |
デフォルトで検索するルートフォルダ | ✅(Mojibake自動修復) |
roots (URL クエリ) |
同上(URLパラメータなら確実) | ✅ |
x-categories (ヘッダー) |
デフォルトで検索するサブフォルダ | ✅(Mojibake自動修復) |
categories (URL クエリ) |
同上(URLパラメータなら確実) | ✅ |
ドキュメントの追加方法
アクセス権を持つ共有フォルダ(ルートフォルダ)に、ファイルをコピーまたは保存するだけです。
> 反映タイミング: ファイルを追加しても検索に即時反映されません。次回の自動インデックス更新後(深夜バッチ等)に反映されます。すぐに反映させたい場合は CLINE のチャット欄に以下のように入力してください。
>> ドキュメントのインデックスを今すぐ更新してください。
>
> CLINE が自動的に update_index ツールを呼び出し、バックグラウンドで更新を開始します。進捗を確認したい場合は インデックスの更新状況を教えてください。 と入力してください。
アクセス権について
- フォルダの読み書き権限は OS のファイル共有設定で管理します
- MCP サーバーの API キーは「どのルートフォルダを検索できるか」を制御するものです
- フォルダへの OS アクセス権があっても、API キー権限がなければ検索できません(逆も同様)
API キーを設定しなかった場合の動作
API キーを未設定のまま接続した場合の動作は、acl.json の _default 設定によって決まります。
acl.json の状態 |
動作 |
|---|---|
_default エントリが定義されている |
_default の allowed_roots に指定されたルートフォルダのみ検索可能 |
_default エントリが定義されていない |
全アクセス拒否(「Access denied」エラーになる) |
> 管理者が _default に "Public" などのフォルダを設定している場合は、API キーなしでも Public フォルダのみ検索できます。自分専用のフォルダにアクセスしたい場合は API キーの発行を管理者に依頼してください。
対応ファイル形式
| 形式 | 拡張子 | 備考 |
|---|---|---|
.pdf |
テキスト抽出 + 画像ページは OCR | |
| Word | .docx |
テキスト抽出 |
| Excel | .xlsx |
全シートのセル値を抽出 |
| PowerPoint | .pptx |
全スライドのテキストを抽出 |
| 画像 | .png
.jpg
.jpeg
.bmp |
OCR でテキスト抽出 |
| テキスト | .txt
.md
+ extra_text_extensions で指定したもの |
そのまま読み込み |
| 設定ファイル等 | .json
.xml
.yaml
.yml
.toml
.ini
.env
.log
.conf |
そのまま読み込み |
| Web | .html
.htm
.css
.js
.ts |
そのまま読み込み |
| Python | .py |
そのまま読み込み |
| C / C++ | .c
.cpp
.cc
.cxx
.h
.hpp
.hxx |
そのまま読み込み |
| Verilog / SystemVerilog | .v
.sv
.svh
.vh |
そのまま読み込み |
| Rust | .rs |
そのまま読み込み |
| Go | .go |
そのまま読み込み |
| Java / Kotlin | .java
.kt |
そのまま読み込み |
| シェルスクリプト等 | .sh
.bash
.bat
.ps1 |
そのまま読み込み |
| その他言語 | .rb
.php
.swift
.cs |
そのまま読み込み |
> 対応していない形式: .xls(旧 Excel)・.doc(旧 Word)・動画・音声ファイルなど。
制約事項
| 項目 | 制約内容 |
|---|---|
| 検索範囲 | 自分の API キーに紐づいたルートフォルダのみ検索可能 |
| API キー未設定時 | acl.json の _default 設定に従う |
| 取得件数 | 1回の検索でデフォルト5件(n_results パラメータで変更可) |
| リアルタイム反映 | ファイル追加後は次回インデックス更新まで検索に反映されない |
| OCR 精度 | 画像型 PDF や手書き文書は OCR モデルの精度に依存 |
| 日本語フォルダ名 | 検索は問題なし。CLINE の接続設定でのヘッダー指定は文字化けあり(URLクエリ使用推奨) |
管理者に依頼が必要な事項
| 依頼内容 | 説明 |
|---|---|
| API キーの発行 | 初回利用時や CLINE 接続設定に必要 |
| 共有フォルダのアクセス権変更 | 別のルートフォルダへの読み書き権限を追加したい場合 |
| MCP 検索権限の変更 | API キーの allowed_roots を変更したい場合 |
| インデックスの即時更新・強制再構築 | すぐに検索反映させたい場合や検索結果がおかしい場合 |
| 新しいファイル形式への対応 | 未対応形式を追加したい場合(要開発対応) |
よくある質問
Q. 検索しても関連するドキュメントが出てこない
A. 以下を確認してください。
- 共有フォルダにファイルが追加されているか確認する
- 追加後にインデックス更新が完了しているか確認する(深夜バッチ or 手動更新)
- 検索クエリを別の言い回しで試してみる(日本語・英語どちらも可)
Q. 特定のフォルダの文書は見えるがほかのフォルダが見えない
A. API キーの権限(allowed_roots)に対象ルートフォルダが含まれていない可能性があります。管理者にアクセス権の追加を依頼してください。
Q. インデックスを今すぐ更新したい
A. CLINE のチャット欄に以下のように入力するだけで更新が始まります。難しい操作は不要です。
> 更新の開始
>> ドキュメントのインデックスを今すぐ更新してください。
>
>
> 進捗の確認
>> インデックスの更新状況を教えてください。
>
>
> CLINE が update_index / get_sync_status ツールをそれぞれ呼び出します。数十ファイルであれば数分で完了します。
Q. PDF の内容が正しく検索されない
A. 画像として作成された PDF(スキャンした文書など)は OCR 処理されますが、画質や言語によっては精度が下がる場合があります。管理者にご相談ください。
Q. CLINE にサーバーの URL や API キーをどう設定すればいいか
A. 管理者から提供された URL・API キーを CLINE の MCP サーバー設定に入力してください。設定方法は「CLINE への接続設定」を参照してください。
📖 リファレンス
利用できるツール (MCP Tools)
| ツール名 | 説明 |
|---|---|
search_documents |
自然言語クエリでドキュメントを検索(結果は自動的にコンテキスト制限が適用) |
list_roots |
アクセス可能なルートフォルダ一覧 |
list_categories |
アクセス可能なカテゴリ(サブフォルダ)一覧 |
get_document_content |
指定パスのドキュメント取得(巨大ドキュメントは自動圧縮、section で特定セクション詳細取得可) |
list_documents |
インデックス済みドキュメント一覧 |
update_index |
インデックスをバックグラウンドで更新 |
get_sync_status |
インデックス更新の進捗確認 |
search_documents パラメータ
| パラメータ | 型 | 説明 |
|---|---|---|
query |
string | 検索クエリ(必須) |
root |
string | 絞り込むルートフォルダ名(省略可) |
category |
string | 絞り込むカテゴリ名(省略可) |
n_results |
integer | 取得件数(デフォルト: 5) |
get_document_content パラメータ
| パラメータ | 型 | 説明 |
|---|---|---|
path |
string | ドキュメントの相対パス(必須) |
section |
string | 取得するセクションの見出し名(省略可。指定すると該当セクションのみ全文取得) |
> セクション指定の例: get_document_content(path="manual.md", section="1. インストール手順")
>
> 巨大ドキュメントで特定の章だけ詳しく読みたい場合に使用します。セクション名が見つからない場合は、利用可能なセクション一覧が返されます。
ファイル構成```
local-rag-mcp-servr/
├── server.py # MCP サーバー本体(SSE / stdio)
├── rag_engine.py # RAG エンジン(ChromaDB / Ollama)
├── context_budget.py # コンテキスト予算管理(巨大ドキュメント圧縮・トークン制限)
├── file_converter.py # 文書変換エンジン(PDF OCR 等)
├── file_watcher.py # ファイル変更監視(watchdog)
├── update_index.py # インデックス手動更新ツール
├── _generate_source_hashes.py # 既存環境向けハッシュ生成ツール(OCRスキップ用)
├── stop.py # サーバー停止ツール
├── _cleanup_db.py # DB メンテナンスツール(バックスラッシュパス削除)
├── config.json # 設定ファイル
├── acl.json # アクセス制御設定
├── requirements.txt # Python 依存パッケージ
├── CHANGELOG.md # 更新履歴
└── README.md # このファイル
---
## ライセンス
MIT License
### サードパーティライセンス
本プロジェクトは OCR 処理のオプションとして **PaddleOCR** をサポートしています。
PaddleOCR は Apache License 2.0 の下でライセンスされています。```text
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
