# https://github.com/Dianel555/paper-search-mcp-nodejs Project Manual

Generated at: 2026-07-09 04:41:46 UTC

## Table of Contents

- [Project Overview and Supported Platforms](#page-1)
- [System Architecture and Core Utilities](#page-2)
- [Platform Searchers and MCP Tool Reference](#page-3)
- [Deployment, Configuration, and Troubleshooting](#page-4)

<a id='page-1'></a>

## Project Overview and Supported Platforms

### Related Pages

Related topics: [System Architecture and Core Utilities](#page-2), [Platform Searchers and MCP Tool Reference](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/README.md)
- [package.json](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/package.json)
- [src/index.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/index.ts)
- [src/models/Paper.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/models/Paper.ts)
- [src/providers/arxiv.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/providers/arxiv.ts)
- [src/providers/webOfScience.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/providers/webOfScience.ts)
- [src/config.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/config.ts)
- [tsconfig.json](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/tsconfig.json)
</details>

# 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:

| Provider | Authentication | Notes |
| --- | --- | --- |
| arXiv | None | Public API; known to be sensitive to network timeouts (see issue #6) |
| Web of Science | API key required | Rate limiting and daily quota guard added in 0.2.6 (PR #4) |
| PubMed / CrossRef | None | Public REST endpoints |
| Google Scholar | Optional | Scraping-based; rate-limited |

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]()

```mermaid
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]()

---

<a id='page-2'></a>

## System Architecture and Core Utilities

### Related Pages

Related topics: [Project Overview and Supported Platforms](#page-1), [Platform Searchers and MCP Tool Reference](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/server.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/server.ts)
- [src/platforms/PaperSource.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/platforms/PaperSource.ts)
- [src/mcp/handleToolCall.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/mcp/handleToolCall.ts)
- [src/mcp/schemas.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/mcp/schemas.ts)
- [src/mcp/tools.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/mcp/tools.ts)
- [src/mcp/searchers.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/mcp/searchers.ts)
</details>

# 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.

| Layer | Module | Responsibility |
|-------|--------|----------------|
| Entry | `src/server.ts` | Constructs the `McpServer`, registers tools, selects transport (`stdio` by default). |
| Tool surface | `src/mcp/tools.ts` | Declares MCP tools and maps each one to a handler. |
| Validation | `src/mcp/schemas.ts` | Zod schemas defining input arguments per tool. |
| Routing | `src/mcp/handleToolCall.ts` | Switches on tool name and invokes the appropriate searcher. |
| Provider abstraction | `src/platforms/PaperSource.ts` | Shared interface every platform implements. |
| Searchers | `src/mcp/searchers.ts` | Composes `PaperSource` adapters, applies defaults, aggregates results. |

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](https://github.com/Dianel555/paper-search-mcp-nodejs/issues/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](https://github.com/Dianel555/paper-search-mcp-nodejs/issues/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](https://github.com/Dianel555/paper-search-mcp-nodejs/issues/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]().

---

<a id='page-3'></a>

## Platform Searchers and MCP Tool Reference

### Related Pages

Related topics: [System Architecture and Core Utilities](#page-2), [Deployment, Configuration, and Troubleshooting](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/platforms/ArxivSearcher.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/platforms/ArxivSearcher.ts)
- [src/platforms/BioRxivSearcher.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/platforms/BioRxivSearcher.ts)
- [src/platforms/CrossrefSearcher.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/platforms/CrossrefSearcher.ts)
- [src/platforms/GoogleScholarSearcher.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/platforms/GoogleScholarSearcher.ts)
- [src/platforms/IACRSearcher.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/platforms/IACRSearcher.ts)
- [src/platforms/PubMedSearcher.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/platforms/PubMedSearcher.ts)
</details>

# 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

| Provider | File | Auth Required | Notes |
|---|---|---|---|
| Arxiv | `ArxivSearcher.ts` | No | Free arXiv API; known to occasionally time out under load (issue #6) |
| BioRxiv | `BioRxivSearcher.ts` | No | Preprint server API |
| Crossref | `CrossrefSearcher.ts` | No | DOI metadata; polite pool via contact email |
| Google Scholar | `GoogleScholarSearcher.ts` | No | Scrapes public search pages |
| IACR | `IACRSearcher.ts` | No | Cryptology ePrint Archive |
| PubMed | `PubMedSearcher.ts` | No | E-utilities (esearch + efetch) |
| Web of Science | (Web of Science searcher) | **Yes** | Added rate limiting + daily quota guard in 0.2.6; fixes sort/citation parsing |

`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]()`

---

<a id='page-4'></a>

## Deployment, Configuration, and Troubleshooting

### Related Pages

Related topics: [Project Overview and Supported Platforms](#page-1), [Platform Searchers and MCP Tool Reference](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [.env.example](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/.env.example)
- [README.md](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/README.md)
- [README-sc.md](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/README-sc.md)
- [package.json](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/package.json)
- [src/platforms/ArxivSearcher.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/platforms/ArxivSearcher.ts)
- [src/platforms/GoogleScholarSearcher.ts](https://github.com/Dianel555/paper-search-mcp-nodejs/blob/main/src/platforms/GoogleScholarSearcher.ts)
</details>

# 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:

| Category | Variable example | Purpose |
|---|---|---|
| Provider toggles | `PAPER_SEARCH_*_ENABLED` | Enable/disable individual platforms |
| Credentials | `WOS_API_KEY`, `SERP_API_KEY` | API keys for paid/limited providers |
| HTTP behavior | `HTTP_TIMEOUT_MS`, `HTTP_PROXY` | Network tuning |
| Logging | `LOG_LEVEL`, `LOG_FORMAT` | Observability |

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](https://github.com/Dianel555/paper-search-mcp-nodejs/issues/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](https://github.com/Dianel555/paper-search-mcp-nodejs/releases/tag/0.2.6).

```mermaid
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](https://github.com/Dianel555/paper-search-mcp-nodejs/issues/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](https://github.com/Dianel555/paper-search-mcp-nodejs/releases/tag/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](https://github.com/Dianel555/paper-search-mcp-nodejs/releases/tag/0.2.1).

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: Dianel555/paper-search-mcp-nodejs

Summary: 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
- Evidence strength: source_linked
- 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.
- Evidence: capability.host_targets | https://github.com/Dianel555/paper-search-mcp-nodejs

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/Dianel555/paper-search-mcp-nodejs

## 3. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/Dianel555/paper-search-mcp-nodejs/issues/6

## 4. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- 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
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- 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
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/Dianel555/paper-search-mcp-nodejs

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Dianel555/paper-search-mcp-nodejs

## 8. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Dianel555/paper-search-mcp-nodejs

<!-- canonical_name: Dianel555/paper-search-mcp-nodejs; human_manual_source: deepwiki_human_wiki -->