```
        ______________________________________________________
       |                                                      |
       |                   research _ mcp                      |
       |                                                      |
       |          a research institute, in a server           |
       |______________________________________________________|
          ||     ||     ||     ||     ||     ||     ||     ||
          ||     ||     ||     ||     ||     ||     ||     ||
          ||     ||     ||     ||     ||     ||     ||     ||
        __||_____||_____||_____||_____||_____||_____||_____||__
       |______________________________________________________|
```

> An MCP server that mirrors the skills and workflows of an industry-leading research institute — academic rigour and private-sector pragmatism — exposed to any MCP-capable client (Claude Desktop, Claude Code, Antigravity, and others).

`research_mcp` encodes the **craft of research** as a set of reasoning tools, a curated knowledge base, and end-to-end workflows. It is grounded in a defensible canon of methodological authority (see [`SOURCE_AUTHORITY.md`](./SOURCE_AUTHORITY.md)) so that its guidance is principled and consistent, not improvised.

It runs **locally over stdio**, so it composes with tools already on your machine — `curl`/`wget` for retrieval and your installed Chrome (via Playwright) for JavaScript-heavy pages — and with free, keyless scholarly APIs (OpenAlex, Crossref, arXiv, OSF) plus Unpaywall for open-access full text. HTML and PDF are converted to text **in-process** (no `pandoc`/`pdftotext` required).

```
   ~ . ~ . ~ . ~ . ~ . ~ . ~ . ~ . ~ . ~ . ~ . ~ . ~ . ~ . ~
```

## The research lifecycle

A great research institute does a handful of things exceptionally well, in sequence. `research_mcp` provides a tool, a workflow, or both for each stage:

```
   scope ──▶ design ──▶ instrument ──▶ find & appraise ──▶ synthesise
                                                               │
   translate ◀── govern ◀── review ◀── analyse ◀──────────────┘
```

The methodology core is **domain-agnostic** — it works for any field — with an optional **HR / people-analytics lens** that adds presets, workforce-survey templates, and a "translate findings into an HRLT or board brief" capability.

## Features

Everything the server exposes, at a glance:

```
research_mcp
│
├── tools (27)
│   │
│   ├── research craft (11)
│   │     scope-question        sharpen a fuzzy idea into researchable questions
│   │     design-study          choose a fit-for-purpose design + validity threats
│   │     develop-instrument    build surveys/protocols with a reliability plan
│   │     plan-analysis         pick the analysis; guard against p-hacking/HARKing
│   │     appraise-evidence     risk-of-bias + GRADE appraisal of a study
│   │     appraise-source       credibility/provenance of a non-study source (CRAAP/SIFT)
│   │     synthesise-evidence   evidence table, heterogeneity, certainty of a body
│   │     check-reporting       validate against PRISMA/CONSORT/STROBE/COREQ/TRIPOD/AGREE
│   │     peer-review           a rigorous, constructive reviewer report
│   │     assess-ethics         Belmont/Helsinki/integrity/open-science/responsible-AI
│   │     translate-to-practice turn findings into a decision-maker brief (BLUF)
│   │
│   ├── retrieval & discovery (8)
│   │     fetch-url             retrieve web content server-side (curl→wget→Chrome)
│   │     web-search            open-web discovery (Brave / SearXNG / DuckDuckGo)
│   │     search-literature     scholarly search (OpenAlex, Crossref, arXiv, OSF)
│   │     fetch-paper           paper → metadata + open-access full text (Unpaywall)
│   │     extract-from-pdf      in-process PDF text extraction
│   │     citation-graph        forward/backward citation neighbourhood of a paper
│   │     author-profile        researcher metrics and key works
│   │     export-bibliography   BibTeX / RIS / CSL-JSON via DOI content negotiation
│   │
│   ├── local integrations (5)
│   │     zotero-search         search your local Zotero library
│   │     zotero-save           save a paper to Zotero
│   │     vault-search          search your Obsidian vault
│   │     vault-read            read a vault note
│   │     vault-write-note      write a note into your vault
│   │
│   └── HR / people-analytics lens (3)
│         people-analytics-preset    frame an HR study (engagement, attrition, DEI…)
│         workforce-survey-template  assemble a validated-style workforce survey
│         governance-check           review an AI/data use against risk tiers + checklist
│
├── workflow prompts (4)
│     study-design-sprint   idea → question → design → instrument → analysis → ethics
│     systematic-review     protocol → search → screen → appraise → synthesise → PRISMA
│     evidence-brief        rapid evidence assessment → audience-tuned decision brief
│     peer-review-pass      full manuscript review with deep dives
│
└── knowledge resources (11)
      research://research-design       design canon + the four validities
      research://appraisal             risk-of-bias frameworks + GRADE
      research://reporting-standards   PRISMA/CONSORT/STROBE/COREQ/TRIPOD/AGREE
      research://measurement           scale development, reliability/validity, surveys
      research://analysis              test selection, ASA p-value principles, qual coding
      research://synthesis             review types, synthesis methods, the SR pipeline
      research://ethics                Belmont, Helsinki, integrity, open science, AI use
      research://source-hierarchy      the 7-tier source-quality cadence
      research://practice-translation  evidence-based-management translation (HR lens)
      research://hr-lens               people-analytics presets and survey blocks
      research://governance            AI/data governance risk tiers + checklist
```

The data tools (`search-literature`, `web-search`, `author-profile`, `citation-graph`) also return machine-readable `structuredContent` alongside their text.

## Architecture

```
research_mcp (stdio MCP server, TypeScript)
├── tools/        reasoning skills (scope, design, appraise, synthesise, review, translate…)
├── resources/    the knowledge base (methodology canon, reporting standards, ethics)
├── prompts/      end-to-end workflows (systematic review, study-design sprint, evidence brief…)
└── lib/          codified canon, scholarly connectors, the retrieval ladder, in-process extraction
```

- **Local-first by design.** Running on your machine, retrieval carries *your* IP/VPN and a real browser User-Agent, so it reaches what you can reach; Zotero, your Obsidian vault, and system Chrome are all on `localhost`.
- **Retrieval ladder.** An allow-listed `curl` → `wget` → headless-Chrome (Playwright) escalation; HTML/PDF are converted to text in-process (jsdom + Readability + Turndown; pdfjs).
- **Knowledge-grounded.** Tools compose a codified canon (`lib/data/`) into structured guidance rather than improvising; conflicts resolve via `SOURCE_AUTHORITY.md`.

## Source-quality cadence

Discovery spans peer-reviewed literature *and* the open web, governed by a 7-tier [source-quality cadence](src/lib/data/source-hierarchy.ts): syntheses → peer-reviewed → preprints → official/primary documents → expert secondary → interested primary → general web. Results are ranked so cited, peer-reviewed work outranks zero-citation preprints, but the cadence descends legitimately for novel or fast-moving topics (e.g. an emerging AI legal matter) where primary documents and expert analysis outweigh thin academic evidence. `appraise-source` weighs any non-study source by provenance and interest.

## Quick start

```bash
git clone https://github.com/simonives/research_mcp.git
cd research_mcp
npm install
npm run build
npm start          # runs the server over stdio
```

Register with Claude Code (run from the repo root, or use an absolute path):

```bash
claude mcp add research -s user -- node "$(pwd)/dist/index.js"
```

Or add to a Claude Desktop / Antigravity MCP config block pointing at `dist/index.js`. Reconnect/restart the client after registering or rebuilding so it picks up the latest tools.

## Configuration

Configuration is supplied via environment variables, or a **gitignored `.env`** in the project root — copy [`.env.example`](./.env.example) and fill it in. The server loads `.env` on startup (resolved relative to the project, so it works from any directory); anything already set in the environment or MCP-client config takes precedence. All variables are optional — the offline core needs none.

| Variable | Enables |
|----------|---------|
| `RESEARCH_MCP_OBSIDIAN_VAULT` | Path to an Obsidian vault → activates the `vault-*` tools |
| `RESEARCH_MCP_ZOTERO_URL` | Override the Zotero local API base (default `http://localhost:23119/api`) |
| `RESEARCH_MCP_CONTACT` | Email for scholarly-API "polite pools" and to enable the Unpaywall OA resolver |
| `RESEARCH_MCP_USER_AGENT` | Override the browser User-Agent used by `fetch-url` |
| `RESEARCH_MCP_CACHE_DIR` | Where retrieved files and API responses are cached |
| `RESEARCH_MCP_BRAVE_KEY` | Brave Search API key → reliable backend for `web-search` (free tier) |
| `RESEARCH_MCP_SEARXNG_URL` | A SearXNG instance URL → self-hosted backend for `web-search` |
| `RESEARCH_MCP_SEARCH_BACKEND` | Force `web-search` backend: `duckduckgo` (default, keyless best-effort), `brave`, or `searxng` |

> **Note on `web-search`:** keyless scraping (DuckDuckGo) is frequently bot-blocked from a server IP. For reliable server-side web search, set `RESEARCH_MCP_BRAVE_KEY` or `RESEARCH_MCP_SEARXNG_URL`; otherwise use the assistant's own web search for discovery and `fetch-url` to retrieve. Shadow libraries (e.g. LibGen) are deliberately **not** integrated; for paywalled works use Unpaywall OA, a `cookie_file` for entitled access, or interlibrary loan.

Zotero tools also require the Zotero 7+ desktop app running with its local API enabled.

## Development

```bash
npm run build        # compile TypeScript → dist/
npm run dev          # run from source with tsx
npm run typecheck    # type-check without emitting
npm test             # regression harness over stdio (offline, CI-safe)
npm run test:online  # + live connector checks (network)
```

The test harness (`scripts/smoke-test.mjs`) drives the built server over the MCP protocol and asserts the contract of every tool, prompt, and resource — run it after any change. Contribution guidelines are in [`CONTRIBUTING.md`](./CONTRIBUTING.md).

## Knowledge integrity

This server makes claims about research methodology. When sources conflict, it resolves them using an explicit authority hierarchy documented in [`SOURCE_AUTHORITY.md`](./SOURCE_AUTHORITY.md). Contributions that enrich the knowledge base **must** follow that hierarchy.

## Built with Claude Code

`research_mcp` was designed and built with [Claude Code](https://claude.com/claude-code) (Anthropic) — from the initial scaffolding through implementation, live testing, and configuration — pair-built with its author. The methodology it encodes remains grounded in the human authorities catalogued in [`SOURCE_AUTHORITY.md`](./SOURCE_AUTHORITY.md).

## License

[MIT](./LICENSE) © 2026 Simon Ives