understand-quickly

@looptech-ai/understand-quickly-mcp

一个轻量的 Model Context Protocol 服务，可将 understand-quickly 注册表开放给任何 MCP 客户端（Claude Desktop、Codex、Cursor 等）。

状态：仅为存根级别。端到端功能可用，但有意保持精简——不支持流式传输、嵌入或身份验证。

功能

它封装了公开的 registry.json，并开放四个工具：

工具	参数	返回值
list_repos	{ format?, tag?, status? }	{ id, format, description, status, tags, last_synced, graph_url } 数组
find_graph_for_repo	{ id?, github_url? }（至少需要提供一项）	单个注册表条目的 graph_url 和漂移元数据，或 { found: false, suggestions: [...] }，其中最多包含 5 个模糊匹配的 id
get_graph	{ id }	该条目对应 graph_url 的已解析图 JSON
search_concepts	{ query, id? }	默认：返回预计算 stats.json 中聚合的概念匹配项（单次 GET，缓存 60 秒）。提供 id 时：在单个图的节点中进行子字符串匹配。如果无法访问 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"）。

如果未找到条目，响应为 { found: false, suggestions: [...] }，其中最多包含 5 个模糊匹配的 id（与转为小写的 id 相比，Levenshtein 距离 ≤ 3）。

search_concepts

默认情况下——也就是未提供 id 时——search_concepts 会读取预计算的 stats.json 汇总数据（单次缓存 GET），并返回匹配的概念词条及其条目计数，以及最多 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

需要 Node 20+（使用全局 fetch）。

本地运行

用于开发：

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 使用的预计算统计数据来源。

当前限制

• 仅使用内存缓存。 每个服务进程每分钟重新获取一次。没有跨进程或磁盘缓存。
• 跨图扇出仅用作回退方案。 当 search_concepts 进行回退（没有 stats.json）时，它会按顺序扫描前 5 个 status: ok 条目。
• 子串搜索比较简单。 不支持模糊匹配、排序或嵌入。
• 不支持流式传输或进度报告。 工具会一直阻塞，直到上游响应。
• 尽力枚举节点。 单图回退方案假定图中有 nodes / entities / concepts / items 数组；否则会遍历顶层数组值。
• 上游 graph_url 获取失败时不会重试或退避——获取失败的条目会返回空结果，而不是报错。

对于 MVP 来说，这些限制都可以接受。如果你有更多需求，请提交 issue。