# Research Scope [Health: Active]

**Category:** 🔬 Research  
**Repository:** https://github.com/AxelVerneBooks/research-scope-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 295  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/research-scope

## Description
Plan research, score sources for freshness/COI, and enforce claim-level citations in reports.

## Tools
Capabilities this server exposes over MCP:

- **plan_research** — source-target plan with kill criteria
- **fetch_and_score** — 0–100 score + flags (primary, freshness, paywall, COI), registered for reporting
- **build_report** — report shell saved under `data/reports/`, `[Sn]` citation numbering
- **check_report** — pass/fail + orphan-claim error list

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "research-scope": {
    "command": "npx",
    "args": ["-y","research-scope-mcp"]
  }
}
```

## Documentation & README

# 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

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

Run over stdio (most clients):

```bash
npx research-scope-mcp
```

Or over Streamable HTTP (remote deployments):

```bash
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](https://github.com/AxelVerneBooks/research-scope-mcp/blob/HEAD/clients/claude-code.json),
[Cursor](https://github.com/AxelVerneBooks/research-scope-mcp/blob/HEAD/clients/cursor.json), and a Cline-friendly
[`llms-install.md`](https://github.com/AxelVerneBooks/research-scope-mcp/blob/HEAD/clients/llms-install.md).

## Docker

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

## Tools

| Tool | Input | Output |
|---|---|---|
| `plan_research` | `scope`, optional `domain_hints` | source-target plan with kill criteria |
| `fetch_and_score` | `source_url` | 0–100 score + flags (primary, freshness, paywall, COI), registered for reporting |
| `build_report` | `topic`, `sources[]` (must already be scored) | report shell saved under `data/reports/`, `[Sn]` citation numbering |
| `check_report` | `report_id` or `report_path` | pass/fail + orphan-claim error list |

## Example walkthrough

See [docs/runs/](https://github.com/AxelVerneBooks/research-scope-mcp/blob/HEAD/docs/runs/) for two worked runs with inputs and outputs, and
[docs/notes/](https://github.com/AxelVerneBooks/research-scope-mcp/blob/HEAD/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](https://github.com/AxelVerneBooks/research-scope-mcp/blob/HEAD/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

| Dimension | Max | Notes |
|---|---|---|
| Availability & substance | 20 | extractable text length |
| Primary-source status | 32 | host class (gov/edu/filings) or self-published primary (press/announcement paths) |
| Freshness | 24 | ≤30d full marks, decays to 2 at >5y, 0 if undetectable |
| Access | 12 | paywall/registration walls lose marks |
| Independence | 12 | sponsored/affiliate/partnership markers |

`score ≥ 80` → A, `≥ 65` → B, `≥ 45` → C, else D. The rubric is inside
[src/scoring/score.ts](https://github.com/AxelVerneBooks/research-scope-mcp/blob/HEAD/src/scoring/score.ts) and returns its evidence, so a score is
auditable, not a vibe.

## License

MIT. See [SECURITY.md](https://github.com/AxelVerneBooks/research-scope-mcp/blob/HEAD/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](https://github.com/AxelVerneBooks/research-scope-mcp/blob/HEAD/CHANGELOG.md) updates.