research_mcp

        ______________________________________________________
       |                                                      |
       |                   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) 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: 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

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):

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

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.

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. Contributions that enrich the knowledge base must follow that hierarchy.

Built with Claude Code

research_mcp was designed and built with 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.

License

MIT © 2026 Simon Ives