内容
<!-- mcp-name: io.github.tiptreesystems/lacuna-research-mcp -->
<p align="center">
<img src="https://raw.githubusercontent.com/tiptreesystems/lacuna-research-mcp/main/assets/banner.svg" alt="Lacuna Research MCP — 为机器学习研究赋予您的代码代理以创新能力" width="100%" />
</p>
<p align="center">
<a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white" alt="Python 3.11+" /></a>
<a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-server-7C3AED" alt="MCP server" /></a>
<a href="https://github.com/tiptreesystems/lacuna-research-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT license" /></a>
</p>
# Lacuna Research MCP
### 🔬 为机器学习研究赋予您的代码代理以创新能力
Lacuna Research MCP 为 AI 研究人员的代码代理提供：
- **新颖的研究提案。** 探索通过 [Alien Science](https://openreview.net/pdf?id=XZWkDET1ia) 生成的新颖研究想法。
- **研究方向。** 导航具有链接论文、作者和提案的概念集群。
- **代理准备的文献。** 以 Markdown 格式搜索最近的论文，并附带源链接。
- **研究人员情报。** 跟踪作者、出版物、方向、影响和相关研究人员。
- **研究现状映射。** 比较不同研究机构、顶级研究人员和发文情况。
[Lacuna](https://lacuna.tiptreesystems.com) 由 [Tiptree Systems](https://tiptreesystems.com) 构建，是一个机器学习研究图谱：一个异构知识图，连接论文、研究方向、作者、会议、机构和生成的研究提案，带有从每个派生对象到确切论文和生成它的页面的源轨迹。其管道协调 OpenAlex、OpenReview、DBLP 和 arXiv 的学者记录；从论文文本中提取概念元素，并将它们聚类成研究方向（[Lacuna 论文](https://arxiv.org/abs/2606.26246)）；并使用 [Alien Science](https://arxiv.org/abs/2603.01092) 从这些方向中采样新颖的研究提案。该图谱涵盖了 **730,000 篇论文**、**190,000+ 作者资料**、**38,000+ 研究方向** 和 **3,000+ 研究提案**，基于 **1500 万个概念元素** — 并且随着新的 arXiv 和其他 AI 论文的摄入而不断增长。
[安装](#安装) · [首次使用](#首次使用) · [工具](#工具) · [API 参考](#api-参考) · [配置](#环境变量)
## 安装
安装 Lacuna Research MCP 的最简单方法是询问您的代码代理，例如 Codex 或 Claude Code：
> 使用 PyPI 的 `lacuna-research-mcp` 包为此客户端安装并配置。
对于手动设置，以下说明使用 [`uvx`](https://docs.astral.sh/uv/guides/tools/) 运行 PyPI 上最新的标记版本。首先安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)；Lacuna Research MCP 需要 Python 3.11 或更新版本。
### Codex
使用 Codex CLI 添加服务器：
```bash
codex mcp add lacuna-research -- uvx lacuna-research-mcp
```
或者，将以下内容添加到 `~/.codex/config.toml`（或 `.codex/config.toml`，适用于受信任的项目）：
```toml
[mcp_servers.lacuna-research]
command = "uvx"
args = ["lacuna-research-mcp"]
```
运行 `codex mcp list` 以验证服务器已配置。Codex 应用程序、CLI 和 IDE 扩展在同一台机器上共享此配置。
### Claude Code
使用 Claude Code CLI 为所有项目添加服务器：
```bash
claude mcp add --scope user lacuna-research -- uvx lacuna-research-mcp
```
省略 `--scope user` 仅为当前项目添加。或者，在 `~/.claude.json` 中添加以下内容：
```json
{
"mcpServers": {
"lacuna-research": {
"type": "stdio",
"command": "uvx",
"args": ["lacuna-research-mcp"]
}
}
}
```
运行 `claude mcp get lacuna-research` 以验证服务器已配置。
### Claude Desktop
打开 **设置 → 开发者 → 编辑配置**，然后在 `claude_desktop_config.json` 中的 `mcpServers` 下添加服务器：
```json
{
"mcpServers": {
"lacuna-research": {
"command": "uvx",
"args": ["lacuna-research-mcp"]
}
}
}
```
保存文件后重启 Claude Desktop。
### 其他 MCP 客户端
对于任何支持本地 stdio MCP 服务器的客户端，请使用此标准配置：
```json
{
"mcpServers": {
"lacuna-research": {
"command": "uvx",
"args": ["lacuna-research-mcp"]
}
}
}
```
### 独立命令
将 MCP 服务器安装为永久命令：
```bash
uv tool install lacuna-research-mcp
lacuna-research-mcp
```
在不安装永久命令的情况下运行：
```bash
uvx lacuna-research-mcp
```
### 最新开发版本
PyPI 包含标记版本。要尝试 `main` 分支上的最新代码：
```bash
uvx --from git+https://github.com/tiptreesystems/lacuna-research-mcp.git lacuna-research-mcp
```
### 本地开发
使用 uv：
```bash
git clone https://github.com/tiptreesystems/lacuna-research-mcp.git
cd lacuna-research-mcp
uv sync --extra dev
uv run lacuna-research-mcp
```
使用 pip：
```bash
cd <path-to-lacuna-research-mcp>
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .
```
## 首次使用
连接服务器后，调用：
1. `search_lacuna(query="LLM jailbreak defense", search_type="hypothesis", limit=10)`
2. `search_lacuna(query="methods for detecting prompt injection attacks", search_type="papers", limit=10)` （默认生产词性 + 语义论文排名）
3. `get_hypothesis(hypothesis_id_or_url="bd35de182c2325ae")`
4. `get_paper(artifact_id_or_url="art_79c57fbfec094f26b79c422cf08fed34")` （默认为 `view="context"`）
5. `get_direction(cluster_id_or_url=25108)` （默认为 `view="context"`）
## 范围
该语料库涵盖机器学习和人工智能研究：论文、研究方向、作者的研究成果、会议、机构和生成的研究假设。它不包含传记、新闻或非研究网络内容。代理应从其他来源回答超出该范围的问题。
## 工具
- `search_lacuna`
使用 Lacuna 的公共 `/api/v1/search` 端点，用于查找方向、论文、作者、会议、机构和假设。显式论文搜索（`search_type="paper"`）在其他排名参数保持默认值时使用服务器的生产词性 + 语义排名器。传递 `search_type="hypothesis"`（或 `"hypotheses"` / `"proposal"` / `"proposals"`）进行假设搜索。
- `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)`
论文查找。`view="context"`（默认）请求紧凑的面向代理的上下文；其他视图是 `"full"`、`"preview"`、`"blog"`、`"figures"`、`"concepts"` 或 `"neighbors"`。在上下文视图中，`figure_limit` 限制了图预览（服务器默认值为 3；传递 0 以禁止预览，同时保留 `figures_truncated` 信号）。
- 作者工具：
`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`。上下文工具默认为紧凑（上限列表，重复块删除；会议保留最近活动切片，始终包括请求的年份）。使用 `get_institution_authors` 分页浏览机构的完整作者列表。
## API 参考
| MCP 工具 | Lacuna API 端点 |
| --- | --- |
| `search_lacuna(query, search_type, limit, offset, date_from, date_to, venue, sort, ranking_profile, fields)` | `GET /api/v1/search`（`fields` 限制/权重文本字段用于词性排名，例如 `title^4,abstract`，并选择实验词性排名器；对于默认相关性排序的论文搜索，此操作绕过生产词性 + 语义排名器。允许的字段是 `title`、`abstract`、`summary`、`concepts`、`name`、`top_names`、`venue`，每个仅适用于它们携带的类型 — `title`：论文/集群/会议/假设；`abstract`/`summary`/`concepts`：论文；`name`：作者/机构/会议；`top_names`：集群/假设；`venue`：论文/会议（`search_type="all"` 跨所有）。权重必须满足 `0 < weight <= 100`。未知字段、超出范围的权重、类型不兼容的字段和 `fields` 与 `ranking_profile="semantic"` 组合时会被拒绝，因为服务器会无声地丢弃、限制或忽略它们。） |
| `get_hypothesis(hypothesis_id_or_url, view="context")` | `view="context"` → `GET /api/v1/context/hypothesis/{hypothesis_id}?view=compact`；`view="full"` → `GET /api/v1/hypotheses/{hypothesis_id}` |
| `get_direction(cluster_id_or_url, view="context")` | `view="context"` → `GET /api/v1/context/direction/{cluster_id}?view=compact`；`view="full"` → `GET /api/v1/clusters/{cluster_id}` |
| `get_direction_papers(cluster_id_or_url, page, limit, view="compact")` | `GET /api/v1/clusters/{cluster_id}/papers?view=compact`（默认）或 `?view=complete` |
| `get_paper(artifact_id_or_url, view="context", figure_limit=None)` | `view="context"` → `GET /api/v1/context/paper/{artifact_id}?view=compact`（`&figure_limit=N` 设置时）；`view="full"` → `GET /api/v1/papers/{artifact_id}`；`view="preview"` → `…/preview`；`view="blog"` → `…/blog`；`view="figures"` → `…/figures`；`view="concepts"` → `…/concepts`；`view="neighbors"` → `…/neighbors` |
| `get_author_papers(author_id_or_url, limit=50, offset=0)` | `GET /api/v1/authors/{author_id}/papers` |
| `get_author_directions(author_id_or_url, limit=50, offset=0)` | `GET /api/v1/authors/{author_id}/directions` |
| `get_author_context(author_id_or_url, view="context", include_neighbors=false)` | `view="context"` → `GET /api/v1/context/author/{author_id}?view=compact`；`view="full"` → `GET /api/v1/context/author/{author_id}`（`include_neighbors=true` 显式请求相似作者） |
| `get_author_neighbors(author_id_or_url, limit=8, offset=0)` | `GET /api/v1/authors/{author_id}/neighbors` |
| `get_venue_context(venue_key_or_url, year, view="context")` | `view="context"` → `GET /api/v1/context/venue/{vkey}[/{year}]?view=compact`；`view="full"` → 同一路由无 `view` |
| `get_institution_context(institution_key_or_url, view="context")` | `view="context"` → `GET /api/v1/context/institution/{ikey}?view=compact`；`view="full"` → 同一路由无 `view` |
| `get_institution_authors(institution_key_or_url, limit=50, offset=0)` | `GET /api/v1/institutions/{ikey}/authors` |
对于 id 或 URL 参数，请传递 `search_lacuna` 返回的原始 id 或相应的 Lacuna 页面 URL。MCP 规范化 Lacuna 相对的 `url` 和 `*_
对于 id 或 URL 参数，请传递 `search_lacuna` 返回的原始 id 或相应的 Lacuna 页面 URL。MCP 规范化 Lacuna 相对 URL 和 markdown 字段中的 URL，例如 `summary_markdown` 和 `description`。
`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` 未设置，它使用服务器的生产词性 + 语义排名器，具有优雅的回退。对于 `search_type="all"` 的默认词性排名，MCP 默认使用服务器的词性排名。
- `semantic`
用于基于嵌入的论文检索。语义查询省略了正常的词性排名腿，但服务器仍然可以叠加精确标题的词性匹配。仅支持 `paper` 和 `all` 搜索（只有论文才有语义嵌入）。
- `bm25_title_abstract` / `bm25`
用于仅限标题和摘要的词性匹配。作者和机构搜索被拒绝（那些记录没有标题或摘要字段）。对于 `title` 和 `abstract` 字段不支持 `ranking_profile="semantic"`，因为服务器将无声地回退到子字符串搜索并忽略请求的排名配置文件。
所有搜索都使用服务器默认配置，除非提供 `ranking_profile`。MCP 拒绝不支持的配置文件/类型组合，因为服务器将无声地回退到子字符串搜索并忽略请求的排名配置文件。
`sort` 接受 `relevance`（默认）、`year_desc` 和 `year_asc`。年份排序不能与 `ranking_profile="semantic"` 结合使用 — 服务器将无声地忽略排序 — 因此对于最新和最相关的查询，请保留语义排名并使用 `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 token，作为 `Authorization: Bearer ...` 发送，用于 Lacuna 私有部署。
- `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`
FastMCP 应用程序创建、工具注册、生命周期清理和 `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`
运行时常量、包用户代理构造和环境解析。
- `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`（如果可用）或作者、图表和相关方向的缩略图。方向上下文包括 `summary_markdown`、上限论文/作者/相关方向和截断标记。使用 `view="full"` 获取原始元数据，以及其他论文视图（`preview`、`blog`、`figures`、`concepts`、`neighbors`），当您需要一个孤立的子资源时。
- 显式相关性排序的论文搜索（无自定义 `fields`）默认使用服务器的生产词性 + 语义排名器。设置 `ranking_profile="semantic"` 进行基于嵌入的检索（可能带有精确标题叠加），或 `"bm25_title_abstract"` 进行标题和摘要词性匹配。
- 搜索类型别名在客户端规范化，因此接受并映射到服务器的单一值的是 `papers`、`directions` 和 `hypotheses`。
- 大多数详细信息工具接受搜索返回的 ID 或相应的 Lacuna URL。
- `url`/`*_url` 响应字段和 `summary_markdown`、`article_markdown`、`markdown`、`content` 或 `description` 命名字段中的相对 Lacuna URL 规范化为绝对 URL。
- 会议和机构密钥是不透明的哈希值（例如 `d7bf22905bd6`），而不是人类可读的名称如 `icml`。首先使用 `search_lacuna(search_type="venue")` 查找密钥，或将 `/venue/...` 页面 URL 传递给 `get_venue_context`。
## 引文
如果您发现我们的工作对您有所帮助，请随意引用 Lacuna 研究提案和研究地图背后的论文。
**研究提案生成 — Alien Science**
```bibtex
@inproceedings{artiles2026alien,
title = {Alien Science: Sampling Coherent but Cognitively Unavailable Research Directions from Idea Atoms},
author = {Artiles, Alejandro H. and Weiss, Martin and Brinkmann, Levin and Goyal, Anirudh and Rahaman, Nasim},
booktitle = {ICLR 2026 Workshop on Post-AGI Science and Society},
year = {2026},
url = {https://openreview.net/forum?id=XZWkDET1ia}
}
```
**研究地图 — Lacuna**
```bibtex
@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](https://github.com/tiptreesystems/lacuna-research-mcp/blob/main/LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器