# RBAi Corpus MCP Server

Search **7M biomedical papers by meaning** directly from your IDE. This MCP
server exposes one tool, `search_corpus`, which runs a semantic search over the
RBAi Corpus (Qwen3-Embedding-0.6B + HNSW cosine over 7 million paper
abstracts) and returns the most relevant papers with similarity scores,
metadata, and DOI links.

Your AI assistant decides when to call it — you just ask in plain language.

---

## Requirements

- **Node.js 18 or newer** (uses global `fetch`, ESM, and `AbortSignal.timeout`)
- **The `@modelcontextprotocol/sdk` package** on the module path. Two easy ways:
  1. **Run from the backend directory** — `apps/backend` already has the SDK in
     `node_modules`. Just copy `rbai-corpus-mcp.js` there and point your IDE
     config at it. No extra install needed.
  2. **Any other folder** — run `npm install @modelcontextprotocol/sdk`, then
     place `rbai-corpus-mcp.js` in that folder.
- **An RBAi Corpus API key** (`rbai_sk_...`). Without a key it still works, but
  you're limited to **5 searches per minute** (anonymous, IP-based). A key gives
  you a much higher daily quota.

### Get an API key

1. Visit **https://www.thedreamlabinnovations.com** (RBAi Corpus section).
2. Request a key — it's returned once as `rbai_sk_...`. Save it immediately; it
   can't be retrieved again.

---

## Setup

### 1. Save the server script

Download `rbai-corpus-mcp.js` to a permanent location, e.g.
`/Users/you/tools/rbai-corpus-mcp.js` (Mac/Linux) or
`C:\Users\you\tools\rbai-corpus-mcp.js` (Windows).

If you're not running it from `apps/backend`, install the SDK in the same
folder:

```bash
cd /folder/where/you/saved/it
npm install @modelcontextprotocol/sdk
```

### 2. Add it to your IDE

Pick your client below. In every case, replace `/path/to/rbai-corpus-mcp.js`
with the **absolute path** to the script, and `rbai_sk_your_key_here` with your
real API key.

#### Claude Desktop

Edit the config file:
- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "rbai-corpus": {
      "command": "node",
      "args": ["/path/to/rbai-corpus-mcp.js"],
      "env": {
        "CORPUS_API_URL": "https://dreamlab-main.vercel.app/api/v1/corpus",
        "CORPUS_API_KEY": "rbai_sk_your_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. The `search_corpus` tool will appear in the available
tools.

#### Cursor

Settings → MCP → **Add new MCP server**:

- **Name:** `rbai-corpus`
- **Type:** `stdio`
- **Command:** `node /path/to/rbai-corpus-mcp.js`
- **Env:**
  - `CORPUS_API_URL=https://dreamlab-main.vercel.app/api/v1/corpus`
  - `CORPUS_API_KEY=rbai_sk_your_key_here`

#### VS Code (with an MCP extension)

Add to `.vscode/mcp.json` in your workspace (or user settings):

```json
{
  "servers": {
    "rbai-corpus": {
      "command": "node",
      "args": ["/path/to/rbai-corpus-mcp.js"],
      "env": {
        "CORPUS_API_URL": "https://dreamlab-main.vercel.app/api/v1/corpus",
        "CORPUS_API_KEY": "rbai_sk_your_key_here"
      }
    }
  }
}
```

#### Any other MCP-compatible client

The server is a standard **stdio** MCP server. Point your client at:

- **Command:** `node`
- **Args:** `["/path/to/rbai-corpus-mcp.js"]`
- **Env:** `CORPUS_API_URL`, `CORPUS_API_KEY`

A ready-to-edit `rbai-corpus-mcp.json` is included next to this guide.

---

## Environment variables

| Variable         | Required | Default                                                          | Description                                    |
| ---------------- | -------- | ---------------------------------------------------------------- | ---------------------------------------------- |
| `CORPUS_API_URL` | no       | `https://dreamlab-main.vercel.app/api/v1/corpus`                 | Base URL of the corpus API (no trailing slash) |
| `CORPUS_API_KEY` | no\*     | _(empty — anonymous, 5 req/min)_                                 | Your `rbai_sk_...` API key for a higher quota  |

\* Strongly recommended. Without it you hit the anonymous rate limit fast.

---

## Usage

Once connected, just ask your AI in plain language. It will call
`search_corpus` automatically when a literature question comes up:

- "Search for papers on alpha-synuclein aggregation in Parkinson's"
- "Find recent papers (2023+) on CRISPR off-target effects"
- "What papers discuss tumor microenvironment immunotherapy with 50+ citations?"
- "Find open-access papers from 2020 onward on mitochondrial dynamics in sepsis"

### Tool parameters

| Parameter       | Type    | Required | Description                                        |
| --------------- | ------- | -------- | -------------------------------------------------- |
| `query`         | string  | yes      | The research question or topic (by meaning)        |
| `topK`          | number  | no       | Results to return (default 20, max 100)            |
| `yearFrom`      | number  | no       | Only papers from this year onwards                 |
| `yearTo`        | number  | no       | Only papers up to this year                        |
| `isOpenAccess`  | boolean | no       | Only open-access papers                            |
| `minCitations`  | number  | no       | Minimum citation count                             |

### Example output

```
Found 20 papers (searched 7,000,000 abstracts, took 5234ms):

[1] 81.8% — Detection of elevated levels of α-synuclein oligomers in CSF...
    Authors: Smith J, et al. (2023) · Journal: Nature Neuroscience
    DOI: 10.1038/xxx · 45 citations · Open Access

[2] 81.7% — Proposal and Point of View on Targeting α-synuclein...
    Authors: Lee K, et al. (2022) · Journal: Cell Reports Medicine
    DOI: 10.1016/yyy · 128 citations
```

---

## Troubleshooting

- **"Rate limit exceeded"** — you're anonymous (no `CORPUS_API_KEY`) and hit 5
  searches/min. Set your API key. If you already have a key, you've hit the
  daily quota; it resets every 24h.
- **"embedding service is offline"** — the backend's corpus embedding endpoint
  (DO Qwen / Azure) is temporarily down. Try again in a few minutes.
- **"Cannot find module '@modelcontextprotocol/sdk'"** — the SDK isn't on the
  module path. Run the script from `apps/backend`, or run
  `npm install @modelcontextprotocol/sdk` in the script's folder.
- **Tool doesn't appear in the IDE** — restart the IDE after editing the config,
  and double-check the `args` path is absolute and correct for your OS.

---

## How it works

This is a thin stdio client. It does **no** database access, no Prisma, no
Express, and no embedding itself. For each `search_corpus` call it:

1. POSTs `{ query, topK, ...filters }` to `${CORPUS_API_URL}/search` with
   `Authorization: Bearer ${CORPUS_API_KEY}`.
2. The backend embeds the query (DO Qwen3-Embedding-0.6B, 1024-dim) and runs an
   HNSW cosine search over the 7M-paper `CorpusPaperCache`.
3. This script formats the JSON response into the readable text above and hands
   it back to the IDE over stdio.

That's it — one file, one tool, one HTTP call.