@cyanheads/pubmed-mcp-server 1.2.4 → 1.3.1

package/README.md

@@ -1,15 +1,19 @@
-# PubMed MCP Server
+<div align="center">
 
-[![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue.svg)](https://www.typescriptlang.org/)
-[![Model Context Protocol](https://img.shields.io/badge/MCP%20SDK-^1.13.0-green.svg)](https://modelcontextprotocol.io/)
-[![Version](https://img.shields.io/badge/Version-1.2.3-blue.svg)](./CHANGELOG.md)
-[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![Status](https://img.shields.io/badge/Status-Stable-green.svg)](https://github.com/cyanheads/pubmed-mcp-server/issues)
-[![GitHub](https://img.shields.io/github/stars/cyanheads/pubmed-mcp-server?style=social)](https://github.com/cyanheads/pubmed-mcp-server)
+# pubmed-mcp-server
 
 **Empower your AI agents and research tools with seamless PubMed integration!**
 
-An MCP (Model Context Protocol) server providing comprehensive access to PubMed's biomedical literature database. Enables LLMs and AI agents to search, retrieve, analyze, and visualize scientific publications through NCBI's E-utilities API with advanced research workflow capabilities.
+[![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
+[![Model Context Protocol](https://img.shields.io/badge/MCP%20SDK-^1.17.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/)
+[![Version](https://img.shields.io/badge/Version-1.3.1-blue.svg?style=flat-square)](./CHANGELOG.md)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](https://opensource.org/licenses/Apache-2.0)
+[![Status](https://img.shields.io/badge/Status-Stable-green.svg?style=flat-square)](https://github.com/cyanheads/pubmed-mcp-server/issues)
+[![GitHub](https://img.shields.io/github/stars/cyanheads/pubmed-mcp-server?style=social)](https://github.com/cyanheads/pubmed-mcp-server)
+
+</div>
+
+Model Context Protocol (MCP) Server providing comprehensive access to PubMed's biomedical literature database. Enables LLMs and AI agents to search, retrieve, analyze, and visualize scientific publications through NCBI's E-utilities API with advanced research workflow capabilities.
 
 Built on the [`cyanheads/mcp-ts-template`](https://github.com/cyanheads/mcp-ts-template), this server follows a modular architecture with robust error handling, logging, and security features.
 
@@ -17,23 +21,22 @@ Built on the [`cyanheads/mcp-ts-template`](https://github.com/cyanheads/mcp-ts-t
 
 This server equips your AI with specialized tools to interact with PubMed:
 
-| Tool Name                                                                               | Description                                                                                                                                                                                                  | Key Features                                                                                                                                                                                                                                                                                                                                                                                         |
-| :-------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`search_pubmed_articles`](./src/mcp-server/tools/searchPubMedArticles/)                | Searches PubMed for articles based on your query. (See [Example](./examples/search_pubmed_articles_example.md))                                                                                              | - Filter by max results, sort order, date range, publication types.<br/>- Uses NCBI ESearch for PMIDs.<br/>- Optionally fetches brief summaries (title, authors, source, dates) via ESummary.                                                                                                                                                                                                        |
-| [`fetch_pubmed_content`](./src/mcp-server/tools/fetchPubMedContent/)                    | Retrieves detailed information for PubMed articles. Can use a list of PMIDs or ESearch history (queryKey/webEnv) with pagination. (See [Example](./examples/fetch_pubmed_content_example.md))                | - Flexible `detailLevel`: `abstract_plus` (parsed details, optional MeSH/grant), `full_xml` (JSON representation of the PubMedArticle XML structure), `medline_text` (MEDLINE format), `citation_data` (minimal for citations).<br/>- Supports direct PMID list or `queryKey`/`webEnv` from ESearch history.<br/>- Supports `retstart`/`retmax` for pagination with history.<br/>- Uses NCBI EFetch. |
-| [`get_pubmed_article_connections`](./src/mcp-server/tools/getPubMedArticleConnections/) | Finds related articles (cited by, similar, references) or formats citations for a PMID. (See [Ex.1](./examples/get_pubmed_article_connections_1.md), [Ex.2](./examples/get_pubmed_article_connections_2.md)) | - Uses NCBI ELink for relationships.<br/>- Uses NCBI EFetch for citation data (RIS, BibTeX, APA, MLA).<br/>- Filter by max related results.                                                                                                                                                                                                                                                          |
-| [`pubmed_research_agent`](./src/mcp-server/tools/pubmedResearchAgent/)                  | Generates a standardized JSON research plan outline from component details. (See [Example](./examples/pubmed_research_agent_example.md))                                                                     | - Accepts granular inputs for all research phases.<br/>- Optionally embeds instructive prompts for agent execution.<br/>- Structures rough ideas into a formal, machine-readable plan for further processing.                                                                                                                                                                                        |
-| [`generate_pubmed_chart`](./src/mcp-server/tools/generatePubMedChart/)                  | Generates a chart image (PNG) from given input data. (See [Examples](./examples/generate_pubmed_chart))                                                                                                      | - Supports a wide range of chart types: `bar`, `line`, `scatter`, `pie`, `doughnut`, `bubble`, `radar`, and `polarArea`.<br/>- Takes data values and field specifications for axes and series.<br/>- Uses `Chart.js` and `chartjs-node-canvas` for direct server-side rendering.                                                                                                                     |
+| Tool Name                                                                               | Description                                                                             | Example                                                                                                          |
+| :-------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |
+| [`search_pubmed_articles`](./src/mcp-server/tools/searchPubMedArticles/)                | Searches PubMed for articles based on your query.                                       | [View Example](./examples/search_pubmed_articles_example.md)                                                     |
+| [`fetch_pubmed_content`](./src/mcp-server/tools/fetchPubMedContent/)                    | Retrieves detailed information for PubMed articles.                                     | [View Example](./examples/fetch_pubmed_content_example.md)                                                       |
+| [`get_pubmed_article_connections`](./src/mcp-server/tools/getPubMedArticleConnections/) | Finds related articles (cited by, similar, references) or formats citations for a PMID. | [Ex. 1](./examples/get_pubmed_article_connections_1.md), [Ex. 2](./examples/get_pubmed_article_connections_2.md) |
+| [`pubmed_research_agent`](./src/mcp-server/tools/pubmedResearchAgent/)                  | Generates a standardized JSON research plan outline from component details.             | [View Example](./examples/pubmed_research_agent_example.md)                                                      |
+| [`generate_pubmed_chart`](./src/mcp-server/tools/generatePubMedChart/)                  | Generates a chart image (PNG) from given input data.                                    | [View Examples](./examples/generate_pubmed_chart/)                                                               |
 
 ---
 
 ## Table of Contents
 
-| [Overview](#overview) | [Features](#features) | [Installation](#installation) |
-
-| [Configuration](#configuration) | [Project Structure](#project-structure) |
-
-| [Tools](#tools) | [Resources](#resources) | [Development](#development) | [License](#license) |
+| [Overview](#overview)           | [Features](#features)                          | [Installation](#installation) |
+| :------------------------------ | :--------------------------------------------- | :---------------------------- |
+| [Configuration](#configuration) | [Project Structure](#project-structure)        |
+| [Tools](#tools)                 | [Development & Testing](#development--testing) | [License](#license)           |
 
 ## Overview
 
@@ -58,11 +61,11 @@ Leverages the robust utilities provided by the `mcp-ts-template`:
 
 - **Logging**: Structured, configurable logging (file rotation, stdout JSON, MCP notifications) with sensitive data redaction.
 - **Error Handling**: Centralized error processing, standardized error types (`McpError`), and automatic logging.
-- **Configuration**: Environment variable loading (`dotenv`) with comprehensive validation.
+- **Configuration**: Environment variable loading (`dotenv`) with comprehensive validation using Zod.
 - **Input Validation/Sanitization**: Uses `zod` for schema validation and custom sanitization logic.
 - **Request Context**: Tracking and correlation of operations via unique request IDs using `AsyncLocalStorage`.
 - **Type Safety**: Strong typing enforced by TypeScript and Zod schemas.
-- **HTTP Transport**: High-performance HTTP server using **Hono**, featuring session management with garbage collection and CORS support.
+- **HTTP Transport**: High-performance HTTP server using **Hono**, featuring session management and authentication support.
 - **Authentication**: Robust authentication layer supporting JWT and OAuth 2.1, with fine-grained scope enforcement.
 - **Deployment**: Multi-stage `Dockerfile` for creating small, secure production images with native dependency support.
 
@@ -83,56 +86,8 @@ Leverages the robust utilities provided by the `mcp-ts-template`:
 
 - [Node.js (>=18.0.0)](https://nodejs.org/)
 - [npm](https://www.npmjs.com/) (comes with Node.js)
-- [Docker](https://www.docker.com/) (optional, for containerized deployment)
 - **NCBI API Key** (recommended for higher rate limits) - [Get one here](https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/)
 
-### Install via npm (recommended)
-
-```bash
-npm install @cyanheads/pubmed-mcp-server
-```
-
-### Alternatively Install from Source
-
-1. Clone the repository:
-
-   ```bash
-   git clone https://github.com/cyanheads/pubmed-mcp-server.git
-   cd pubmed-mcp-server
-   ```
-
-2. Install dependencies:
-
-   ```bash
-   npm install
-   ```
-
-3. Build the project:
-   ```bash
-   npm run build
-   *or npm run rebuild*
-   ```
-
-## Configuration
-
-### Environment Variables
-
-Configure the server using environment variables. These environmental variables are set within your MCP client config/settings (e.g. `claude_desktop_config.json` for Claude Desktop)
-
-| Variable               | Description                                                                              | Default                        |
-| ---------------------- | ---------------------------------------------------------------------------------------- | ------------------------------ |
-| `MCP_TRANSPORT_TYPE`   | Transport mechanism: `stdio` or `http`.                                                  | `stdio`                        |
-| `MCP_HTTP_PORT`        | Port for the HTTP server (if `MCP_TRANSPORT_TYPE=http`).                                 | `3010`                         |
-| `MCP_HTTP_HOST`        | Host address for the HTTP server (if `MCP_TRANSPORT_TYPE=http`).                         | `127.0.0.1`                    |
-| `MCP_ALLOWED_ORIGINS`  | Comma-separated list of allowed origins for CORS (if `MCP_TRANSPORT_TYPE=http`).         | (none)                         |
-| `MCP_LOG_LEVEL`        | Logging level (`debug`, `info`, `notice`, `warning`, `error`, `crit`, `alert`, `emerg`). | `debug`                        |
-| `LOG_OUTPUT_MODE`      | Logging output mode: `file` or `stdout`.                                                 | `file`                         |
-| `MCP_AUTH_MODE`        | Authentication mode for HTTP: `jwt` or `oauth`.                                          | `jwt`                          |
-| `MCP_AUTH_SECRET_KEY`  | **Required for `jwt` auth.** Minimum 32-character secret key for JWT authentication.     | (none)                         |
-| `NCBI_API_KEY`         | **Recommended.** Your NCBI API Key for higher rate limits and reliable access.           | (none)                         |
-| `NCBI_TOOL_IDENTIFIER` | Tool identifier for NCBI E-utility requests.                                             | `@cyanheads/pubmed-mcp-server` |
-| `LOGS_DIR`             | Directory for log file storage (if `LOG_OUTPUT_MODE=file`).                              | `logs/`                        |
-
 ### MCP Client Settings
 
 Add the following to your MCP client's configuration file (e.g., `cline_mcp_settings.json`). This configuration uses `npx` to run the server, which will automatically install the package if not already present:
@@ -145,14 +100,55 @@ Add the following to your MCP client's configuration file (e.g., `cline_mcp_sett
       "args": ["@cyanheads/pubmed-mcp-server"],
       "env": {
         "NCBI_API_KEY": "your_ncbi_api_key_here"
-      },
-      "disabled": false,
-      "autoApprove": []
+      }
     }
   }
 }
 ```
 
+### If running manually (not via MCP client for development or testing)
+
+#### Install via npm
+
+```bash
+npm install @cyanheads/pubmed-mcp-server
+```
+
+#### Alternatively Install from Source
+
+1.  Clone the repository:
+    ```bash
+    git clone https://github.com/cyanheads/pubmed-mcp-server.git
+    cd pubmed-mcp-server
+    ```
+2.  Install dependencies:
+    ```bash
+    npm install
+    ```
+3.  Build the project:
+    ```bash
+    npm run build
+    ```
+
+## Configuration
+
+### Environment Variables
+
+Configure the server using environment variables. For local development, these can be set in a `.env` file at the project root or directly in your environment. Otherwise, you can set them in your MCP client configuration as shown above.
+
+| Variable              | Description                                                                              | Default       |
+| :-------------------- | :--------------------------------------------------------------------------------------- | :------------ |
+| `MCP_TRANSPORT_TYPE`  | Transport mechanism: `stdio` or `http`.                                                  | `stdio`       |
+| `MCP_HTTP_PORT`       | Port for the HTTP server (if `MCP_TRANSPORT_TYPE=http`).                                 | `3010`        |
+| `MCP_HTTP_HOST`       | Host address for the HTTP server (if `MCP_TRANSPORT_TYPE=http`).                         | `127.0.0.1`   |
+| `MCP_ALLOWED_ORIGINS` | Comma-separated list of allowed origins for CORS (if `MCP_TRANSPORT_TYPE=http`).         | (none)        |
+| `MCP_LOG_LEVEL`       | Logging level (`debug`, `info`, `notice`, `warning`, `error`, `crit`, `alert`, `emerg`). | `debug`       |
+| `MCP_AUTH_MODE`       | Authentication mode for HTTP: `jwt` or `oauth`.                                          | `jwt`         |
+| `MCP_AUTH_SECRET_KEY` | **Required for `jwt` auth.** Minimum 32-character secret key for JWT authentication.     | (none)        |
+| `NCBI_API_KEY`        | **Recommended.** Your NCBI API Key for higher rate limits and reliable access.           | (none)        |
+| `LOGS_DIR`            | Directory for log file storage.                                                          | `logs/`       |
+| `NODE_ENV`            | Runtime environment (`development`, `production`).                                       | `development` |
+
 ## Project Structure
 
 The codebase follows a modular structure within the `src/` directory:
@@ -165,7 +161,6 @@ src/
 ├── mcp-server/           # Core MCP server logic and capability registration
 │   ├── server.ts         # Server setup, capability registration
 │   ├── transports/       # Transport handling (stdio, http)
-│   ├── resources/        # MCP Resource implementations
 │   └── tools/            # MCP Tool implementations (subdirs per tool)
 ├── services/             # External service integrations
 │   └── NCBI/             # NCBI E-utilities API client and parsing
@@ -191,40 +186,38 @@ _Note: All tools support comprehensive error handling and return structured JSON
 
 ## Examples
 
-Comprehensive usage examples are available in the [`examples/`](examples/) directory:
+Comprehensive usage examples for each tool are available in the [`examples/`](examples/) directory.
 
-- [Search PubMed Articles](examples/search_pubmed_articles_example.md)
-- [Fetch Article Content](examples/fetch_pubmed_content_example.md)
-- [Article Connections](examples/get_pubmed_article_connections_1.md)
-- [Research Planning](examples/pubmed_research_agent_example.md)
-- [Chart Generation](./examples/generate_pubmed_chart/) - Generated chart examples (bar, line, scatter, pie, bubble, radar, polarArea) are available in the `examples/generate_pubmed_chart/` directory.
+- **`search_pubmed_articles`**: [View Example](./examples/search_pubmed_articles_example.md)
+- **`fetch_pubmed_content`**: [View Example](./examples/fetch_pubmed_content_example.md)
+- **`get_pubmed_article_connections`**: [Ex. 1](./examples/get_pubmed_article_connections_1.md), [Ex. 2](./examples/get_pubmed_article_connections_2.md)
+- **`pubmed_research_agent`**: [View Example](./examples/pubmed_research_agent_example.md)
+- **`generate_pubmed_chart`**: [View Examples](./examples/generate_pubmed_chart/)
 
-## Development
+## Development & Testing
 
-### Build and Test
+### Development Scripts
 
 ```bash
 # Build the project (compile TS to JS in dist/ and make executable)
 npm run build
 
-# Test the server locally using the MCP inspector tool (stdio transport)
-npm run inspector
-
-# Test the server locally using the MCP inspector tool (http transport)
-npm run inspector:http
-
 # Clean build artifacts
 npm run clean
 
-# Generate a file tree representation for documentation
-npm run tree
-
 # Clean build artifacts and then rebuild the project
 npm run rebuild
 
 # Format code with Prettier
 npm run format
 
+# Generate a file tree representation for documentation
+npm run tree
+```
+
+### Running the Server
+
+```bash
 # Start the server using stdio (default)
 npm start
 # Or explicitly:
@@ -232,6 +225,12 @@ npm run start:stdio
 
 # Start the server using HTTP transport
 npm run start:http
+
+# Test the server locally using the MCP inspector tool (stdio transport)
+npm run inspector
+
+# Test the server locally using the MCP inspector tool (http transport)
+npm run inspector:http
 ```
 
 ## License

package/dist/config/index.d.ts

@@ -4,78 +4,39 @@
  * environment variables and `package.json`. It uses Zod for schema validation
  * to ensure type safety and correctness of configuration parameters.
  *
- * Key responsibilities:
- * - Load environment variables from a `.env` file.
- * - Read `package.json` for default server name and version.
- * - Define a Zod schema for all expected environment variables.
- * - Validate environment variables against the schema.
- * - Construct and export a comprehensive `config` object.
- * - Export individual configuration values like `logLevel` and `environment` for convenience.
- *
  * @module src/config/index
  */
-/**
- * Main application configuration object.
- * Aggregates settings from validated environment variables and `package.json`.
- */
 export declare const config: {
-    /** MCP server name. Env `MCP_SERVER_NAME` > `package.json` name > "mcp-ts-template". */
+    pkg: {
+        name: string;
+        version: string;
+    };
     mcpServerName: string;
-    /** MCP server version. Env `MCP_SERVER_VERSION` > `package.json` version > "0.0.0". */
     mcpServerVersion: string;
-    /** Logging level. From `MCP_LOG_LEVEL` env var. Default: "debug". */
     logLevel: string;
-    /** Defines the logging output mode ('file' or 'stdout'). From `LOG_OUTPUT_MODE`. */
-    logOutputMode: "file" | "stdout";
-    /** Absolute path to the logs directory (if logOutputMode is 'file'). From `LOGS_DIR`. */
     logsPath: string | null;
-    /** Runtime environment. From `NODE_ENV` env var. Default: "development". */
     environment: string;
-    /** MCP transport type ('stdio' or 'http'). From `MCP_TRANSPORT_TYPE` env var. Default: "stdio". */
     mcpTransportType: "stdio" | "http";
-    /** HTTP server port (if http transport). From `MCP_HTTP_PORT` env var. Default: 3010. */
+    mcpSessionMode: "stateless" | "stateful" | "auto";
     mcpHttpPort: number;
-    /** HTTP server host (if http transport). From `MCP_HTTP_HOST` env var. Default: "127.0.0.1". */
     mcpHttpHost: string;
-    /** Array of allowed CORS origins (http transport). From `MCP_ALLOWED_ORIGINS` (comma-separated). */
+    mcpHttpEndpointPath: string;
+    mcpHttpMaxPortRetries: number;
+    mcpHttpPortRetryDelayMs: number;
+    mcpStatefulSessionStaleTimeoutMs: number;
     mcpAllowedOrigins: string[] | undefined;
-    /** Auth secret key (JWTs, http transport). From `MCP_AUTH_SECRET_KEY`. CRITICAL. */
+    mcpAuthMode: "jwt" | "oauth" | "none";
     mcpAuthSecretKey: string | undefined;
-    /** Auth mode ('jwt' or 'oauth'). From `MCP_AUTH_MODE`. */
-    mcpAuthMode: "jwt" | "oauth";
-    /** OAuth Issuer URL. From `OAUTH_ISSUER_URL`. */
     oauthIssuerUrl: string | undefined;
-    /** OAuth Audience. From `OAUTH_AUDIENCE`. */
-    oauthAudience: string | undefined;
-    /** OAuth JWKS URI. From `OAUTH_JWKS_URI`. */
     oauthJwksUri: string | undefined;
-    /** NCBI API Key. From `NCBI_API_KEY`. */
+    oauthAudience: string | undefined;
+    devMcpClientId: string | undefined;
+    devMcpScopes: string[] | undefined;
     ncbiApiKey: string | undefined;
-    /** NCBI Tool Identifier. From `NCBI_TOOL_IDENTIFIER`. Defaults to server name/version. */
     ncbiToolIdentifier: string;
-    /** NCBI Admin Email. From `NCBI_ADMIN_EMAIL`. */
     ncbiAdminEmail: string | undefined;
-    /** NCBI Request Delay in MS. From `NCBI_REQUEST_DELAY_MS`. Dynamically set based on API key presence. */
     ncbiRequestDelayMs: number;
-    /** NCBI Max Retries. From `NCBI_MAX_RETRIES`. */
     ncbiMaxRetries: number;
-    /** OAuth Proxy configurations. Undefined if no related env vars are set. */
-    oauthProxy: {
-        authorizationUrl: string | undefined;
-        tokenUrl: string | undefined;
-        revocationUrl: string | undefined;
-        issuerUrl: string | undefined;
-        serviceDocumentationUrl: string | undefined;
-        defaultClientRedirectUris: string[] | undefined;
-    } | undefined;
 };
-/**
- * Configured logging level for the application.
- * Exported for convenience.
- */
 export declare const logLevel: string;
-/**
- * Configured runtime environment ("development", "production", etc.).
- * Exported for convenience.
- */
 export declare const environment: string;