Paper Chaser MCP Server

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

PAPER_CHASER_TOOL_PROFILE=expert
→ search_papers_smart / ask_result_set / map_research_landscape / expand_research_graph
→ search_papers / search_papers_bulk and provider-specific families
→ search_federal_register / get_federal_register_document / get_cfr_text for direct regulatory primary-source control

For expert smart tools, deep is the default quality-first mode. Use balanced only when lower latency matters enough to justify a narrower pass, and reserve fast for smoke tests or debugging.

Guided research no longer accepts a public latencyProfile knob. The server owns that policy and currently applies a deep-backed quality-first path with one bounded review escalation when the first pass is too weak.

Agent response contract

Treat these as the main guided contracts:

For broad agency-guidance discovery, guided routing stays on the regulatory primary-source path. Off-topic authority documents may still appear as leads, but they should not displace more relevant query-anchored guidance or policy documents from the top-level recommendation.

For source-level audits, treat whyClassifiedAsWeakMatch and confidenceSignals.sourceScopeLabel / confidenceSignals.sourceScopeReason as the primary explanation of why an authoritative record was retained as a weak match or off-topic lead.

Additional trust and grounding signals landed in the llm-guidance phase-4 wave. Guided responses can expose confidenceSignals.evidenceQualityProfile, confidenceSignals.synthesisMode, confidenceSignals.evidenceProfileDetail, confidenceSignals.synthesisPath, confidenceSignals.trustRevisionNarrative, and a trustSummary.authoritativeButWeak bucket for primary-source records that are authoritative but not topically responsive. searchStrategy may surface regulatoryIntent, intentFamily, a subjectCard for species and regulatory grounding, and subjectChainGaps describing missing subject-chain evidence. inspect_source pairs each direct-read suggestion with a directReadRecommendationDetails entry shaped as {trustLevel, whyRecommended, cautions} so agents can prioritize direct reads by quality. See Paper Chaser Golden Paths and Guided And Smart Robustness Notes for how to read and act on these signals.

Deferred export design

Session export is intentionally deferred in this wave. The planned future shape is export_search_session(searchSessionId, format) with format in ris, bibtex, or csv, using the guided-v2 source/citation schema so export can land without another public-contract rewrite.

Migration note

If you previously used the smart/raw-first surface directly:

1. Start with research instead of search_papers_smart or search_papers.
2. Use follow_up_research instead of ask_result_set for default grounded QA.
3. Use resolve_reference instead of resolve_citation/search_papers_match as your first known-item recovery step.
4. Keep expert tools for explicit operator workflows by setting PAPER_CHASER_TOOL_PROFILE=expert.
5. Do not send latencyProfile to guided research; the server now owns that policy internally.
6. For expert smart tools, deep is now the default. Choose balanced explicitly when you want the lower-latency fallback.
7. Expect guided wrappers to surface executionProvenance, sessionResolution, sourceResolution, and abstentionDetails.

For the detailed breaking-change note, see Guided Reset Migration Note.

---

Installation

Current distribution options:

• Source checkout: the most direct local path today, especially for development and MCP desktop clients.
• GHCR image: the primary container distribution channel for Docker-backed MCP clients.
• GitHub Release assets: v* tags build wheel and sdist artifacts and attach them to a draft GitHub Release for review.
• PyPI: intentionally gated for now; use source installs or GitHub Release artifacts until that path is re-enabled.

For local source installs:

pip install -e .

Optional extras for the additive AI layer:

• Shared smart-layer runtime only, including deterministic mode: pip install -e ".[ai]"
• OpenAI or Azure OpenAI provider support: pip install -e ".[ai,openai]"
• Hugging Face chat-router support: pip install -e ".[ai,huggingface]"
• NVIDIA provider support: pip install -e ".[ai,nvidia]"
• Anthropic provider support: pip install -e ".[ai,anthropic]"
• Google provider support: pip install -e ".[ai,google]"
• Mistral provider support: pip install -e ".[ai,mistral]"
• Azure AI Foundry eval publishing helpers: pip install -e ".[eval-foundry]"
• Hugging Face eval publishing helpers: pip install -e ".[eval-huggingface]"
• Both eval publishing helper surfaces: pip install -e ".[eval]"
• Add ,ai-faiss to any of the commands above if you want the optional FAISS backend.

Azure OpenAI uses the same openai extra. Hugging Face uses a dedicated huggingface extra that installs the OpenAI-compatible SDK plus the LangChain OpenAI adapter; this repo documents it as a chat-only smart-provider path with embeddings disabled. The eval publishing helpers use separate extras on purpose: eval-foundry is for Azure AI Foundry dataset upload support, and eval-huggingface is for Hugging Face dataset-repo or bucket publishing support. Those extras are independent from the smart-provider chat runtime.

Configuration

The full local environment-variable contract lives in .env.example. That file mirrors the public local knobs supported by docker-compose.yaml. Azure-specific identifiers, secrets, and Bicep parameters are intentionally documented separately in docs/azure-deployment.md.

Desktop MCP clients

Use stdio transport for desktop MCP clients unless you specifically need HTTP. See the Quick start JSON example above for the server definition.

• Claude Desktop config path:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
• Cursor: add the same MCP server definition in Cursor settings.

Search broker and feature flags

Guided mode starts from research. The brokered and provider-specific controls below are expert-path controls.

Smart-layer model defaults

These are the effective planner/synthesis defaults when you enable PAPER_CHASER_ENABLE_AGENTIC=true and do not intentionally override the model vars.

PAPER_CHASER_EMBEDDING_MODEL defaults to text-embedding-3-large, but embeddings stay off until you set PAPER_CHASER_DISABLE_EMBEDDINGS=false. They remain off by default because embeddings have been unreliable in this codebase and improving them is outside the scope of the current guided-policy release. In the current provider surface, embeddings are only used by providers that explicitly support them, which means the documented Hugging Face path remains chat-only even though it uses an OpenAI-compatible router.

Recommended baseline: enable Semantic Scholar, OpenAlex, Crossref, and Unpaywall for general scholarly workflows; enable ScholarAPI when you want explicit full-text or PDF retrieval; keep SerpApi opt-in because it is a paid recall-recovery path.

Broker rules that matter most:

• Default search fallback order is Semantic Scholar, then arXiv, then CORE, then SerpApi when enabled.
• preferredProvider, providerOrder, and PAPER_CHASER_PROVIDER_ORDER accept core, semantic_scholar, arxiv, scholarapi, and serpapi or serpapi_google_scholar.
• Semantic Scholar-only filters such as publicationDateOrYear, fieldsOfStudy, publicationTypes, openAccessPdf, and minCitationCount can force the broker to skip incompatible providers.
• Broker responses surface brokerMetadata.providerUsed, brokerMetadata.attemptedProviders, and brokerMetadata.recommendedPaginationTool so agents can follow the right next step.

Transport and deployment modes

Key distinctions:

• PAPER_CHASER_HTTP_HOST and PAPER_CHASER_HTTP_PORT control the direct shell and hosted deployments. Docker Compose keeps the container bind at 0.0.0.0:8080 and uses PAPER_CHASER_PUBLISHED_HOST / PAPER_CHASER_PUBLISHED_PORT for the host-side mapping.
• paper-chaser-mcp deployment-http runs the deployment wrapper used by Compose and Azure. It adds /healthz plus optional auth and Origin enforcement in front of the MCP endpoint.

Example direct local HTTP run:

PAPER_CHASER_TRANSPORT=streamable-http \
PAPER_CHASER_HTTP_HOST=127.0.0.1 \
PAPER_CHASER_HTTP_PORT=8000 \
python -m paper_chaser_mcp

If you need the full Azure deployment story, including the bootstrap and full workflow modes, read docs/azure-deployment.md, docs/azure-architecture.md, and docs/azure-security-model.md.

Docker MCP package (stdio)

For local MCP clients that launch servers as subprocesses, use the image in stdio mode. For unpublished local iteration, build and run paper-chaser-mcp:local. For the reusable public package, use the published GHCR tag:

docker run --rm -i ghcr.io/joshuasundance-swca/paper-chaser-mcp:latest

For a locally built image:

docker run --rm -i paper-chaser-mcp:local

A Docker-backed MCP client entry typically looks like:

{
  "mcpServers": {
    "paper-chaser": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/joshuasundance-swca/paper-chaser-mcp:latest"]
    }
  }
}

This mode is ideal for local desktop MCP usage because the host launches and owns the server process lifecycle.

The repo also ships server.json so the public OCI image and MCP package metadata stay aligned for registry/discovery tooling. The public-package workflow is tag-driven for GHCR: a v* tag publishes the reusable container image to ghcr.io/joshuasundance-swca/paper-chaser-mcp. MCP Registry publication is intentionally decoupled into a separate manual workflow so GHCR shipping does not depend on registry availability.

Python package publishing is prepared separately in .github/workflows/publish-pypi.yml: pull requests build and twine check the distribution, and the actual publish jobs stay dormant until the repository variable ENABLE_PYPI_PUBLISHING is set to true. After PyPI/TestPyPI access is restored and the trusted publishers are registered, manual dispatch can publish to TestPyPI and a v* tag can publish to PyPI.

GitHub Release assets are handled separately in .github/workflows/publish-github-release.yml: a v* tag or manual dispatch builds wheel and sdist artifacts, verifies them with twine check, generates SHA256SUMS, and uploads them to a draft GitHub Release page so Python artifacts can be reviewed before broader public promotion.

Docker Compose (HTTP wrapper mode)

For local HTTP testing, MCP Inspector, or bridge-style integrations, this repo ships docker-compose.yaml with localhost-only defaults. Compose explicitly starts the deployment-http subcommand, so HTTP wrapper behavior does not depend on the image's default transport.

Compose keeps the container bind host and internal port fixed at 0.0.0.0:8080 and overrides the app default transport to streamable-http, so browser tools and bridge-style clients can connect over http://127.0.0.1:8000/mcp without extra shell flags. The compose file exposes the user-facing knobs: transport, MCP path, provider keys, provider toggles, auth, and the published host port mapping.

1. Copy .env.example to .env.
2. Fill in any optional provider keys you want to use.
3. Start the service:

docker compose -f docker-compose.yaml up --build

The service listens on http://127.0.0.1:8000 by default, serves /healthz for probes, and exposes MCP over http://127.0.0.1:8000/mcp.

curl http://127.0.0.1:8000/healthz

If you set PAPER_CHASER_HTTP_AUTH_TOKEN and leave PAPER_CHASER_HTTP_AUTH_HEADER=authorization, the deployment wrapper expects Authorization: Bearer <token> on /mcp. The checked-in Azure scaffold overrides the header name to x-backend-auth and has API Management inject that header for backend-only traffic. The published host defaults to 127.0.0.1; only change PAPER_CHASER_PUBLISHED_HOST when you intentionally want the container reachable beyond the local machine.

If you leave the provider key fields blank, local clients still work. The server falls back to the free/default provider paths where supported, and SerpApi stays disabled by default.

Docker Compose Inspector sidecar

For browser-based debugging without installing Node locally, use the dedicated Inspector stack:

docker compose -f compose.inspector.yaml up --build

This stack keeps Inspector separate from the MCP server image and binds the UI and proxy to localhost only:

• Inspector UI: http://127.0.0.1:6274
• Inspector proxy: http://127.0.0.1:6277

Inspector proxy authentication remains enabled by default. Use docker compose -f compose.inspector.yaml logs mcp-inspector to read the session token that Inspector prints on startup.

Inside Inspector, connect using Streamable HTTP and set:

• URL: http://paper-chaser-mcp:8080/mcp
• Transport: streamable-http

compose.inspector.yaml accepts IMAGE overrides, so you can test a specific tag without editing files:

IMAGE=ghcr.io/joshuasundance-swca/paper-chaser-mcp:latest docker compose -f compose.inspector.yaml up

Tools

Full tool reference. See the Quick tool decision guide above for where to start.

Guided default tools

Expert smart research layer

These tools are expert profile paths for deeper orchestration and provider control.

Paper search

Known-item lookup and citation repair

Citations, references, and authors

Paper enrichment and OA discovery

ScholarAPI text and PDF retrieval

OpenAlex entities

ECOS species dossiers

Documentation truncated — see the full README on GitHub.