RAGMap MCP

RAGMap MCP（ローカル）

RAG 対応 MCP サーバーを数秒で検索・絞り込みできます。このパッケージは、ホスト型 RAGMap サブレジストリ API に接続するローカルの stdio MCP ブリッジです。

チームで利用される理由

• 接着コード不要：npx で実行し、MCP で通信するだけです。
• エージェント優先：安定性の高い小さなツールコントラクトで、予測可能な出力が得られます。
• デフォルトで本番環境向け：ホスト型 API にすぐ接続できます。
• 読み取り専用：キーは不要です。

利用できる機能

• 主な用途：Claude Desktop、Cursor、およびあらゆる MCP ホスト向けの MCP stdio トランスポートです。
• ツール：rag_find_servers、rag_get_server、rag_list_categories、rag_explain_score。

エージェント向け（設定不要）： 検出には GET https://ragmap-api.web.app/.well-known/agent.json を使用し、REST API の呼び出しには apiEndpoints、このパッケージの実行には mcpInstall を使用してください。リポジトリの AGENT-USAGE.md を参照してください。

---

MapRag（RAGMap）

MapRag は、検索のための検出・ルーティングレイヤーです。 RAG 対応 MCP サーバーをインデックス化し、構造化メタデータを付加して、引用、鮮度、プライバシー、ドメイン、レイテンシーなどの制約に応じて、タスクに適した検索サーバーを**エージェント（および人間）**がすばやく見つけられるようにします。

MapRag 自体は RAG を行いません。 検索を行うための最適な RAG ツール／サーバー の選択を支援します。

ステータス（v1.0）

• 公式 MCP Registry を取り込み（読み取り専用）、検索のユースケース向けにサーバーレコードを拡充します。
• API で埋め込みが有効な場合（OpenAI キーが必要）はセマンティック検索とキーワード検索を行い、それ以外の場合はキーワード検索のみを行います。
• 拡充項目：categories、ragScore、reasons、hasRemote、およびリモートトランスポートの到達可能性メタデータ。
• フィルター：query、categories、minScore、transport、registryType、hasRemote、reachable、reachableMaxAgeHours。
• プログラムから利用できるインターフェースを 2 つ提供します：レジストリ互換 REST API（サブレジストリ）と MCP サーバー（リモート HTTP ＋ローカル stdio）。

ロードマップ

• より豊富な機能モデル（ドメイン、グラウンディング／引用、鮮度、プライバシー／データ保存場所、認証、制限）。
• 信頼性の指標（到達可能性、スキーマの安定性、レイテンシー／稼働時間）。
• サーバーの閲覧・絞り込み・比較に使えるユーザー向け UI。

概要全文：https://github.com/khalidsaidi/ragmap/blob/main/docs/OVERVIEW.md

アーキテクチャ（概要）

---

クイックスタート（60 秒）

MCP_AGENT_NAME=local-test \
npx -y @khalidsaidi/ragmap-mcp@latest

デフォルトでは、ホスト型 API ベース https://ragmap-api.web.app を使用します。

ローカル開発の場合：

RAGMAP_API_BASE_URL=http://localhost:3000 \
npx -y @khalidsaidi/ragmap-mcp@latest

インストール（任意）

グローバルインストールする場合：

npm i -g @khalidsaidi/ragmap-mcp
ragmap-mcp

スモークテスト（1 コマンド）

printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1","capabilities":{},"clientInfo":{"name":"quick","version":"0.0.1"}}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
'{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"rag_find_servers","arguments":{"query":"rag","limit":3}}}' \
| npx -y @khalidsaidi/ragmap-mcp@latest

---

Claude Desktop の設定

{
  "mcpServers": {
    "ragmap": {
      "command": "npx",
      "args": ["-y", "@khalidsaidi/ragmap-mcp@latest"],
      "env": {
        "MCP_AGENT_NAME": "claude-desktop",
        "RAGMAP_API_BASE_URL": "https://ragmap-api.web.app"
      }
    }
  }
}

---

リモート MCP（インストール不要）

ローカルにインストールせず、ストリーム可能な HTTP 経由で MCP を利用する場合は、ホスト型エンドポイントを使用してください：

claude mcp add --transport http ragmap https://ragmap-api.web.app/mcp

---

ツール

• rag_find_servers - RAG 対応 MCP サーバーを検索・絞り込みします
• rag_get_server - 名前でサーバーレコードを取得します（最新バージョン）
• rag_list_categories - 既知の RAG カテゴリを一覧表示します
• rag_explain_score - サーバーの RAG スコアについて説明します

注意：

• ツールの応答は JSON テキストとして返されるため、あらゆる MCP ホストでそのまま表示できます。
• 絞り込みは RAGMap API のサーバー側で行われます。

ツール呼び出しの例

• RAG に対応していそうなリモート（streamable-http）サーバーを検索：rag_find_servers({ query: "rag", minScore: 30, transport: "streamable-http", hasRemote: "true", limit: 10 })
• 特定のレジストリタイプで公開されたサーバーを検索：rag_find_servers({ query: "qdrant", registryType: "pypi" })
• カテゴリを一覧表示：rag_list_categories({})
• RAGMap 自身のレコードを取得するか、スコアを説明する（公開済みのレジストリ名を使用）：rag_get_server({ name: "io.github.khalidsaidi/ragmap" })、rag_explain_score({ name: "io.github.khalidsaidi/ragmap" })

例：「引用付きのプライバシー優先ドキュメント RAG」

これは MapRag が想定して設計されているクエリの例です。現時点では、カテゴリとトランスポートのフィルターを使って近似できます：

{
  "tool": "rag_find_servers",
  "input": {
    "query": "docs rag citations",
    "categories": ["documents"],
    "minScore": 30,
    "transport": "stdio",
    "hasRemote": "true",
    "limit": 5
  }
}

---

環境変数

変数	必須	説明
RAGMAP_API_BASE_URL	いいえ	REST API のベース URL（デフォルト：https://ragmap-api.web.app）
API_BASE_URL	いいえ	RAGMAP_API_BASE_URL の別名
MCP_AGENT_NAME	いいえ	クライアント識別子（API 呼び出し時に X-Agent-Name として追加されます）
SERVICE_VERSION	いいえ	MCP ホストに報告されるバージョン文字列

---

トラブルシューティング（簡易版）

• 結果が見つからない
  • rag、retrieval、vector、qdrant など、より広いクエリを試してください。
  • minScore の値を下げるか、省略してください。
• 接続エラー
  • お使いの環境から RAGMAP_API_BASE_URL にアクセスできることを確認してください。
  • ホストされた API の場合は、ブラウザーで https://ragmap-api.web.app/health を開いてみてください。

---

リンク

• ドキュメント／OpenAPI：https://ragmap-api.web.app/docs
• エージェントカード：https://ragmap-api.web.app/.well-known/agent.json
• MCP リモート（HTTP）：https://ragmap-api.web.app/mcp
• リポジトリ：https://github.com/khalidsaidi/ragmap