understand-quickly

@looptech-ai/understand-quickly-mcp

Model Context Protocol サーバーの薄いラッパーで、understand-quickly レジストリをあらゆる MCP クライアント（Claude Desktop、Codex、Cursor など）に公開します。

ステータス：スタブ品質です。エンドツーエンドで動作しますが、意図的に最小限の実装になっています — ストリーミング、埋め込み、認証はありません。

できること

公開されている registry.json をラップし、4 つのツールを公開します。

ツール	パラメーター	戻り値
list_repos	{ format?, tag?, status? }	{ id, format, description, status, tags, last_synced, graph_url } の配列
find_graph_for_repo	{ id?, github_url? } （少なくとも 1 つは必須）	レジストリエントリ 1 件の graph_url とドリフトメタデータ、または最大 5 件のあいまい一致した id を含む { found: false, suggestions: [...] }
get_graph	{ id }	該当エントリの graph_url にある解析済みグラフ JSON
search_concepts	{ query, id? }	デフォルト：事前計算済みの stats.json から集約されたコンセプトの一致（GET 1 回、60 秒間キャッシュ）。id を指定した場合：1 つのグラフのノードを対象とした部分一致。stats.json にアクセスできない場合は、上限付きの全グラフへのファンアウトにフォールバックします。

レジストリのレスポンスはメモリ内に 60 秒間キャッシュされます。stats.json にも同じ 60 秒の TTL キャッシュが使用されます。

find_graph_for_repo

id（レジストリ id、owner/repo）または github_url のいずれかを受け取ります。URL パーサーは以下の形式に対応しています。

• https://github.com/owner/repo
• https://github.com/owner/repo.git
• https://github.com/owner/repo/ （末尾のスラッシュ）
• https://github.com/owner/repo/tree/main/... （ブランチ／サブパス）
• [email protected]:owner/repo.git

エントリが見つかった場合、レジストリにこれらのフィールドがあると、レスポンスに last_synced、last_sha、source_sha、head_sha、commits_behind、および整形された drift_summary（例："behind by 17 commits"）が含まれます。

エントリが見つからない場合、レスポンスは、最大 5 件のあいまい一致した id を含む { found: false, suggestions: [...] } になります（小文字化した id に対するレーベンシュタイン距離 ≤ 3）。

search_concepts

デフォルトでは、つまり id が指定されていない場合、search_concepts は事前計算済みの stats.json 集計（キャッシュされる GET 1 回）を読み込み、一致するコンセプト用語と、そのエントリ数および最大 3 件のサンプルレジストリ id を返します。これにより、リクエスト時に最大 5 件のグラフを取得していた以前の動作を置き換えます。

id が指定されている場合は、従来の単一グラフノード検索（id／label／name に対する部分一致）にフォールバックします。stats.json を利用できない場合（404 またはスキーマ不一致）は、後方互換性のため、上限付きの全グラフへのファンアウトにフォールバックします。

レスポンスの source フィールドは、リクエストの処理に使用されたモード（"stats"、"graph"、"fanout"）を示します。

インストール

cd mcp
npm install
npm run build   # compiles TypeScript -> dist/
npm test        # runs node:test across registry/cache and tool logic

（グローバルな fetch を使用するため）Node 20 以降が必要です。

ローカルで実行

開発用：

npm run dev

ビルド済みバイナリの場合：

npm start

このサーバーは stdio JSON-RPC を使用します。キー入力には応答しないため、MCP クライアントから接続してください。

Claude Desktop に登録

以下を Claude Desktop の claude_desktop_config.json に追加します（macOS でのパスは ~/Library/Application Support/Claude/claude_desktop_config.json です）。

{
  "mcpServers": {
    "understand-quickly": {
      "command": "npx",
      "args": [
        "tsx",
        "/absolute/path/to/understand-quickly/mcp/src/index.ts"
      ],
      "env": {
        "UNDERSTAND_QUICKLY_REGISTRY": "https://looptech-ai.github.io/understand-quickly/registry.json"
      }
    }
  }
}

/absolute/path/to/... を、チェックアウトした実際のパスに置き換えてください。保存後、Claude Desktop を再起動します。

コンパイル済みの出力を実行する場合は、以下に切り替えてください。

{
  "mcpServers": {
    "understand-quickly": {
      "command": "node",
      "args": ["/absolute/path/to/understand-quickly/mcp/dist/index.js"]
    }
  }
}

環境変数

変数	デフォルト	用途
UNDERSTAND_QUICKLY_REGISTRY	https://looptech-ai.github.io/understand-quickly/registry.json	レジストリの取得元を上書きします（例：ローカルファイルまたはフォークを指定）。
UNDERSTAND_QUICKLY_STATS	https://looptech-ai.github.io/understand-quickly/stats.json	search_concepts が使用する事前計算済み統計情報の取得元を上書きします。

現在の制限事項

• インメモリキャッシュのみです。 サーバープロセスごとに、1 分に 1 回再取得します。プロセス間またはディスク上でのキャッシュはありません。
• グラフ間のファンアウトはフォールバックに限られます。 search_concepts がフォールバックする場合（stats.json がない場合）、status: ok のエントリーのうち、先頭 5 件のみを順番にスキャンします。
• 部分文字列検索は単純です。 あいまい検索、ランキング、埋め込みはありません。
• ストリーミングや進捗報告はありません。 ツールは上流から応答があるまでブロックします。
• ノード列挙はベストエフォートです。 単一グラフのフォールバックでは、グラフに nodes / entities / concepts / items 配列があることを前提とします。ない場合は、トップレベルの配列値をたどります。
• 上流の graph_url の取得に対する再試行やバックオフはありません。 取得に失敗した場合、エラーを返す代わりに、そのエントリーの結果は空になります。

これらはすべて MVP として許容できるものです。より多くの機能が必要な場合は、イシューを作成してください。