paper-search-rs

A native Rust MCP server for academic paper metadata search. It targets MCP 2025-11-25, runs over stdio, and returns schema-defined structured results.

The Python implementation is preserved on the v0 branch. PDF downloading, full-text reading, RAG, and reference management are intentionally out of scope.

Features

• Four providers: arXiv, Semantic Scholar, Scopus, and Web of Science
• Bounded async fan-out with provider failure isolation
• Typed inputSchema, outputSchema, and structuredContent
• JSON TextContent compatibility copy for every tool result
• DOI/title deduplication, sorting, and normalized post-search filters
• Rate limiting, retry/backoff, caching, timeouts, and HTTP/HTTPS/SOCKS proxy support
• JCR/Impact Factor, CAS quartile, CCF rank, and warning-list enrichment
• Native ShowJCR updates without a system git or SQLite dependency

Build

Requires Rust 1.95.0 (pinned in rust-toolchain.toml).

cargo build --release --locked
./target/release/paper-search-rs --version

To install the current checkout into Cargo's binary directory:

cargo install --path . --locked

The native binary can also be distributed through npm and PyPI without compiling Rust locally.

After the packages are published, run the same native stdio server through either package manager:

npx --yes paper-search-rs
uvx paper-search-rs

Both commands select a prebuilt binary. They do not download source code or require a Rust toolchain on the user's machine.

MCP Client Configuration

The server supports stdio only. Use an absolute binary path:

{
  "mcpServers": {
    "paper-search": {
      "command": "/absolute/path/to/paper-search-rs",
      "env": {
        "PAPER_SEARCH_DEFAULT_PLATFORMS": "arxiv,semantic_scholar"
      }
    }
  }
}

Using the npm package:

{
  "mcpServers": {
    "paper-search": {
      "command": "npx",
      "args": ["--yes", "paper-search-rs"],
      "env": {
        "PAPER_SEARCH_DEFAULT_PLATFORMS": "arxiv,semantic_scholar"
      }
    }
  }
}

Using the PyPI wheel through uvx:

{
  "mcpServers": {
    "paper-search": {
      "command": "uvx",
      "args": ["paper-search-rs"],
      "env": {
        "PAPER_SEARCH_DEFAULT_PLATFORMS": "arxiv,semantic_scholar"
      }
    }
  }
}

Example with credentialed providers and JCR:

{
  "mcpServers": {
    "paper-search": {
      "command": "/absolute/path/to/paper-search-rs",
      "env": {
        "PAPER_SEARCH_DEFAULT_PLATFORMS": "arxiv,semantic_scholar,scopus,webofscience",
        "SCOPUS_API_KEY": "your-scopus-key",
        "WOS_API_KEY": "your-wos-key",
        "PAPER_SEARCH_JCR_ENABLED": "true"
      }
    }
  }
}

MCP Tools

paper_search

Always registered. If platforms is omitted, all providers listed in PAPER_SEARCH_DEFAULT_PLATFORMS are searched.

Example:

{
  "query": "construction safety",
  "platforms": ["webofscience"],
  "year_from": 2021,
  "year_to": 2025,
  "wos_options": {
    "document_type": "Article",
    "page": 1
  }
}

The result envelope contains papers, failures, optional diagnostics, and an optional global error. Partial provider failures do not discard successful results. A complete provider failure returns the same structured envelope with MCP isError=true.

jcr_lookup

Registered only when PAPER_SEARCH_JCR_ENABLED=true. Accepts journal, issn, or both. Results include Impact Factor, JCR rank/quartile/category, CAS fields, CCF fields, and warning status.

{
  "journal": "Nature"
}

Configuration

Configuration is environment-only. Invalid values fail startup with a redacted stderr message.

Core

PAPER_SEARCH_DEFAULT_PLATFORMS is explicit: configuring an API key does not silently enable its provider. Supported values are arxiv, semantic_scholar, scopus, and webofscience.

Provider settings

Per-provider overrides use PAPER_SEARCH_PLATFORM_<PLATFORM>_<FIELD>:

• ..._MAX_RESULTS
• ..._RATE_LIMIT_RPS
• ..._PROXY

Credential variables:

Proxy URLs are read from HTTP_PROXY, HTTPS_PROXY, and SOCKS_PROXY. A search provider uses the configured proxy only when its ..._PROXY=true; native JCR updates use the global proxy settings.

JCR

Manual update:

paper-search-rs update-jcr
paper-search-rs update-jcr --force

Updates fetch an exact ShowJCR revision over HTTPS, extract to a staging directory, validate the index, and atomically publish it. Existing usable data remains active if an update fails.

Development

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features
cargo build --release --locked
npm --prefix npm test
node scripts/smoke-npm-local.mjs
scripts/smoke-uvx-local.sh

Live smoke tests are opt-in. The public-provider test needs no credentials:

cargo test --test live_smoke searches_public_providers -- --ignored --nocapture

With the corresponding environment credentials loaded, run Scopus and Web of Science separately:

cargo test --test live_smoke searches_scopus_with_credentials -- --ignored --nocapture
cargo test --test live_smoke searches_web_of_science_with_credentials -- --ignored --nocapture

The ShowJCR smoke downloads into an automatically removed temporary directory:

cargo test --test live_smoke updates_and_queries_live_jcr -- --ignored --nocapture

Native Targets

• aarch64-apple-darwin
• x86_64-apple-darwin
• x86_64-unknown-linux-gnu
• aarch64-unknown-linux-gnu
• x86_64-pc-windows-msvc

License

Apache-2.0