Lacuna Research

Lacuna Research MCP

Lacuna, созданная Tiptree Systems, — это карта исследований в области машинного обучения: неоднородный граф знаний, связывающий статьи, направления исследований, авторов, площадки публикаций, учреждения и сгенерированные исследовательские предложения. Для каждого производного объекта в нём прослеживается цепочка источников вплоть до конкретной статьи и страницы, на основе которых он создан.

Lacuna Research MCP предоставляет агентам для написания кода, используемым исследователями ИИ:

• Сгенерированные исследовательские предложения. Изучайте исследовательские идеи, созданные с помощью 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 и откройте раздел Customize, чтобы проверить два навыка и подключение 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)

Используйте размещённый MCP-сервер Lacuna с любым клиентом, поддерживающим Streamable HTTP. Локальная установка не требуется.

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

В Claude откройте Customize → Connectors → + Add → Add custom connector. Назовите его Lacuna Research, вставьте URL выше и при запросе аутентификации выберите No sign in. Завершите добавление, затем включите коннектор в беседе через + → Connectors.

В рабочих пространствах Team и Enterprise коннектор сначала нужно добавить в разделе Organization settings → Connectors. Подробности см. в инструкции по настройке пользовательского коннектора Claude.

Локальная установка

Проще всего установить Lacuna Research MCP, попросив своего агента для написания кода, например Codex или Claude Code:

Установи и настрой пакет lacuna-research-mcp из PyPI для этого клиента.

Для ручной настройки приведённые ниже инструкции используют 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, чтобы добавить сервер только для текущего проекта. Или добавьте следующую запись в объект верхнего уровня mcpServers в файле ~/.claude.json:

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

Выполните claude mcp get lacuna-research, чтобы проверить настройку сервера.

Claude Desktop

Откройте Settings → Developer → Edit Config, затем добавьте сервер в раздел mcpServers файла claude_desktop_config.json:

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

После сохранения файла перезапустите Claude Desktop.

Другие клиенты MCP

Для любого клиента, поддерживающего локальные MCP-серверы stdio, используйте эту стандартную конфигурацию:

{
  "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 is a prerelease...»), значит, uv использует предварительную версию Python 3.14, которую MCP SDK не поддерживает. Обновите uv (uv self update), установите выпущенную версию Python (uv python install 3.14) или выполните uvx --python 3.13 lacuna-research-mcp.

Самостоятельно размещённый HTTP-сервер

Чтобы обслуживать удалённых клиентов MCP через Streamable HTTP вместо stdio:

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

Адрес конечной точки: /mcp. Сервер не хранит состояние и отвечает в формате JSON, поэтому может работать за балансировщиком нагрузки без привязки к сессии. При значении --host 127.0.0.1 по умолчанию сервер принимает заголовки Host только от localhost, поэтому при пересылке общедоступного имени хоста обратным прокси привяжите сервер к адресу, отличному от loopback.

Последняя версия для разработки

В 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 создаются новые исследовательские предложения. Карта охватывает более 2,29 миллиона статей, 215 000+ профилей авторов, 28 000+ направлений исследований, 25 000+ исследовательских предложений и 5 300+ площадок публикаций — и постоянно пополняется новыми статьями из arXiv и других работ по ИИ.

Область охвата

Корпус охватывает исследования в области машинного обучения и ИИ: статьи, направления исследований, научные работы авторов, площадки публикаций, учреждения, сгенерированные исследовательские гипотезы и исследовательские ресурсы (репозитории GitHub, наборы данных и модели Hugging Face, записи Zenodo), связанные со статьями. В нём нет биографий, новостей и веб-контента, не связанного с исследованиями. На вопросы за пределами этой области агенты должны отвечать, используя другие источники.

Что доступно

• search_lacuna Использует общедоступную конечную точку /api/v1/search Lacuna для поиска направлений, статей, авторов, площадок, учреждений, гипотез и ресурсов. Явный поиск статей (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" (по умолчанию) возвращает строки, готовые для цитирования (идентификатор, URL, название, год, площадка, несколько авторов, фрагмент аннотации); view="full" возвращает исходные записи статей из вышестоящего источника.
• get_paper(artifact_id_or_url, view="context", figure_limit=None, include_resources=True) Поиск статьи с доступными версиями; для чтения используйте идентификатор артефакта версии. Связанные ресурсы (репозитории кода, наборы данных, модели и демонстрации) по умолчанию включаются в представления context и full; передайте include_resources=False, чтобы исключить их. Другие представления игнорируют этот параметр. view="context" (по умолчанию) запрашивает компактный контекст для агента; другие представления: "full", "preview", "blog", "figures", "concepts" или "neighbors". В представлении context параметр figure_limit ограничивает предварительный просмотр рисунков (значение сервера по умолчанию — 3; передайте 0, чтобы отключить предварительный просмотр, сохранив сигнал figures_truncated).
• get_resource(resource_id_or_url) Поиск ресурса по идентификатору (из результатов поиска ресурсов или списка resources у get_paper) либо по URL Lacuna /resource/...: внешний 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

Для аргументов, принимающих идентификатор или URL, передавайте либо необработанный идентификатор, возвращённый search_lacuna, либо соответствующий URL страницы Lacuna. MCP преобразует относительные к Lacuna поля url и *_url в абсолютные URL, а также преобразует ссылки Lacuna в абсолютные URL (включая страницы /resource/...) внутри полей с именами summary_markdown, article_markdown, markdown, content или description.

get_author_context ограничивается на стороне сервера в обоих представлениях. Представление compact по умолчанию возвращает тщательно составленную сводку; 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" включает статьи с 1 января 2020 года по 31 марта 2022 года.

search_lacuna предоставляет следующие профили ранжирования:

• default / lexical Профиль по умолчанию для всех поисковых запросов. Если search_type="paper", sort="relevance" и fields не заданы, используется производственный лексико-семантический ранжировщик сервера с резервным вариантом на случай сбоя. Вместо этого значение search_type="all" по умолчанию в MCP использует стандартное лексическое ранжирование сервера.
• 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, чтобы идентифицировать размещённый сервер MCP для Lacuna и учитывать его собственный лимит частоты поисковых запросов.
• LACUNA_MCP_LOG_LEVEL По умолчанию — WARNING (одно из значений: DEBUG, INFO, WARNING, ERROR, CRITICAL). Значение по умолчанию обеспечивает тихую работу; снижайте его только для отладки, поскольку INFO/DEBUG позволяют HTTP-клиенту записывать в stderr полные URL запросов, включая строку поискового запроса, которые некоторые хосты MCP сохраняют.

Переменные окружения считываются один раз при создании сервера MCP или при первом прямом вызове инструмента/API, если модуль импортирован без вызова create_mcp().

Структура реализации

Сервер — это тонкий адаптер MCP поверх HTTP API Lacuna. Реализация разделена по обязанностям:

• lacuna_research_mcp/server.py Создание приложения MCPServer, регистрация инструментов, очистка при завершении жизненного цикла и точка входа CLI lacuna-research-mcp.
• lacuna_research_mcp/tools.py Функции инструментов MCP. Каждый инструмент нормализует входные данные, вызывает соответствующую конечную точку API Lacuna через общие вспомогательные функции клиента и возвращает данные в формате, совместимом с 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 Вспомогательные функции, принимающие необработанные идентификаторы или URL страниц Lacuna и извлекающие безопасные сегменты пути API.
• lacuna_research_mcp/normalize.py Постобработка ответов для относительных URL Lacuna и ссылок в Markdown.
• lacuna_research_mcp/errors.py Тип исключения для ошибок доступа к API Lacuna, предназначенный для отображения пользователю.

Примечания

• 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" для лексического поиска по заголовку и аннотации.
• Большинство инструментов для получения подробной информации принимают либо идентификатор, возвращённый поиском, либо соответствующий URL Lacuna.
• Относительные URL Lacuna в полях ответа url/*_url и полях с именами summary_markdown, article_markdown, markdown, content или description преобразуются в абсолютные URL.
• Ключи площадок и учреждений — это непрозрачные хеши (например, d7bf22905bd6), а не понятные человеку названия вроде icml. Сначала найдите ключ с помощью search_lacuna(search_type="venue") или передайте URL страницы /venue/....

Цитирование

Если наша работа оказалась полезной, можете процитировать статьи, лежащие в основе генерации исследовательских предложений и карты исследований 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.