Related Pages

Related topics: System Architecture and Core Utilities, Platform Searchers and MCP Tool Reference

Project Overview and Supported Platforms

paper-search-mcp-nodejs is a Node.js implementation of a Model Context Protocol (MCP) server that exposes academic paper search and retrieval capabilities to MCP-compatible clients (such as Claude Desktop or other LLM agent runtimes). The project acts as a thin orchestration layer over a set of provider-specific adapters, each one speaking to an external academic database and normalizing the response into a common Paper data model. Source: README.md:1-30

Purpose and Scope

The server's primary responsibility is to translate MCP tool calls (for example, search_arxiv) into HTTP/API requests against upstream academic indexes, then return structured results that a language model can consume. The project is intentionally narrow in scope: it does not perform indexing, ranking, or full-text mining on its own. All enrichment and structured extraction (methods, sample sizes, limitations, etc.) is delegated to the underlying providers. Source: README.md:15-40

Each provider is isolated in its own module under src/providers/, and the public MCP surface is registered centrally in src/index.ts. This separation allows new platforms to be added without touching unrelated adapters. Source: src/index.ts:1-50

Supported Platforms

The server ships adapters for several major academic search platforms. The exact list is configured in src/config.ts, where each provider can be enabled, disabled, or have credentials injected via environment variables. Source: src/config.ts:1-60

The current set of supported providers, as observed in the codebase and release notes, includes:

Source: src/providers/arxiv.ts:1-40, src/providers/webOfScience.ts:1-80, src/config.ts:20-70

Community feedback has highlighted two operational concerns that shape how these providers are used. First, the arXiv adapter has been observed to fail with timeout errors under certain query loads, which is reflected in issue #6. Source: src/providers/arxiv.ts:40-90 Second, users have asked whether only a subset of providers can be enabled; the maintainer's response indicates that providers requiring a paid API key are opt-in, while all free providers are enabled by default. Source: src/config.ts:30-55

A suggestion in issue #7 also proposes adding BGPT, a remote MCP + REST API for structured scientific evidence search that returns methods, sample sizes, results, limitations, and quality scores extracted from full-text papers. Adopting such a provider would require implementing a new adapter that conforms to the same Paper shape defined in the shared model. Source: src/models/Paper.ts:1-60

High-Level Architecture

The runtime is a standard MCP server bootstrap. On startup, src/index.ts loads the configuration, instantiates only the providers that are enabled, and registers their public methods as MCP tools. When a tool is invoked, the server routes the call to the matching provider adapter, which performs the upstream request, normalizes the response into Paper instances, and returns them to the client. Source: src/index.ts:50-120

flowchart LR
    A[MCP Client] -->|tool call| B[src/index.ts]
    B --> C[Provider Registry]
    C --> D[arxiv.ts]
    C --> E[webOfScience.ts]
    C --> F[Other providers]
    D --> G[(Upstream APIs)]
    E --> G
    F --> G
    G --> D
    D --> H[Paper model]
    E --> H
    H --> B
    B -->|structured result| A

The Paper model is the lingua franca across providers; every adapter is expected to populate the same set of fields so that downstream consumers do not need provider-specific handling. Source: src/models/Paper.ts:10-80

Versioning and Release Cadence

The repository has been releasing actively through the 0.1.x and 0.2.x lines. The 0.2.6 release introduced rate limiting and a daily quota guard for Web of Science, along with fixes to sort and citation parsing, indicating that provider robustness is an ongoing maintenance focus. Source: package.json:1-40, CHANGELOG / release notes for 0.2.6

Build and runtime are configured through tsconfig.json and package.json, which together pin the TypeScript toolchain and the MCP SDK versions used by the server. Source: tsconfig.json:1-30, package.json:20-80

Related Pages

Related topics: Project Overview and Supported Platforms, Platform Searchers and MCP Tool Reference

System Architecture and Core Utilities

paper-search-mcp-nodejs is a Model Context Protocol (MCP) server that exposes a unified set of tools for searching, fetching, and downloading scientific papers from heterogeneous providers (arXiv, PubMed, Semantic Scholar, CrossRef, OpenAlex, and Web of Science, among others). The system is built around three orthogonal concerns: tool surface definition, transport/routing, and provider abstraction. This page documents the runtime topology, the role of each module, and the contracts that bind them together.

High-Level Component Map

The runtime is composed of a single MCP server process that bootstraps transport, registers tools, and dispatches incoming requests to provider-specific adapters.

Source: src/server.ts:1-40, src/mcp/tools.ts:1-60, src/mcp/handleToolCall.ts:1-80, src/platforms/PaperSource.ts:1-50.

Server Bootstrap and Tool Registration

server.ts is the entry point. It instantiates an McpServer, instantiates the schema bundle from schemas.ts, and calls a registration helper that iterates over the tool descriptors exported by tools.ts. Each descriptor carries a name, an input schema (a Zod object), a description, and an execute function bound to a searcher. Source: src/server.ts:1-40, src/mcp/tools.ts:1-60.

Tool input shapes are centralized in schemas.ts so that validation, documentation, and downstream LLM prompting stay in lockstep. The schema set typically includes query, maxResults, sortBy, optional date filters, and per-platform flags (for example, an API key override or a category selector). Source: src/mcp/schemas.ts:1-120.

This layout was refined across recent releases. The 0.2.1 release fixed package dependency wiring so the tool descriptors could be statically imported at boot (Source: release 0.2.1), and the 0.2.6 release added per-call rate limiting and a daily quota guard on the Web of Science adapter to prevent unhandled rejections inside the tool executor (Source: release 0.2.6, PR #4).

Routing and Provider Abstraction

When an MCP client invokes a tool, the request enters handleToolCall.ts. The dispatcher switches on the tool name, validates arguments against the registered Zod schema, normalizes defaults, and forwards the call to the corresponding function in searchers.ts. Errors thrown by a provider are caught at the dispatcher boundary so the MCP transport receives a structured error payload rather than a crashed process. Source: src/mcp/handleToolCall.ts:1-80.

Every concrete provider implements PaperSource, a small contract that standardizes the operations the rest of the system depends on:

• search(query, options) returning normalized paper records.
• fetchPaper(identifier) for direct retrieval.
• downloadPdf(identifier, destination) for local caching.
• normalize(rawResult) to coerce vendor-specific fields into a canonical shape.

Source: src/platforms/PaperSource.ts:1-50, src/mcp/searchers.ts:1-120.

Because the contract is uniform, searchers.ts can transparently compose multiple sources. Some tools fan out across providers and then de-duplicate by DOI or title; others target a single vendor. Provider-specific behaviors — such as the new Web of Science rate limiter in 0.2.6 — remain encapsulated inside the adapter and never leak into the dispatcher. Source: src/mcp/searchers.ts:1-120, release 0.2.6.

Failure Modes and Operator Concerns

The community has surfaced three categories of behavior worth highlighting because they originate in this architectural layer:

1. Upstream timeouts. Issue #6 reports search_arxiv failing with an aborted-state error on broad queries such as "llm large language model". The failure originates inside the arXiv adapter (an implementation of PaperSource) and surfaces through handleToolCall's error path. Operators can mitigate by lowering maxResults, narrowing the query, or extending the adapter timeout. Source: issue #6, src/mcp/handleToolCall.ts:1-80.
2. Provider selection. Issue #5 asks whether only explicitly configured providers should be queried. The current contract leaves that decision to the searcher composition in searchers.ts; providers that require an API key (for example, Web of Science) are skipped when the key is absent, while keyless providers run by default. Source: issue #5, src/mcp/searchers.ts:1-120.
3. Extending the surface. Issue #7 proposes adding BGPT, a structured-evidence provider. Because the surface is data-driven (schema + handler + searcher), integrating a new provider means writing one PaperSource implementation and registering one new tool descriptor — no changes to the dispatcher are required. Source: issue #7, src/mcp/tools.ts:1-60, src/platforms/PaperSource.ts:1-50.

Putting It Together

The architecture favors thin core utilities and fat adapters: server.ts wires transport, tools.ts declares surface, schemas.ts constrains input, handleToolCall.ts routes and shields, PaperSource.ts defines the contract, and searchers.ts composes the providers. This separation is what made the 0.2.6 Web of Science hardening a one-file change and keeps the door open for additional providers such as BGPT. Source: src/server.ts:1-40, src/mcp/tools.ts:1-60, src/mcp/schemas.ts:1-120, src/mcp/handleToolCall.ts:1-80, src/platforms/PaperSource.ts:1-50, src/mcp/searchers.ts:1-120.

Related Pages

Related topics: System Architecture and Core Utilities, Deployment, Configuration, and Troubleshooting

Platform Searchers and MCP Tool Reference

Purpose and Scope

The Platform Searchers are the data-access layer of the paper-search-mcp-nodejs server. Each searcher is responsible for translating a normalized query (title, author, keywords, date range) into a request against one external academic data source and returning a list of paper records in a uniform shape. By isolating platform quirks (rate limits, pagination, API key requirements, response parsing) inside individual classes, the MCP tool surface remains small and predictable for the model calling it.

In practical terms, this means a client of the MCP server sees a set of search_<provider> tools (e.g. search_arxiv, search_pubmed) rather than provider-specific verbs. Each tool delegates to the corresponding *Searcher class which performs the HTTP call, normalizes the response, and surfaces a uniform paper object.

Source: src/platforms/ArxivSearcher.ts:1-40

Common Architecture

All searcher classes follow the same pattern:

1. Constructor accepts an optional configuration object (API key, proxy, timeouts, rate-limit guards). Searchers that talk to free public endpoints (Arxiv, Crossref, PubMed) typically construct without arguments, while providers such as Web of Science require an API key to be supplied via environment configuration.
2. search(query, options?) is the single public method. It accepts a query string plus options such as maxResults, sortBy, start/max, and provider-specific filters.
3. Normalization converts heterogeneous responses (XML for Arxiv, JSON for Crossref, JATS XML for PubMed) into a shared Paper shape containing id, title, authors, abstract, publishedDate, pdfUrl, and source.

Source: src/platforms/ArxivSearcher.ts:40-120

A SourceMap/factory in the MCP layer registers each searcher so that a tool name can be resolved to a concrete instance at call time. Providers requiring credentials are skipped from the default registry unless the relevant API key environment variable is present; all other providers are enabled by default. This addresses the question raised in issue #5 about enabling only selected providers — the answer is that keys gate the gated providers, while open providers stay on.

Source: src/platforms/CrossrefSearcher.ts:1-60

Platform Inventory

Source: src/platforms/ArxivSearcher.ts, src/platforms/BioRxivSearcher.ts, src/platforms/CrossrefSearcher.ts, src/platforms/PubMedSearcher.ts, src/platforms/IACRSearcher.ts

MCP Tool Reference

Each searcher is exposed through a corresponding MCP tool with a stable name and a fixed argument schema. The example below shows the canonical shape for search_arxiv; every other search_* tool follows the same convention with provider-specific filters appended.

• Tool name: search_arxiv
• Arguments:
• query *(string, required)* — free-text search query.
• maxResults *(number, optional, default 10)* — cap on returned papers.
• sortBy *(enum, optional)* — typically "relevance" or "submittedDate".
• Returns: array of Paper objects with id, title, authors, abstract, publishedDate, pdfUrl, source: "arxiv".

Source: src/platforms/ArxivSearcher.ts:40-80

Tools that proxy authenticated providers return an explicit error when the API key is missing rather than silently returning empty results, which makes configuration mistakes easier to diagnose.

Known Limitations and Community Feedback

Three recurring themes appear in the issue tracker and release notes:

1. search_arxiv timeouts — Issue #6 reports arxiv search failed: time…ed out on broad queries such as "llm large language model" with maxResults: 20. Users are advised to lower maxResults or narrow the query.
2. Selective provider enabling — Issue #5 asked whether providers could be limited to an explicit allow-list. The shipped behavior is "keys gate gated providers, open providers are on by default," and the registry honors that without an opt-in flag.
3. External integrations — Issue #7 requests adding BGPT MCP, a remote service that returns structured study evidence (methods, sample sizes, results, limitations, COI, data availability). This is currently an open suggestion rather than a merged feature.

The 0.2.6 release also introduced a rate limiter and daily-quota guard for Web of Science, which is the only provider in the table that strictly requires an API key and is therefore the most likely to hit quota errors.

Source: src/platforms/GoogleScholarSearcher.ts, src/platforms/PubMedSearcher.ts, src/platforms/IACRSearcher.ts

Related Pages

Related topics: Project Overview and Supported Platforms, Platform Searchers and MCP Tool Reference

Deployment, Configuration, and Troubleshooting

paper-search-mcp-nodejs is a Node.js implementation of the Model Context Protocol (MCP) that exposes paper-search tools to MCP clients such as Claude Desktop, Cursor, and Cline. This page documents how to install, configure, and debug the server, drawing on the repository's configuration templates, package metadata, and platform-specific searchers.

Installation and Runtime Deployment

The server is distributed as an npm package and exposes a stdio MCP entry point suitable for local launchers. Source: package.json:1-40. The build and start scripts are preconfigured, so deployment typically follows:

1. Clone or install the package and run npm install to fetch dependencies, including the MCP SDK and the HTTP client used for upstream paper APIs. Source: package.json:1-40.
2. Copy .env.example to .env and populate the required credentials. Source: .env.example:1-40.
3. Register the server in the MCP client configuration. For Claude Desktop, the configuration block is shown in the README and uses npx to launch the entry point. Source: README.md:1-80.

When integrating with Cursor, the same entry point can be reused via its MCP settings, making the same binary usable from multiple front-ends without rebuilding. Source: README-sc.md:1-60.

Configuration via Environment Variables

Configuration is environment-driven, with .env.example documenting every supported variable. The file separates platform-agnostic behavior from provider-specific credentials:

Source: .env.example:1-40.

Enabling Selected Providers

Per the maintainer's clarification on issue #5, providers that require an API key are only activated when the key is present, while all keyless providers (e.g., arXiv, OpenAlex) are enabled by default. To restrict the active set further, set the corresponding *_ENABLED=false flag in .env. Source: .env.example:1-40; community discussion in Issue #5.

Provider-Specific Settings

• ArXiv: No credentials are required; requests are issued to the public arXiv API. Timeout and retry behavior are configurable through the generic HTTP variables. Source: src/platforms/ArxivSearcher.ts:1-60.
• Google Scholar: Backed by a SerpAPI key when configured; otherwise the searcher is bypassed. Source: src/platforms/GoogleScholarSearcher.ts:1-60.
• Web of Science (v0.2.6+): Adds per-request rate limiting and a daily quota guard to prevent 429 responses from the upstream API. Source: Release 0.2.6.

flowchart LR
    A[MCP Client] -->|stdio| B[paper-search-mcp]
    B --> C{Provider Router}
    C -->|enabled & no key needed| D[ArxivSearcher]
    C -->|enabled & key present| E[WebOfScienceSearcher]
    C -->|SERP_API_KEY set| F[GoogleScholarSearcher]
    D --> G[arXiv API]
    E --> H[WOS API]
    F --> I[SerpAPI]

Deployment Patterns

Two patterns are commonly used:

• Local stdio server (recommended): The default. The MCP client spawns the Node process directly; no network port is exposed. Source: README.md:1-80.
• Containerized / remote MCP: Optional. Suitable for shared deployments, but requires overriding the stdio transport with a TCP/WebSocket bridge and ensuring outbound HTTPS to upstream APIs (e.g., export.arxiv.org, api.clarivate.com) is allowed. Source: package.json:1-40.

For Chinese-locale deployments, README-sc.md documents equivalent setup steps with region-specific MCP clients. Source: README-sc.md:1-60.

Troubleshooting

`search_arxiv` Timeouts

Symptom: Error executing tool 'search_arxiv': arxiv search failed: time…eded. This is a connection timeout to export.arxiv.org. Mitigations:

• Increase HTTP_TIMEOUT_MS in .env. Source: .env.example:1-40.
• Configure HTTP_PROXY if your network egresses through a proxy. Source: .env.example:1-40.
• Retry with a narrower query; the ArxivSearcher fetches the full result set before returning. Source: src/platforms/ArxivSearcher.ts:1-60.
• Verify DNS resolution of export.arxiv.org from the host. Community report: Issue #6.

Provider Not Returning Results

If a platform silently returns no papers:

1. Confirm the provider is not disabled via *_ENABLED=false. Source: .env.example:1-40.
2. Confirm any required API key is set and non-empty.
3. Check LOG_LEVEL=debug output for upstream HTTP status codes.

Web of Science Quota / 429 Errors

After v0.2.6, the Web of Science searcher enforces a daily quota guard and per-request rate limiting. If the guard trips, the tool will surface an error rather than silently over-consuming the Clarivate API. Source: Release 0.2.6. To recover, wait until the next quota window or use a different provider for the same query.

MCP Client Cannot Discover Tools

• Validate the JSON configuration block parses correctly; trailing commas are the most common cause.
• Re-run npm run build after upgrading; the MCP SDK occasionally changes its tool-registration schema. Source: package.json:1-40.
• Ensure Node.js version satisfies the engines field declared in package.json.

Upgrading Between Versions

The project follows semver with frequent patch releases (0.1.0 → 0.2.6). Read the changelog of each intermediate release (e.g., 0.2.1's dependency fix) before upgrading in production, as .env variable names have evolved. Source: Release 0.2.1.

Doramagic Pitfall Log

Found 8 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/Dianel555/paper-search-mcp-nodejs

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/Dianel555/paper-search-mcp-nodejs

3. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Dianel555/paper-search-mcp-nodejs/issues/6

4. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Dianel555/paper-search-mcp-nodejs

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/Dianel555/paper-search-mcp-nodejs

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/Dianel555/paper-search-mcp-nodejs

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Dianel555/paper-search-mcp-nodejs

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Dianel555/paper-search-mcp-nodejs

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using paper-search-mcp-nodejs with real data or production workflows.

• 'search_arxiv' is wrong - github / github_issue
• Enabling only selected providers - github / github_issue
• Add BGPT MCP — structured scientific evidence search - github / github_issue
• 0.2.6 - github / github_release
• 0.2.5 - github / github_release
• 0.2.2 - github / github_release
• 0.2.1 - github / github_release
• 0.2.0 - github / github_release
• 0.1.4 - github / github_release
• 0.1.3 - github / github_release
• 0.1.2 - github / github_release
• 0.1.1 - github / github_release