MCPクライアントまたはターミナルから、埋め込みAPIに送信することなくプライベート文書を検索できます。
mcp-local-ragは、お使いのマシン上のPDF、DOCX、Markdown、テキストファイルをインデックス化します。検索はセマンティック類似度とキーワードマッチングを組み合わせるため、クエリは意図と、API名、クラス名、エラーコードなどの正確な技術用語の両方にマッチできます。
ローカルで実行: 文書の解析、埋め込み、保存、検索はすべてお使いのマシン上で実行されます。 初期モデルのダウンロード後は、テキストの取り込みと検索はオフラインで動作します。
ハイブリッド検索: セマンティック検索が関連概念を見つけ、キーワードマッチングが正確な技術用語を強調します。
設定可能な埋め込み: 文書の言語とドメインに合ったHugging Face埋め込みモデルを選択できます。
セマンティックチャンキング: 文書は固定文字数ではなくトピックの境界で分割されます。Markdownコードブロックはそのまま保持されます。
MCPとCLI: AIコーディングツールまたはターミナルから直接、同じインデックスを使用できます。
APIキー、Docker、Python、外部データベースは不要です。
Related MCP server: cowork-semantic-search
Node.js 22以降
npmパッケージと埋め込みモデルをダウンロードするための初回利用時のインターネット接続
検索したい文書を含むディレクトリ
BASE_DIRをそのディレクトリに設定します。これはファイル操作のセキュリティ境界でもあります。以下の/absolute/path/to/your/documentsをディレクトリの絶対パスに置き換えてください。
mcp-local-ragは標準のMCPプロトコルをローカルstdioサーバー経由で使用するため、ローカルMCPサーバーをサポートするAIコーディングツールやその他のMCPホストで動作します。
以下の例のいずれかを使用するか、npx -y mcp-local-ragを登録し、クライアントのMCP設定形式を使用してBASE_DIRを設定してください。
Claude Codeの場合: 次のコマンドを実行します:
claude mcp add local-rag --scope user --env BASE_DIR=/absolute/path/to/your/documents -- npx -y mcp-local-ragCodexの場合: ~/.codex/config.tomlに追加します:
[mcp_servers.local-rag]
command = "npx"
args = ["-y", "mcp-local-rag"]
[mcp_servers.local-rag.env]
BASE_DIR = "/absolute/path/to/your/documents"OpenCodeの場合: ~/.config/opencode/opencode.json（またはopencode.jsonc）に追加します:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"local-rag": {
"type": "local",
"command": ["npx", "-y", "mcp-local-rag"],
"environment": {
"BASE_DIR": "/absolute/path/to/your/documents"
}
}
}
}Cursorの場合: ~/.cursor/mcp.jsonに追加します:
{
"mcpServers": {
"local-rag": {
"command": "npx",
"args": ["-y", "mcp-local-rag"],
"env": {
"BASE_DIR": "/absolute/path/to/your/documents"
}
}
}
}クライアントを再起動し、インデックスの構築を依頼します:
Sync all documents in the configured root and wait until it finishes.最初の同期ではデフォルトの埋め込みモデル（約90 MB）をダウンロードし、取り込みが始まるまでに1〜2分かかる場合があります。以降の実行ではローカルキャッシュを使用します。
同期が完了したら:
What does the API documentation say about authentication?MCPクライアントなしでCLIを使用する場合:
npx mcp-local-rag ingest ./docs/
npx mcp-local-rag query "authentication API"CLIはデフォルトで現在のディレクトリを文書ルートとして使用します。同じデフォルトインデックスを使用するには、両方のコマンドを同じディレクトリから実行するか、BASE_DIRとDB_PATHを明示的に設定してください。
一部の文書セットは、機密性や組織のポリシーにより、ホスト型の埋め込みサービスに送信できません。インデックスをローカルに保持することで、クエリごとのAPIコストを追加することなく検索可能になります。
セマンティック検索だけでは、技術文書で重要な正確な識別子を見逃す可能性があります。キーワードの再ランキングにより、自然言語検索を犠牲にすることなく、これらの用語を可視化できます。
入力 | 取り込み方法 |
PDF、DOCX、TXT、Markdown | ファイル取り込みまたはディレクトリ同期 |
クライアントがすでに取得したHTML |
|
メモリ内のプレーンテキストまたはMarkdown | 安定したソース識別子を持つ |
HTMLの取得はサーバーに組み込まれていません。MCPクライアントがページを取得し、そのHTMLをingest_dataに渡すことができます。
Excel、PowerPoint、スタンドアロン画像、ソースコードのファイル拡張子は、ファイル取り込みではサポートされていません。PDFはオプションでローカルのビジョンモデルを使用して図を説明できますが、これはOCRや画像検索ではありません。
ツール | 目的 |
| 設定されたすべてのルートまたは1つのパスとインデックスを調整 |
| 実行中の同期ジョブをポーリング |
| 1つのファイルを取り込むか置き換える |
| クライアントがすでに保持しているテキスト、Markdown、またはHTMLを取り込む |
| セマンティックマッチングとキーワードブーストで検索 |
| 検索結果から周囲のチャンクを読み取る |
| サポートされているファイルとその取り込み状態を表示 |
| インデックス化されたファイルまたは |
| インデックスと検索の状態を表示 |
sync_startは新規および変更されたファイルを取り込み、バイト単位で同一のファイルをスキップし、存在しなくなったファイルのインデックスエントリを削除します:
Sync everything under the configured document roots and wait for completion.このツールは即座にjobIdを返します。クライアントはsync_statusをポーリングして、状態がsucceededまたはfailedになるまで待機する必要があります。同期は視覚的なキャプションを生成しません。MCPサーバー環境でSTORE_IMAGES=trueを設定すると、同期によって選択された新規または変更されたファイルのサポートされているPDFおよびDOCX画像が保存されます。変更されていないファイルはスキップされたままです。
サーバープロセスによって保持される同期ジョブは1つだけです。新しいジョブは完了したレコードを置き換え、サーバーを再起動すると破棄されます。
ingest_fileはPDF、DOCX、TXT、Markdownを受け入れます。MCPファイルパスは絶対パスである必要があり、設定された文書ルート内に収まる必要があります:
Ingest the document at /Users/me/docs/api-spec.pdf.同じパスを再取り込みすると、既存のチャンクが置き換えられます。
What does the API documentation say about authentication?
Find the documented behavior of ERR_CONNECTION_REFUSED.結果には、テキスト、ソースパス、タイトル、チャンクインデックス、関連性スコア、およびそのチャンクに保存された画像が含まれます。MCPは各画像を、その結果IDとペアになった画像コンテンツブロックとして返します。CLIのqueryは、各結果に{ imageIndex, mimeType, data }のimages配列を含めます。回答にさらにコンテキストが必要な場合は、結果からchunkIndexとfilePathまたはsourceのいずれかをread_chunk_neighborsに渡します:
Read the surrounding chunks for that authentication result.query_documentsとlist_filesはどちらも、オプションの絶対scopeパスプレフィックス、またはプレフィックスのリストを受け入れます。プレフィックスは正確なパスとその子孫にマッチします。
MCPクライアントがページを取得した後、ingest_dataを使用します:
Fetch https://example.com/docs and ingest the HTML.サーバーはメインの記事を抽出し、Markdownに変換して、指定されたソース識別子の下に保存します。同じソースを再利用すると、既存のコンテンツが更新されます。
外部コンテンツをインデックス化する際は、ソースサイトの利用規約と著作権を尊重してください。
ビジュアルモードは、図が多いPDFページに生成されたキャプションを追加します。これはオプトインであり、通常の取り込み中にビジョンモデルを読み込みません。
Ingest /Users/me/docs/research-paper.pdf with visual: true.npx mcp-local-rag ingest ./docs/research-paper.pdf --visual画像の保存はビジュアルキャプションとは独立しています。MCPサーバーにSTORE_IMAGES=trueを設定するか、CLIの取り込みと同期に--imagesを渡します:
npx mcp-local-rag ingest ./docs/research-paper.pdf --images
npx mcp-local-rag sync ./docs/ --imagesPDFの保存では、検出された図/表の領域を使用します。DOCXの保存には、既存のMammoth変換が<img>として出力するPNG/JPEG画像のみが含まれます。グラフ、SmartArt、シェイプは個別にレンダリングされません。保存された画像は周囲のテキストに従って最終的なセマンティックチャンクに入り、ランキング、スコア、結果数は変更されません。
|
| PDFの動作 |
false | false | テキストのみ。ビジュアルキャプションや返される画像はありません。 |
true | false | 生成されたキャプションが検索可能なテキストになります。画像は保存も返却もされません。 |
true | true | 生成されたキャプションが検索可能なテキストになり、マッチしたチャンクの画像がインラインで返されます。 |
false | true | 画像は近くの保持されたPDFテキストに添付され、マッチしたチャンクに対してインラインで返されます。VLMはインポート、ロード、実行されません。 |
プロファイル | モデルキャッシュ | ユースケース |
| 約250 MB | 軽量なビジュアルインデックス作成 |
| 約2.9 GB | ラベル、注釈、その他の画像内テキストを含む図 |
MCP経由でvisualQuality: "quality"、CLI経由で--visual-quality qualityを使用して大きいモデルを選択します。測定されたCPU推論はfastの約2倍遅かったですが、結果はハードウェアとモデルの更新に依存します。
キャプションは補助的なテキストであり、忠実な転写ではありません。取得したキャプションと文書テキストは、指示ではなく信頼できない入力として扱ってください。
高いリミットでは、マッチしたチャンクとその添付ファイルがモデル/クライアントのコンテキスト上限に近づく可能性があります。呼び出しモデルの利用可能なコンテキストを考慮してクエリリミットを選択してください。
CLIはMCPクライアントなしで同じパーサー、エンベッダー、ベクターストアを使用します:
npx mcp-local-rag ingest ./docs/
npx mcp-local-rag sync ./docs/
npx mcp-local-rag query "authentication API"
npx mcp-local-rag query "auth" --scope /docs/api --scope /docs/guide
npx mcp-local-rag read-neighbors --file-path /abs/path.md --chunk-index 5
npx mcp-local-rag list
npx mcp-local-rag status
npx mcp-local-rag delete ./docs/old.pdf
npx mcp-local-rag delete --source "https://example.com/docs"--db-path、--cache-dir、--model-nameなどのグローバルオプションはサブコマンドの前に置きます。サブコマンドのオプションはその後に置きます:
npx mcp-local-rag --db-path ./my-db query "authentication"完全なコマンドリファレンスについてはnpx mcp-local-rag --helpを実行してください。
CLIはMCPクライアント設定を読み取りません。両方のインターフェースでインデックスを共有する場合は、同じ環境変数またはフラグを設定してください。特に、共有データベースではMODEL_NAMEとCLIの--model-nameが一致している必要があります。
キーワードブーストはデフォルトで有効です。関連性ギャップのグループ化、距離フィルター、ファイルフィルターは、より厳密な結果選択が必要なコーパス向けのオプションコントロールです。
変数 | デフォルト | 説明 |
|
| キーワードブースト係数（0.0〜1.0）。0はキーワード再ランキングを無効にし、1は最大ブーストを適用します。 |
| （未設定） |
|
| （未設定） | 低関連性の結果をフィルタリングします（例: |
| （未設定） | 結果を上位Nファイルに制限します（例: 単一の最良ファイルには |
多くの識別子を含むAPI仕様やその他の文書では、より強いキーワード重みが正確な用語のランキングを改善できます:
"env": {
"RAG_HYBRID_WEIGHT": "0.7"
}0.7: デフォルトよりわずかに強い完全一致リランキング
1.0: 最大のキーワードブースト
取り込み時:
パーサーが入力形式のテキストを抽出します。
セマンティックチャンカーがトピックの境界を見つけ、Markdown コードブロックを保持します。
Transformers.js がローカルで埋め込みを生成します。
LanceDB がチャンク、メタデータ、ベクトル、全文インデックスを保存します。
検索時:
クエリは同じモデルで埋め込みされます。
ベクトル検索が意味的に関連するチャンクを取得します。
設定されている場合、オプションの距離フィルターと関連グループフィルターが候補を絞り込みます。
全文一致が完全一致のクエリ用語を強調します。
Agent Skills は AI アシスタントにクエリと取り込みのガイダンスを提供します:
npx mcp-local-rag skills install --claude-code
npx mcp-local-rag skills install --claude-code --global
npx mcp-local-rag skills install --codexインストールされたスキルは、クエリの作成、結果の絞り込み、HTML の取り込みをカバーします。アシスタントが自動的にアクティブ化しない場合は、mcp-local-rag スキルを明示的に使用するよう依頼してください。
MCP サーバーは環境変数を読み取ります。CLI はリストされたグローバル環境変数とフラグを受け入れます。CLI の取り込みと同期での画像ストレージは --images でのみ有効になります。
環境変数 | CLI フラグ | デフォルト | 説明 |
|
| 現在のディレクトリ | 1 つのドキュメントルート。CLI フラグは |
| N/A | (未設定) | ドキュメントルートの JSON 配列。 |
|
|
| ベクトルデータベースの場所 |
|
|
| モデルキャッシュディレクトリ |
|
|
| Hugging Face 埋め込みモデル |
|
|
| 最大ファイルサイズ（バイト単位） |
|
|
| 最小チャンク長（文字数、1〜10000） |
| N/A |
| MCP サーバーのみ: サポートされている PDF/DOCX 画像を保存し、一致したチャンクとともに返します。CLI は |
| N/A |
| ONNX Runtime 実行デバイス |
| N/A |
| 選択したモデルに渡される埋め込み dtype |
BASE_DIR と BASE_DIRS)mcp-local-rag は、設定されたルート内でのみファイル操作を許可します。複数のルートの場合、BASE_DIRS は空でないパスの JSON 配列である必要があります:
export BASE_DIRS='["/Users/me/Documents/work","/Users/me/Projects/specs"]'ルート設定は次の順序で解決されます:
CLI --base-dir <path> フラグ (ingest、list、sync で繰り返し指定可能)
BASE_DIRS
BASE_DIR
現在のディレクトリ
各ソースは、マージするのではなく、優先度の低いソースを置き換えます。無効な BASE_DIRS 設定は、BASE_DIR や現在のディレクトリにフォールバックする代わりに失敗します。status は MCP で引き続き利用できるため、クライアントは設定エラーを報告できます。
npx mcp-local-rag ingest --base-dir /Users/me/work --base-dir /Users/me/specs /Users/me/work/readme.md
npx mcp-local-rag list --base-dir /Users/me/work --base-dir /Users/me/specs
npx mcp-local-rag sync --base-dir /Users/me/work --base-dir /Users/me/specs
BASE_DIRS='["/Users/me/work","/Users/me/specs"]' npx mcp-local-rag listDB_PATH と CACHE_DIR は、デフォルトではプロセスの作業ディレクトリからの相対パスです。MCP クライアントが異なるプロジェクトディレクトリからサーバーを起動する可能性がある場合は、絶対パスを設定してください。
MODEL_NAME を設定するか、--model-name を渡して、ドキュメントの言語とドメインに合った Hugging Face 埋め込みモデルを選択します。
mcp-local-rag は、平均プーリングと L2 正規化で埋め込みを生成します。モデルを選択するときは、プーリング方法が検索品質に影響を与える可能性があるため、これらの設定が推奨される推論設定と一致するかどうかを確認してください。
MODEL_NAME、RAG_DEVICE、または RAG_DTYPE を変更すると、既存のベクトルと互換性がなくなる可能性があります。埋め込み設定を変更した後は、新しい DB_PATH を使用するか、既存のインデックスを削除して再取り込みしてください。
英語ドキュメントのモデル例は Xenova/bge-small-en-v1.5 です。
ファイルアクセスは BASE_DIR、BASE_DIRS、または CLI --base-dir ルートに制限されます。
設定されたすべてのルートの外側に解決されるシンボリックリンクは拒否されます。
ドキュメント処理と検索は、必要なモデルがキャッシュされた後はネットワークリクエストを行いません。
サーバーは 1 人のローカルユーザー向けに設計されており、認証やアクセス制御は提供しません。
同じ DB_PATH に対して複数の CLI または MCP ライターを実行しないでください。同期中は読み取り専用クエリを実行できます。
ライターがアクティブでないときに DB_PATH ディレクトリをコピーしてインデックスをバックアップします。
最初にドキュメントを取り込む必要があります。"List all ingested files" を実行して確認してください。
インターネット接続を確認してください。プロキシの背後にある場合は、ネットワーク設定を構成してください。モデルは 手動でダウンロード することもできます。
デフォルトの制限は 100MB です。大きなファイルを分割するか、MAX_FILE_SIZE を増やしてください。
status でチャンク数を確認してください。チャンクが多い大きなドキュメントはクエリが遅くなる可能性があります。非常に大きなファイルの分割を検討してください。
ファイルパスが設定されたルートのいずれか (BASE_DIR、任意の BASE_DIRS エントリ、または任意の CLI --base-dir) 内にあることを確認してください。絶対パスを使用してください。
BASE_DIRS は、1 つ以上の空でないパス文字列の JSON 配列を受け入れます:
有効: BASE_DIRS='["/Users/me/work","/Users/me/specs"]'
無効: BASE_DIRS=/a:/b (区切り文字構文はサポートされていません)
無効: BASE_DIRS='[]' (空の配列)
設定ファイルの構文を確認します
クライアントを完全に再起動します (Mac の Cursor では Cmd+Q)
直接テストします: npx mcp-local-rag がエラーなく実行されるはずです
貢献を歓迎します! セットアップとガイドラインについては CONTRIBUTING.md を参照してください。
MIT ライセンス。個人利用および商用利用は無料です。
エージェンティックコーディングのためのローカル RAG の構築: セマンティックチャンキングとハイブリッド検索設計の技術的な詳細。
Anthropic の Model Context Protocol、LanceDB、Transformers.js を使用して構築されています。
Delete a previously ingested file or data from the vector database. Use filePath for files ingested via ingest_file, or source for data ingested via ingest_data. Either filePath or source must be provided. Returns deleted (operation succeeded), removedChunks, and existed (whether anything was actually present).
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | Source identifier used in ingest_data. Examples: "https://example.com/page", "clipboard://2024-12-30" | |
| filePath | No | Absolute path to the file (for ingest_file). Example: "/Users/user/documents/manual.pdf" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Mentions return fields but does not disclose side effects, permissions, or error cases (e.g., what happens if nothing matches).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no redundancy. Purpose, usage, and return are clearly separated and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, parameters, constraints, and return values. Lacks explanation of edge cases (both params provided or neither) but is generally sufficient given tool simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, yet description adds context by linking each parameter to the specific ingestion method and clarifying the mutual exclusivity requirement, which is not in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (delete) and object (previously ingested file/data from vector database). Distinguishes from sibling tools which are for ingestion, listing, querying, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use filePath vs. source and states that at least one must be provided. Could further specify behavior if both are given or if the item does not exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ingest in-memory content as a string (use ingest_file for files on disk). The source identifier enables re-ingestion to update existing content. Returns { filePath, chunkCount, timestamp, fileTitle }.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The content to ingest (text, HTML, or Markdown) | |
| metadata | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses return format but does not discuss side effects, idempotency, or rate limits. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste: first sentence states purpose and sibling alternative, second sentence adds key behavioral detail and return format. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given nested object parameters and no output schema, the description covers purpose, parameters with examples, and return values. Lacks error conditions or prerequisites, but sufficient for most agents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds meaning to both parameters: content format types and detailed metadata source examples. Schema coverage is 50% but description compensates with concrete usage guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states it ingests in-memory content as a string and differentiates from ingest_file for files on disk. Specific verb+resource with clear distinction from a sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions when to use this tool ('use ingest_file for files on disk') and hints at re-ingestion capability. Lacks explicit when-not-to-use scenarios, but the sibling distinction is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ingest a document file (PDF, DOCX, TXT, MD) into the vector database. Path must be absolute; re-ingesting the same path replaces its existing data. Returns { filePath, chunkCount, timestamp, fileTitle }.
| Name | Required | Description | Default |
|---|---|---|---|
| visual | No | Run VLM captioning on figure pages (PDF only; default false). | |
| filePath | Yes | Absolute path to the file to ingest. Example: "/Users/user/documents/manual.pdf" | |
| visualQuality | No | VLM profile when visual is true (default "fast"). "quality" is more accurate on figures with in-image text but much heavier and slower. Ignored when visual is false. | fast |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that ingestion is a write operation, that re-ingesting replaces existing data, and that it supports VLM captioning for PDFs with different quality profiles. It also specifies the return structure. This is thorough for a tool of this complexity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence front-loads the main purpose, and the second adds critical behavioral details. No extra words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no output schema, and no nested objects, the description covers input requirements (absolute path), behavior (replace on re-ingest), return fields, and an optional feature (VLM captioning). It briefly addresses PDF-only behavior. Missing details like error handling or unsupported file types, but overall sufficient for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds context like 'Path must be absolute' and the effect of re-ingesting, but the schema already describes each parameter adequately. No additional semantic depth beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Ingest', the resource 'document file (PDF, DOCX, TXT, MD)', and the destination 'into the vector database'. It distinguishes from siblings like 'delete_file' and 'list_files' by specifying file ingestion. The mention of absolute path and re-ingest behavior adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context: 'Path must be absolute' and 're-ingesting the same path replaces its existing data'. However, it does not explicitly state when to use this tool versus alternatives (e.g., 'ingest_data'), nor does it give exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List supported files (PDF, DOCX, TXT, MD) under the configured base directories and whether each is ingested. Returns { baseDirs, files, sources }; sources lists ingested items reported apart from the file scan, chiefly ingest_data content (web pages, clipboard, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Optional absolute path prefix(es) — one string or a list (unioned) — restricting the listing to files reachable at a path equal to or under a prefix within the base directories. "/docs/api" matches "/docs/api/x.md" but not "/docs/apiv2". Must be absolute (server OS style); a relative prefix matches nothing. A prefix outside every base directory yields an empty files list, so compare it against the baseDirs in the response before concluding no files exist. Scope filters files by their scan path; ingest_data sources, which have no base-directory path, are always listed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It adds value by explaining that 'sources' contains ingested items like web pages/clipboard, and that files are scanned from base directories. It doesn't explicitly state this is read-only or describe side effects, but the 'list' verb implies safety. Some edge behavior (e.g., invalid scope yielding empty files list) is only visible in the schema, not the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences: the first states the core purpose, and the second explains the return structure and the 'sources' nuance. There is no redundancy or filler, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a listing tool with one optional parameter and no output schema, the description sufficiently covers the purpose, return shape, and the non-obvious 'sources' concept. It doesn't need to explain return values in detail since the return shape is stated. Path edge cases are handled in the schema, so the description is complete enough for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers 100% of the parameter 'scope' with a detailed explanation of prefix matching and path constraints. The tool description adds no additional parameter semantics beyond what the schema already provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('list') and resource ('supported files (PDF, DOCX, TXT, MD)') under configured base directories, plus the ingestion status. This clearly distinguishes it from sibling tools like ingest_file, delete_file, and sync_status, which perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for inspecting the file inventory and its ingestion status, which is a distinct use case. It also explains the return shape to set expectations. However, it doesn't explicitly mention when not to use it or reference sibling alternatives, though the purpose is clear enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search ingested documents with hybrid keyword + semantic matching. Returns results sorted by relevance, each with filePath, chunkIndex, text, fileTitle, score (0 = best, higher = worse), and source (for ingest_data items).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 10, range 1-20). Lower favors precision, higher recall. | |
| query | Yes | Search query. Preserve specific user terms (for keyword match); add context when the query is vague (for semantic match). | |
| scope | No | Optional absolute path prefix(es) — one string or a list (unioned) — restricting results to a filePath equal to or under a prefix. "/docs/api" matches "/docs/api/auth.md" but not "/docs/apiv2". Must be absolute (server OS style); a relative prefix matches nothing — derive one from a filePath returned by an earlier query, or omit scope. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description details return fields, sorting by relevance, and score meaning (0=best, higher=worse). It lacks pagination details but is generally transparent for a read-only search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with clear, front-loaded purpose and a concise list of return fields. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers purpose, behavior, and return fields comprehensively. Context from sibling tools and parameter count is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description adds value by listing output fields not present in schema, enhancing parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches ingested documents using hybrid keyword and semantic matching, and lists the return fields. It is distinct from sibling tools like list_files and read_chunk_neighbors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (for searching documents) but does not explicitly state when not to use or provide alternatives among siblings. No exclusion criteria mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the chunks immediately before and after a query_documents result, in the same document, for more surrounding context. Pass chunkIndex from the result plus exactly one of filePath (ingest_file) or source (ingest_data). Returns the target chunk (isTarget: true) and its neighbors, ascending by chunkIndex; an out-of-range chunkIndex returns []. Defaults: before=2, after=2 (max 50 each).
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Number of chunks to retrieve after the target (0–50, default 2). | |
| before | No | Number of chunks to retrieve before the target (0–50, default 2). | |
| source | No | Source identifier (for ingest_data documents). Provide exactly one of filePath or source. Examples: "https://example.com/page", "clipboard://2024-12-30". | |
| filePath | No | Absolute path to the file (for ingest_file documents). Provide exactly one of filePath or source. Example: "/Users/user/documents/manual.pdf". | |
| chunkIndex | Yes | Zero-based target chunk index (non-negative integer). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It details the behavior (reads neighbors), return structure (target with isTarget: true, ascending order), edge case (out-of-range returns []), and limits (defaults before/after=2, max 50 each). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise, and front-loaded with the most important information. No redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully covers the tool's behavior, parameter usage, return structure, and edge cases. It ties to the sibling tool query_documents, providing necessary context for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with descriptions for all five parameters. The description adds value by explaining the mutual exclusivity of filePath and source, the default values for before and after, and the connection to query_documents for chunkIndex.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb ('Read'), the resource ('chunks immediately before and after'), and the context ('in the same document, for more surrounding context'). It ties the tool to query_documents, distinguishing it from siblings like query_documents itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit instructions on parameter usage: pass chunkIndex from query_documents and exactly one of filePath or source. It also states defaults and max limits. However, it doesn't explicitly state when not to use this tool or mention alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get index status: { documentCount, chunkCount, memoryUsage (MB), uptime (s), ftsIndexEnabled, searchMode }.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not explicitly state read-only nature or other behavioral traits like cost or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, description fully covers functionality and return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; description adds value by listing return fields beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states it gets index status and lists return fields, clearly distinguishing from sibling tools like delete_file or query_documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use vs alternatives, but the simple nature (no parameters) makes usage implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reconcile the index with the files on disk: ingest new and changed files, leave unchanged files alone, and remove index entries for files that are gone. Returns { jobId } without waiting for the run to finish; poll sync_status with that jobId for progress and the final outcome. Only one job is kept, and it is lost when the server process exits.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Optional absolute path to a file or directory inside a configured base directory; list_files returns those directories as baseDirs. A file synchronizes only itself and a directory only its own subtree, leaving every path outside it untouched. Omit it to synchronize every configured base directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses key behaviors: asynchronous execution (returns jobId without waiting), single-job constraint, and job loss on server exit. It also notes that index entries are removed for missing files, making side effects transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: the first states the core purpose, the second explains the return value and polling, and the third adds a critical lifecycle constraint. Every sentence contributes essential information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one optional parameter, no annotations, and no output schema, the description fully captures the tool's behavior, return format, and lifecycle. It also refers to sync_status for progress, completing the operational picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a 100% coverage description for the 'path' parameter, explaining its optionality, scope, and behavior. The tool description adds no extra parameter context, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Reconcile the index with the files on disk' and enumerates specific behaviors (ingest new/changed, leave unchanged, remove gone entries). This distinguishes it from sibling tools like ingest_file or delete_file, which handle single files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (reconciling an index with disk state) and implicitly contrasts with sync_status for polling. It lacks explicit 'when not to use' statements or alternative tool names, but the context is unambiguous enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current or latest sync job record: { jobId, state ("running" | "succeeded" | "failed"), total (null until scanning has counted the files on disk), completed (upserted + skipped + empty; pruned is counted separately), summary { upserted, skipped, empty, pruned }, warnings, error (null unless the job failed) }. An unknown jobId means the job was replaced by a newer one or lost with a previous server process.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | Identifier returned by sync_start. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes full responsibility for behavioral disclosure. It transparently explains field nullability (total null until scanning, error null unless failed), the enumerated state values, and the unknown jobId case. This gives the agent a complete picture of expected behavior and edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but intentionally structured to mirror the returned object, making the field relationships clear. The second sentence adds essential edge-case information without fluff. It is compact given the amount of detail about the response shape.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description fully defines every return field and its conditional behavior, including a nested summary object. It also references sync_start and server process loss to situate usage, making the tool self-sufficient in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers jobId ('Identifier returned by sync_start') at 100% coverage. The description adds extra meaning beyond the schema by explaining the consequences of an unknown jobId, which enriches the parameter's semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get the current or latest sync job record', providing a specific verb+resource. It further details the exact output shape including state values, total/completed semantics, and nested summary, clearly distinguishing it from sibling tools like sync_start.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage: after starting a sync job, call this to retrieve its status. It explains the meaning of an unknown jobId (replaced or lost with server process), which guides the agent on interpreting results. However, it does not explicitly name alternatives or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.17.3list_files1 field changedInput schema / properties / scope / descriptionPrevious value: -"Optional absolute path prefix(es) — one string or a list (unioned) — restricting the listing to files reachable at a path equal to or under a prefix within the base directories. \"/docs/api\" matches \"/docs/api/x.md\" but not \"/docs/apiv2\". Must be absolute (server OS style); a relative prefix matches nothing. Scope filters files by their scan path; ingest_data sources, which have no base-directory path, are always listed."New value: +"Optional absolute path prefix(es) — one string or a list (unioned) — restricting the listing to files reachable at a path equal to or under a prefix within the base directories. \"/docs/api\" matches \"/docs/api/x.md\" but not \"/docs/apiv2\". Must be absolute (server OS style); a relative prefix matches nothing. A prefix outside every base directory yields an empty files list, so compare it against the baseDirs in the response before concluding no files exist. Scope filters files by their scan path; ingest_data sources, which have no base-directory path, are always listed."sync_startsync_statusv0.16.1list_files1 field changedInput schema / properties / scopeAdded value: +{
+ "description": "Optional absolute path prefix(es) — one string or a list (unioned) — restricting the listing to files reachable at a path equal to or under a prefix within the base directories. \"/docs/api\" matches \"/docs/api/x.md\" but not \"/docs/apiv2\". Must be absolute (server OS style); a relative prefix matches nothing. Scope filters files by their scan path; ingest_data sources, which have no base-directory path, are always listed.",
+ "oneOf": [
+ {
+ "type": "string"
+ },
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ ]
+}v0.15.3ingest_data1 field changedInput schema / properties / metadata / properties / format / descriptionPrevious value: -"Content format: \"text\", \"html\", or \"markdown\""New value: +"Content format: text (plain/copied text), html (fetched web pages), or markdown."ingest_file2 fields changedInput schema / properties / visual / descriptionPrevious value: -"If true and the file is a PDF, run VLM captioning on figure pages. No effect on non-PDF files."New value: +"Run VLM captioning on figure pages (PDF only; default false)."Input schema / properties / visualQuality / descriptionPrevious value: -"VLM profile to use when visual is true. \"fast\" (default) is the lightweight SmolVLM-256M; \"quality\" is Qwen2.5-VL-3B-Instruct-ONNX with higher fidelity on figures with in-image text (~10x model-cache footprint, ~2x per-page inference). The server also accepts an empty string as a synonym for omitted (normalized to \"fast\"). Silently ignored when visual is false."New value: +"VLM profile when visual is true (default \"fast\"). \"quality\" is more accurate on figures with in-image text but much heavier and slower. Ignored when visual is false."query_documents3 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum number of results to return (default: 10, range: 1-20). Recommended: 5 for precision, 10 for balance, 20 for broad exploration."New value: +"Max results (default 10, range 1-20). Lower favors precision, higher recall."Input schema / properties / query / descriptionPrevious value: -"Search query. Include specific terms and add context if needed."New value: +"Search query. Preserve specific user terms (for keyword match); add context when the query is vague (for semantic match)."Input schema / properties / scopeAdded value: +{
+ "description": "Optional absolute path prefix(es) — one string or a list (unioned) — restricting results to a filePath equal to or under a prefix. \"/docs/api\" matches \"/docs/api/auth.md\" but not \"/docs/apiv2\". Must be absolute (server OS style); a relative prefix matches nothing — derive one from a filePath returned by an earlier query, or omit scope.",
+ "oneOf": [
+ {
+ "type": "string"
+ },
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ ]
+}read_chunk_neighbors2 fields changedInput schema / properties / filePath / descriptionPrevious value: -"Absolute path to the file (for documents ingested via ingest_file). Example: \"/Users/user/documents/manual.pdf\". Provide either filePath or source, not both."New value: +"Absolute path to the file (for ingest_file documents). Provide exactly one of filePath or source. Example: \"/Users/user/documents/manual.pdf\"."Input schema / properties / source / descriptionPrevious value: -"Source identifier used in ingest_data (for data ingested via ingest_data). Examples: \"https://example.com/page\", \"clipboard://2024-12-30\". Provide either filePath or source, not both."New value: +"Source identifier (for ingest_data documents). Provide exactly one of filePath or source. Examples: \"https://example.com/page\", \"clipboard://2024-12-30\"."v0.15.0query_documents3 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum number of results to return (default: 10). Recommended: 5 for precision, 10 for balance, 20 for broad exploration."New value: +"Maximum number of results to return (default: 10, range: 1-20). Recommended: 5 for precision, 10 for balance, 20 for broad exploration."Input schema / properties / limit / maximumAdded value: +20Input schema / properties / limit / minimumAdded value: +1v0.14.1ingest_file1 field changedInput schema / properties / visualQualityAdded value: +{
+ "default": "fast",
+ "description": "VLM profile to use when visual is true. \"fast\" (default) is the lightweight SmolVLM-256M; \"quality\" is Qwen2.5-VL-3B-Instruct-ONNX with higher fidelity on figures with in-image text (~10x model-cache footprint, ~2x per-page inference). The server also accepts an empty string as a synonym for omitted (normalized to \"fast\"). Silently ignored when visual is false.",
+ "enum": [
+ "fast",
+ "quality"
+ ],
+ "type": "string"
+}v0.14.0ingest_file1 field changedInput schema / properties / visualAdded value: +{
+ "description": "If true and the file is a PDF, run VLM captioning on figure pages. No effect on non-PDF files.",
+ "type": "boolean"
+}v0.13.0read_chunk_neighborsv1.0.0delete_fileingest_dataquery_documents2 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum number of results to return (default: 5, max recommended: 20)"New value: +"Maximum number of results to return (default: 10). Recommended: 5 for precision, 10 for balance, 20 for broad exploration."Input schema / properties / query / descriptionPrevious value: -"Natural language search query (e.g., \"transformer architecture\", \"API documentation\")"New value: +"Search query. Include specific terms and add context if needed."ingest_filelist_filesquery_documentsstatusEach tool has a distinct purpose: sync_status tracks job progress while status reports index stats; ingest_file vs ingest_data clearly separate file-based and in-memory ingestion; query_documents, read_chunk_neighbors, delete_file, list_files, and sync_start all target different operations. No two tools are likely to be confused.
Most tools follow a verb_noun pattern (query_documents, ingest_file, delete_file, list_files, read_chunk_neighbors), but sync_status, sync_start, and status deviate, using noun compounds or a standalone noun. The mix is readable but not uniform.
9 tools is well-scoped for a local RAG server, covering ingestion (file and data), deletion, querying, context expansion, file listing, and status/sync operations without unnecessary redundancy or bloat.
The set covers the core lifecycle: ingest (file/data), delete, search, and context retrieval. Minor gaps include no direct way to fetch all chunks of a specific document or a bulk clear operation, but these can be worked around with existing tools like query_documents and sync_start.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Ingest, manage, and retrieve documents for RAG-powered AI applications
Versioned documentation registry and semantic search for AI tools and coding assistants.
Self-hosted AI-native knowledge workspace with hybrid search, GraphRAG, and MCP.
Search everything you save: YouTube, articles, podcasts, PDFs, Notion, Obsidian. API key or OAuth.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/shinpr/mcp-local-rag'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
