Skip to main content
Glama
README.md
<!-- 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 — Empower your coding agent for machine learning research" 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&amp;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](https://lacuna.tiptreesystems.com), built by [Tiptree Systems](https://tiptreesystems.com), is a research map of machine learning: a heterogeneous knowledge graph linking papers, research directions, authors, venues, institutions, and generated research proposals, with a source trail from every derived object back to the exact paper and page that produced it.

Lacuna Research MCP gives AI researchers' coding agents:

- **Generated research proposals.** Explore research ideas generated with [The Alien Space of Science](https://arxiv.org/abs/2603.01092).
- **Research directions.** Navigate concept clusters with linked papers, authors, and proposals.
- **Agent-ready literature.** Search recent papers in markdown with source links.
- **Researcher intelligence.** Trace authors, publications, directions, impact, and related researchers.
- **Landscape mapping.** Compare venues, institutions, leading researchers, and publication activity.

For example, trace an implementation to its recorded paper relationships:

> Find the paper behind Dao-AILab/flash-attention. Show the recorded connection
> to the repository and link the original paper.

This example follows **repository → recorded paper relationship → paper and sources**.
Lacuna returns the `official_code_for` relationship to
[FlashAttention](https://lacuna.tiptreesystems.com/work/flashattention-fast-and-memory-efficient-exact-attention/version/art_15dcb323b0ad4ce28209944c81d9c45c),
with links to the repository and original paper. Inspect those sources to verify
the connection. [Run the example](https://github.com/tiptreesystems/lacuna-research-mcp/blob/main/examples/README.md) or
[work through the notebook](https://github.com/tiptreesystems/lacuna-research-mcp/blob/main/examples/code_to_paper.ipynb).

[Install](#install) · [Research skills](#research-skills) · [First use](#first-use) · [Tools](#what-it-exposes) · [API reference](#wrapped-apis) · [Configuration](#environment-variables)

## Install

### Agent plugin for Cursor

This repository also packages the hosted MCP connection and the two
[research skills](#research-skills) as an
[Agent Plugin](https://agent-plugins.org/). Cursor supports this format.

To test it locally, copy this repository to
`~/.cursor/plugins/local/lacuna-research-mcp`, reload Cursor, and open
**Customize** to check the two skills and the MCP connection. The plugin connects
to `https://lacuna.tiptreesystems.com/api/mcp`; no local Python installation or
Lacuna account is required. Enable either this connection or a manually configured
Lacuna server to avoid duplicate tools.

### Cursor and VS Code

Use the hosted server with no local Python installation or Lacuna account:

[![Add to Cursor](https://img.shields.io/badge/Add_to-Cursor-111827)](https://cursor.com/en/install-mcp?name=lacuna-research&config=eyJ1cmwiOiJodHRwczovL2xhY3VuYS50aXB0cmVlc3lzdGVtcy5jb20vYXBpL21jcCJ9)
[![Add to VS Code](https://img.shields.io/badge/Add_to-VS_Code-007ACC)](https://vscode.dev/redirect/mcp/install?name=lacuna-research&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Flacuna.tiptreesystems.com%2Fapi%2Fmcp%22%7D)

The buttons open your editor's MCP installation flow. Review the server URL and
confirm installation. After connecting, ask the FlashAttention question above;
your agent should use `search_lacuna`, `get_resource`, and `get_paper`.

<details>
<summary>Manual configuration if the install link doesn't open</summary>

In Cursor, merge this entry into `mcpServers` in `.cursor/mcp.json`:

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

In VS Code, merge this entry into `servers` in `.vscode/mcp.json`:

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

Keep any existing server entries. Open your editor's MCP settings to verify the
connection and enable Lacuna's tools for the conversation.

</details>

### Hosted MCP server (Claude connector)

Use Lacuna's hosted MCP server with any client that supports Streamable HTTP. No local installation is required.

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

In Claude, open **Customize → Connectors → + Add → Add custom connector**. Name it **Lacuna Research**, paste the URL above, and select **No sign in** if prompted for authentication. Finish adding it, then enable it from **+ → Connectors** in your conversation.

For Team and Enterprise workspaces, the connector must first be added under **Organization settings → Connectors**. See [Claude's custom connector setup](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for details.

### Local installation

The easiest way to install Lacuna Research MCP is to ask your coding agent, such as Codex or Claude Code:

> Install and configure the `lacuna-research-mcp` package from PyPI for this client.

For manual setup, the instructions below use [`uvx`](https://docs.astral.sh/uv/guides/tools/) to run the latest tagged release from PyPI. Install [uv](https://docs.astral.sh/uv/getting-started/installation/) first; Lacuna Research MCP requires Python 3.11 or newer.

### Codex

Add the server with the Codex CLI:

```bash
codex mcp add lacuna-research -- uvx lacuna-research-mcp
```

Alternatively, add the following to `~/.codex/config.toml` (or to `.codex/config.toml` in a trusted project for project-only setup):

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

Run `codex mcp list` to verify the server is configured. The Codex app, CLI, and IDE extension share this configuration on the same machine.

### Claude Code

Add the server for all of your projects with the Claude Code CLI:

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

Omit `--scope user` to add it only to the current project. Alternatively, add the following under the top-level `mcpServers` object in `~/.claude.json`:

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

Run `claude mcp get lacuna-research` to verify the server is configured.

### Claude Desktop

Open **Settings → Developer → Edit Config**, then add the server under `mcpServers` in `claude_desktop_config.json`:

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

Restart Claude Desktop after saving the file.

### Other MCP clients

For any client that supports local stdio MCP servers, use this standard configuration:

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

### Standalone command

Install the MCP server as a persistent command:

```bash
uv tool install lacuna-research-mcp
lacuna-research-mcp
```

Run it without installing a persistent command:

```bash
uvx lacuna-research-mcp
```

If this exits with a prerelease error (for example, "Python 3.14.0rc2 is a prerelease..."),
your uv is using an early Python 3.14 prerelease that the MCP SDK does not support.
Update uv (`uv self update`), install a released Python (`uv python install 3.14`),
or run `uvx --python 3.13 lacuna-research-mcp`.

### Self-hosted HTTP server

To serve remote MCP clients over Streamable HTTP instead of stdio:

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

The endpoint is `/mcp`. The server is stateless and answers with JSON, so it can run behind a load balancer without session affinity. With the default `--host 127.0.0.1`, the server accepts only localhost `Host` headers, so bind a non-loopback address when a reverse proxy forwards a public hostname.

### Latest development version

PyPI contains tagged releases. To try the latest code from the `main` branch instead:

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

### Local development

With 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
```

With 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 .
```

## Research skills

The MCP server provides tools. These optional skills teach your agent how to use
them for two research tasks:

| Skill | Example request |
| --- | --- |
| [Check prior work](https://github.com/tiptreesystems/lacuna-research-mcp/blob/main/skills/lacuna-prior-work/SKILL.md) | Before I implement token merging for a vision transformer, find the closest work and a baseline to include. |
| [Trace code to papers](https://github.com/tiptreesystems/lacuna-research-mcp/blob/main/skills/lacuna-code-to-paper/SKILL.md) | Which paper does Dao-AILab/flash-attention implement? Show the recorded relationship and sources. |

Connect the MCP server first. Then, with Node.js 22.20+ installed, run the
[skills CLI](https://github.com/vercel-labs/skills) from your project:

```bash
npx skills add tiptreesystems/lacuna-research-mcp
```

Choose the skills and agent you use. To install only the code-to-paper workflow:

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

Skills install to the current project by default. They don't install or configure
the MCP server. Start a new agent session after installation if your client needs
one to discover new skills.

## First use

Ask one of the questions above in your connected agent, or try a reading-list question:

> My list has FlashAttention and FlashAttention-2. What baselines or limitations
> should I read about for long-context attention?

For a reproducible example with no model API key, clone this repository and run:

```bash
uv run examples/code_to_paper.py
```

The [notebook](https://github.com/tiptreesystems/lacuna-research-mcp/blob/main/examples/code_to_paper.ipynb) explains each step and compares the
source trail with a single paper search. For direct tool use, the same flow is:

1. `search_lacuna(query="FlashAttention", search_type="resource", resource_kind="codebase", limit=5)`
2. Check the repository identity, then pass its returned ID to `get_resource(resource_id_or_url=...)`.
3. Follow a returned `publications[].paper_id` with `get_paper(artifact_id_or_url=..., view="context", figure_limit=0)`.

For literature search, use `search_lacuna(query="methods for detecting prompt injection attacks", search_type="paper", limit=5)`.
For generated proposals, use `search_lacuna(query="LLM jailbreak defense", search_type="hypothesis", limit=5)`
and follow a returned ID with `get_hypothesis`. Generated proposals are ideas to
investigate, not evidence of published findings.

## About Lacuna

Lacuna's pipeline reconciles scholarly records from OpenAlex, OpenReview, DBLP, and arXiv; extracts concept elements from paper text and clusters them into research directions ([Lacuna paper](https://arxiv.org/abs/2606.26246)); and samples novel research proposals from those directions with [The Alien Space of Science](https://arxiv.org/abs/2603.01092). The map spans more than **2.29 million papers**, **215,000+ author profiles**, **28,000+ research directions**, **25,000+ research proposals**, and **5,300+ venues** — and it grows continuously as new arXiv and other AI papers are ingested.

## Scope

The corpus covers machine learning and AI research: papers, research directions, authors' research output, venues, institutions, generated research hypotheses, and research resources (GitHub repositories, Hugging Face datasets and models, Zenodo records) linked to papers. It does not contain biographies, news, or non-research web content. Agents should answer questions outside that scope from other sources.

## What it exposes

- `search_lacuna`
  Uses Lacuna's public `/api/v1/search` endpoint for directions, papers, authors, venues, institutions, hypotheses, and resources. Explicit paper searches (`search_type="paper"`) use the server's production lexical+semantic ranker when the other ranking arguments remain at their defaults. Pass `search_type="hypothesis"` for hypothesis search. Pass `search_type="resource"` for code repositories, datasets, models, and demos linked to papers, optionally filtered with `resource_kind` (`codebase`, `dataset`, `model`, `demo`) and `provider` (`github`, `huggingface`, `zenodo`); for example, `resource_kind="dataset"` finds benchmark datasets. Resource search rejects `date_from`/`date_to`, `venue`, year sorts, and semantic ranking (resources carry no dates, venues, or embeddings).
- `get_hypothesis(hypothesis_id_or_url, view="context")`
  Hypothesis/proposal. `view="context"` (default) is a compact single-fetch proposal context (summary, abstract, linked directions); `view="full"` returns the server's version record with version history and signal counts. Proposal bodies are in `versions[].markdown`.
- `get_direction(cluster_id_or_url, view="context")`
  Research direction/cluster. `view="context"` (default) requests the compact agent-oriented summary; `view="full"` returns the raw cluster record.
- `get_direction_papers(cluster_id_or_url, page, limit, view="compact")`
  Paginated papers attached to a direction. `view="compact"` (default) returns citation-ready rows (id, url, title, year, venue, a few authors, abstract snippet); `view="full"` returns the raw upstream paper records.
- `get_paper(artifact_id_or_url, view="context", figure_limit=None, include_resources=True, offset=0, max_chars=None)`
  Paper lookup with available versions; use a version’s artifact ID to read it. Linked resources (code repositories, datasets, models, and demos) are included by default in context and full views; pass `include_resources=False` to omit them. Other views ignore this option. `view="context"` (default) requests the compact agent-oriented context; other views are `"full"`, `"preview"`, `"blog"`, `"figures"`, `"concepts"`, `"neighbors"`, or `"fulltext"` (arXiv LaTeX source where Lacuna has it, otherwise text extracted from the PDF; paged with `max_chars` and `offset`). In context view, `figure_limit` caps the figure preview (server default 3; pass 0 to suppress previews while keeping a `figures_truncated` signal).
- `get_resource(resource_id_or_url)`
  Resource lookup by id (from resource search or `get_paper`'s `resources` list) or Lacuna `/resource/...` URL: external URL, summary, facets (tasks, modalities, size, license), provider metrics, README/card excerpt, linked papers under `publications` (with `paper_id` and relationship such as `dataset_for`), related directions, and mentioned resources.
- Author tools:
  `get_author_context(…, view="context")`, `get_author_papers`, `get_author_directions`, and `get_author_neighbors`. Start with `get_author_context`, which defaults to the compact agent-oriented view (capped papers plus a readable `impact_directions` list instead of raw `impact_clusters` telemetry). Use the dedicated papers, directions, and neighbors tools to page through those collections without repeating the author context. `view="full"` returns the server-bounded full-shape context (collections remain capped at 100). Pass `include_neighbors=true` to explicitly include similar authors; this may add significant server latency.
- Venue and institution tools:
  `get_venue_context(…, view="context")`, `get_institution_context(…, view="context")`, `get_institution_authors`. Context tools default to compact (capped lists, duplicated blocks dropped; venue keeps a recent-activity slice that always includes the requested `year`). Use `get_institution_authors` to page through an institution's complete author list.

## Wrapped APIs

| MCP tool | Lacuna API endpoint |
| --- | --- |
| `search_lacuna(query, search_type, limit, offset, author_id_or_url, date_from, date_to, venue, sort, ranking_profile, fields, resource_kind, provider)` | `GET /api/v1/search` (`resource_kind` and `provider` are sent as repeated `kind` and `provider` query params and require `search_type="resource"` or `"all"`. `author_id_or_url` constrains `search_type="paper"` to one author, accepting a raw author ID or Lacuna author page URL. `fields` restricts/weights the text fields used for lexical ranking, e.g. `title^4,abstract`, and selects the experimental lexical ranker; for a default relevance-sorted paper search, this bypasses the production lexical+semantic ranker. Allowed fields are `title`, `abstract`, `summary`, `concepts`, `name`, `top_names`, `venue`, `description`, `topics`, `provider_key`, `paper_titles`, each valid only for the types that carry it — `title`: paper/cluster/venue/hypothesis/resource; `description`/`topics`/`provider_key`/`paper_titles`: resource; `abstract`/`summary`/`concepts`: paper; `name`: author/institution/venue; `top_names`: cluster/hypothesis; `venue`: paper/venue (`search_type="all"` spans all). Weights must satisfy `0 < weight <= 100`. Unknown fields, out-of-range weights, type-incompatible fields, and `fields` combined with `ranking_profile="semantic"` are rejected, since the server would otherwise silently drop, cap, or ignore them.) |
| `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` (default) or `?view=complete` |
| `get_paper(artifact_id_or_url, view="context", figure_limit=None, include_resources=True, offset=0, max_chars=None)` | `view="context"` → `GET /api/v1/context/paper/{artifact_id}?view=compact` (`&figure_limit=N` when set); `view="full"` → `GET /api/v1/papers/{artifact_id}`; `view="preview"` → `…/preview`; `view="blog"` → `…/blog`; `view="figures"` → `…/figures`; `view="concepts"` → `…/concepts`; `view="neighbors"` → `…/neighbors`; `view="fulltext"` → `…/fulltext?offset=&max_chars=`; context and full send `include_resources`. A Work page URL (`/work/<name>`, `/work/<slug>/wrk_…`) or bare `wrk_…` id is read through `GET /api/v1/context/work/{work_id_or_name}` first |
| `get_resource(resource_id_or_url)` | `GET /api/v1/resources/{resource_id}` |
| `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` explicitly requests similar authors) |
| `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"` → same route without `view` |
| `get_institution_context(institution_key_or_url, view="context")` | `view="context"` → `GET /api/v1/context/institution/{ikey}?view=compact`; `view="full"` → same route without `view` |
| `get_institution_authors(institution_key_or_url, limit=50, offset=0)` | `GET /api/v1/institutions/{ikey}/authors` |

For id-or-URL arguments, pass either the raw id returned by `search_lacuna` or the corresponding Lacuna page URL. The MCP normalizes Lacuna-relative `url` and `*_url` fields to absolute URLs, and it also absolutifies Lacuna links (including `/resource/...` pages) inside fields named `summary_markdown`, `article_markdown`, `markdown`, `content`, or `description`.

`get_author_context` is bounded server-side in both views. The default compact view returns a curated briefing; `view="full"` returns the larger complete shape with embedded collections capped at 100. Use `get_author_papers` and `get_author_directions` rather than trying to page embedded context collections.

Search requests are capped at 50 results per call, and direction-paper page
requests are capped at 100 results per call.
In `search_lacuna`, `date_from` and `date_to` are inclusive publication-date
bounds. Accepted formats are `YYYY`, `YYYY-MM`, and `YYYY-MM-DD`; for example,
`date_from="2020", date_to="2022-03"` includes papers from January 1, 2020
through March 31, 2022.

`search_lacuna` exposes these ranking profiles:

- `default` / `lexical`
  The default profile for all searches. With `search_type="paper"`, `sort="relevance"`, and `fields` unset, it uses the server's production lexical+semantic ranker with graceful fallback. The MCP's default `search_type="all"` uses the server's default lexical ranking instead.
- `semantic`
  Use for embedding-based paper retrieval. The semantic query omits the normal lexical ranking leg, but the server can still overlay exact-title lexical matches. Only supported for `paper` and `all` searches (only papers have semantic embeddings), and not with `resource_kind`/`provider` filters.
- `bm25_title_abstract` / `bm25`
  Use for lexical matching constrained to title and abstract. Rejected for `author` and `institution` searches (those records have no title or abstract fields).

All searches use the server default unless `ranking_profile` is provided. The MCP rejects unsupported profile/type combinations because the server would otherwise fall back to substring search and silently ignore the requested ranking profile.

`sort` accepts `relevance` (default), `year_desc`, and `year_asc`. Year sorts cannot be combined with `ranking_profile="semantic"` — the server would silently ignore the sort — so the MCP rejects that combination; for recent-and-relevant queries, keep semantic ranking and constrain recency with `date_from`/`date_to` instead.

## Environment variables

- `LACUNA_SITE_URL`
  Defaults to `https://lacuna.tiptreesystems.com`
- `LACUNA_MCP_TIMEOUT`
  Defaults to `30`
- `LACUNA_MCP_MAX_RETRIES`
  Defaults to `2`; applies to timeouts, transport errors, and HTTP `429`, `502`, `503`, and `504` responses.
- `LACUNA_MCP_USER_AGENT`
  Defaults to `lacuna-research-mcp/{package_version}`
- `LACUNA_MCP_BEARER_TOKEN`
  Optional bearer token sent as `Authorization: Bearer ...` for private Lacuna deployments.
- `LACUNA_MCP_CLIENT_TOKEN`
  Optional token sent as `X-Lacuna-Client-Token` to identify a hosted MCP server to Lacuna for its own search rate limit.
- `LACUNA_MCP_LOG_LEVEL`
  Defaults to `WARNING` (one of `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`). The default keeps normal operation quiet; lower it only for debugging, since `INFO`/`DEBUG` let the HTTP client log full request URLs — including the search query string — to stderr, which some MCP hosts retain.

Environment variables are read once when the MCP server is created, or on the first direct tool/API call if the module is imported without calling `create_mcp()`.

## Implementation layout

The server is a thin MCP adapter over Lacuna's HTTP API. The implementation is split by responsibility:

- `lacuna_research_mcp/server.py`
  MCPServer app creation, tool registration, lifespan cleanup, and the `lacuna-research-mcp` CLI entrypoint.
- `lacuna_research_mcp/tools.py`
  MCP tool functions. Each tool normalizes its inputs, calls the matching Lacuna API endpoint through the shared client helpers, and returns JSON-compatible data.
- `lacuna_research_mcp/client.py`
  Runtime HTTP access to Lacuna: the event-loop-bound `httpx.AsyncClient`, retry handling, error wrapping, JSON parsing, URL normalization on responses, and `api_get`/`api_object`/`api_payload`.
- `lacuna_research_mcp/config.py`
  Runtime constants, `RuntimeConfig`, package user-agent construction, and environment parsing.
- `lacuna_research_mcp/ids.py`
  Helpers that accept either raw ids or Lacuna page URLs and extract safe API path segments.
- `lacuna_research_mcp/normalize.py`
  Response post-processing for relative Lacuna URLs and markdown links.
- `lacuna_research_mcp/errors.py`
  User-facing exception type for Lacuna API access failures.

## Notes

- `get_paper` and `get_direction` default to `view="context"`. These context views request Lacuna's compact agent-oriented payloads by default to keep MCP responses small. Paper context includes `summary_markdown` when available (otherwise `abstract`), authors, and figures; direction context includes `summary_markdown`, capped papers/authors/related directions, and truncation markers. Use `view="full"` when you need the raw metadata, and the other paper views (`preview`, `blog`, `figures`, `concepts`, `neighbors`) when you want one isolated sub-resource.
- An explicit relevance-sorted paper search with no custom `fields` defaults to the server's production lexical+semantic ranker. Set `ranking_profile="semantic"` for embedding-based retrieval (with a possible exact-title overlay) or `"bm25_title_abstract"` for title-and-abstract lexical matching.
- Most detail tools accept either the id returned by search or the corresponding Lacuna URL.
- Relative Lacuna URLs in `url`/`*_url` response fields and fields named `summary_markdown`, `article_markdown`, `markdown`, `content`, or `description` are normalized to absolute URLs.
- Venue and institution keys are opaque hashes (for example `d7bf22905bd6`), never human-readable names like `icml`. Find the key with `search_lacuna(search_type="venue")` first, or pass a `/venue/...` page URL.

## Citation

If you find our work helpful, feel free to cite the papers behind Lacuna's research-proposal generation and research map.

**Research-proposal generation — The Alien Space of Science**

```bibtex
@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}
}
```

**Research map — 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}
}
```

## License

MIT. See [LICENSE](https://github.com/tiptreesystems/lacuna-research-mcp/blob/main/LICENSE).

TDQS

A4.1/5.0

Scored across 13 tools

Disambiguation4/5

Each tool maps to a distinct entity+action (paper, direction, author, venue, institution, resource, hypothesis), and the four author tools are separated by explicit use cases (papers, directions, profile, neighbors). There is mild overlap where get_author_context bundles main papers and directions that get_author_papers/get_author_directions return in full, and where get_institution_context's capped author list overlaps get_institution_authors, but the descriptions make the compact-vs-paginated distinction clear.

Naming Consistency4/5

Names follow a predictable get_<entity>[_<subresource>] pattern throughout (get_paper, get_direction_papers, get_author_neighbors, get_institution_authors). The only deviation is search_lacuna, which breaks the get_ verb style, though as the single entry-point search tool it is still easy to place.

Tool Count5/5

Thirteen tools is well within the ideal band and each one earns its place by covering a distinct entity type in a multi-entity research corpus. The search mega-tool absorbs query-side variation instead of spawning a dozen narrow search endpoints.

Completeness4/5

Coverage is broad and mostly symmetric: paper, direction, author, venue, institution, resource, and hypothesis all have retrieval paths, and pagination exists for direction papers and institution authors. Minor gaps remain, notably no paginated venue-paper listing (parallel to get_direction_papers) and no explicit citation/reference traversal beyond the 'neighbors' related-papers view.

Maintenance

ActivityActive
ResponsivenessLimited data