Research Scope

research-scope-mcp

Turn a scattered source set into a decision-ready, traceable report.

research-scope-mcp is an MCP server that runs a research-to-report workflow any MCP client can drive end to end:

1. plan_research(scope) — turns a research scope into a source-target plan with kill criteria ("fewer than 1 primary + 2 independent secondaries → stop and report insufficient sources, don't proceed on thin evidence").
2. fetch_and_score(source_url) — crawls one source and returns an explainable 0–100 quality score: primary-source detection, publication freshness, paywall and conflict-of-interest flags — every dimension returned with the evidence.
3. build_report(topic, sources) — assembles a citation-registry report shell (claims section + numbered registry + scoring appendix) for the scored sources.
4. check_report(report) — verifies every substantive claim cites ≥1 scored source. Orphan claims come back as an error list, not a pass.

The problem it solves: agent-written reports that sound confident but can't show where any sentence came from. This server makes scoring and citation coverage mechanically enforced, so the report is auditable by a human in 90 seconds.

Install

npm install -g research-scope-mcp   # once published; local: npm ci && npm run build

Run over stdio (most clients):

npx research-scope-mcp

Or over Streamable HTTP (remote deployments):

npx research-scope-mcp --http --port 3001
# unauthenticated requests get 401 + WWW-Authenticate discovery, never a bare 403

Client config

Drop-in config snippets for Claude Code, Cursor, and a Cline-friendly llms-install.md.

Docker

docker build -t research-scope-mcp -f docker/Dockerfile .
docker run --rm -i -p 3001:3001 research-scope-mcp --http --port 3001

Tools

Example walkthrough

See docs/runs/ for two worked runs with inputs and outputs, and docs/notes/ for what to do when something times out or 401s.

Demo capture

npm run demo:capture (or node tools/demo-capture.mjs) replays the scripted 60-second demo flow against the shipped server — spawn dist/index.js over stdio with a fresh temp data dir, plan_research → fetch_and_score a .gov page (real fetch) → build_report, inject one cited claim plus one deliberately orphan claim, and confirm check_report refuses to bless it — writing each frame out as a {t, dir, msg} JSONL transcript. By default it targets docs/marketing/demo-60s/run-capture.jsonl (the transcript the product-page demo player's footer sha256 is anchored to); it refuses to overwrite that file without --force. Requires network access for the one real fetch; repo data/ is never touched.

Scoring rubric

score ≥ 80 → A, ≥ 65 → B, ≥ 45 → C, else D. The rubric is inside src/scoring/score.ts and returns its evidence, so a score is auditable, not a vibe.

License

MIT. See SECURITY.md for reporting security issues.

Paid kit

This server is the free, tested core of the Research-to-Report MCP Kit (field guide, worked example packs, setup support). Available at the kit store — link in CHANGELOG.md updates.