Paper Chaser MCP

Release status: The repository, CLI, Docker image metadata, and public MCP identity are now aligned on paper-chaser-mcp. GHCR images and GitHub Release assets are the primary public distribution channels; PyPI remains intentionally gated until account recovery and trusted-publisher setup are complete.

An MCP server for academic research — search papers, chase citations, look up authors, repair broken references, explore species dossiers, and retrieve regulatory text, all from one FastMCP server that AI assistants can call directly.

Providers: Semantic Scholar · arXiv · OpenAlex · CORE · SerpApi Google Scholar (opt-in, paid) · Crossref · Unpaywall · ECOS · FederalRegister.gov · GovInfo

Contents

• What can it do?
• Guided vs expert profiles
• Quick start
• Quick tool decision guide
• Core workflows
• Agent response contract
• Deferred export design
• Migration note
• Installation
• Configuration
• Tools
• Resources and prompts
• Microsoft packaging assets
• Testing with MCP Inspector
• Development
• Guides
• License
• Links

What can it do?

Paper Chaser MCP is now guided-first: the default public surface is designed to be hard to misuse and explicit about trust.

• Default research entrypoint: research handles discovery, known-item recovery, citation repair, and regulatory routing in one trust-graded path, with a server-owned quality-first policy for guided use.
• Grounded follow-up: follow_up_research answers against one saved searchSessionId; if you omit it, the server only infers a session when the choice is unique. Saved-session follow-up can classify mixed source sets into on-topic evidence, weaker context, and off-target leads when the stored metadata is already sufficient.
• Decision metadata: guided responses surface executionProvenance, and ambiguous follow-up or source-inspection flows return structured sessionResolution / sourceResolution payloads instead of opaque errors.
• Reference-first recovery: resolve_reference handles DOI/arXiv/URL, citation fragments, and regulatory-style references, and exact DOI/arXiv/ paper-URL inputs resolve as exact anchors rather than falling through to fuzzy repair. Ambiguous title-only or conflicting metadata matches can now return multiple_candidates or needs_disambiguation; treat those as candidate anchors, not citation-ready resolutions.
• Compact top-level answer: guided research leads with a short recommendation-first summary, while keeping the structured evidence, leads, and provenance fields available below it.
• Source auditability: inspect_source exposes one sourceId with provenance, trust state, weak-match rationale, and quality-aware direct-read next steps; omitted searchSessionId is only accepted when one compatible saved session exists.
• Runtime truth: get_runtime_status surfaces active profile/transport and provider-state warnings without requiring low-level diagnostics. configuredSmartProvider is the configured smart bundle; activeSmartProvider is the latest effective execution path, cold-start snapshots emit an explicit provisional warning instead of claiming deterministic fallback before the first smart call settles, and the top-level provider sets now split disabledProviderSet, suppressedProviderSet, degradedProviderSet, and quotaLimitedProviderSet instead of collapsing them.
• Expert depth remains available: raw/smart/provider-specific tools still exist for operator workflows under the expert profile.

Guided vs expert profiles

Use PAPER_CHASER_TOOL_PROFILE to choose the advertised surface:

Practical default: PAPER_CHASER_TOOL_PROFILE=guided with PAPER_CHASER_HIDE_DISABLED_TOOLS=true.

Quick start

If you want the fastest local path, install from source and add the server to your MCP client in stdio mode:

pip install -e .

{
  "mcpServers": {
    "paper-chaser": {
      "command": "python",
      "args": ["-m", "paper_chaser_mcp"],
      "env": {
        "PAPER_CHASER_TOOL_PROFILE": "guided",
        "PAPER_CHASER_HIDE_DISABLED_TOOLS": "true",
        "PAPER_CHASER_ENABLE_SEMANTIC_SCHOLAR": "true",
        "PAPER_CHASER_ENABLE_ARXIV": "true",
        "PAPER_CHASER_ENABLE_CORE": "false"
      }
    }
  }
}

Then start with one of these prompts in your MCP client:

• Research retrieval-augmented generation for coding agents and return only trustworthy findings.
• Use my last searchSessionId to answer one grounded follow-up question.
• Resolve this citation fragment: Vaswani et al. 2017 Attention Is All You Need.
• Research the regulatory history of California condor under 50 CFR 17.95.

If you want a local env template for shell runs or Docker Compose, copy .env.example to .env and fill in only the providers you use.

Quick tool decision guide

Core workflows

1. Guided research first

research(query="retrieval-augmented generation for coding agents", limit=5)
→ inspect resultStatus, answerability, summary, evidence, leads, routingSummary
→ if resultStatus=needs_disambiguation with clarification.reason=underspecified_reference_fragment:
  tighten the anchor or pivot to resolve_reference instead of forcing retrieval
→ if resultStatus=abstained and sources are suppressed: inspect suppressedSourceSummaries before rerunning or escalating
→ save searchSessionId for follow-up or source inspection

2. Ask one grounded follow-up

follow_up_research(searchSessionId="...", question="What evaluation tradeoffs show up here?")
→ inspect answerStatus
→ if answered: use answer + evidence (compact default: sources are identified by selectedEvidenceIds)
→ if abstained/insufficient_evidence: use nextActions, suppressedSourceSummaries, and inspect_source
→ mixed saved sessions can still answer relevance-triage questions such as which items are on-topic vs off-target
→ uniquely anchored recommendation asks can also return a safe start-here answer plus topRecommendation
→ if you omit searchSessionId and multiple saved sessions exist: provide it explicitly
→ for full source records pass responseMode="standard"; for diagnostics responseMode="debug"
→ for selection asks ("where should I start?", "most recent?"), read topRecommendation

3. Resolve references before broad search when possible

resolve_reference(reference="10.1038/nrn3241")
→ exact DOI/arXiv/paper URL should resolve directly when supported
resolve_reference(reference="Rockstrom et al planetary boundaries 2009 Nature 461 472")
→ inspect status and bestMatch/alternatives
→ only treat bestMatch as citation-ready when status=resolved
→ if status=multiple_candidates or needs_disambiguation: pick a candidate or add a stronger author/year/venue clue before citing it
→ if resolved: run research with the resolved anchor

4. Inspect one source before citing it

inspect_source(searchSessionId="...", evidenceId="...")
→ inspect verificationStatus, topicalRelevance, whyClassifiedAsWeakMatch, confidenceSignals, canonicalUrl, directReadRecommendations
→ if searchSessionId is omitted and inference is ambiguous, rerun with an explicit saved session id

5. Handle abstention and clarification explicitly

• If research.resultStatus is abstained or needs_disambiguation, do not invent synthesis. Narrow with a concrete anchor: DOI, exact title, species name, agency, year, or venue.
• When research returns needs_disambiguation with clarification.reason=underspecified_reference_fragment, the server is intentionally stopping before speculative retrieval on a vague citation/reference fragment. Tighten the clue set or switch to resolve_reference.
• If follow_up_research.answerStatus is abstained or insufficient_evidence, treat it as a safety signal. Use inspect_source and rerun research with tighter scope.

6. Expert fallback when you need fine control