Research Notebook MCP

An MCP server that turns any BOSS agent into a research assistant. It gives your agent (Claude Code, Codex, Gemini, OpenCode - anything BOSS drives) a set of tools to capture cited sources, keep linked notes, and export a bibliography or a literature-review outline - all stored as plain files inside the project you are working in.

Point it at a project, browse and read as usual, and ask your agent to "cite this page", "note down why this matters", or "draft an outline of what I have so far". The notebook is a single human-readable notebook.json plus the Markdown and BibTeX files it generates, so nothing is locked away.

Why this helps researchers

The expensive part of a literature review is not reading, it is keeping track: where a fact came from, which paper made which claim, and how a pile of notes turns into a structured draft. A general chat agent forgets all of this between turns. This server gives the agent a durable, structured memory built around the two things a researcher actually accumulates:

• Sources you cite, with real bibliographic metadata (title, authors, date, journal or site, DOI) extracted automatically from the page.

• Notes you write, each linked to the sources behind it.

From those it can produce a BibTeX file for LaTeX/Overleaf, an annotated bibliography, or a literature-review outline that groups your notes by theme and threads in the right citations.

Related MCP server: Tacitus MCP Server

The tools

Quick start

git clone https://github.com/Rushikeshiitb/boss-research-notebook-mcp.git
cd boss-research-notebook-mcp
npm install
npm run build

Run it directly (it speaks MCP over stdio):

RESEARCH_NOTEBOOK_DIR="$PWD/.research-notebook" node dist/index.js

Or install it on your PATH as research-notebook-mcp (the package declares a bin):

npm install -g .          # from the cloned repo
# now `research-notebook-mcp` launches the server over stdio

Cite keys

Sources get a human-friendly citation key in the usual author-year-word style, for example vaswani2017attention. Collisions are disambiguated with a trailing letter (smith2020a, smith2020b). You can refer to any source by either its cite key or its internal id in every tool that takes a source.

Connecting it to BOSS

BOSS drives coding CLIs (Claude Code, Codex, Gemini, OpenCode), and each of them loads MCP servers from its own configuration - so you register this server with the CLI you use inside BOSS. It is a stdio server: the client launches it and talks over stdin/stdout.

Project-scoped config file (portable across clients). Drop a .mcp.json in the root of the project you open in BOSS:

{
  "mcpServers": {
    "research-notebook": {
      "command": "node",
      "args": ["/absolute/path/to/boss-research-notebook-mcp/dist/index.js"],
      "env": {
        "RESEARCH_NOTEBOOK_DIR": "/absolute/path/to/your/project/.research-notebook",
        "RESEARCH_NOTEBOOK_TITLE": "My Literature Review"
      }
    }
  }
}

Claude Code, one command (run it in your project directory):

claude mcp add research-notebook \
  -e RESEARCH_NOTEBOOK_DIR="$PWD/.research-notebook" \
  -- node /absolute/path/to/boss-research-notebook-mcp/dist/index.js

If you installed it globally (npm install -g .), the command is simply research-notebook-mcp in place of node .../dist/index.js.

Once connected, the 17 tools above appear to your agent alongside the rest of the tools it can call.

Configuration

What gets written

Everything lives in the notebook directory:

• notebook.json - the canonical store (sources and notes). Written atomically (unique temp file + rename) under an advisory lock.

• references.bib - BibTeX, when you ask export_bibtex to write.

• references.md - Markdown bibliography, when you ask export_markdown to write.

• outline.md - the literature-review scaffold, when you ask generate_outline to write.

Because it is all plain text in your project, it version-controls cleanly and you can read or edit it without the server. Every source and note needs a non-empty id; the server normalises array fields on load (missing ones become empty, tags are lowercased and de-duplicated, unknown keys are kept) and refuses to start if an entry cannot be read at all.

Editing it while the server runs: the server loads notebook.json once and writes the whole document back on each change. If the file changes on disk underneath it - you hand-edited it, or a second server shares the directory - the next write is refused rather than silently overwriting your edit: the server reloads the on-disk version and returns a conflict error asking you to re-apply your change. A refused or failed write never corrupts the file or the in-memory copy. Writes are serialized by a lock file, so two servers on one directory take turns instead of clobbering each other.

Example workflow

1. cite_url on a paper you are reading, with a quote and tags: ["method"].

2. add_note capturing your take, linked to that source.

3. Repeat while you read.

4. generate_outline to get a themed draft with citations threaded in.

5. export_bibtex to drop references.bib into your LaTeX project.

Privacy and safety

• The only outbound request the server makes is cite_url fetching a page. Because the agent, not you, picks that URL, the fetch is hardened against being pointed at your own network (SSRF):

  • only http/https;

  • the hostname is resolved and every address it returns is checked - the request is refused if any is loopback, private, link-local (cloud metadata at 169.254.169.254), CGNAT or IPv6 loopback/ULA/link-local/mapped-private;

  • the connection is pinned to the validated address, so a name cannot be re-resolved to a private address after the check (DNS-rebinding);

  • redirects are followed manually and each hop is re-validated, so a public page cannot bounce the fetch to an internal one;

  • the response body is capped (5 MiB) and the fetch gives up after 30 s. Nothing else leaves your machine.

• All data is stored locally in the notebook directory. There is no external service and no telemetry.

• A failed or blocked fetch is reported cleanly; you can always fall back to add_source to record a citation by hand.

Development

npm run typecheck   # tsc --noEmit
npm test            # vitest: unit + in-memory MCP integration tests
npm run build       # emit dist/

The test suite covers metadata extraction (OpenGraph, Google Scholar / highwire citation_* tags, JSON-LD, and degenerate pages), cite-key generation and collisions, the notebook store and its persistence, BibTeX and Markdown rendering, and a full end-to-end pass driving the real MCP server over an in-memory transport with a stubbed fetch.

Layout

src/
  types.ts      data model (sources, notes, notebook)
  metadata.ts   pure HTML -> bibliographic metadata extraction
  citekey.ts    author-year-word cite keys, with de-duplication
  notebook.ts   the store: CRUD, search, atomic persistence
  bibtex.ts     BibTeX export
  markdown.ts   bibliography + literature-review outline
  server.ts     MCP tool registration (fetch and store injected)
  index.ts      stdio entry point

License

Apache-2.0, matching the BOSS Console core.