@cyanheads/biorxiv-mcp-server 0.2.3 → 0.2.5

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 (29) hide show
  1. package/AGENTS.md +56 -18
  2. package/CLAUDE.md +56 -18
  3. package/Dockerfile +9 -4
  4. package/README.md +4 -3
  5. package/changelog/0.2.x/0.2.4.md +17 -0
  6. package/changelog/0.2.x/0.2.5.md +29 -0
  7. package/changelog/template.md +55 -16
  8. package/dist/mcp-server/tools/definitions/biorxiv-search-preprints.tool.d.ts +11 -0
  9. package/dist/mcp-server/tools/definitions/biorxiv-search-preprints.tool.d.ts.map +1 -1
  10. package/dist/mcp-server/tools/definitions/biorxiv-search-preprints.tool.js +29 -3
  11. package/dist/mcp-server/tools/definitions/biorxiv-search-preprints.tool.js.map +1 -1
  12. package/dist/mcp-server/tools/definitions/index.d.ts +6 -0
  13. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  14. package/dist/services/biorxiv/biorxiv-service.d.ts.map +1 -1
  15. package/dist/services/biorxiv/biorxiv-service.js +7 -10
  16. package/dist/services/biorxiv/biorxiv-service.js.map +1 -1
  17. package/dist/services/biorxiv-fulltext/biorxiv-fulltext-service.d.ts.map +1 -1
  18. package/dist/services/biorxiv-fulltext/biorxiv-fulltext-service.js +3 -4
  19. package/dist/services/biorxiv-fulltext/biorxiv-fulltext-service.js.map +1 -1
  20. package/dist/services/europe-pmc/europe-pmc-service.d.ts +4 -0
  21. package/dist/services/europe-pmc/europe-pmc-service.d.ts.map +1 -1
  22. package/dist/services/europe-pmc/europe-pmc-service.js +83 -36
  23. package/dist/services/europe-pmc/europe-pmc-service.js.map +1 -1
  24. package/dist/services/shared.d.ts +6 -13
  25. package/dist/services/shared.d.ts.map +1 -1
  26. package/dist/services/shared.js +6 -13
  27. package/dist/services/shared.js.map +1 -1
  28. package/package.json +7 -7
  29. package/server.json +3 -3
package/AGENTS.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Agent Protocol
2
2
 
3
3
  **Server:** biorxiv-mcp-server
4
- **Version:** 0.2.3
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.11.1`
4
+ **Version:** 0.2.5
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.3`
6
6
  **Engines:** Bun ≥1.3.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/sdk` ^1.30.0
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
8
8
  **Zod:** ^4.4.3
9
9
 
10
10
  > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
@@ -35,7 +35,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
35
35
  - **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
36
36
  - **Use `ctx.log`** for request-scoped logging. No `console` calls.
37
37
  - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
38
- - **Check `ctx.elicit` / `ctx.sample`** for presence before calling.
38
+ - **Need input the caller didn't supply?** `return ctx.requestInput(...)` and read `ctx.inputs` when the handler is re-entered. Never `await` for user input mid-handler.
39
39
  - **Secrets in env vars only** — never hardcoded.
40
40
  - **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed before moving on. The comment is for future readers — state the concrete changes, not the conversation that produced them.
41
41
 
@@ -112,12 +112,16 @@ Handlers receive a unified `ctx` object. Key properties:
112
112
 
113
113
  | Property | Description |
114
114
  |:---------|:------------|
115
- | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
116
- | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
115
+ | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |
116
+ | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
117
+ | `ctx.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present. |
118
+ | `ctx.inputs` | Reader over a retried request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped`. Empty on the first round. |
117
119
  | `ctx.recoveryFor(reason)` | Typed lookup of the contract `recovery` for a declared reason. Returns `{ recovery: { hint } }` for known reasons, `{}` otherwise. Spread into `ctx.fail` data to mirror the contract hint into `content[]`. |
120
+ | `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |
121
+ | `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
118
122
  | `ctx.signal` | `AbortSignal` for cancellation. |
119
123
  | `ctx.requestId` | Unique request ID. |
120
- | `ctx.tenantId` | Tenant ID from JWT, `'default'` for stdio or HTTP+`MCP_AUTH_MODE=none`. |
124
+ | `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
121
125
 
122
126
  ---
123
127
 
@@ -146,6 +150,8 @@ async handler(input, ctx) {
146
150
  }
147
151
  ```
148
152
 
153
+ **Declare contracts inline on each tool.** The contract is part of the tool's public surface — one file should give the full picture. Don't extract a shared `errors[]` constant; per-tool repetition is the intended cost of locality.
154
+
149
155
  **Fallback (no contract entry fits):** error factories or plain `Error`.
150
156
 
151
157
  ```ts
@@ -166,8 +172,9 @@ src/
166
172
  config/
167
173
  server-config.ts # bioRxiv-specific env vars (BIORXIV_MAILTO, API base URLs)
168
174
  services/
169
- shared.ts # Shared utilities (asRc, detectHtmlError, normalizeUpstreamText,
170
- # isValidCalendarDate, parseRetryAfterSeconds, findRateLimit, SERVER_VERSION)
175
+ shared.ts # Shared utilities (detectHtmlError, normalizeUpstreamText,
176
+ # isValidCalendarDate, parseRetryAfterSeconds, findRateLimit, describeWait,
177
+ # SERVER_VERSION)
171
178
  biorxiv/
172
179
  biorxiv-service.ts # BiorxivApiService — details, publications, pubs endpoints
173
180
  types.ts # Domain types (Preprint, PublishedVersion, …)
@@ -213,9 +220,9 @@ src/
213
220
 
214
221
  ## Skills
215
222
 
216
- Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
223
+ Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry.
217
224
 
218
- **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). This makes skills available as context without needing to reference `skills/` paths manually. After framework updates, run the `maintenance` skill — it re-syncs the agent directory automatically (Phase B).
225
+ **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
219
226
 
220
227
  Available skills:
221
228
 
@@ -242,7 +249,7 @@ Available skills:
242
249
  | `api-auth` | Auth modes, scopes, JWT/OAuth |
243
250
  | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
244
251
  | `api-config` | AppConfig, parseConfig, env vars |
245
- | `api-context` | Context interface, logger, state, progress |
252
+ | `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input |
246
253
  | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
247
254
  | `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
248
255
  | `api-mirror` | MirrorService: persistent, self-refreshing local mirror of a bulk upstream dataset (embedded SQLite + FTS5) — Tier 3 opt-in |
@@ -253,6 +260,7 @@ Available skills:
253
260
  | `api-workers` | Cloudflare Workers runtime |
254
261
  | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
255
262
  | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
263
+ | `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
256
264
 
257
265
  **Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
258
266
 
@@ -262,6 +270,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
262
270
 
263
271
  ## Commands
264
272
 
273
+ **Runtime:** Scripts use Bun's native TypeScript execution — `bun run <cmd>` is the standard invocation.
274
+
265
275
  | Command | Purpose |
266
276
  |:--------|:--------|
267
277
  | `bun run build` | Compile TypeScript |
@@ -270,10 +280,11 @@ When you complete a skill's checklist, check the boxes and add a completion time
270
280
  | `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
271
281
  | `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
272
282
  | `bun run tree` | Generate directory structure doc |
273
- | `bun run format` | Auto-fix formatting |
274
- | `bun run test` | Run tests |
275
- | `bun run lint:mcp` | Validate MCP definitions against spec |
276
- | `bun run lint:packaging` | Verify env var alignment between `manifest.json` and `server.json` |
283
+ | `bun run format` | Auto-fix formatting (safe fixes only) |
284
+ | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
285
+ | `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
286
+ | `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
287
+ | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
277
288
  | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
278
289
  | `bun run list-skills` | Surface available local skills for sub-agents |
279
290
  | `bun run start:stdio` | Production mode (stdio) |
@@ -286,12 +297,39 @@ When you complete a skill's checklist, check the boxes and add a completion time
286
297
 
287
298
  ## Bundling
288
299
 
289
- `bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips dependency-shipped agent docs (`node_modules/**` `skills/`, `.claude/`, `.agents/`, `SKILL.md`) that root-anchored `.mcpbignore` patterns cannot reach. MCPB is stdio-only — HTTP deployments are unaffected. Delete `manifest.json` and `.mcpbignore` to opt out; `lint:packaging` skips cleanly.
300
+ `bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. MCPB is stdio-only — HTTP deployments are unaffected. Delete `manifest.json` and `.mcpbignore` to opt out; `lint:packaging` skips cleanly.
290
301
 
291
302
  **Adding an env var requires both files:** `server.json` (`environmentVariables[]`) and `manifest.json` (`mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies alignment.
292
303
 
293
304
  ---
294
305
 
306
+ ## Changelog
307
+
308
+ Directory-based, grouped by minor series via the `.x` semver-wildcard convention. Source of truth: `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.2.x/0.2.5.md`) — one file per release, shipped in the npm package. At release, author the per-version file with a concrete version and date, then run `bun run changelog:build` to regenerate the rollup. `changelog/template.md` is a **pristine format reference** — never edited or moved; read it for the frontmatter + section layout when scaffolding. `CHANGELOG.md` is a **navigation index** (header + link + summary per version), regenerated by `bun run changelog:build` — devcheck hard-fails on drift; never hand-edit it.
309
+
310
+ Each per-version file opens with YAML frontmatter:
311
+
312
+ ```markdown
313
+ ---
314
+ summary: "One-line headline, ≤350 chars" # required — powers the rollup index
315
+ breaking: false # optional — true flags breaking changes
316
+ security: false # optional — true ONLY for a source-code security fix, never a dependency CVE bump
317
+ ---
318
+
319
+ # 0.2.5 — YYYY-MM-DD
320
+ ...
321
+ ```
322
+
323
+ `breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section — set it only for a security fix in this server's *own source code*, never for a routine dependency or transitive CVE bump (record those under `## Dependencies`). When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
324
+
325
+ `agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
326
+
327
+ **Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
328
+
329
+ **Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
330
+
331
+ ---
332
+
295
333
  ## Imports
296
334
 
297
335
  ```ts
@@ -309,7 +347,7 @@ import { getEuropePmcService } from '@/services/europe-pmc/europe-pmc-service.js
309
347
  ## Checklist
310
348
 
311
349
  - [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()`)
312
- - [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`)
350
+ - [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`). When regex/length constraints matter, use `z.union([z.literal(''), z.string().regex(...).describe(...)])` — literal variants are exempt from `describe-on-fields`.
313
351
  - [ ] JSDoc `@fileoverview` + `@module` on every file
314
352
  - [ ] `ctx.log` for logging, `ctx.state` for storage
315
353
  - [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
package/CLAUDE.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Agent Protocol
2
2
 
3
3
  **Server:** biorxiv-mcp-server
4
- **Version:** 0.2.3
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.11.1`
4
+ **Version:** 0.2.5
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.3`
6
6
  **Engines:** Bun ≥1.3.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/sdk` ^1.30.0
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
8
8
  **Zod:** ^4.4.3
9
9
 
10
10
  > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
@@ -35,7 +35,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
35
35
  - **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
36
36
  - **Use `ctx.log`** for request-scoped logging. No `console` calls.
37
37
  - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
38
- - **Check `ctx.elicit` / `ctx.sample`** for presence before calling.
38
+ - **Need input the caller didn't supply?** `return ctx.requestInput(...)` and read `ctx.inputs` when the handler is re-entered. Never `await` for user input mid-handler.
39
39
  - **Secrets in env vars only** — never hardcoded.
40
40
  - **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed before moving on. The comment is for future readers — state the concrete changes, not the conversation that produced them.
41
41
 
@@ -112,12 +112,16 @@ Handlers receive a unified `ctx` object. Key properties:
112
112
 
113
113
  | Property | Description |
114
114
  |:---------|:------------|
115
- | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
116
- | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
115
+ | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |
116
+ | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
117
+ | `ctx.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present. |
118
+ | `ctx.inputs` | Reader over a retried request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped`. Empty on the first round. |
117
119
  | `ctx.recoveryFor(reason)` | Typed lookup of the contract `recovery` for a declared reason. Returns `{ recovery: { hint } }` for known reasons, `{}` otherwise. Spread into `ctx.fail` data to mirror the contract hint into `content[]`. |
120
+ | `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |
121
+ | `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
118
122
  | `ctx.signal` | `AbortSignal` for cancellation. |
119
123
  | `ctx.requestId` | Unique request ID. |
120
- | `ctx.tenantId` | Tenant ID from JWT, `'default'` for stdio or HTTP+`MCP_AUTH_MODE=none`. |
124
+ | `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
121
125
 
122
126
  ---
123
127
 
@@ -146,6 +150,8 @@ async handler(input, ctx) {
146
150
  }
147
151
  ```
148
152
 
153
+ **Declare contracts inline on each tool.** The contract is part of the tool's public surface — one file should give the full picture. Don't extract a shared `errors[]` constant; per-tool repetition is the intended cost of locality.
154
+
149
155
  **Fallback (no contract entry fits):** error factories or plain `Error`.
150
156
 
151
157
  ```ts
@@ -166,8 +172,9 @@ src/
166
172
  config/
167
173
  server-config.ts # bioRxiv-specific env vars (BIORXIV_MAILTO, API base URLs)
168
174
  services/
169
- shared.ts # Shared utilities (asRc, detectHtmlError, normalizeUpstreamText,
170
- # isValidCalendarDate, parseRetryAfterSeconds, findRateLimit, SERVER_VERSION)
175
+ shared.ts # Shared utilities (detectHtmlError, normalizeUpstreamText,
176
+ # isValidCalendarDate, parseRetryAfterSeconds, findRateLimit, describeWait,
177
+ # SERVER_VERSION)
171
178
  biorxiv/
172
179
  biorxiv-service.ts # BiorxivApiService — details, publications, pubs endpoints
173
180
  types.ts # Domain types (Preprint, PublishedVersion, …)
@@ -213,9 +220,9 @@ src/
213
220
 
214
221
  ## Skills
215
222
 
216
- Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
223
+ Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry.
217
224
 
218
- **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). This makes skills available as context without needing to reference `skills/` paths manually. After framework updates, run the `maintenance` skill — it re-syncs the agent directory automatically (Phase B).
225
+ **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
219
226
 
220
227
  Available skills:
221
228
 
@@ -242,7 +249,7 @@ Available skills:
242
249
  | `api-auth` | Auth modes, scopes, JWT/OAuth |
243
250
  | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
244
251
  | `api-config` | AppConfig, parseConfig, env vars |
245
- | `api-context` | Context interface, logger, state, progress |
252
+ | `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input |
246
253
  | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
247
254
  | `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
248
255
  | `api-mirror` | MirrorService: persistent, self-refreshing local mirror of a bulk upstream dataset (embedded SQLite + FTS5) — Tier 3 opt-in |
@@ -253,6 +260,7 @@ Available skills:
253
260
  | `api-workers` | Cloudflare Workers runtime |
254
261
  | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
255
262
  | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
263
+ | `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
256
264
 
257
265
  **Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
258
266
 
@@ -262,6 +270,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
262
270
 
263
271
  ## Commands
264
272
 
273
+ **Runtime:** Scripts use Bun's native TypeScript execution — `bun run <cmd>` is the standard invocation.
274
+
265
275
  | Command | Purpose |
266
276
  |:--------|:--------|
267
277
  | `bun run build` | Compile TypeScript |
@@ -270,10 +280,11 @@ When you complete a skill's checklist, check the boxes and add a completion time
270
280
  | `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
271
281
  | `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
272
282
  | `bun run tree` | Generate directory structure doc |
273
- | `bun run format` | Auto-fix formatting |
274
- | `bun run test` | Run tests |
275
- | `bun run lint:mcp` | Validate MCP definitions against spec |
276
- | `bun run lint:packaging` | Verify env var alignment between `manifest.json` and `server.json` |
283
+ | `bun run format` | Auto-fix formatting (safe fixes only) |
284
+ | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
285
+ | `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
286
+ | `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
287
+ | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
277
288
  | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
278
289
  | `bun run list-skills` | Surface available local skills for sub-agents |
279
290
  | `bun run start:stdio` | Production mode (stdio) |
@@ -286,12 +297,39 @@ When you complete a skill's checklist, check the boxes and add a completion time
286
297
 
287
298
  ## Bundling
288
299
 
289
- `bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips dependency-shipped agent docs (`node_modules/**` `skills/`, `.claude/`, `.agents/`, `SKILL.md`) that root-anchored `.mcpbignore` patterns cannot reach. MCPB is stdio-only — HTTP deployments are unaffected. Delete `manifest.json` and `.mcpbignore` to opt out; `lint:packaging` skips cleanly.
300
+ `bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. MCPB is stdio-only — HTTP deployments are unaffected. Delete `manifest.json` and `.mcpbignore` to opt out; `lint:packaging` skips cleanly.
290
301
 
291
302
  **Adding an env var requires both files:** `server.json` (`environmentVariables[]`) and `manifest.json` (`mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies alignment.
292
303
 
293
304
  ---
294
305
 
306
+ ## Changelog
307
+
308
+ Directory-based, grouped by minor series via the `.x` semver-wildcard convention. Source of truth: `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.2.x/0.2.5.md`) — one file per release, shipped in the npm package. At release, author the per-version file with a concrete version and date, then run `bun run changelog:build` to regenerate the rollup. `changelog/template.md` is a **pristine format reference** — never edited or moved; read it for the frontmatter + section layout when scaffolding. `CHANGELOG.md` is a **navigation index** (header + link + summary per version), regenerated by `bun run changelog:build` — devcheck hard-fails on drift; never hand-edit it.
309
+
310
+ Each per-version file opens with YAML frontmatter:
311
+
312
+ ```markdown
313
+ ---
314
+ summary: "One-line headline, ≤350 chars" # required — powers the rollup index
315
+ breaking: false # optional — true flags breaking changes
316
+ security: false # optional — true ONLY for a source-code security fix, never a dependency CVE bump
317
+ ---
318
+
319
+ # 0.2.5 — YYYY-MM-DD
320
+ ...
321
+ ```
322
+
323
+ `breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section — set it only for a security fix in this server's *own source code*, never for a routine dependency or transitive CVE bump (record those under `## Dependencies`). When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
324
+
325
+ `agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
326
+
327
+ **Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
328
+
329
+ **Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
330
+
331
+ ---
332
+
295
333
  ## Imports
296
334
 
297
335
  ```ts
@@ -309,7 +347,7 @@ import { getEuropePmcService } from '@/services/europe-pmc/europe-pmc-service.js
309
347
  ## Checklist
310
348
 
311
349
  - [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()`)
312
- - [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`)
350
+ - [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`). When regex/length constraints matter, use `z.union([z.literal(''), z.string().regex(...).describe(...)])` — literal variants are exempt from `describe-on-fields`.
313
351
  - [ ] JSDoc `@fileoverview` + `@module` on every file
314
352
  - [ ] `ctx.log` for logging, `ctx.state` for storage
315
353
  - [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
package/Dockerfile CHANGED
@@ -4,7 +4,7 @@
4
4
  # This stage installs all dependencies (including dev), builds the TypeScript
5
5
  # source code into JavaScript, and prepares the production assets.
6
6
  # ==============================================================================
7
- FROM oven/bun:1.3.14 AS build
7
+ FROM oven/bun:1.4.0 AS build
8
8
 
9
9
  WORKDIR /usr/src/app
10
10
 
@@ -30,7 +30,7 @@ RUN bun run build
30
30
  # application. It uses a slim base image and only includes production
31
31
  # dependencies and build artifacts.
32
32
  # ==============================================================================
33
- FROM oven/bun:1.3.14-slim AS production
33
+ FROM oven/bun:1.4.0-slim AS production
34
34
 
35
35
  WORKDIR /usr/src/app
36
36
 
@@ -51,8 +51,13 @@ COPY package.json bun.lock ./
51
51
 
52
52
  # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
53
53
  # that are not needed in the final production image.
54
+ # `--omit=peer` drops the framework's optional peer tiers (test runner, service
55
+ # SDKs, parsers) that Bun would otherwise auto-install. Anything this server
56
+ # actually imports belongs in its own `dependencies`, so nothing needed at
57
+ # runtime is lost. The OTEL step below carries the same flag — without it, that
58
+ # install re-resolves the graph and pulls every optional peer back in.
54
59
  RUN --mount=type=cache,target=/root/.bun/install/cache \
55
- bun install --production --frozen-lockfile --ignore-scripts
60
+ bun install --production --omit=peer --frozen-lockfile --ignore-scripts
56
61
 
57
62
  # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
58
63
  # These are not bundled by default to keep the base image lean. Enable at build time
@@ -60,7 +65,7 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
60
65
  ARG OTEL_ENABLED=true
61
66
  RUN --mount=type=cache,target=/root/.bun/install/cache \
62
67
  if [ "$OTEL_ENABLED" = "true" ]; then \
63
- bun add --omit=dev --ignore-scripts @hono/otel \
68
+ bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
64
69
  @opentelemetry/instrumentation-http \
65
70
  @opentelemetry/exporter-metrics-otlp-http \
66
71
  @opentelemetry/exporter-trace-otlp-http \
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
 
8
8
  <div align="center">
9
9
 
10
- [![Version](https://img.shields.io/badge/Version-0.2.3-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/biorxiv-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.30.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/biorxiv-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/biorxiv-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-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
+ [![Version](https://img.shields.io/badge/Version-0.2.5-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/biorxiv-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/biorxiv-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/biorxiv-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
11
11
 
12
12
  </div>
13
13
 
@@ -71,6 +71,7 @@ Keyword and/or author search with relevance ranking.
71
71
  - Optional date range filters (`date_from`, `date_to`)
72
72
  - Enriched results carry the same latest-revision fields `biorxiv_get_preprint` returns — including `type`, `license`, `funder`, and `authorCorrespondingInstitution`
73
73
  - Enrichment failures degrade gracefully to EuropePMC-only metadata, surfaced via `partial_results` and a per-record `enrichment_error` (`service_error`, `rate_limited`, or `not_found`)
74
+ - A EuropePMC rate limit (HTTP 429) raises a retryable `rate_limited` error carrying the origin's `Retry-After` wait — the search is the primary call and has no metadata to fall back on, unlike the enrichment step
74
75
 
75
76
  ---
76
77
 
@@ -120,7 +121,7 @@ Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp
120
121
  bioRxiv-specific:
121
122
 
122
123
  - `BiorxivApiService` wraps `api.biorxiv.org` — details, publications, and crosswalk endpoints with retry and exponential backoff. An origin rate limit (HTTP 429) is classified as a retryable `rate_limited` error carrying the parsed `Retry-After` wait; the upstream response body never reaches the error payload
123
- - `EuropePmcService` wraps the EuropePMC search endpoint for relevance-ranked keyword and/or author results
124
+ - `EuropePmcService` wraps the EuropePMC search endpoint for relevance-ranked keyword and/or author results. An origin rate limit (HTTP 429) is classified the same way as the JSON API's — a retryable `rate_limited` error carrying the parsed `Retry-After` wait, with the upstream response body kept out of the error payload
124
125
  - `BiorxivFullTextService` fetches and extracts Markdown from the rendered HTML article pages on `www.biorxiv.org` / `www.medrxiv.org` — a distinct origin from the JSON API
125
126
  - Two-server fan-out via `Promise.allSettled` — both `biorxiv` and `medrxiv` queried in parallel when `server="both"`, results merged and deduplicated by DOI
126
127
  - Polite `User-Agent` header including a mailto address (`BIORXIV_MAILTO` env var) per Cold Spring Harbor Lab API guidelines
@@ -189,7 +190,7 @@ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 BIORXIV_MAILTO=your@email.com bun run
189
190
 
190
191
  ### Prerequisites
191
192
 
192
- - [Bun v1.3.2](https://bun.sh/) or higher (or Node.js v24+).
193
+ - [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).
193
194
 
194
195
  ### Installation
195
196
 
@@ -0,0 +1,17 @@
1
+ ---
2
+ summary: "EuropePmcService classifies HTTP 429 as a retryable rate_limited error instead of surfacing it as search_unavailable with the wait dropped (#42)"
3
+ breaking: false
4
+ security: false
5
+ ---
6
+
7
+ # 0.2.4 — 2026-08-09
8
+
9
+ ## Changed
10
+
11
+ - **`EuropePmcService.search`** — HTTP 429 from EuropePMC is now classified as a retryable `rate_limited` error carrying the parsed `Retry-After` wait, mirroring `BiorxivApiService`: `expectedStatuses: [429]` on the fetch, classification outside `withRetry`, and a payload rebuilt from scratch so the upstream response body never reaches the caller. [#42](https://github.com/cyanheads/biorxiv-mcp-server/issues/42)
12
+ - **`biorxiv_search_preprints`** — gained a `rate_limited` error-contract entry for the EuropePMC search path; its recovery hint names the wait and states the scope of the limit rather than promising `biorxiv_list_recent` will answer, since the search runs first and establishes nothing about `api.biorxiv.org`. The enrichment path is unchanged and still degrades to EuropePMC-only metadata on a 429. [#42](https://github.com/cyanheads/biorxiv-mcp-server/issues/42)
13
+
14
+ ## Fixed
15
+
16
+ - **`docs/design.md`** — error-contract table corrected three rows citing `InvalidParams` where the source throws `ValidationError`, added two missing rows, removed a resilience-table row contradicting the one beneath it, and corrected an overclaim that every origin sends `Retry-After`.
17
+ - **`EuropePmcService` test suite** — two HTML-error-page tests asserted only `.rejects.toThrow()` over a mock shape the real service never produces; they now assert the classified error code, so removing the HTML-error guard fails the tests instead of passing.
@@ -0,0 +1,29 @@
1
+ ---
2
+ summary: "Adopts @cyanheads/mcp-ts-core 0.12.3 (MCP SDK v2): HTTP now serves protocol revision 2026-07-28, tool inputs reject undeclared keys, and a source run defaults MCP_SESSION_MODE to stateless"
3
+ breaking: false
4
+ security: false
5
+ ---
6
+
7
+ # 0.2.5 — 2026-08-25
8
+
9
+ ## Added
10
+
11
+ - **`.github/CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`** — community-health files, alongside the existing `SECURITY.md` and issue forms.
12
+
13
+ ## Changed
14
+
15
+ - **`@cyanheads/mcp-ts-core`** `^0.11.1` → `^0.12.3` — adopts the SDK v2 migration (`@modelcontextprotocol/server` `^2.0.0`, was `@modelcontextprotocol/sdk` `^1.30.0`). The HTTP endpoint now serves protocol revision 2026-07-28 alongside the 2025-era revisions it already served.
16
+ - **Tool inputs are strict** — a key not declared on a tool's input schema is now rejected by name instead of silently ignored, and every `inputSchema` advertises `additionalProperties: false`. None of this server's 6 tools declare `.passthrough()`/`.catchall()`, so the change applies unmodified across the surface.
17
+ - **`.env.example`** — `MCP_SESSION_MODE` is now set to `stateless` rather than left commented at the old `stateful` default, so copying the example into `.env` for a source run now serves stateless sessions unless overridden. New commented options documented for HTTP resumability, GC-pressure relief, and log rate limiting.
18
+ - **`.github/SECURITY.md`** — vulnerability-report contact moved to `security@caseyjhand.com`.
19
+ - **`Dockerfile`** — the production `bun install` and the OTEL `bun add` now pass `--omit=peer`, dropping the framework's optional peer tiers (test runner, service SDKs, parsers) from the runtime image.
20
+
21
+ ## Dependencies
22
+
23
+ - **`@cyanheads/mcp-ts-core`** `^0.11.1` → `^0.12.3`
24
+ - **`bun`** (`packageManager`, `Dockerfile` pins) `1.3.14` → `1.4.0`
25
+ - **`@biomejs/biome`** `2.5.7` → `2.5.10`
26
+ - **`@types/node`** `26.1.2` → `26.2.0`
27
+ - **`tsc-alias`** `^1.9.1` → `^1.9.2`
28
+ - **`vitest`** `^4.1.10` → `^4.1.11`
29
+ - **`nanoid`** (transitive, via `postcss`) `3.3.17` → `3.3.18` — clears [GHSA-2v37-7h3g-55p8](https://github.com/advisories/GHSA-2v37-7h3g-55p8) (high: indefinite loop on a zero `size`), reached through `depcheck` and `vitest`'s dev-only dependency graph.
@@ -4,10 +4,11 @@
4
4
  # to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
5
5
  # with a concrete date.
6
6
 
7
- # Required. One-line GitHub Release-style headline. 350 character cap.
8
- # Default short and scannable. Don't pad, don't stitch unrelated changes with
9
- # semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
10
- # inside the value as a key separator and fails GitHub's strict parser.
7
+ # Required. One-line GitHub Release-style headline. 350 character cap — a
8
+ # ceiling, not a target. Default short and scannable. Don't pad, don't stitch
9
+ # unrelated changes with commas/semicolons into an inventory — pick the
10
+ # headline, like a tag's theme line. Quotes required: unquoted YAML treats
11
+ # `: ` inside the value as a key separator and fails GitHub's strict parser.
11
12
  summary: ""
12
13
 
13
14
  # Set `true` when consumers must change code to upgrade: API removals,
@@ -24,9 +25,10 @@ security: false
24
25
 
25
26
  # Optional free-form notes for maintenance agents processing this release.
26
27
  # Not rendered in CHANGELOG — consumed by agents running `maintenance` on
27
- # downstream servers. Use for adoption instructions that don't fit the
28
- # human-facing sections: new files to create, fields to populate, one-time
29
- # migration steps. Omit the field entirely when there's nothing to say.
28
+ # downstream servers. ADOPTION STEPS ONLY — new files to create, fields to
29
+ # populate, one-time migration steps. Never a second rendering of the body:
30
+ # if a body bullet already says it, name the bullet's symbol instead of
31
+ # re-explaining. Omit the field entirely when there's nothing to say.
30
32
  # agent-notes: |
31
33
  # <instructions for downstream maintenance agents>
32
34
  ---
@@ -41,17 +43,54 @@ security: false
41
43
  each bullet with the symbol or concept name in **bold** so they can skip
42
44
  what's irrelevant and zoom in on what's not.
43
45
 
44
- Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
45
- name the symbol, state what changed, stop. Use a second sentence only when
46
- it carries weight. If a bullet feels long, it is.
47
-
48
- Cut: mechanism walkthroughs (those belong in JSDoc, CLAUDE.md/AGENTS.md, or the
49
- relevant skill), ceremonial framings ("This release introduces…",
50
- backwards-compat paragraphs), file-by-file test enumerations, internal
51
- implementation notes. Prefer code/symbol names over English re-explanations.
46
+ Tone: terse, fact-dense, not verbose. Bullet shape: **symbol** + what
47
+ changed + at most one consumer-facing caveat. One sentence by default, two
48
+ when the second carries weight — a bullet past ~40 words or three sentences
49
+ is wrong. The depth lives one hop away: the linked issue carries the why,
50
+ the commit diff carries the how. The changelog names what changed and what
51
+ a consumer does about it; a reader who wants mechanism opens the link.
52
+
53
+ Model length on THIS guide, never on the previous entry — entries modeled
54
+ on entries compound.
55
+
56
+ Cut (each has shipped as a wall of text; these are the cruft):
57
+ - History/justification narration — how the bug worked, why the old
58
+ behavior was wrong. One short clause at most; the issue carries the story.
59
+ - Design-rationale defense — "chosen over Y because…", "guarding the
60
+ getter is not enough…". That is the author arguing with a reviewer;
61
+ reviewers read the PR, not the changelog.
62
+ - Defensive unchanged-clauses — "X is unchanged", "byte-identical to
63
+ <prev>". Keep one only where its absence would cause a real misread,
64
+ as a short parenthetical.
65
+ - Edge-case inventories — marker lists, not-flagged lists, escape tables.
66
+ Tests and the issue carry those.
67
+ - Mechanism walkthroughs (JSDoc, CLAUDE.md/AGENTS.md, or the relevant
68
+ skill own those), ceremonial framings ("This release introduces…"),
69
+ backwards-compat paragraphs, file-by-file test enumerations. Prefer
70
+ code/symbol names over English re-explanations.
71
+
72
+ Verified ≠ included: the every-claim-verified-from-the-diff rule bounds
73
+ the TRUTH of what you write, never the AMOUNT.
74
+
75
+ Example — same fact, right size:
76
+
77
+ TOO LONG: **`fetchWithTimeout`'s `timeoutMs` bounds the whole exchange**
78
+ (#341). `fetch` resolves once headers arrive and the deadline was
79
+ cleared as the helper returned, so a peer that answered promptly and
80
+ then stalled the stream held the request open indefinitely. A 2xx
81
+ carrying a body now comes back as a passthrough wrapper that disarms
82
+ the deadline when the body closes, errors, or is cancelled; …
83
+ [+90 more words of mechanism and edge cases]
84
+
85
+ RIGHT: **`fetchWithTimeout`'s `timeoutMs` now bounds the whole
86
+ exchange, not just the headers** (#341). A stalled body aborts with
87
+ the same `Timeout` error; the returned `Response` is a wrapper, so
88
+ identity assertions (`toBe(response)`) no longer hold.
52
89
 
53
90
  Narrative intro: skip by default. Add one short sentence only when the
54
- release theme genuinely needs framing the bullets can't carry.
91
+ release theme genuinely needs framing the bullets can't carry. When many
92
+ bullets share one upgrade consequence, state it ONCE — intro line or
93
+ agent-notes — never per bullet.
55
94
 
56
95
  Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
57
96
  Fixed, Security. Include only sections with entries; delete the rest
@@ -12,6 +12,11 @@
12
12
  * failing the search, including an origin rate limit (HTTP 429) — which gets
13
13
  * its own enrichment_error value so a caller can tell a wait-and-retry from a
14
14
  * generic upstream error without parsing prose.
15
+ *
16
+ * The two paths are separate: enrichment degrades because EuropePMC metadata
17
+ * is still there to fall back on, while the EuropePMC search itself is this
18
+ * tool's primary call and has nothing to degrade to, so a 429 there raises a
19
+ * retryable `rate_limited` error carrying the origin's Retry-After wait.
15
20
  * @module mcp-server/tools/definitions/biorxiv-search-preprints.tool
16
21
  */
17
22
  import { z } from '@cyanheads/mcp-ts-core';
@@ -64,6 +69,12 @@ export declare const biorxivSearchPreprintsTool: import("@cyanheads/mcp-ts-core"
64
69
  readonly code: JsonRpcErrorCode.ServiceUnavailable;
65
70
  readonly when: "EuropePMC search endpoint is unreachable or returns a server error.";
66
71
  readonly recovery: "EuropePMC may be temporarily unavailable. Retry after a short delay or use biorxiv_list_recent with a date range instead.";
72
+ }, {
73
+ readonly reason: "rate_limited";
74
+ readonly code: JsonRpcErrorCode.RateLimited;
75
+ readonly retryable: true;
76
+ readonly when: "The EuropePMC search endpoint rejected the keyword search with HTTP 429. Distinct from a rate-limited enrichment call, which degrades to EuropePMC-only metadata instead of failing.";
77
+ readonly recovery: "Wait the retryAfter seconds before searching again. biorxiv_list_recent queries api.biorxiv.org, which this limit does not cover, so try a date-range listing meanwhile.";
67
78
  }], {
68
79
  readonly totalCount: z.ZodNumber;
69
80
  readonly nextCursorMark: z.ZodOptional<z.ZodString>;
@@ -1 +1 @@
1
- {"version":3,"file":"biorxiv-search-preprints.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/biorxiv-search-preprints.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA2EjE,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsZrC,CAAC"}
1
+ {"version":3,"file":"biorxiv-search-preprints.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/biorxiv-search-preprints.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA2EjE,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAibrC,CAAC"}