Lacuna Research

Lacuna Research MCP

Lacuna 由 Tiptree Systems 构建，是一张机器学习研究地图：一个异构知识图谱，连接论文、研究方向、作者、发表场所、机构和生成的研究提案，并为每个衍生对象提供来源链，追溯到生成它的确切论文和页面。

Lacuna Research MCP 为 AI 研究人员的编码代理提供：

• 生成的研究提案。 探索使用 The Alien Space of Science 生成的研究想法。
• 研究方向。 浏览包含关联论文、作者和提案的概念集群。
• 适用于代理的文献。 以 Markdown 格式搜索近期论文，并附带来源链接。
• 研究人员情报。 追踪作者、出版物、研究方向、影响力和相关研究人员。
• 研究版图映射。 比较发表场所、机构、领军研究人员和出版活动。

例如，追溯某个实现与其记录的论文关系：

找出 Dao-AILab/flash-attention 背后的论文。展示记录的 仓库关联，并链接原始论文。

此示例沿着 仓库 → 记录的论文关系 → 论文及来源 进行追溯。 Lacuna 会返回 official_code_for 关系，指向 FlashAttention， 并提供仓库和原始论文的链接。检查这些来源以验证 关联。运行示例 或 跟着笔记本操作。

安装 · 研究技能 · 首次使用 · 工具 · API 参考 · 配置

安装

Cursor 代理插件

此仓库还将托管 MCP 连接和两个 研究技能 打包为 代理插件。Cursor 支持此格式。

要在本地测试，请将此仓库复制到 ~/.cursor/plugins/local/lacuna-research-mcp，重新加载 Cursor，然后打开 自定义，检查这两项技能和 MCP 连接。该插件会连接到 https://lacuna.tiptreesystems.com/api/mcp；无需本地安装 Python 或 Lacuna 账户。启用此连接或手动配置的 Lacuna 服务器之一，以避免工具重复。

Cursor 和 VS Code

使用托管服务器，无需本地安装 Python 或 Lacuna 账户：

这些按钮会打开编辑器的 MCP 安装流程。检查服务器 URL 并 确认安装。连接后，询问上面的 FlashAttention 问题； 你的代理应使用 search_lacuna、get_resource 和 get_paper。

{
  "mcpServers": {
    "lacuna-research": {"url": "https://lacuna.tiptreesystems.com/api/mcp"}
  }
}

{
  "servers": {
    "lacuna-research": {"type": "http", "url": "https://lacuna.tiptreesystems.com/api/mcp"}
  }
}

托管 MCP 服务器（Claude 连接器）

使用 Lacuna 的托管 MCP 服务器，适用于任何支持 Streamable HTTP 的客户端。无需本地安装。

https://lacuna.tiptreesystems.com/api/mcp

在 Claude 中，打开 自定义 → 连接器 → + 添加 → 添加自定义连接器。将其命名为 Lacuna Research，粘贴上方的 URL；如果系统提示进行身份验证，请选择 无需登录。完成添加后，在对话中通过 + → 连接器 启用它。

对于 Team 和 Enterprise 工作区，必须先在 组织设置 → 连接器 中添加该连接器。详情请参阅 Claude 自定义连接器设置。

本地安装

安装 Lacuna Research MCP 最简单的方法是让你的编码代理（例如 Codex 或 Claude Code）执行：

为此客户端安装并配置 PyPI 上的 lacuna-research-mcp 软件包。

如需手动设置，以下说明使用 uvx 从 PyPI 运行最新的已标记版本。请先安装 uv；Lacuna Research MCP 要求 Python 3.11 或更高版本。

Codex

使用 Codex CLI 添加服务器：

codex mcp add lacuna-research -- uvx lacuna-research-mcp

或者，将以下内容添加到 ~/.codex/config.toml（或在受信任的项目中添加到 .codex/config.toml，以仅对该项目进行设置）：

[mcp_servers.lacuna-research]
command = "uvx"
args = ["lacuna-research-mcp"]

运行 codex mcp list，验证服务器是否已配置。Codex 应用、CLI 和 IDE 扩展在同一台机器上共用此配置。

Claude Code

使用 Claude Code CLI 为所有项目添加服务器：

claude mcp add --scope user lacuna-research -- uvx lacuna-research-mcp

省略 --scope user，即可仅为当前项目添加服务器。或者，在 ~/.claude.json 的顶层 mcpServers 对象下添加以下内容：

{
  "mcpServers": {
    "lacuna-research": {
      "type": "stdio",
      "command": "uvx",
      "args": ["lacuna-research-mcp"]
    }
  }
}

运行 claude mcp get lacuna-research，验证服务器是否已配置。

Claude Desktop

打开 设置 → 开发者 → 编辑配置，然后在 claude_desktop_config.json 的 mcpServers 下添加服务器：

{
  "mcpServers": {
    "lacuna-research": {
      "command": "uvx",
      "args": ["lacuna-research-mcp"]
    }
  }
}

保存文件后，重启 Claude Desktop。

其他 MCP 客户端

对于任何支持本地 stdio MCP 服务器的客户端，请使用以下标准配置：

{
  "mcpServers": {
    "lacuna-research": {
      "command": "uvx",
      "args": ["lacuna-research-mcp"]
    }
  }
}

独立命令

将 MCP 服务器安装为持久命令：

uv tool install lacuna-research-mcp
lacuna-research-mcp

无需安装持久命令即可运行：

uvx lacuna-research-mcp

如果出现预发布版本错误（例如，“Python 3.14.0rc2 是预发布版本……”）， 说明你的 uv 正在使用 MCP SDK 不支持的 Python 3.14 早期预发布版本。 请更新 uv（uv self update）、安装正式发布的 Python（uv python install 3.14）， 或运行 uvx --python 3.13 lacuna-research-mcp。

自托管 HTTP 服务器

如需通过 Streamable HTTP 而非 stdio 为远程 MCP 客户端提供服务：

uvx lacuna-research-mcp --transport streamable-http --host 0.0.0.0 --port 8000

端点为 /mcp。服务器是无状态的，并以 JSON 响应，因此可以在负载均衡器后运行，无需会话亲和性。使用默认的 --host 127.0.0.1 时，服务器只接受 localhost Host 标头，因此如果反向代理要转发公共主机名，请绑定到非环回地址。

最新开发版本

PyPI 提供已标记的版本。如需尝试来自 main 分支的最新代码：

uvx --from git+https://github.com/tiptreesystems/lacuna-research-mcp.git lacuna-research-mcp

本地开发

使用 uv：

git clone https://github.com/tiptreesystems/lacuna-research-mcp.git
cd lacuna-research-mcp
uv sync --extra dev
uv run lacuna-research-mcp

使用 pip：

cd <path-to-lacuna-research-mcp>
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .

研究技能

MCP 服务器提供工具。这些可选技能会教你的代理如何将工具用于 两项研究任务：

请先连接 MCP 服务器。然后，在安装 Node.js 22.20+ 后，从你的项目运行 技能 CLI：

npx skills add tiptreesystems/lacuna-research-mcp

选择要使用的技能和代理。若只安装从代码追溯到论文的工作流：

npx skills add tiptreesystems/lacuna-research-mcp --skill lacuna-code-to-paper

默认情况下，技能会安装到当前项目中。它们不会安装或配置 MCP 服务器。如果你的客户端需要通过新会话发现新技能，请在安装后启动新的代理会话。

首次使用

在已连接的代理中提出上面的问题之一，或尝试询问待读列表：

我的列表中有 FlashAttention 和 FlashAttention-2。对于长上下文注意力， 我还应该阅读哪些基线或局限性？

如需运行无需模型 API 密钥的可复现示例，请克隆此仓库并运行：

uv run examples/code_to_paper.py

笔记本 逐步说明了每个步骤，并将来源链与单次论文搜索进行比较。若要直接使用工具，流程相同：

1. search_lacuna(query="FlashAttention", search_type="resource", resource_kind="codebase", limit=5)
2. 检查仓库身份，然后将其返回的 ID 传递给 get_resource(resource_id_or_url=...)。
3. 对返回的 publications[].paper_id 调用 get_paper(artifact_id_or_url=..., view="context", figure_limit=0)。

搜索文献时，使用 search_lacuna(query="methods for detecting prompt injection attacks", search_type="paper", limit=5)。 生成研究提案时，使用 search_lacuna(query="LLM jailbreak defense", search_type="hypothesis", limit=5)， 并将返回的 ID 传递给 get_hypothesis。生成的提案是有待 研究的想法，并非已发表研究结果的证据。

关于 Lacuna

Lacuna 的处理流程会整合来自 OpenAlex、OpenReview、DBLP 和 arXiv 的学术记录；从论文文本中提取概念元素，并将其聚类为研究方向（Lacuna 论文）；再使用 The Alien Space of Science 从这些方向中采样新颖的研究提案。这张地图涵盖超过 229 万篇论文、21.5 万多个作者档案、2.8 万多个研究方向、2.5 万多个研究提案和 5,300 多个发表场所，并随着新的 arXiv 论文及其他 AI 论文不断纳入而持续扩展。

范围

语料涵盖机器学习和 AI 研究：论文、研究方向、作者的研究成果、发表场所、机构、生成的研究假设，以及与论文关联的研究资源（GitHub 仓库、Hugging Face 数据集和模型、Zenodo 记录）。其中不包含人物传记、新闻或非研究类网络内容。对于超出此范围的问题，代理应从其他来源作答。

提供的内容

• search_lacuna 使用 Lacuna 的公开 /api/v1/search 端点查询方向、论文、作者、场所、机构、假设和资源。显式论文搜索（search_type="paper"）在其他排序参数保持默认值时，使用服务器的生产级词法+语义排序器。搜索假设时传入 search_type="hypothesis"。搜索与论文关联的代码仓库、数据集、模型和演示时传入 search_type="resource"，还可使用 resource_kind（codebase、dataset、model、demo）和 provider（github、huggingface、zenodo）进行筛选；例如，resource_kind="dataset" 可查找基准数据集。资源搜索不接受 date_from/date_to、venue、年份排序和语义排序（资源没有日期、场所或嵌入向量）。
• get_hypothesis(hypothesis_id_or_url, view="context") 假设/提案。view="context"（默认）返回精简的单次提案上下文（摘要、概要、关联方向）；view="full" 返回服务器的版本记录，其中包含版本历史和信号计数。提案正文位于 versions[].markdown。
• get_direction(cluster_id_or_url, view="context") 研究方向/聚类。view="context"（默认）请求精简的、面向智能体的摘要；view="full" 返回原始聚类记录。
• get_direction_papers(cluster_id_or_url, page, limit, view="compact") 与某个方向关联的分页论文。view="compact"（默认）返回可用于引用的行（id、url、标题、年份、场所、少量作者、摘要片段）；view="full" 返回原始上游论文记录。
• get_paper(artifact_id_or_url, view="context", figure_limit=None, include_resources=True) 查询论文及其可用版本；使用版本的制品 ID 读取该版本。默认情况下，上下文视图和完整视图会包含关联资源（代码仓库、数据集、模型和演示）；传入 include_resources=False 可将其省略。其他视图会忽略此选项。view="context"（默认）请求精简的、面向智能体的上下文；其他视图包括 "full"、"preview"、"blog"、"figures"、"concepts" 或 "neighbors"。在上下文视图中，figure_limit 限制图示预览数量（服务器默认值为 3；传入 0 可隐藏预览，同时保留 figures_truncated 信号）。
• get_resource(resource_id_or_url) 通过 ID（来自资源搜索或 get_paper 的 resources 列表）或 Lacuna /resource/... URL 查询资源：外部 URL、摘要、分类（任务、模态、规模、许可证）、提供方指标、README/卡片摘录、publications 下关联的论文（包含 paper_id 和诸如 dataset_for 的关系）、相关方向以及提及的资源。
• 作者工具： get_author_context(…, view="context")、get_author_papers、get_author_directions 和 get_author_neighbors。从 get_author_context 开始；它默认使用精简的、面向智能体的视图（论文数量有限，并提供易读的 impact_directions 列表，而非原始的 impact_clusters 遥测数据）。使用专用的论文、方向和邻居工具分页浏览这些集合，无需重复获取作者上下文。view="full" 返回受服务器限制的完整结构上下文（集合数量上限为 100）。传入 include_neighbors=true 可显式包含相似作者；这可能会显著增加服务器延迟。
• 场所和机构工具： get_venue_context(…, view="context")、get_institution_context(…, view="context")、get_institution_authors。上下文工具默认使用精简视图（列表数量有限，省略重复区块；场所视图保留近期活动片段，且始终包含请求的 year）。使用 get_institution_authors 分页浏览机构的完整作者列表。

封装的 API

对于 ID 或 URL 参数，传入 search_lacuna 返回的原始 ID，或对应的 Lacuna 页面 URL。MCP 会将 Lacuna 相对路径的 url 和 *_url 字段规范化为绝对 URL，也会将名为 summary_markdown、article_markdown、markdown、content 或 description 的字段中的 Lacuna 链接（包括 /resource/... 页面）转换为绝对 URL。

get_author_context 在两种视图中都受服务器端限制。默认的精简视图会返回精选简报；view="full" 会返回更大的完整结构，其中嵌入的集合数量上限为 100。请使用 get_author_papers 和 get_author_directions，不要尝试对嵌入的上下文集合分页。

每次搜索请求最多返回 50 条结果，每次方向论文分页请求最多返回 100 条结果。 在 search_lacuna 中，date_from 和 date_to 是包含边界日期的出版日期范围。 接受的格式为 YYYY、YYYY-MM 和 YYYY-MM-DD；例如， date_from="2020", date_to="2022-03" 会包含 2020 年 1 月 1 日 至 2022 年 3 月 31 日发表的论文。

search_lacuna 提供以下排序配置：

• default / lexical 所有搜索的默认配置。当 search_type="paper"、sort="relevance" 和 fields 未设置时，它会使用服务器的生产级词法+语义排序器，并在必要时平稳回退。MCP 的默认 search_type="all" 则使用服务器的默认词法排序。
• semantic 用于基于嵌入向量的论文检索。语义查询会省略常规词法排序环节，但服务器仍可叠加精确标题的词法匹配。仅支持 paper 和 all 搜索（只有论文具有语义嵌入），且不能与 resource_kind/provider 筛选器同时使用。
• bm25_title_abstract / bm25 用于限定在标题和摘要范围内进行词法匹配。author 和 institution 搜索不接受此配置（这些记录没有标题或摘要字段）。

除非提供 ranking_profile，否则所有搜索均使用服务器默认配置。MCP 会拒绝不受支持的配置/类型组合，因为否则服务器会回退到子串搜索，并静默忽略请求的排序配置。

sort 接受 relevance（默认）、year_desc 和 year_asc。年份排序不能与 ranking_profile="semantic" 同时使用——服务器会静默忽略排序——因此 MCP 会拒绝这种组合；若要查询近期且相关的内容，请保留语义排序，并改用 date_from/date_to 限定时间范围。

环境变量

• LACUNA_SITE_URL 默认值为 https://lacuna.tiptreesystems.com
• LACUNA_MCP_TIMEOUT 默认值为 30
• LACUNA_MCP_MAX_RETRIES 默认值为 2；适用于超时、传输错误以及 HTTP 429、502、503 和 504 响应。
• LACUNA_MCP_USER_AGENT 默认值为 lacuna-research-mcp/{package_version}
• LACUNA_MCP_BEARER_TOKEN 可选的 bearer 令牌，作为 Authorization: Bearer ... 发送，用于私有 Lacuna 部署。
• LACUNA_MCP_CLIENT_TOKEN 可选令牌，作为 X-Lacuna-Client-Token 发送，以便 Lacuna 识别托管的 MCP 服务器并应用其自身的搜索速率限制。
• LACUNA_MCP_LOG_LEVEL 默认值为 WARNING（取值之一：DEBUG、INFO、WARNING、ERROR、CRITICAL）。默认设置可让常规运行保持安静；仅在调试时调低级别，因为 INFO/DEBUG 会让 HTTP 客户端将完整请求 URL（包括搜索查询字符串）记录到 stderr，而某些 MCP 宿主会保留这些日志。

环境变量会在创建 MCP 服务器时读取一次；如果导入模块时未调用 create_mcp()，则会在首次直接调用工具/API 时读取。

实现布局

该服务器是 Lacuna HTTP API 上的轻量 MCP 适配器。实现按职责拆分：

• lacuna_research_mcp/server.py MCPServer 应用创建、工具注册、生命周期清理以及 lacuna-research-mcp CLI 入口点。
• lacuna_research_mcp/tools.py MCP 工具函数。每个工具都会规范化输入，通过共享客户端辅助函数调用对应的 Lacuna API 端点，并返回兼容 JSON 的数据。
• lacuna_research_mcp/client.py 对 Lacuna 的运行时 HTTP 访问：绑定事件循环的 httpx.AsyncClient、重试处理、错误封装、JSON 解析、响应中的 URL 规范化，以及 api_get/api_object/api_payload。
• lacuna_research_mcp/config.py 运行时常量、RuntimeConfig、软件包 user-agent 构造以及环境变量解析。
• lacuna_research_mcp/ids.py 接受原始 ID 或 Lacuna 页面 URL，并提取安全 API 路径片段的辅助函数。
• lacuna_research_mcp/normalize.py 对相对 Lacuna URL 和 Markdown 链接进行响应后处理。
• lacuna_research_mcp/errors.py 用于 Lacuna API 访问失败的面向用户异常类型。

备注

• get_paper 和 get_direction 默认使用 view="context"。这些上下文视图默认请求 Lacuna 的紧凑型、面向智能体的负载，以缩小 MCP 响应。论文上下文在可用时包含 summary_markdown（否则包含 abstract）、作者和图表；方向上下文包含 summary_markdown、数量受限的论文/作者/相关方向，以及截断标记。需要原始元数据时使用 view="full"；需要单独的子资源时，使用其他论文视图（preview、blog、figures、concepts、neighbors）。
• 显式执行按相关性排序的论文搜索且未指定自定义 fields 时，默认使用服务器的生产级词法+语义排序器。设置 ranking_profile="semantic" 可使用基于嵌入的检索（可能叠加精确标题匹配），设置 "bm25_title_abstract" 可使用标题和摘要的词法匹配。
• 大多数详情工具都接受搜索返回的 id 或对应的 Lacuna URL。
• url/*_url 响应字段中的相对 Lacuna URL，以及名为 summary_markdown、article_markdown、markdown、content 或 description 的字段中的相对 URL，都会被规范化为绝对 URL。
• 会议和机构的键是不可读的哈希值（例如 d7bf22905bd6），而不是 icml 这样的可读名称。请先使用 search_lacuna(search_type="venue") 查找键，或传入 /venue/... 页面 URL。

引用

如果您认为我们的工作有帮助，欢迎引用 Lacuna 的研究提案生成和研究地图背后的论文。

研究提案生成 — The Alien Space of Science

@inproceedings{artiles2026alien,
  title     = {The Alien Space of Science: Sampling Coherent but Cognitively Unavailable Research Directions},
  author    = {Artiles, Alejandro H. and Weiss, Martin and Brinkmann, Levin and Rahwan, Iyad and Sch{\"o}lkopf, Bernhard and Pal, Christopher and Larochelle, Hugo and Goyal, Anirudh and Rahaman, Nasim},
  booktitle = {Advances in Neural Information Processing Systems},
  year      = {2026},
  eprint    = {2603.01092},
  archivePrefix = {arXiv},
  url       = {https://arxiv.org/abs/2603.01092}
}

研究地图 — Lacuna

@misc{weiss2026lacunaresearchmapmachine,
  title         = {Lacuna: A Research Map for Machine Learning},
  author        = {Martin Weiss and Miles Q. Li and Alejandro H. Artiles and Yacine Mkhinini and Chris Pal and Hugo Larochelle and Nasim Rahaman},
  year          = {2026},
  eprint        = {2606.26246},
  archivePrefix = {arXiv},
  primaryClass  = {cs.DL},
  url           = {https://arxiv.org/abs/2606.26246}
}

许可证

MIT。请参阅 LICENSE。