@cyanheads/pubmed-mcp-server 2.0.1 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +65 -12
  2. package/dist/index.js +1301 -790
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,11 +1,15 @@
1
1
  <div align="center">
2
2
  <h1>pubmed-mcp-server</h1>
3
- <p><b>MCP server for the NCBI E-utilities API. Search PubMed, fetch article metadata, generate citations, explore MeSH terms, and discover related research. Runs over stdio or HTTP. Deployable to Cloudflare Workers.</b></p>
3
+ <p><b>MCP server for the NCBI E-utilities API. Search PubMed, fetch article metadata and full text, generate citations, explore MeSH terms, and discover related research. Runs over stdio or HTTP. Deployable to Cloudflare Workers.</b>
4
+ <div>7 Tools • 1 Resource • 1 Prompt</div>
5
+ </p>
4
6
  </div>
5
7
 
6
8
  <div align="center">
7
9
 
8
- [![npm](https://img.shields.io/npm/v/@cyanheads/pubmed-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/pubmed-mcp-server) [![Version](https://img.shields.io/badge/Version-2.0.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://modelcontextprotocol.io/specification/2025-11-25) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.27.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Status](https://img.shields.io/badge/Status-Stable-brightgreen.svg?style=flat-square)](https://github.com/cyanheads/pubmed-mcp-server/issues) [![TypeScript](https://img.shields.io/badge/TypeScript-^5.9.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
10
+ [![npm](https://img.shields.io/npm/v/@cyanheads/pubmed-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/pubmed-mcp-server) [![Version](https://img.shields.io/badge/Version-2.1.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://modelcontextprotocol.io/specification/2025-11-25)
11
+
12
+ [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.27.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Status](https://img.shields.io/badge/Status-Stable-brightgreen.svg?style=flat-square)](https://github.com/cyanheads/pubmed-mcp-server/issues) [![TypeScript](https://img.shields.io/badge/TypeScript-^5.9.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
9
13
 
10
14
  </div>
11
15
 
@@ -13,12 +17,13 @@
13
17
 
14
18
  ## Tools
15
19
 
16
- Six tools for working with PubMed and NCBI data:
20
+ Seven tools for working with PubMed and NCBI data:
17
21
 
18
22
  | Tool | Description |
19
23
  |:---|:---|
20
24
  | `pubmed_search` | Search PubMed with full query syntax, field-specific filters, date ranges, pagination, and optional brief summaries |
21
25
  | `pubmed_fetch` | Fetch full article metadata by PMIDs — abstract, authors, journal, MeSH terms, grants |
26
+ | `pmc_fetch` | Fetch full-text articles from PubMed Central — body sections, references, and metadata for open-access articles |
22
27
  | `pubmed_cite` | Generate formatted citations in APA 7th, MLA 9th, BibTeX, or RIS |
23
28
  | `pubmed_related` | Find similar articles, citing articles, or references for a given PMID |
24
29
  | `pubmed_spell` | Spell-check biomedical queries using NCBI's ESpell service |
@@ -44,12 +49,27 @@ Search PubMed with full NCBI query syntax and filters.
44
49
  Fetch full article metadata by PubMed IDs.
45
50
 
46
51
  - Batch fetch up to 200 articles at once (auto-switches to POST for large batches)
47
- - Returns structured data: title, abstract, authors with affiliations, journal info, DOI
52
+ - Returns structured data: title, abstract, authors with deduplicated affiliations, journal info, DOI
53
+ - Direct links to PubMed and PubMed Central (when available)
48
54
  - Optional MeSH terms, grant information, and publication types
49
55
  - Handles PubMed's inconsistent XML (structured abstracts, missing fields, varying date formats)
50
56
 
51
57
  ---
52
58
 
59
+ ### `pmc_fetch`
60
+
61
+ Fetch full-text articles from PubMed Central (PMC).
62
+
63
+ - Accepts PMC IDs directly or PubMed IDs (auto-resolved to PMCIDs via ELink)
64
+ - Returns complete article body text organized by sections and subsections
65
+ - Optional reference list from back matter
66
+ - Section filtering by title (case-insensitive match, e.g. `["methods", "results"]`)
67
+ - Configurable max sections to limit response size
68
+ - Up to 10 articles per request
69
+ - Only open-access articles available in PMC will return full text
70
+
71
+ ---
72
+
53
73
  ### `pubmed_cite`
54
74
 
55
75
  Generate formatted citations for articles.
@@ -84,8 +104,8 @@ Spell-check a biomedical query using NCBI's ESpell.
84
104
 
85
105
  Search and explore the MeSH (Medical Subject Headings) vocabulary.
86
106
 
87
- - Search MeSH terms by name
88
- - Optional detailed records with tree numbers, scope notes, and entry terms
107
+ - Search MeSH terms by name with exact-heading matching
108
+ - Detailed records with tree numbers, scope notes, and entry terms by default
89
109
  - Useful for building precise PubMed queries with controlled vocabulary
90
110
 
91
111
  ## Resource and prompt
@@ -135,11 +155,44 @@ Add the following to your MCP client configuration file.
135
155
  }
136
156
  ```
137
157
 
138
- Or for Streamable HTTP:
158
+ Or with npx (no Bun required):
159
+
160
+ ```json
161
+ {
162
+ "mcpServers": {
163
+ "pubmed": {
164
+ "type": "stdio",
165
+ "command": "npx",
166
+ "args": ["-y", "@cyanheads/pubmed-mcp-server@latest"],
167
+ "env": {
168
+ "MCP_TRANSPORT_TYPE": "stdio",
169
+ "MCP_LOG_LEVEL": "info",
170
+ "NCBI_API_KEY": "your-key-here"
171
+ }
172
+ }
173
+ }
174
+ }
175
+ ```
176
+
177
+ Or with Docker:
139
178
 
140
- ```bash
141
- MCP_TRANSPORT_TYPE=http
142
- MCP_HTTP_PORT=3017
179
+ ```json
180
+ {
181
+ "mcpServers": {
182
+ "pubmed": {
183
+ "type": "stdio",
184
+ "command": "docker",
185
+ "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/pubmed-mcp-server:latest"]
186
+ }
187
+ }
188
+ }
189
+ ```
190
+
191
+ For Streamable HTTP, set the transport and start the server:
192
+
193
+ ```sh
194
+ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3017 bun run start:http
195
+ # Server listens at http://localhost:3017/mcp
143
196
  ```
144
197
 
145
198
  ### Prerequisites
@@ -176,7 +229,7 @@ All configuration is centralized and validated at startup in `src/config/index.t
176
229
  | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http` | `stdio` |
177
230
  | `MCP_HTTP_PORT` | HTTP server port | `3017` |
178
231
  | `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth` | `none` |
179
- | `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.) | `debug` |
232
+ | `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.) | `info` |
180
233
  | `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1` | `in-memory` |
181
234
  | `NCBI_API_KEY` | NCBI API key for higher rate limits (10 req/s vs 3 req/s) | none |
182
235
  | `NCBI_ADMIN_EMAIL` | Contact email sent with NCBI requests (recommended by NCBI) | none |
@@ -230,7 +283,7 @@ bun run deploy:dev
230
283
 
231
284
  | Directory | Purpose |
232
285
  |:---|:---|
233
- | `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Six PubMed tools. |
286
+ | `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Seven PubMed tools. |
234
287
  | `src/mcp-server/resources` | Resource definitions. Database info resource. |
235
288
  | `src/mcp-server/prompts` | Prompt definitions. Research plan prompt. |
236
289
  | `src/mcp-server/transports` | HTTP and stdio transports, including auth middleware. |