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

Federal Register and CFR

SerpApi extras (opt-in, paid)

Recovery and diagnostics

ECOS walkthrough

California least tern is a representative end-to-end ECOS flow:

1. Call search_species_ecos with query="California least tern" to get the ECOS species id 8104.
2. Call get_species_profile_ecos with species_id="8104" to inspect the species dossier, grouped recovery documents, biological opinions, and conservation-plan links.
3. Call list_species_documents_ecos with species_id="8104" and, for example, documentKinds=["recovery_plan","five_year_review","biological_opinion"] to flatten the document inventory.
4. Call get_document_text_ecos on the 2025 five-year-review PDF or the revised recovery plan PDF to turn the source document into Markdown for downstream analysis.

Resources and prompts

• Resource: guide://paper-chaser/agent-workflows - compact onboarding guide for choosing tools and following pagination safely
• Resource: paper://{paper_id} - compact markdown + structured payload for a resolved paper
• Resource: author://{author_id} - compact markdown + structured payload for a resolved author
• Resource: search://{searchSessionId} - saved result set surfaced from tool outputs
• Resource: trail://paper/{paper_id}?direction=citations|references - compact citation/reference trail resource
• Prompt: plan_paper_chaser_search - reusable planning prompt with guided-first defaults and explicit expert fallback
• Prompt: plan_smart_paper_chaser_search - planning prompt for intentional expert smart-mode workflows
• Prompt: triage_literature - guided triage workflow for trust-aware theme mapping and next-step selection
• Prompt: plan_citation_chase - citation-expansion planning prompt
• Prompt: refine_query - bounded query-refinement prompt for broad or noisy searches

Primary read-tool responses also surface:

• agentHints - recommended next tools, retry guidance, and warnings
• clarification - bounded clarification fallback when the server cannot safely disambiguate on its own
• resourceUris - follow-on resources that compatible clients can open directly
• searchSessionId - reusable result-set handle for smart follow-up workflows and cached expansion/search trails

Microsoft packaging assets

This repository keeps one universal MCP server surface and ships additive packaging assets for Microsoft-oriented clients:

• mcp-tools.core.json - guided low-context default surface (research, follow_up_research, resolve_reference, inspect_source, get_runtime_status)
• mcp-tools.full.json - guided + expert package for environments intentionally running with PAPER_CHASER_TOOL_PROFILE=expert
• microsoft-plugin.sample.json - sample declarative-agent / plugin-oriented metadata

These assets target Streamable HTTP and compact tool outputs. They are packaging guidance, not a separate runtime build.

Testing with MCP Inspector

The recommended local path is the Docker sidecar workflow:

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

This keeps Inspector out of the production MCP image and binds Inspector ports to localhost only.

If you prefer a host-installed Inspector, you can still run:

npm install -g @modelcontextprotocol/inspector
mcp-inspector python -m paper_chaser_mcp

Development

Install the package with development extras:

pip install -e ".[dev]"

If you also want the additive AI layer plus every hosted-provider integration in the same environment:

pip install -e ".[all]"

all expands to ai,openai,huggingface,nvidia,anthropic,google,mistral,dev, so Azure OpenAI still uses the same openai extra while Hugging Face remains a separate chat-only OpenAI-compatible install surface.

If you need the optional FAISS backend locally as well:

pip install -e ".[all,ai-faiss]"

Project dependencies are declared in pyproject.toml; there is no separate runtime requirements.txt to keep in sync.

Run the local test suite:

pytest

Install and run the configured pre-commit hooks:

pre-commit install
pre-commit run --all-files

pre-commit install installs both the fast pre-commit hooks and the heavier pre-push gates configured in .pre-commit-config.yaml. Manual-stage hooks are not invoked automatically; run pre-commit run --hook-stage manual --all-files (or the direct commands above) when you want the full local gate.

The development extras include pytest, pytest-asyncio, pytest-cov, ruff, mypy, bandit, build, bumpver, pip-audit, shellcheck-py, types-defusedxml, and pre-commit. GitHub dependency automation is configured for both Python packages and GitHub Actions via Dependabot, with pull requests checked by the dependency review workflow.

For local parity with CI on GitHub workflow files, keep shellcheck available on PATH before running pre-commit. Installing shellcheck-py in the active repo venv satisfies this for many setups; verify with shellcheck --version instead of assuming inline workflow bash is being linted locally.

Version bumps

Version metadata is managed with bumpver from pyproject.toml. The checked-in package version stays in plain PEP 440 form such as 0.2.0, while the release tag shape remains v0.2.0 to match the existing publish workflow trigger.

For PR-branch-safe review, dry-run a patch bump without touching git state:

bumpver update --patch --dry --no-fetch --no-commit --no-tag-commit --no-push

For an actual release-prep branch, update the checked-in version contract but still leave commit, tag, and push under explicit maintainer control:

bumpver update --patch --no-commit --no-tag-commit --no-push

Full local validation

The repo's CI-equivalent local gate is broader than pytest alone. For a thorough local pass, run:

python -m pip check
pre-commit run --all-files
python -m pytest --cov=paper_chaser_mcp --cov-report=term-missing --cov-fail-under=87
python -m mypy --config-file pyproject.toml
python -m ruff check .
python -m bandit -c pyproject.toml -r paper_chaser_mcp
python -m build
python -m pip_audit . --progress-spinner off

If you prefer to invoke the heavier hook-managed checks through pre-commit, pre-commit run --hook-stage manual --all-files runs the manual-stage pip check, coverage, build, and pip-audit hooks defined in .pre-commit-config.yaml.

When you touch Azure IaC, deployment docs, the Dockerfile, the APIM policy, or the Azure deployment workflow, also run:

python scripts/validate_psrule_azure.py
python scripts/validate_deployment.py --skip-docker

For parity with the Deploy Azure workflow's full deployment validation path, run:

python scripts/validate_deployment.py --require-az --require-docker --image-tag paper-chaser-mcp:ci-validate

GitHub Agentic Workflow smoke test

The repository includes an agentic regression workflow at .github/workflows/test-paper-chaser.md (source) and .github/workflows/test-paper-chaser.lock.yml (compiled lock file). It runs the agent against the local MCP server inside GitHub Actions, exercises the primary golden paths, evaluates agent UX quality, and can file actionable issues for follow-on work.

After editing the Markdown workflow, recompile and validate:

gh aw compile test-paper-chaser --dir .github/workflows
pre-commit run --all-files

Commit both the .md source and .lock.yml output together, then run Test Paper Chaser MCP from the GitHub Actions UI.

Workflow inputs: mode (smoke, comprehensive, or feature_probe), tool_profile (guided by default, expert when you intentionally want raw/provider-specific coverage), and an optional focus_prompt. Select them via workflow_dispatch inputs.

Required secrets: COPILOT_GITHUB_TOKEN is required. GH_AW_MODEL_AGENT_COPILOT (Actions variable, optional) controls the agent model. CORE_API_KEY and SEMANTIC_SCHOLAR_API_KEY are optional.

The repository also includes .github/workflows/agentic-assign.yml, which automatically assigns GitHub Copilot to issues labeled agentic and needs-copilot (unless also labeled needs-human, blocked, or no-agent). The Validate workflow recompiles test-paper-chaser.md on CI and fails if the lock file is stale, so pull requests cannot silently drift out of sync. The workflow is "deployed" when GitHub Actions sees the committed .lock.yml on the branch where it should run.

See SECURITY.md for the public-repo security posture and the recommended private reporting path for vulnerabilities.

For maintainer orientation after the module split, start with docs/agent-handoff.md. The public MCP surface stays in paper_chaser_mcp/server.py, while implementation lives in paper_chaser_mcp/dispatch.py, paper_chaser_mcp/search.py, paper_chaser_mcp/tools.py, paper_chaser_mcp/runtime.py, paper_chaser_mcp/models/, and provider subpackages under paper_chaser_mcp/clients/.

Guides

• GitHub Copilot Instructions - repo-specific guidance for GitHub Copilot and the GitHub cloud coding agent, including workflow defaults and durable planning expectations.
• Agent Handoff - current repo status, validation commands, and next recommended work for follow-on agents.
• LLM Selection Guide - planner versus synthesis responsibilities, current smart-layer model defaults, the eval-bootstrap funnel around generate_eval_topics.py and run_eval_autopilot.py, and criteria for choosing LLMs in this repo.
• LLM Evaluation Program Plan - role-based evaluation strategy, dataset-generation plan, evaluator stack, and phased rollout for rigorous LLM performance measurement in this repo.
• LLM Evaluation Dataset Schema - JSONL schema, field rules, governance conventions, and storage layout for role-based evaluation seed sets and future benchmark expansion.
• LLM Evaluation Platform Strategy - how to combine repo-local evals with Azure AI Foundry, Hugging Face, and live-trace active-learning loops without losing portability.
• LLM Evaluation Trace Promotion - workflow and helper format for promoting reviewed live traces into durable evaluation rows.

Optional live eval-candidate capture can be enabled with PAPER_CHASER_ENABLE_EVAL_TRACE_CAPTURE=true and PAPER_CHASER_EVAL_TRACE_PATH=..., then converted into a review queue with scripts/build_eval_review_queue.py before promotion.

Portable exports for downstream evaluation and training systems are available via scripts/export_eval_assets.py, including Foundry-friendly eval JSONL, Hugging Face dataset JSONL, and chat-style training JSONL from review-approved traces.

Service-specific publish helpers are available via scripts/upload_foundry_eval_dataset.py and scripts/upload_hf_eval_assets.py for pushing reviewed exports into a Foundry project dataset, a Hugging Face dataset repo, or a Hugging Face bucket.

Expert batch curation runs can now emit batch-summary.json and batch-ledger.csv alongside the raw report, captured events, and review queue so offline drift and throughput checks do not depend on replaying the full JSONL artifacts.

For repo-local eval bootstrap, the current top-level workflow is:

• scripts/generate_eval_topics.py for planner-led topic generation, taxonomy assignment, ranking, pruning, balancing, and scenario emission
• scripts/run_eval_autopilot.py for profile-driven generation, immutable run bundles, holdout checks, and guarded workflow handoff
• scripts/run_eval_workflow.py for expert batch capture, review or promotion, dataset splitting, and live provider-matrix evaluation

The checked-in autopilot sample profiles now include balanced-science defaults plus narrow-run profiles such as single-seed-exploratory-review, single-seed-exploratory-safe, and single-seed-diagnostic-force. Those narrow-run profiles can enable single-seed diversification so one-seed runs ask the planner for additional review, regulatory, and methods-oriented variants instead of depending only on looser workflow thresholds.

See docs/llm-evaluation-integrations.md for the current Foundry and Hugging Face integration posture, including when hf-mount is a good fit for a shared capture sink.

• Release And Publishing Plan - the current release playbook for GHCR, GitHub Release assets, manual MCP Registry publication, and dormant PyPI.
• Guided Reset Migration Note - breaking default-surface change, guided-vs-expert split, and client migration checklist.
• Paper Chaser Golden Paths - primary personas, workflow defaults, success signals, and future workflow-oriented follow-up work.
• Azure Deployment - deployment modes, required secrets and variables, and validation paths for the private Azure rollout.
• Azure Architecture - trust boundaries, runtime topology, and credential separation for the Azure scaffold.
• Azure Security Model - credential classes, Key Vault usage, and backend-auth separation in the Azure rollout.
• Provider Upgrade Program - provider roles, latency profiles, diagnostics, benchmark corpus, and acceptance gates for the reliability-first provider upgrade.
• OpenRouter Provider Guide - implementation-focused guidance for adding and operating OpenRouter as a chat-only smart-layer provider, including the current Trinity bring-up plan.
• ScholarAPI Integration Guide - planning guide for adding ScholarAPI as an explicit discovery, monitoring, full-text, and PDF provider without weakening the current graph-oriented provider contracts.
• OpenAlex API Guide - implementation-focused guidance for the repo's explicit OpenAlex MCP surface, including authentication, credit-based limits, paging, /works semantics, and normalization caveats.
• Semantic Scholar API Guide - practical guidance for respectful and effective Semantic Scholar API usage with async rate limiting, retries, and .env-based local development.
• SerpApi Google Scholar Guide - deep research notes on SerpApi capabilities, tradeoffs, and cost/compliance considerations; the repo ships the explicit cited-by, versions, author, account, and citation-format flows documented there.
• FastMCP Migration Plan - historical architecture rationale for the FastMCP migration and compatibility surface.

License

MIT

Links

Protocol and runtime

• Model Context Protocol
• FastMCP
• SerpApi pricing

Scholarly providers

• Semantic Scholar API
• arXiv API User's Manual
• CORE API v3 Documentation
• OpenAlex API docs
• ScholarAPI docs
• SerpApi Google Scholar API
• Crossref REST API
• Unpaywall API

Regulatory and species sources

• ECOS
• FederalRegister.gov API
• GovInfo API