Lacuna Research

Lacuna Research MCP

Lacuna, desenvolvido pela Tiptree Systems, é um mapa de pesquisa em aprendizado de máquina: um grafo de conhecimento heterogêneo que conecta artigos, linhas de pesquisa, autores, veículos de publicação, instituições e propostas de pesquisa geradas, com um histórico de fontes que leva de cada objeto derivado ao artigo e à página exatos que o originaram.

O Lacuna Research MCP oferece aos agentes de programação de pesquisadores de IA:

• Propostas de pesquisa geradas. Explore ideias de pesquisa geradas com The Alien Space of Science.
• Linhas de pesquisa. Navegue por agrupamentos de conceitos com artigos, autores e propostas vinculados.
• Literatura pronta para agentes. Pesquise artigos recentes em Markdown com links para as fontes.
• Inteligência sobre pesquisadores. Rastreie autores, publicações, linhas de pesquisa, impacto e pesquisadores relacionados.
• Mapeamento do panorama. Compare veículos de publicação, instituições, pesquisadores de destaque e atividade de publicação.

Por exemplo, rastreie uma implementação até as relações registradas com artigos:

Encontre o artigo por trás de Dao-AILab/flash-attention. Mostre a relação registrada com o repositório e vincule o artigo original.

Este exemplo segue repositório → relação registrada com o artigo → artigo e fontes. O Lacuna retorna a relação official_code_for com FlashAttention, com links para o repositório e o artigo original. Inspecione essas fontes para verificar a conexão. Execute o exemplo ou acompanhe o notebook.

Instalação · Skills de pesquisa · Primeiro uso · Ferramentas · Referência da API · Configuração

Instalação

Plugin de agente para Cursor

Este repositório também empacota a conexão MCP hospedada e as duas skills de pesquisa como um Agent Plugin. O Cursor oferece suporte a esse formato.

Para testá-lo localmente, copie este repositório para ~/.cursor/plugins/local/lacuna-research-mcp, recarregue o Cursor e abra Customize para verificar as duas skills e a conexão MCP. O plugin se conecta a https://lacuna.tiptreesystems.com/api/mcp; não é necessário instalar o Python localmente nem ter uma conta Lacuna. Ative esta conexão ou um servidor Lacuna configurado manualmente para evitar ferramentas duplicadas.

Cursor e VS Code

Use o servidor hospedado sem instalar o Python localmente nem ter uma conta Lacuna:

Os botões abrem o fluxo de instalação MCP do seu editor. Confira a URL do servidor e confirme a instalação. Depois de conectar, faça a pergunta sobre FlashAttention acima; seu agente deverá usar search_lacuna, get_resource e get_paper.

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

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

Servidor MCP hospedado (conector do Claude)

Use o servidor MCP hospedado do Lacuna com qualquer cliente compatível com Streamable HTTP. Não é necessária instalação local.

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

No Claude, abra Customize → Connectors → + Add → Add custom connector. Dê a ele o nome Lacuna Research, cole a URL acima e selecione No sign in se a autenticação for solicitada. Conclua a adição e, em seguida, ative-o em + → Connectors na conversa.

Em espaços de trabalho Team e Enterprise, primeiro é necessário adicionar o conector em Organization settings → Connectors. Consulte a configuração de conectores personalizados do Claude para obter detalhes.

Instalação local

A maneira mais fácil de instalar o Lacuna Research MCP é pedir ao seu agente de programação, como Codex ou Claude Code:

Instale e configure o pacote lacuna-research-mcp do PyPI para este cliente.

Para configurar manualmente, as instruções abaixo usam uvx para executar a versão mais recente marcada no PyPI. Instale uv primeiro; o Lacuna Research MCP requer Python 3.11 ou mais recente.

Codex

Adicione o servidor com a CLI do Codex:

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

Como alternativa, adicione o seguinte a ~/.codex/config.toml (ou a .codex/config.toml em um projeto confiável, para configurar apenas o projeto):

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

Execute codex mcp list para verificar se o servidor está configurado. O aplicativo Codex, a CLI e a extensão de IDE compartilham essa configuração na mesma máquina.

Claude Code

Adicione o servidor a todos os seus projetos com a CLI do Claude Code:

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

Omita --scope user para adicioná-lo somente ao projeto atual. Como alternativa, adicione o seguinte ao objeto de nível superior mcpServers em ~/.claude.json:

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

Execute claude mcp get lacuna-research para verificar se o servidor está configurado.

Claude Desktop

Abra Settings → Developer → Edit Config e adicione o servidor em mcpServers em claude_desktop_config.json:

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

Reinicie o Claude Desktop depois de salvar o arquivo.

Outros clientes MCP

Para qualquer cliente compatível com servidores MCP locais via stdio, use esta configuração padrão:

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

Comando independente

Instale o servidor MCP como um comando persistente:

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

Execute-o sem instalar um comando persistente:

uvx lacuna-research-mcp

Se isso terminar com um erro de pré-lançamento (por exemplo, "Python 3.14.0rc2 is a prerelease..."), seu uv está usando uma versão de pré-lançamento inicial do Python 3.14, incompatível com o MCP SDK. Atualize o uv (uv self update), instale uma versão lançada do Python (uv python install 3.14), ou execute uvx --python 3.13 lacuna-research-mcp.

Servidor HTTP auto-hospedado

Para atender clientes MCP remotos por Streamable HTTP em vez de stdio:

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

O endpoint é /mcp. O servidor não mantém estado e responde com JSON, portanto pode ser executado atrás de um balanceador de carga sem afinidade de sessão. Com o --host 127.0.0.1 padrão, o servidor aceita somente cabeçalhos Host de localhost; portanto, vincule-o a um endereço que não seja de loopback quando um proxy reverso encaminhar um nome de host público.

Versão de desenvolvimento mais recente

O PyPI contém versões marcadas. Para experimentar o código mais recente da branch main:

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

Desenvolvimento local

Com uv:

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

Com 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 .

Skills de pesquisa

O servidor MCP fornece ferramentas. Estas skills opcionais ensinam seu agente a usá-las em duas tarefas de pesquisa:

Conecte primeiro o servidor MCP. Em seguida, com Node.js 22.20+ instalado, execute a CLI de skills no seu projeto:

npx skills add tiptreesystems/lacuna-research-mcp

Escolha as skills e o agente que você usa. Para instalar somente o fluxo de trabalho de código para artigo:

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

Por padrão, as skills são instaladas no projeto atual. Elas não instalam nem configuram o servidor MCP. Inicie uma nova sessão do agente após a instalação se o seu cliente precisar de uma nova sessão para descobrir as skills.

Primeiro uso

Faça uma das perguntas acima no agente conectado ou experimente uma pergunta sobre uma lista de leitura:

Minha lista tem FlashAttention e FlashAttention-2. Quais linhas de base ou limitações devo ler sobre atenção de contexto longo?

Para um exemplo reproduzível sem chave de API de modelo, clone este repositório e execute:

uv run examples/code_to_paper.py

O notebook explica cada etapa e compara o histórico de fontes com uma única pesquisa de artigos. Para usar as ferramentas diretamente, o fluxo é:

1. search_lacuna(query="FlashAttention", search_type="resource", resource_kind="codebase", limit=5)
2. Confira a identidade do repositório e passe o ID retornado para get_resource(resource_id_or_url=...).
3. Siga um publications[].paper_id retornado com get_paper(artifact_id_or_url=..., view="context", figure_limit=0).

Para pesquisar literatura, use search_lacuna(query="methods for detecting prompt injection attacks", search_type="paper", limit=5). Para propostas geradas, use search_lacuna(query="LLM jailbreak defense", search_type="hypothesis", limit=5) e siga um ID retornado com get_hypothesis. Propostas geradas são ideias para investigar, não evidências de descobertas publicadas.

Sobre o Lacuna

O pipeline do Lacuna reconcilia registros acadêmicos do OpenAlex, OpenReview, DBLP e arXiv; extrai elementos conceituais do texto dos artigos e os agrupa em linhas de pesquisa (artigo do Lacuna); e amostra propostas de pesquisa inéditas dessas linhas com The Alien Space of Science. O mapa abrange mais de 2,29 milhões de artigos, 215.000+ perfis de autores, 28.000+ linhas de pesquisa, 25.000+ propostas de pesquisa e 5.300+ veículos de publicação — e cresce continuamente à medida que novos artigos do arXiv e de outras fontes de IA são incorporados.

Escopo

O corpus abrange pesquisas em aprendizado de máquina e IA: artigos, linhas de pesquisa, produção acadêmica de autores, veículos de publicação, instituições, hipóteses de pesquisa geradas e recursos de pesquisa (repositórios GitHub, conjuntos de dados e modelos do Hugging Face, registros do Zenodo) vinculados a artigos. Ele não contém biografias, notícias nem conteúdo da web que não seja de pesquisa. Agentes devem responder a perguntas fora desse escopo usando outras fontes.

O que ele disponibiliza

• search_lacuna Usa o endpoint público /api/v1/search da Lacuna para direções, artigos, autores, periódicos, instituições, hipóteses e recursos. Buscas explícitas de artigos (search_type="paper") usam o ranqueador lexical+semântico de produção do servidor quando os outros argumentos de classificação permanecem nos valores padrão. Passe search_type="hypothesis" para buscar hipóteses. Passe search_type="resource" para buscar repositórios de código, conjuntos de dados, modelos e demonstrações vinculados a artigos, opcionalmente filtrados com resource_kind (codebase, dataset, model, demo) e provider (github, huggingface, zenodo); por exemplo, resource_kind="dataset" encontra conjuntos de dados de benchmark. A busca de recursos rejeita date_from/date_to, venue, ordenações por ano e classificação semântica (os recursos não têm datas, periódicos nem embeddings).
• get_hypothesis(hypothesis_id_or_url, view="context") Hipótese/proposta. view="context" (padrão) é um contexto compacto de proposta obtido em uma única busca (resumo, abstract, direções vinculadas); view="full" retorna o registro de versões do servidor com histórico de versões e contagens de sinais. Os corpos das propostas estão em versions[].markdown.
• get_direction(cluster_id_or_url, view="context") Direção de pesquisa/agrupamento. view="context" (padrão) solicita o resumo compacto voltado a agentes; view="full" retorna o registro bruto do agrupamento.
• get_direction_papers(cluster_id_or_url, page, limit, view="compact") Artigos paginados associados a uma direção. view="compact" (padrão) retorna linhas prontas para citação (id, url, título, ano, periódico, alguns autores, trecho do abstract); view="full" retorna os registros brutos dos artigos da fonte upstream.
• get_paper(artifact_id_or_url, view="context", figure_limit=None, include_resources=True) Consulta de artigo com versões disponíveis; use o ID de artefato de uma versão para lê-la. Os recursos vinculados (repositórios de código, conjuntos de dados, modelos e demonstrações) são incluídos por padrão nas visualizações de contexto e completa; passe include_resources=False para omiti-los. As outras visualizações ignoram essa opção. view="context" (padrão) solicita o contexto compacto voltado a agentes; as outras visualizações são "full", "preview", "blog", "figures", "concepts" ou "neighbors". Na visualização de contexto, figure_limit limita a prévia de figuras (padrão do servidor: 3; passe 0 para suprimir as prévias e manter um sinal figures_truncated).
• get_resource(resource_id_or_url) Consulta de recurso por id (da busca de recursos ou da lista resources de get_paper) ou URL /resource/... da Lacuna: URL externa, resumo, facetas (tarefas, modalidades, tamanho, licença), métricas do provedor, trecho do README/cartão, artigos vinculados em publications (com paper_id e relação, como dataset_for), direções relacionadas e recursos mencionados.
• Ferramentas de autor: get_author_context(…, view="context"), get_author_papers, get_author_directions e get_author_neighbors. Comece com get_author_context, que usa por padrão a visualização compacta voltada a agentes (artigos limitados e uma lista impact_directions legível, em vez de telemetria bruta impact_clusters). Use as ferramentas dedicadas de artigos, direções e vizinhos para percorrer essas coleções sem repetir o contexto do autor. view="full" retorna o contexto completo, limitado pelo servidor (as coleções permanecem limitadas a 100). Passe include_neighbors=true para incluir explicitamente autores semelhantes; isso pode aumentar significativamente a latência do servidor.
• Ferramentas de periódico e instituição: get_venue_context(…, view="context"), get_institution_context(…, view="context"), get_institution_authors. As ferramentas de contexto usam por padrão o formato compacto (listas limitadas, blocos duplicados removidos; o periódico mantém um recorte de atividade recente que sempre inclui o year solicitado). Use get_institution_authors para percorrer a lista completa de autores de uma instituição.

APIs encapsuladas

Para argumentos de id ou URL, passe o id bruto retornado por search_lacuna ou a URL da página correspondente na Lacuna. O MCP normaliza os campos url e *_url relativos à Lacuna para URLs absolutas e também converte links da Lacuna em URLs absolutas (incluindo páginas /resource/...) dentro dos campos chamados summary_markdown, article_markdown, markdown, content ou description.

get_author_context é limitado no servidor em ambas as visualizações. A visualização compacta padrão retorna um resumo selecionado; view="full" retorna a estrutura completa ampliada, com coleções incorporadas limitadas a 100. Use get_author_papers e get_author_directions em vez de tentar paginar coleções de contexto incorporadas.

As buscas são limitadas a 50 resultados por chamada, e as solicitações de páginas de artigos por direção são limitadas a 100 resultados por chamada. Em search_lacuna, date_from e date_to são limites inclusivos de data de publicação. Os formatos aceitos são YYYY, YYYY-MM e YYYY-MM-DD; por exemplo, date_from="2020", date_to="2022-03" inclui artigos de 1º de janeiro de 2020 a 31 de março de 2022.

search_lacuna expõe estes perfis de classificação:

• default / lexical O perfil padrão para todas as buscas. Com search_type="paper", sort="relevance" e fields não definidos, usa o ranqueador lexical+semântico de produção do servidor, com fallback gradual. O search_type="all" padrão do MCP usa a classificação lexical padrão do servidor.
• semantic Use para recuperação de artigos baseada em embeddings. A consulta semântica omite a etapa normal de classificação lexical, mas o servidor ainda pode sobrepor correspondências lexicais de títulos exatos. Compatível apenas com buscas de paper e all (somente artigos têm embeddings semânticos), e não com filtros resource_kind/provider.
• bm25_title_abstract / bm25 Use para correspondência lexical restrita ao título e ao abstract. Rejeitado em buscas de author e institution (esses registros não têm campos de título ou abstract).

Todas as buscas usam o padrão do servidor, a menos que ranking_profile seja fornecido. O MCP rejeita combinações de perfil/tipo não compatíveis, pois, caso contrário, o servidor recorreria à busca por substring e ignoraria silenciosamente o perfil de classificação solicitado.

sort aceita relevance (padrão), year_desc e year_asc. Ordenações por ano não podem ser combinadas com ranking_profile="semantic" — o servidor ignoraria silenciosamente a ordenação —, portanto o MCP rejeita essa combinação; para consultas que priorizam resultados recentes e relevantes, mantenha a classificação semântica e restrinja a recência com date_from/date_to.

Variáveis de ambiente

• LACUNA_SITE_URL O padrão é https://lacuna.tiptreesystems.com
• LACUNA_MCP_TIMEOUT O padrão é 30
• LACUNA_MCP_MAX_RETRIES O padrão é 2; aplica-se a timeouts, erros de transporte e respostas HTTP 429, 502, 503 e 504.
• LACUNA_MCP_USER_AGENT O padrão é lacuna-research-mcp/{package_version}
• LACUNA_MCP_BEARER_TOKEN Token bearer opcional enviado como Authorization: Bearer ... para implantações privadas da Lacuna.
• LACUNA_MCP_CLIENT_TOKEN Token opcional enviado como X-Lacuna-Client-Token para identificar um servidor MCP hospedado à Lacuna, para o limite de taxa de busca próprio dela.
• LACUNA_MCP_LOG_LEVEL O padrão é WARNING (um de DEBUG, INFO, WARNING, ERROR, CRITICAL). O padrão mantém a operação normal silenciosa; reduza-o apenas para depuração, pois INFO/DEBUG permitem que o cliente HTTP registre URLs completas de solicitação — incluindo a string de consulta da busca — em stderr, que alguns hosts MCP retêm.

As variáveis de ambiente são lidas uma vez quando o servidor MCP é criado ou na primeira chamada direta a uma ferramenta/API, caso o módulo seja importado sem chamar create_mcp().

Estrutura da implementação

O servidor é um adaptador MCP simples sobre a API HTTP da Lacuna. A implementação é dividida por responsabilidade:

• lacuna_research_mcp/server.py Criação do aplicativo MCPServer, registro de ferramentas, limpeza do ciclo de vida e ponto de entrada CLI lacuna-research-mcp.
• lacuna_research_mcp/tools.py Funções das ferramentas MCP. Cada ferramenta normaliza suas entradas, chama o endpoint correspondente da API Lacuna por meio dos auxiliares compartilhados do cliente e retorna dados compatíveis com JSON.
• lacuna_research_mcp/client.py Acesso HTTP em tempo de execução à Lacuna: o httpx.AsyncClient vinculado ao loop de eventos, tratamento de novas tentativas, encapsulamento de erros, análise de JSON, normalização de URLs nas respostas e api_get/api_object/api_payload.
• lacuna_research_mcp/config.py Constantes de tempo de execução, RuntimeConfig, construção do user-agent do pacote e análise do ambiente.
• lacuna_research_mcp/ids.py Auxiliares que aceitam ids brutos ou URLs de páginas da Lacuna e extraem segmentos seguros de caminhos da API.
• lacuna_research_mcp/normalize.py Pós-processamento de respostas para URLs relativas da Lacuna e links Markdown.
• lacuna_research_mcp/errors.py Tipo de exceção voltado ao usuário para falhas de acesso à API Lacuna.

Observações

• get_paper e get_direction usam view="context" por padrão. Essas visualizações de contexto solicitam, por padrão, os payloads compactos e orientados a agentes do Lacuna para manter pequenas as respostas do MCP. O contexto de artigos inclui summary_markdown quando disponível (caso contrário, abstract), autores e figuras; o contexto de direções inclui summary_markdown, artigos/autores/direções relacionadas limitados e marcadores de truncamento. Use view="full" quando precisar dos metadados brutos e as outras visualizações de artigos (preview, blog, figures, concepts, neighbors) quando quiser um subrecurso isolado.
• Uma busca explícita de artigos ordenada por relevância, sem fields personalizado, usa por padrão o ranqueador lexical+semântico de produção do servidor. Defina ranking_profile="semantic" para recuperação baseada em embeddings (com uma possível sobreposição de títulos exatos) ou "bm25_title_abstract" para correspondência lexical de títulos e resumos.
• A maioria das ferramentas de detalhes aceita o ID retornado pela busca ou a URL correspondente do Lacuna.
• URLs relativas do Lacuna nos campos de resposta url/*_url e nos campos chamados summary_markdown, article_markdown, markdown, content ou description são normalizadas para URLs absolutas.
• As chaves de locais de publicação e instituições são hashes opacos (por exemplo, d7bf22905bd6), nunca nomes legíveis por humanos como icml. Primeiro, encontre a chave com search_lacuna(search_type="venue") ou passe uma URL de página /venue/....

Citação

Se nosso trabalho for útil para você, sinta-se à vontade para citar os artigos por trás da geração de propostas de pesquisa e do mapa de pesquisa do Lacuna.

Geração de propostas de pesquisa — 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}
}

Mapa de pesquisa — 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}
}

Licença

MIT. Consulte LICENSE.