@cyanheads/biorxiv-mcp-server 0.2.6 → 0.2.8
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.
- package/AGENTS.md +51 -24
- package/CLAUDE.md +51 -24
- package/Dockerfile +9 -7
- package/README.md +76 -60
- package/changelog/0.2.x/0.2.7.md +35 -0
- package/changelog/0.2.x/0.2.8.md +26 -0
- package/changelog/template.md +9 -26
- package/dist/config/server-config.d.ts +8 -6
- package/dist/config/server-config.d.ts.map +1 -1
- package/dist/config/server-config.js +10 -12
- package/dist/config/server-config.js.map +1 -1
- package/dist/index.d.ts +3 -3
- package/dist/index.js +6 -7
- package/dist/index.js.map +1 -1
- package/dist/mcp-server/tools/definitions/biorxiv-get-fulltext.tool.d.ts +18 -5
- package/dist/mcp-server/tools/definitions/biorxiv-get-fulltext.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/biorxiv-get-fulltext.tool.js +87 -33
- package/dist/mcp-server/tools/definitions/biorxiv-get-fulltext.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/biorxiv-get-preprint.tool.d.ts +4 -2
- package/dist/mcp-server/tools/definitions/biorxiv-get-preprint.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/biorxiv-get-preprint.tool.js +19 -12
- package/dist/mcp-server/tools/definitions/biorxiv-get-preprint.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/biorxiv-get-published-version.tool.d.ts +19 -9
- package/dist/mcp-server/tools/definitions/biorxiv-get-published-version.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/biorxiv-get-published-version.tool.js +125 -40
- package/dist/mcp-server/tools/definitions/biorxiv-get-published-version.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/biorxiv-list-categories.tool.js +1 -1
- package/dist/mcp-server/tools/definitions/biorxiv-list-categories.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/biorxiv-list-recent.tool.d.ts +5 -2
- package/dist/mcp-server/tools/definitions/biorxiv-list-recent.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/biorxiv-list-recent.tool.js +76 -47
- package/dist/mcp-server/tools/definitions/biorxiv-list-recent.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/biorxiv-search-preprints.tool.d.ts +12 -1
- package/dist/mcp-server/tools/definitions/biorxiv-search-preprints.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/biorxiv-search-preprints.tool.js +33 -6
- package/dist/mcp-server/tools/definitions/biorxiv-search-preprints.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +30 -11
- package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
- package/dist/services/biorxiv/biorxiv-service.d.ts +27 -4
- package/dist/services/biorxiv/biorxiv-service.d.ts.map +1 -1
- package/dist/services/biorxiv/biorxiv-service.js +105 -47
- package/dist/services/biorxiv/biorxiv-service.js.map +1 -1
- package/dist/services/biorxiv/types.d.ts +5 -0
- package/dist/services/biorxiv/types.d.ts.map +1 -1
- package/dist/services/biorxiv-fulltext/biorxiv-fulltext-service.d.ts +6 -3
- package/dist/services/biorxiv-fulltext/biorxiv-fulltext-service.d.ts.map +1 -1
- package/dist/services/biorxiv-fulltext/biorxiv-fulltext-service.js +6 -7
- package/dist/services/biorxiv-fulltext/biorxiv-fulltext-service.js.map +1 -1
- package/dist/services/europe-pmc/europe-pmc-service.d.ts +7 -3
- package/dist/services/europe-pmc/europe-pmc-service.d.ts.map +1 -1
- package/dist/services/europe-pmc/europe-pmc-service.js +55 -13
- package/dist/services/europe-pmc/europe-pmc-service.js.map +1 -1
- package/dist/services/shared.d.ts +23 -1
- package/dist/services/shared.d.ts.map +1 -1
- package/dist/services/shared.js +45 -1
- package/dist/services/shared.js.map +1 -1
- package/package.json +14 -13
- package/server.json +9 -3
package/AGENTS.md
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
# Agent Protocol
|
|
2
2
|
|
|
3
3
|
**Server:** biorxiv-mcp-server
|
|
4
|
-
**Version:** 0.2.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.
|
|
6
|
-
**Engines:** Bun ≥1.
|
|
4
|
+
**Version:** 0.2.8
|
|
5
|
+
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
|
|
6
|
+
**Engines:** Bun ≥1.4.0, Node ≥24.0.0
|
|
7
7
|
**MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
|
|
8
|
-
**Zod:** ^4.
|
|
8
|
+
**Zod:** ^4.6.5
|
|
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.
|
|
11
11
|
|
|
@@ -37,7 +37,8 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
|
|
|
37
37
|
- **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
|
|
38
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
|
+
- **Cut noise.** Add only what earns its place: no speculative generality, no guards for states the framework already prevents (Zod-validated params, classified errors), no abstraction until a third caller proves it, no option nothing sets.
|
|
41
|
+
- **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
|
|
41
42
|
|
|
42
43
|
---
|
|
43
44
|
|
|
@@ -102,7 +103,21 @@ export function getServerConfig(): z.infer<typeof ServerConfigSchema> {
|
|
|
102
103
|
}
|
|
103
104
|
```
|
|
104
105
|
|
|
105
|
-
`parseEnvConfig` maps Zod schema paths → env var names so validation errors name the actual variable rather than the internal path.
|
|
106
|
+
`parseEnvConfig` maps Zod schema paths → env var names so validation errors name the actual variable rather than the internal path. It reads an empty string and an unsubstituted whole-value `${…}` placeholder (an MCPB optional field left blank) as unset, so an optional field stays `undefined` and a defaulted field takes its default — no per-field `z.preprocess` guard needed.
|
|
107
|
+
|
|
108
|
+
### Session posture and shutdown
|
|
109
|
+
|
|
110
|
+
```ts
|
|
111
|
+
await createApp({
|
|
112
|
+
sessionMode: 'stateless', // or { default: 'stateful', require: 'stateful' }
|
|
113
|
+
setup(core) { startMyWatcher(core.config); },
|
|
114
|
+
async teardown() { await stopMyWatcher(); },
|
|
115
|
+
});
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
`sessionMode` declares the HTTP session posture in `src/` instead of leaving it to a deployment's `MCP_SESSION_MODE`, which still wins whenever it carries a meaningful value. This server declares `stateless` — no tool calls `ctx.requestInput`. Add `require: 'stateful'` if a tool ever asks the caller for input mid-handler: startup then fails with a `ConfigurationError` rather than serving a mode in which a 2025-era client can never answer the prompt. Stdio is never refused.
|
|
119
|
+
|
|
120
|
+
`teardown(core)` is the `setup()` counterpart — release a watcher, socket, or non-`unref()`'d timer there. It runs after the transport stops and before the logger closes, on every shutdown path. This server's services allocate none, so it declares no `teardown`.
|
|
106
121
|
|
|
107
122
|
---
|
|
108
123
|
|
|
@@ -129,7 +144,7 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
129
144
|
|
|
130
145
|
Handlers throw — the framework catches, classifies, and formats.
|
|
131
146
|
|
|
132
|
-
**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. The `recovery` field is required (≥ 5 words, lint-validated). Spread `ctx.recoveryFor('reason')` into `data` to mirror the contract recovery onto the wire. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
|
|
147
|
+
**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. The `recovery` field is required (≥ 5 words, lint-validated). Spread `ctx.recoveryFor('reason')` into `data` to mirror the contract recovery onto the wire (`data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim), or pass an explicit `recovery: { hint }` when the hint needs runtime context (a computed wait). Forwarding is lint-enforced per throw site — a `ctx.fail` carrying neither warns as `error-contract-recovery-unforwarded`. Every declared reason must be named by a literal `ctx.fail('<reason>'` or `ctx.recoveryFor('<reason>')` in its handler — `lint:mcp`'s `error-contract-unthrown` flags one that isn't; mark an entry the service layer throws with `thrownBy: 'service'` (lint-only metadata) instead. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
|
|
133
148
|
|
|
134
149
|
```ts
|
|
135
150
|
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
@@ -172,7 +187,7 @@ src/
|
|
|
172
187
|
config/
|
|
173
188
|
server-config.ts # bioRxiv-specific env vars (BIORXIV_MAILTO, API base URLs)
|
|
174
189
|
services/
|
|
175
|
-
shared.ts # Shared utilities (detectHtmlError, normalizeUpstreamText,
|
|
190
|
+
shared.ts # Shared utilities (detectHtmlError, normalizeDoi, normalizeUpstreamText,
|
|
176
191
|
# isValidCalendarDate, parseRetryAfterSeconds, findRateLimit, describeWait,
|
|
177
192
|
# SERVER_VERSION)
|
|
178
193
|
biorxiv/
|
|
@@ -208,7 +223,8 @@ src/
|
|
|
208
223
|
|
|
209
224
|
## Domain Conventions
|
|
210
225
|
|
|
211
|
-
- **DOI format:** `10.1101/YYYY.MM.DD.NNNNNN
|
|
226
|
+
- **DOI format:** `10.1101/YYYY.MM.DD.NNNNNN` or `10.64898/…`. Run every DOI input through `normalizeDoi()` (`src/services/shared.ts`), which strips doi.org/article URLs, `doi:`, and `vN`/`.full` suffixes and returns `undefined` for anything still malformed — the bioRxiv API returns empty collections for malformed DOIs without an error code. `/pubs` keyed by preprint DOI never parses a `10.64898/` DOI; see `getPublishedVersionByJournalDoi()`.
|
|
227
|
+
- **Category spelling:** the listing API filters only on lowercase with `/` and `_` read as a space (`hiv aids`), and answers anything else with its unfiltered listing, echoing `messages[0].category: "all"`. `BiorxivApiService` owns the spelling and flags `categoryIgnored`; never present a flagged page as filtered.
|
|
212
228
|
- **Server parameter:** `"biorxiv" | "medrxiv" | "both"`. Default to `"both"`, including for DOI-resolution tools — both servers issue `10.1101/` DOIs, so the DOI never identifies the server and a single-server default silently misses records held by the other. Fan out via `Promise.allSettled` when `"both"` and name the answering server in the output.
|
|
213
229
|
- **Pagination:** integer `cursor` offset (0, 30, 60, …). Page size is fixed at 30 by the API — do not expose a `limit` parameter.
|
|
214
230
|
- **Two-server pagination:** when `server="both"`, surface per-server state: `{ biorxiv: { cursor, total }, medrxiv: { cursor, total } }`. A merged cursor is ambiguous.
|
|
@@ -220,9 +236,9 @@ src/
|
|
|
220
236
|
|
|
221
237
|
## Skills
|
|
222
238
|
|
|
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.
|
|
239
|
+
Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
|
|
224
240
|
|
|
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.
|
|
241
|
+
**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
|
|
226
242
|
|
|
227
243
|
Available skills:
|
|
228
244
|
|
|
@@ -240,12 +256,12 @@ Available skills:
|
|
|
240
256
|
| `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
|
|
241
257
|
| `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
|
|
242
258
|
| `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
|
|
243
|
-
| `devcheck` | Lint, format, typecheck, audit |
|
|
244
259
|
| `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
|
|
245
|
-
| `
|
|
260
|
+
| `git-wrapup` | Land working-tree changes as a commit stack — version bump, changelog, verify, commit by concern, release commit on top. No tag, no push to main; opens the release PR when the project declares release PR mode |
|
|
261
|
+
| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixes as ordinary commits on top of the stack, PR body kept in sync. Release PR mode only |
|
|
262
|
+
| `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
|
|
263
|
+
| `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
|
|
246
264
|
| `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
|
|
247
|
-
| `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
|
|
248
|
-
| `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
|
|
249
265
|
| `api-auth` | Auth modes, scopes, JWT/OAuth |
|
|
250
266
|
| `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
|
|
251
267
|
| `api-config` | AppConfig, parseConfig, env vars |
|
|
@@ -262,7 +278,7 @@ Available skills:
|
|
|
262
278
|
| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
|
|
263
279
|
| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
|
|
264
280
|
|
|
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.
|
|
281
|
+
**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*, `framework-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.
|
|
266
282
|
|
|
267
283
|
When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-05-21`).
|
|
268
284
|
|
|
@@ -278,7 +294,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
278
294
|
| `bun run rebuild` | Clean + build |
|
|
279
295
|
| `bun run clean` | Remove build artifacts |
|
|
280
296
|
| `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
|
|
281
|
-
| `bun run audit:
|
|
297
|
+
| `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update <name>`, then `bun dedupe` |
|
|
298
|
+
| `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` |
|
|
282
299
|
| `bun run tree` | Generate directory structure doc |
|
|
283
300
|
| `bun run format` | Auto-fix formatting (safe fixes only) |
|
|
284
301
|
| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
|
|
@@ -293,13 +310,17 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
293
310
|
| `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
|
|
294
311
|
| `bun run release:github` | Create (or repair) a GitHub Release on the current version's annotated tag |
|
|
295
312
|
|
|
313
|
+
**CI is one file.** `.github/workflows/codeql.yml` is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.
|
|
314
|
+
|
|
296
315
|
---
|
|
297
316
|
|
|
298
317
|
## Bundling
|
|
299
318
|
|
|
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.
|
|
319
|
+
`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 (`framework-skills/`, `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.
|
|
320
|
+
|
|
321
|
+
**Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`.
|
|
301
322
|
|
|
302
|
-
**
|
|
323
|
+
**README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `framework-skills/polish-docs-meta/references/readme.md`.
|
|
303
324
|
|
|
304
325
|
---
|
|
305
326
|
|
|
@@ -324,12 +345,18 @@ security: false # optional — true ONLY for a source
|
|
|
324
345
|
|
|
325
346
|
`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
347
|
|
|
327
|
-
**Section order
|
|
348
|
+
**Section order:** the Keep a Changelog sequence — Added, Changed, Deprecated, Removed, Fixed, Security — then `Dependencies` last. Include only sections with entries — don't ship empty headers.
|
|
328
349
|
|
|
329
350
|
**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
351
|
|
|
331
352
|
---
|
|
332
353
|
|
|
354
|
+
## Publishing
|
|
355
|
+
|
|
356
|
+
**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewritten, so `main` keeps the record of what the review corrected — PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
|
|
357
|
+
|
|
358
|
+
---
|
|
359
|
+
|
|
333
360
|
## Imports
|
|
334
361
|
|
|
335
362
|
```ts
|
|
@@ -356,12 +383,12 @@ import { getEuropePmcService } from '@/services/europe-pmc/europe-pmc-service.js
|
|
|
356
383
|
- [ ] bioRxiv API wrapping: normalization and `format()` preserve uncertainty; do not fabricate facts from missing upstream data (e.g., `published` field may be `"NA"` — surface it as absent, not empty)
|
|
357
384
|
- [ ] bioRxiv API wrapping: tests include at least one sparse payload case with omitted upstream fields
|
|
358
385
|
- [ ] `BIORXIV_MAILTO` included in outbound User-Agent header when set (optional env var)
|
|
359
|
-
- [ ] DOI
|
|
386
|
+
- [ ] DOI input normalized and validated with `normalizeDoi()` before calling API
|
|
360
387
|
- [ ] Two-server fan-out uses `Promise.allSettled`; partial failures reported per-DOI in `failed[]`
|
|
361
388
|
- [ ] `biorxiv_list_recent` with `server="both"` surfaces per-server pagination state, not a merged cursor
|
|
362
389
|
- [ ] Registered in `createApp()` arrays (directly or via barrel exports)
|
|
363
390
|
- [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
|
|
364
|
-
- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` =
|
|
365
|
-
- [ ] `.codex-plugin/mcp.json` updated — server name key
|
|
366
|
-
- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry
|
|
391
|
+
- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description
|
|
392
|
+
- [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable (API key, contact email, instance URL) is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset
|
|
393
|
+
- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.<option>}"` — mirror the `user_config` block in `manifest.json`. Never write `"KEY": ""` into `env`
|
|
367
394
|
- [ ] `bun run devcheck` passes
|
package/CLAUDE.md
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
# Agent Protocol
|
|
2
2
|
|
|
3
3
|
**Server:** biorxiv-mcp-server
|
|
4
|
-
**Version:** 0.2.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.
|
|
6
|
-
**Engines:** Bun ≥1.
|
|
4
|
+
**Version:** 0.2.8
|
|
5
|
+
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
|
|
6
|
+
**Engines:** Bun ≥1.4.0, Node ≥24.0.0
|
|
7
7
|
**MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
|
|
8
|
-
**Zod:** ^4.
|
|
8
|
+
**Zod:** ^4.6.5
|
|
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.
|
|
11
11
|
|
|
@@ -37,7 +37,8 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
|
|
|
37
37
|
- **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
|
|
38
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
|
+
- **Cut noise.** Add only what earns its place: no speculative generality, no guards for states the framework already prevents (Zod-validated params, classified errors), no abstraction until a third caller proves it, no option nothing sets.
|
|
41
|
+
- **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
|
|
41
42
|
|
|
42
43
|
---
|
|
43
44
|
|
|
@@ -102,7 +103,21 @@ export function getServerConfig(): z.infer<typeof ServerConfigSchema> {
|
|
|
102
103
|
}
|
|
103
104
|
```
|
|
104
105
|
|
|
105
|
-
`parseEnvConfig` maps Zod schema paths → env var names so validation errors name the actual variable rather than the internal path.
|
|
106
|
+
`parseEnvConfig` maps Zod schema paths → env var names so validation errors name the actual variable rather than the internal path. It reads an empty string and an unsubstituted whole-value `${…}` placeholder (an MCPB optional field left blank) as unset, so an optional field stays `undefined` and a defaulted field takes its default — no per-field `z.preprocess` guard needed.
|
|
107
|
+
|
|
108
|
+
### Session posture and shutdown
|
|
109
|
+
|
|
110
|
+
```ts
|
|
111
|
+
await createApp({
|
|
112
|
+
sessionMode: 'stateless', // or { default: 'stateful', require: 'stateful' }
|
|
113
|
+
setup(core) { startMyWatcher(core.config); },
|
|
114
|
+
async teardown() { await stopMyWatcher(); },
|
|
115
|
+
});
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
`sessionMode` declares the HTTP session posture in `src/` instead of leaving it to a deployment's `MCP_SESSION_MODE`, which still wins whenever it carries a meaningful value. This server declares `stateless` — no tool calls `ctx.requestInput`. Add `require: 'stateful'` if a tool ever asks the caller for input mid-handler: startup then fails with a `ConfigurationError` rather than serving a mode in which a 2025-era client can never answer the prompt. Stdio is never refused.
|
|
119
|
+
|
|
120
|
+
`teardown(core)` is the `setup()` counterpart — release a watcher, socket, or non-`unref()`'d timer there. It runs after the transport stops and before the logger closes, on every shutdown path. This server's services allocate none, so it declares no `teardown`.
|
|
106
121
|
|
|
107
122
|
---
|
|
108
123
|
|
|
@@ -129,7 +144,7 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
129
144
|
|
|
130
145
|
Handlers throw — the framework catches, classifies, and formats.
|
|
131
146
|
|
|
132
|
-
**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. The `recovery` field is required (≥ 5 words, lint-validated). Spread `ctx.recoveryFor('reason')` into `data` to mirror the contract recovery onto the wire. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
|
|
147
|
+
**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. The `recovery` field is required (≥ 5 words, lint-validated). Spread `ctx.recoveryFor('reason')` into `data` to mirror the contract recovery onto the wire (`data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim), or pass an explicit `recovery: { hint }` when the hint needs runtime context (a computed wait). Forwarding is lint-enforced per throw site — a `ctx.fail` carrying neither warns as `error-contract-recovery-unforwarded`. Every declared reason must be named by a literal `ctx.fail('<reason>'` or `ctx.recoveryFor('<reason>')` in its handler — `lint:mcp`'s `error-contract-unthrown` flags one that isn't; mark an entry the service layer throws with `thrownBy: 'service'` (lint-only metadata) instead. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
|
|
133
148
|
|
|
134
149
|
```ts
|
|
135
150
|
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
@@ -172,7 +187,7 @@ src/
|
|
|
172
187
|
config/
|
|
173
188
|
server-config.ts # bioRxiv-specific env vars (BIORXIV_MAILTO, API base URLs)
|
|
174
189
|
services/
|
|
175
|
-
shared.ts # Shared utilities (detectHtmlError, normalizeUpstreamText,
|
|
190
|
+
shared.ts # Shared utilities (detectHtmlError, normalizeDoi, normalizeUpstreamText,
|
|
176
191
|
# isValidCalendarDate, parseRetryAfterSeconds, findRateLimit, describeWait,
|
|
177
192
|
# SERVER_VERSION)
|
|
178
193
|
biorxiv/
|
|
@@ -208,7 +223,8 @@ src/
|
|
|
208
223
|
|
|
209
224
|
## Domain Conventions
|
|
210
225
|
|
|
211
|
-
- **DOI format:** `10.1101/YYYY.MM.DD.NNNNNN
|
|
226
|
+
- **DOI format:** `10.1101/YYYY.MM.DD.NNNNNN` or `10.64898/…`. Run every DOI input through `normalizeDoi()` (`src/services/shared.ts`), which strips doi.org/article URLs, `doi:`, and `vN`/`.full` suffixes and returns `undefined` for anything still malformed — the bioRxiv API returns empty collections for malformed DOIs without an error code. `/pubs` keyed by preprint DOI never parses a `10.64898/` DOI; see `getPublishedVersionByJournalDoi()`.
|
|
227
|
+
- **Category spelling:** the listing API filters only on lowercase with `/` and `_` read as a space (`hiv aids`), and answers anything else with its unfiltered listing, echoing `messages[0].category: "all"`. `BiorxivApiService` owns the spelling and flags `categoryIgnored`; never present a flagged page as filtered.
|
|
212
228
|
- **Server parameter:** `"biorxiv" | "medrxiv" | "both"`. Default to `"both"`, including for DOI-resolution tools — both servers issue `10.1101/` DOIs, so the DOI never identifies the server and a single-server default silently misses records held by the other. Fan out via `Promise.allSettled` when `"both"` and name the answering server in the output.
|
|
213
229
|
- **Pagination:** integer `cursor` offset (0, 30, 60, …). Page size is fixed at 30 by the API — do not expose a `limit` parameter.
|
|
214
230
|
- **Two-server pagination:** when `server="both"`, surface per-server state: `{ biorxiv: { cursor, total }, medrxiv: { cursor, total } }`. A merged cursor is ambiguous.
|
|
@@ -220,9 +236,9 @@ src/
|
|
|
220
236
|
|
|
221
237
|
## Skills
|
|
222
238
|
|
|
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.
|
|
239
|
+
Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
|
|
224
240
|
|
|
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.
|
|
241
|
+
**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
|
|
226
242
|
|
|
227
243
|
Available skills:
|
|
228
244
|
|
|
@@ -240,12 +256,12 @@ Available skills:
|
|
|
240
256
|
| `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
|
|
241
257
|
| `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
|
|
242
258
|
| `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
|
|
243
|
-
| `devcheck` | Lint, format, typecheck, audit |
|
|
244
259
|
| `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
|
|
245
|
-
| `
|
|
260
|
+
| `git-wrapup` | Land working-tree changes as a commit stack — version bump, changelog, verify, commit by concern, release commit on top. No tag, no push to main; opens the release PR when the project declares release PR mode |
|
|
261
|
+
| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixes as ordinary commits on top of the stack, PR body kept in sync. Release PR mode only |
|
|
262
|
+
| `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
|
|
263
|
+
| `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
|
|
246
264
|
| `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
|
|
247
|
-
| `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
|
|
248
|
-
| `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
|
|
249
265
|
| `api-auth` | Auth modes, scopes, JWT/OAuth |
|
|
250
266
|
| `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
|
|
251
267
|
| `api-config` | AppConfig, parseConfig, env vars |
|
|
@@ -262,7 +278,7 @@ Available skills:
|
|
|
262
278
|
| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
|
|
263
279
|
| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
|
|
264
280
|
|
|
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.
|
|
281
|
+
**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*, `framework-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.
|
|
266
282
|
|
|
267
283
|
When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-05-21`).
|
|
268
284
|
|
|
@@ -278,7 +294,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
278
294
|
| `bun run rebuild` | Clean + build |
|
|
279
295
|
| `bun run clean` | Remove build artifacts |
|
|
280
296
|
| `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
|
|
281
|
-
| `bun run audit:
|
|
297
|
+
| `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update <name>`, then `bun dedupe` |
|
|
298
|
+
| `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` |
|
|
282
299
|
| `bun run tree` | Generate directory structure doc |
|
|
283
300
|
| `bun run format` | Auto-fix formatting (safe fixes only) |
|
|
284
301
|
| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
|
|
@@ -293,13 +310,17 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
293
310
|
| `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
|
|
294
311
|
| `bun run release:github` | Create (or repair) a GitHub Release on the current version's annotated tag |
|
|
295
312
|
|
|
313
|
+
**CI is one file.** `.github/workflows/codeql.yml` is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.
|
|
314
|
+
|
|
296
315
|
---
|
|
297
316
|
|
|
298
317
|
## Bundling
|
|
299
318
|
|
|
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.
|
|
319
|
+
`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 (`framework-skills/`, `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.
|
|
320
|
+
|
|
321
|
+
**Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`.
|
|
301
322
|
|
|
302
|
-
**
|
|
323
|
+
**README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `framework-skills/polish-docs-meta/references/readme.md`.
|
|
303
324
|
|
|
304
325
|
---
|
|
305
326
|
|
|
@@ -324,12 +345,18 @@ security: false # optional — true ONLY for a source
|
|
|
324
345
|
|
|
325
346
|
`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
347
|
|
|
327
|
-
**Section order
|
|
348
|
+
**Section order:** the Keep a Changelog sequence — Added, Changed, Deprecated, Removed, Fixed, Security — then `Dependencies` last. Include only sections with entries — don't ship empty headers.
|
|
328
349
|
|
|
329
350
|
**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
351
|
|
|
331
352
|
---
|
|
332
353
|
|
|
354
|
+
## Publishing
|
|
355
|
+
|
|
356
|
+
**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewritten, so `main` keeps the record of what the review corrected — PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
|
|
357
|
+
|
|
358
|
+
---
|
|
359
|
+
|
|
333
360
|
## Imports
|
|
334
361
|
|
|
335
362
|
```ts
|
|
@@ -356,12 +383,12 @@ import { getEuropePmcService } from '@/services/europe-pmc/europe-pmc-service.js
|
|
|
356
383
|
- [ ] bioRxiv API wrapping: normalization and `format()` preserve uncertainty; do not fabricate facts from missing upstream data (e.g., `published` field may be `"NA"` — surface it as absent, not empty)
|
|
357
384
|
- [ ] bioRxiv API wrapping: tests include at least one sparse payload case with omitted upstream fields
|
|
358
385
|
- [ ] `BIORXIV_MAILTO` included in outbound User-Agent header when set (optional env var)
|
|
359
|
-
- [ ] DOI
|
|
386
|
+
- [ ] DOI input normalized and validated with `normalizeDoi()` before calling API
|
|
360
387
|
- [ ] Two-server fan-out uses `Promise.allSettled`; partial failures reported per-DOI in `failed[]`
|
|
361
388
|
- [ ] `biorxiv_list_recent` with `server="both"` surfaces per-server pagination state, not a merged cursor
|
|
362
389
|
- [ ] Registered in `createApp()` arrays (directly or via barrel exports)
|
|
363
390
|
- [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
|
|
364
|
-
- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` =
|
|
365
|
-
- [ ] `.codex-plugin/mcp.json` updated — server name key
|
|
366
|
-
- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry
|
|
391
|
+
- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description
|
|
392
|
+
- [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable (API key, contact email, instance URL) is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset
|
|
393
|
+
- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.<option>}"` — mirror the `user_config` block in `manifest.json`. Never write `"KEY": ""` into `env`
|
|
367
394
|
- [ ] `bun run devcheck` passes
|
package/Dockerfile
CHANGED
|
@@ -4,13 +4,15 @@
|
|
|
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
|
-
# Pinned to BUILDPLATFORM
|
|
8
|
-
#
|
|
9
|
-
#
|
|
10
|
-
#
|
|
11
|
-
#
|
|
12
|
-
#
|
|
13
|
-
#
|
|
7
|
+
# Pinned to $BUILDPLATFORM rather than the target platform: `bun run build` emits
|
|
8
|
+
# JavaScript, and only `dist/` crosses into the production stage, which runs its
|
|
9
|
+
# own target-arch install. Built for the target instead, the non-native leg of a
|
|
10
|
+
# `--platform linux/amd64,linux/arm64` build runs under QEMU, where bun >= 1.4
|
|
11
|
+
# aborts with a JavaScriptCore allocator assertion and fails the multi-arch push.
|
|
12
|
+
#
|
|
13
|
+
# The constraint this assumes: the build stage produces platform-independent
|
|
14
|
+
# output. A stage that compiles a native addon needs the target-arch toolchain
|
|
15
|
+
# and cannot cross-compile this way — drop the flag there.
|
|
14
16
|
# ==============================================================================
|
|
15
17
|
FROM --platform=$BUILDPLATFORM oven/bun:1.4.0 AS build
|
|
16
18
|
|