@cyanheads/biorxiv-mcp-server 0.2.8 → 0.3.1
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 +42 -31
- package/CLAUDE.md +42 -31
- package/Dockerfile +85 -40
- package/README.md +21 -35
- package/changelog/0.3.x/0.3.0.md +22 -0
- package/changelog/0.3.x/0.3.1.md +33 -0
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- 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 +7 -11
- 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 +1 -1
- 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 +21 -18
- 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.map +1 -1
- package/dist/mcp-server/tools/definitions/biorxiv-get-published-version.tool.js +14 -13
- package/dist/mcp-server/tools/definitions/biorxiv-get-published-version.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/biorxiv-list-recent.tool.d.ts +17 -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 +109 -45
- 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 +9 -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 +73 -27
- package/dist/mcp-server/tools/definitions/biorxiv-search-preprints.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +11 -3
- package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
- package/dist/services/biorxiv/biorxiv-service.d.ts +11 -6
- package/dist/services/biorxiv/biorxiv-service.d.ts.map +1 -1
- package/dist/services/biorxiv/biorxiv-service.js +37 -19
- package/dist/services/biorxiv/biorxiv-service.js.map +1 -1
- package/dist/services/biorxiv/types.d.ts +22 -2
- package/dist/services/biorxiv/types.d.ts.map +1 -1
- package/dist/services/europe-pmc/europe-pmc-service.d.ts +16 -3
- package/dist/services/europe-pmc/europe-pmc-service.d.ts.map +1 -1
- package/dist/services/europe-pmc/europe-pmc-service.js +64 -7
- package/dist/services/europe-pmc/europe-pmc-service.js.map +1 -1
- package/dist/services/europe-pmc/types.d.ts +9 -3
- package/dist/services/europe-pmc/types.d.ts.map +1 -1
- package/dist/services/shared.d.ts +62 -11
- package/dist/services/shared.d.ts.map +1 -1
- package/dist/services/shared.js +244 -17
- package/dist/services/shared.js.map +1 -1
- package/dist/services/upstream-text-tables.d.ts +44 -0
- package/dist/services/upstream-text-tables.d.ts.map +1 -0
- package/dist/services/upstream-text-tables.js +296 -0
- package/dist/services/upstream-text-tables.js.map +1 -0
- package/package.json +10 -9
- package/server.json +10 -24
package/AGENTS.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# Agent Protocol
|
|
2
2
|
|
|
3
3
|
**Server:** biorxiv-mcp-server
|
|
4
|
-
**Version:** 0.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.
|
|
4
|
+
**Version:** 0.3.1
|
|
5
|
+
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.13`
|
|
6
6
|
**Engines:** Bun ≥1.4.0, Node ≥24.0.0
|
|
7
|
-
**MCP SDK:** `@modelcontextprotocol/server` ^2.
|
|
7
|
+
**MCP SDK:** `@modelcontextprotocol/server` ^2.2.0
|
|
8
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.
|
|
@@ -105,8 +105,18 @@ export function getServerConfig(): z.infer<typeof ServerConfigSchema> {
|
|
|
105
105
|
|
|
106
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
107
|
|
|
108
|
+
For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("false")` is `true`, so a coerced flag can't be disabled through the environment. `z.stringbool()` parses `true/false/1/0/yes/no/on/off` and rejects anything else, so `=false` actually disables.
|
|
109
|
+
|
|
110
|
+
### Server identity and instructions
|
|
111
|
+
|
|
112
|
+
`createApp()` accepts optional identity fields forwarded to the SDK's `initialize` response and the server manifest (`/.well-known/mcp.json`): `name`, `title`, `websiteUrl`, `description` (wins over `MCP_SERVER_DESCRIPTION`), `icons`, and `instructions`. This server sets `name` and `title` (both the repo name) and `instructions` in `src/index.ts`.
|
|
113
|
+
|
|
114
|
+
`instructions` is optional server-level orientation, sent on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
|
|
115
|
+
|
|
108
116
|
### Session posture and shutdown
|
|
109
117
|
|
|
118
|
+
Two more `createApp()` options shape how the server runs rather than how it presents itself:
|
|
119
|
+
|
|
110
120
|
```ts
|
|
111
121
|
await createApp({
|
|
112
122
|
sessionMode: 'stateless', // or { default: 'stateful', require: 'stateful' }
|
|
@@ -115,9 +125,9 @@ await createApp({
|
|
|
115
125
|
});
|
|
116
126
|
```
|
|
117
127
|
|
|
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.
|
|
128
|
+
`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 (an empty string and an unsubstituted `${…}` placeholder read as unset and fall through to the option). 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
129
|
|
|
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`.
|
|
130
|
+
`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, and a signal-triggered shutdown then exits the process explicitly (0, or 1 if a step never settles within the framework's 10 s ceiling). This server's services allocate none, so it declares no `teardown`.
|
|
121
131
|
|
|
122
132
|
---
|
|
123
133
|
|
|
@@ -128,14 +138,14 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
128
138
|
| Property | Description |
|
|
129
139
|
|:---------|:------------|
|
|
130
140
|
| `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. |
|
|
131
|
-
| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
|
|
141
|
+
| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any JSON-serializable value; reads return its JSON form (a `Date` comes back as an ISO string). |
|
|
132
142
|
| `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. |
|
|
133
|
-
| `ctx.inputs` |
|
|
134
|
-
| `ctx.
|
|
143
|
+
| `ctx.inputs` | The request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped` — limited to what the client declared (`elicitation` and its form/url modes, `sampling`, `roots`). Client-supplied: a consent gate trusts only a `ctx.state` record it stored when it asked, bound to the operation, caller, and target (see the `api-context` skill). |
|
|
144
|
+
| `ctx.clientCapabilities` | What the client declared for this request, `undefined` when no view exists. Decides whether to ask for optional context (e.g. roots); never a reason to skip a consent prompt. |
|
|
135
145
|
| `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). |
|
|
136
146
|
| `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`. |
|
|
137
147
|
| `ctx.signal` | `AbortSignal` for cancellation. |
|
|
138
|
-
| `ctx.requestId` |
|
|
148
|
+
| `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |
|
|
139
149
|
| `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
|
|
140
150
|
|
|
141
151
|
---
|
|
@@ -144,7 +154,7 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
144
154
|
|
|
145
155
|
Handlers throw — the framework catches, classifies, and formats.
|
|
146
156
|
|
|
147
|
-
**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive
|
|
157
|
+
**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. The framework puts it on the wire whenever a failure carrying that `reason` arrives without a hint — a bare `ctx.fail('reason')` or a service throw with `data: { reason }` — as `data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim; override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters (a computed wait). Every error envelope also carries `data.requestId`, the id the server's log records for that call carry, and `content[]` closes with `(reason … · request <id>)`. 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'` so the rule skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
|
|
148
158
|
|
|
149
159
|
```ts
|
|
150
160
|
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
@@ -157,9 +167,7 @@ errors: [
|
|
|
157
167
|
async handler(input, ctx) {
|
|
158
168
|
const result = await getBiorxivApiService().getDetails(input.doi, input.server ?? 'both');
|
|
159
169
|
if (result.collection.length === 0) {
|
|
160
|
-
throw ctx.fail('doi_not_found', `DOI not found: ${input.doi}
|
|
161
|
-
...ctx.recoveryFor('doi_not_found'),
|
|
162
|
-
});
|
|
170
|
+
throw ctx.fail('doi_not_found', `DOI not found: ${input.doi}`);
|
|
163
171
|
}
|
|
164
172
|
return result;
|
|
165
173
|
}
|
|
@@ -167,7 +175,7 @@ async handler(input, ctx) {
|
|
|
167
175
|
|
|
168
176
|
**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.
|
|
169
177
|
|
|
170
|
-
**Fallback (no contract entry fits):**
|
|
178
|
+
**Fallback (no contract entry fits):** throw via factories or plain `Error`.
|
|
171
179
|
|
|
172
180
|
```ts
|
|
173
181
|
import { notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
|
|
@@ -175,7 +183,7 @@ throw notFound('Preprint not found', { doi });
|
|
|
175
183
|
throw serviceUnavailable('api.biorxiv.org unreachable', { url }, { cause: err });
|
|
176
184
|
```
|
|
177
185
|
|
|
178
|
-
See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all factories, and the contract reference.
|
|
186
|
+
See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.
|
|
179
187
|
|
|
180
188
|
---
|
|
181
189
|
|
|
@@ -187,9 +195,10 @@ src/
|
|
|
187
195
|
config/
|
|
188
196
|
server-config.ts # bioRxiv-specific env vars (BIORXIV_MAILTO, API base URLs)
|
|
189
197
|
services/
|
|
190
|
-
shared.ts # Shared utilities (detectHtmlError, normalizeDoi,
|
|
191
|
-
#
|
|
192
|
-
# SERVER_VERSION)
|
|
198
|
+
shared.ts # Shared utilities (detectHtmlError, normalizeDoi, normalizeRorId,
|
|
199
|
+
# normalizeUpstreamText, escapeMarkdown, isValidCalendarDate,
|
|
200
|
+
# parseRetryAfterSeconds, findRateLimit, describeWait, SERVER_VERSION)
|
|
201
|
+
upstream-text-tables.ts # Closed tables normalizeUpstreamText reads: Highwire placeholders, section headings
|
|
193
202
|
biorxiv/
|
|
194
203
|
biorxiv-service.ts # BiorxivApiService — details, publications, pubs endpoints
|
|
195
204
|
types.ts # Domain types (Preprint, PublishedVersion, …)
|
|
@@ -225,11 +234,13 @@ src/
|
|
|
225
234
|
|
|
226
235
|
- **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
236
|
- **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.
|
|
237
|
+
- **Funder data:** upstream funder `name`s and ROR `id`s on records are misattributed — expose only `awards` (verbatim, never split), never a funder name or ID. The listing's `funder` filter takes a bare ROR ID (`normalizeRorId()` strips the URL form and checks the checksum), is bioRxiv-only, and `"funder value not found"` (flagged `funderNotFound`) is an error, never an empty page.
|
|
228
238
|
- **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.
|
|
229
239
|
- **Pagination:** integer `cursor` offset (0, 30, 60, …). Page size is fixed at 30 by the API — do not expose a `limit` parameter.
|
|
230
240
|
- **Two-server pagination:** when `server="both"`, surface per-server state: `{ biorxiv: { cursor, total }, medrxiv: { cursor, total } }`. A merged cursor is ambiguous.
|
|
231
|
-
- **EuropePMC enrichment:** `biorxiv_search_preprints` uses EuropePMC for relevance then enriches matching DOIs via the details endpoint. Enrichment routes based on `input.server` — when explicit ("biorxiv" or "medrxiv"), always use that server. `10.1101/` prefix is used as a hint only within `server="both"` to prefer bioRxiv first, but is not a reliable discriminator (both servers share this prefix).
|
|
232
|
-
- **`format()` must be content-complete:** Claude Desktop reads `content[]` from `format()`, not `structuredContent`. Revision list, crosswalk data, pagination state, and
|
|
241
|
+
- **EuropePMC enrichment:** `biorxiv_search_preprints` uses EuropePMC for relevance then enriches matching DOIs via the details endpoint. Enrichment routes based on `input.server` — when explicit ("biorxiv" or "medrxiv"), always use that server. `10.1101/` prefix is used as a hint only within `server="both"` to prefer bioRxiv first, but is not a reliable discriminator (both servers share this prefix). The ranked search stays `resulttype=lite`, which never carries an abstract; records that fall back to EuropePMC metadata get theirs from one DOI-keyed `resultType=core` query (`getAbstracts`), made only when abstracts are requested and something fell back. A failed lookup is a notice, never a failed search.
|
|
242
|
+
- **`format()` must be content-complete:** Claude Desktop reads `content[]` from `format()`, not `structuredContent`. Revision list, crosswalk data, pagination state, and every abstract a record carries must all appear in the rendered markdown, not just counts. `include_abstract` (default `false` on `biorxiv_list_recent`, `true` on `biorxiv_search_preprints`) removes the abstract from both surfaces together and no other field.
|
|
243
|
+
- **Upstream text in `format()`:** run titles and abstracts through `normalizeUpstreamText()` in the service (never in `format()`), and pass every upstream free-text field through `escapeMarkdown()` where `format()` interpolates it. It escapes only characters that would change rendering (`A\*T`, `\<COMP id>`; `p<0.05` and `cc_by` stay raw), because agents copy spans out of `content[]` — keep it that narrow. Never escape DOIs, URLs, `structuredContent`, or `biorxiv_get_fulltext`'s extracted `content`.
|
|
233
244
|
- **Polite access:** include `BIORXIV_MAILTO` in the `User-Agent` header when set: `biorxiv-mcp-server/0.1.0 (mailto:${config.mailto})`. The env var is optional — omit the mailto segment when not configured.
|
|
234
245
|
|
|
235
246
|
---
|
|
@@ -262,21 +273,21 @@ Available skills:
|
|
|
262
273
|
| `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
|
|
263
274
|
| `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
|
|
264
275
|
| `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
|
|
276
|
+
| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
|
|
277
|
+
| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
|
|
278
|
+
| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
|
|
265
279
|
| `api-auth` | Auth modes, scopes, JWT/OAuth |
|
|
266
280
|
| `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
|
|
267
281
|
| `api-config` | AppConfig, parseConfig, env vars |
|
|
268
282
|
| `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input |
|
|
269
283
|
| `api-errors` | McpError, JsonRpcErrorCode, error patterns |
|
|
270
284
|
| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
|
|
271
|
-
| `api-mirror` | MirrorService: persistent
|
|
285
|
+
| `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in |
|
|
272
286
|
| `api-services` | LLM, Speech, Graph services |
|
|
273
|
-
| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
|
|
274
287
|
| `api-testing` | createMockContext, test patterns |
|
|
275
288
|
| `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
|
|
289
|
+
| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
|
|
276
290
|
| `api-workers` | Cloudflare Workers runtime |
|
|
277
|
-
| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
|
|
278
|
-
| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
|
|
279
|
-
| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
|
|
280
291
|
|
|
281
292
|
**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.
|
|
282
293
|
|
|
@@ -296,18 +307,18 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
296
307
|
| `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
|
|
297
308
|
| `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
309
|
| `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` |
|
|
310
|
+
| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
|
|
311
|
+
| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
|
|
312
|
+
| `bun run list-skills` | Print the skill registry |
|
|
299
313
|
| `bun run tree` | Generate directory structure doc |
|
|
300
314
|
| `bun run format` | Auto-fix formatting (safe fixes only) |
|
|
301
315
|
| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
|
|
302
316
|
| `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
|
|
303
|
-
| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
|
|
304
|
-
| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
|
|
305
|
-
| `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
|
|
306
|
-
| `bun run list-skills` | Surface available local skills for sub-agents |
|
|
307
317
|
| `bun run start:stdio` | Production mode (stdio) |
|
|
308
318
|
| `bun run start:http` | Production mode (HTTP) |
|
|
309
319
|
| `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
|
|
310
320
|
| `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
|
|
321
|
+
| `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
|
|
311
322
|
| `bun run release:github` | Create (or repair) a GitHub Release on the current version's annotated tag |
|
|
312
323
|
|
|
313
324
|
**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.
|
|
@@ -353,7 +364,7 @@ security: false # optional — true ONLY for a source
|
|
|
353
364
|
|
|
354
365
|
## Publishing
|
|
355
366
|
|
|
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
|
|
367
|
+
**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 release digest: theme line, `## Changes`, `## Gates`, changelog link last); `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
368
|
|
|
358
369
|
---
|
|
359
370
|
|
|
@@ -378,7 +389,7 @@ import { getEuropePmcService } from '@/services/europe-pmc/europe-pmc-service.js
|
|
|
378
389
|
- [ ] JSDoc `@fileoverview` + `@module` on every file
|
|
379
390
|
- [ ] `ctx.log` for logging, `ctx.state` for storage
|
|
380
391
|
- [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
|
|
381
|
-
- [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data — including revision list, crosswalk fields,
|
|
392
|
+
- [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data — including revision list, crosswalk fields, pagination state, and the abstract whenever the record carries one (`include_abstract` drops it from both surfaces at once)
|
|
382
393
|
- [ ] bioRxiv API wrapping: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
|
|
383
394
|
- [ ] 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)
|
|
384
395
|
- [ ] bioRxiv API wrapping: tests include at least one sparse payload case with omitted upstream fields
|
package/CLAUDE.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# Agent Protocol
|
|
2
2
|
|
|
3
3
|
**Server:** biorxiv-mcp-server
|
|
4
|
-
**Version:** 0.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.
|
|
4
|
+
**Version:** 0.3.1
|
|
5
|
+
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.13`
|
|
6
6
|
**Engines:** Bun ≥1.4.0, Node ≥24.0.0
|
|
7
|
-
**MCP SDK:** `@modelcontextprotocol/server` ^2.
|
|
7
|
+
**MCP SDK:** `@modelcontextprotocol/server` ^2.2.0
|
|
8
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.
|
|
@@ -105,8 +105,18 @@ export function getServerConfig(): z.infer<typeof ServerConfigSchema> {
|
|
|
105
105
|
|
|
106
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
107
|
|
|
108
|
+
For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("false")` is `true`, so a coerced flag can't be disabled through the environment. `z.stringbool()` parses `true/false/1/0/yes/no/on/off` and rejects anything else, so `=false` actually disables.
|
|
109
|
+
|
|
110
|
+
### Server identity and instructions
|
|
111
|
+
|
|
112
|
+
`createApp()` accepts optional identity fields forwarded to the SDK's `initialize` response and the server manifest (`/.well-known/mcp.json`): `name`, `title`, `websiteUrl`, `description` (wins over `MCP_SERVER_DESCRIPTION`), `icons`, and `instructions`. This server sets `name` and `title` (both the repo name) and `instructions` in `src/index.ts`.
|
|
113
|
+
|
|
114
|
+
`instructions` is optional server-level orientation, sent on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
|
|
115
|
+
|
|
108
116
|
### Session posture and shutdown
|
|
109
117
|
|
|
118
|
+
Two more `createApp()` options shape how the server runs rather than how it presents itself:
|
|
119
|
+
|
|
110
120
|
```ts
|
|
111
121
|
await createApp({
|
|
112
122
|
sessionMode: 'stateless', // or { default: 'stateful', require: 'stateful' }
|
|
@@ -115,9 +125,9 @@ await createApp({
|
|
|
115
125
|
});
|
|
116
126
|
```
|
|
117
127
|
|
|
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.
|
|
128
|
+
`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 (an empty string and an unsubstituted `${…}` placeholder read as unset and fall through to the option). 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
129
|
|
|
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`.
|
|
130
|
+
`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, and a signal-triggered shutdown then exits the process explicitly (0, or 1 if a step never settles within the framework's 10 s ceiling). This server's services allocate none, so it declares no `teardown`.
|
|
121
131
|
|
|
122
132
|
---
|
|
123
133
|
|
|
@@ -128,14 +138,14 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
128
138
|
| Property | Description |
|
|
129
139
|
|:---------|:------------|
|
|
130
140
|
| `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. |
|
|
131
|
-
| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
|
|
141
|
+
| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any JSON-serializable value; reads return its JSON form (a `Date` comes back as an ISO string). |
|
|
132
142
|
| `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. |
|
|
133
|
-
| `ctx.inputs` |
|
|
134
|
-
| `ctx.
|
|
143
|
+
| `ctx.inputs` | The request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped` — limited to what the client declared (`elicitation` and its form/url modes, `sampling`, `roots`). Client-supplied: a consent gate trusts only a `ctx.state` record it stored when it asked, bound to the operation, caller, and target (see the `api-context` skill). |
|
|
144
|
+
| `ctx.clientCapabilities` | What the client declared for this request, `undefined` when no view exists. Decides whether to ask for optional context (e.g. roots); never a reason to skip a consent prompt. |
|
|
135
145
|
| `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). |
|
|
136
146
|
| `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`. |
|
|
137
147
|
| `ctx.signal` | `AbortSignal` for cancellation. |
|
|
138
|
-
| `ctx.requestId` |
|
|
148
|
+
| `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |
|
|
139
149
|
| `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
|
|
140
150
|
|
|
141
151
|
---
|
|
@@ -144,7 +154,7 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
144
154
|
|
|
145
155
|
Handlers throw — the framework catches, classifies, and formats.
|
|
146
156
|
|
|
147
|
-
**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive
|
|
157
|
+
**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. The framework puts it on the wire whenever a failure carrying that `reason` arrives without a hint — a bare `ctx.fail('reason')` or a service throw with `data: { reason }` — as `data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim; override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters (a computed wait). Every error envelope also carries `data.requestId`, the id the server's log records for that call carry, and `content[]` closes with `(reason … · request <id>)`. 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'` so the rule skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
|
|
148
158
|
|
|
149
159
|
```ts
|
|
150
160
|
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
@@ -157,9 +167,7 @@ errors: [
|
|
|
157
167
|
async handler(input, ctx) {
|
|
158
168
|
const result = await getBiorxivApiService().getDetails(input.doi, input.server ?? 'both');
|
|
159
169
|
if (result.collection.length === 0) {
|
|
160
|
-
throw ctx.fail('doi_not_found', `DOI not found: ${input.doi}
|
|
161
|
-
...ctx.recoveryFor('doi_not_found'),
|
|
162
|
-
});
|
|
170
|
+
throw ctx.fail('doi_not_found', `DOI not found: ${input.doi}`);
|
|
163
171
|
}
|
|
164
172
|
return result;
|
|
165
173
|
}
|
|
@@ -167,7 +175,7 @@ async handler(input, ctx) {
|
|
|
167
175
|
|
|
168
176
|
**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.
|
|
169
177
|
|
|
170
|
-
**Fallback (no contract entry fits):**
|
|
178
|
+
**Fallback (no contract entry fits):** throw via factories or plain `Error`.
|
|
171
179
|
|
|
172
180
|
```ts
|
|
173
181
|
import { notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
|
|
@@ -175,7 +183,7 @@ throw notFound('Preprint not found', { doi });
|
|
|
175
183
|
throw serviceUnavailable('api.biorxiv.org unreachable', { url }, { cause: err });
|
|
176
184
|
```
|
|
177
185
|
|
|
178
|
-
See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all factories, and the contract reference.
|
|
186
|
+
See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.
|
|
179
187
|
|
|
180
188
|
---
|
|
181
189
|
|
|
@@ -187,9 +195,10 @@ src/
|
|
|
187
195
|
config/
|
|
188
196
|
server-config.ts # bioRxiv-specific env vars (BIORXIV_MAILTO, API base URLs)
|
|
189
197
|
services/
|
|
190
|
-
shared.ts # Shared utilities (detectHtmlError, normalizeDoi,
|
|
191
|
-
#
|
|
192
|
-
# SERVER_VERSION)
|
|
198
|
+
shared.ts # Shared utilities (detectHtmlError, normalizeDoi, normalizeRorId,
|
|
199
|
+
# normalizeUpstreamText, escapeMarkdown, isValidCalendarDate,
|
|
200
|
+
# parseRetryAfterSeconds, findRateLimit, describeWait, SERVER_VERSION)
|
|
201
|
+
upstream-text-tables.ts # Closed tables normalizeUpstreamText reads: Highwire placeholders, section headings
|
|
193
202
|
biorxiv/
|
|
194
203
|
biorxiv-service.ts # BiorxivApiService — details, publications, pubs endpoints
|
|
195
204
|
types.ts # Domain types (Preprint, PublishedVersion, …)
|
|
@@ -225,11 +234,13 @@ src/
|
|
|
225
234
|
|
|
226
235
|
- **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
236
|
- **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.
|
|
237
|
+
- **Funder data:** upstream funder `name`s and ROR `id`s on records are misattributed — expose only `awards` (verbatim, never split), never a funder name or ID. The listing's `funder` filter takes a bare ROR ID (`normalizeRorId()` strips the URL form and checks the checksum), is bioRxiv-only, and `"funder value not found"` (flagged `funderNotFound`) is an error, never an empty page.
|
|
228
238
|
- **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.
|
|
229
239
|
- **Pagination:** integer `cursor` offset (0, 30, 60, …). Page size is fixed at 30 by the API — do not expose a `limit` parameter.
|
|
230
240
|
- **Two-server pagination:** when `server="both"`, surface per-server state: `{ biorxiv: { cursor, total }, medrxiv: { cursor, total } }`. A merged cursor is ambiguous.
|
|
231
|
-
- **EuropePMC enrichment:** `biorxiv_search_preprints` uses EuropePMC for relevance then enriches matching DOIs via the details endpoint. Enrichment routes based on `input.server` — when explicit ("biorxiv" or "medrxiv"), always use that server. `10.1101/` prefix is used as a hint only within `server="both"` to prefer bioRxiv first, but is not a reliable discriminator (both servers share this prefix).
|
|
232
|
-
- **`format()` must be content-complete:** Claude Desktop reads `content[]` from `format()`, not `structuredContent`. Revision list, crosswalk data, pagination state, and
|
|
241
|
+
- **EuropePMC enrichment:** `biorxiv_search_preprints` uses EuropePMC for relevance then enriches matching DOIs via the details endpoint. Enrichment routes based on `input.server` — when explicit ("biorxiv" or "medrxiv"), always use that server. `10.1101/` prefix is used as a hint only within `server="both"` to prefer bioRxiv first, but is not a reliable discriminator (both servers share this prefix). The ranked search stays `resulttype=lite`, which never carries an abstract; records that fall back to EuropePMC metadata get theirs from one DOI-keyed `resultType=core` query (`getAbstracts`), made only when abstracts are requested and something fell back. A failed lookup is a notice, never a failed search.
|
|
242
|
+
- **`format()` must be content-complete:** Claude Desktop reads `content[]` from `format()`, not `structuredContent`. Revision list, crosswalk data, pagination state, and every abstract a record carries must all appear in the rendered markdown, not just counts. `include_abstract` (default `false` on `biorxiv_list_recent`, `true` on `biorxiv_search_preprints`) removes the abstract from both surfaces together and no other field.
|
|
243
|
+
- **Upstream text in `format()`:** run titles and abstracts through `normalizeUpstreamText()` in the service (never in `format()`), and pass every upstream free-text field through `escapeMarkdown()` where `format()` interpolates it. It escapes only characters that would change rendering (`A\*T`, `\<COMP id>`; `p<0.05` and `cc_by` stay raw), because agents copy spans out of `content[]` — keep it that narrow. Never escape DOIs, URLs, `structuredContent`, or `biorxiv_get_fulltext`'s extracted `content`.
|
|
233
244
|
- **Polite access:** include `BIORXIV_MAILTO` in the `User-Agent` header when set: `biorxiv-mcp-server/0.1.0 (mailto:${config.mailto})`. The env var is optional — omit the mailto segment when not configured.
|
|
234
245
|
|
|
235
246
|
---
|
|
@@ -262,21 +273,21 @@ Available skills:
|
|
|
262
273
|
| `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
|
|
263
274
|
| `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
|
|
264
275
|
| `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
|
|
276
|
+
| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
|
|
277
|
+
| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
|
|
278
|
+
| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
|
|
265
279
|
| `api-auth` | Auth modes, scopes, JWT/OAuth |
|
|
266
280
|
| `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
|
|
267
281
|
| `api-config` | AppConfig, parseConfig, env vars |
|
|
268
282
|
| `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input |
|
|
269
283
|
| `api-errors` | McpError, JsonRpcErrorCode, error patterns |
|
|
270
284
|
| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
|
|
271
|
-
| `api-mirror` | MirrorService: persistent
|
|
285
|
+
| `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in |
|
|
272
286
|
| `api-services` | LLM, Speech, Graph services |
|
|
273
|
-
| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
|
|
274
287
|
| `api-testing` | createMockContext, test patterns |
|
|
275
288
|
| `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
|
|
289
|
+
| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
|
|
276
290
|
| `api-workers` | Cloudflare Workers runtime |
|
|
277
|
-
| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
|
|
278
|
-
| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
|
|
279
|
-
| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
|
|
280
291
|
|
|
281
292
|
**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.
|
|
282
293
|
|
|
@@ -296,18 +307,18 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
296
307
|
| `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
|
|
297
308
|
| `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
309
|
| `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` |
|
|
310
|
+
| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
|
|
311
|
+
| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
|
|
312
|
+
| `bun run list-skills` | Print the skill registry |
|
|
299
313
|
| `bun run tree` | Generate directory structure doc |
|
|
300
314
|
| `bun run format` | Auto-fix formatting (safe fixes only) |
|
|
301
315
|
| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
|
|
302
316
|
| `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
|
|
303
|
-
| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
|
|
304
|
-
| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
|
|
305
|
-
| `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
|
|
306
|
-
| `bun run list-skills` | Surface available local skills for sub-agents |
|
|
307
317
|
| `bun run start:stdio` | Production mode (stdio) |
|
|
308
318
|
| `bun run start:http` | Production mode (HTTP) |
|
|
309
319
|
| `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
|
|
310
320
|
| `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
|
|
321
|
+
| `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
|
|
311
322
|
| `bun run release:github` | Create (or repair) a GitHub Release on the current version's annotated tag |
|
|
312
323
|
|
|
313
324
|
**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.
|
|
@@ -353,7 +364,7 @@ security: false # optional — true ONLY for a source
|
|
|
353
364
|
|
|
354
365
|
## Publishing
|
|
355
366
|
|
|
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
|
|
367
|
+
**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 release digest: theme line, `## Changes`, `## Gates`, changelog link last); `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
368
|
|
|
358
369
|
---
|
|
359
370
|
|
|
@@ -378,7 +389,7 @@ import { getEuropePmcService } from '@/services/europe-pmc/europe-pmc-service.js
|
|
|
378
389
|
- [ ] JSDoc `@fileoverview` + `@module` on every file
|
|
379
390
|
- [ ] `ctx.log` for logging, `ctx.state` for storage
|
|
380
391
|
- [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
|
|
381
|
-
- [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data — including revision list, crosswalk fields,
|
|
392
|
+
- [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data — including revision list, crosswalk fields, pagination state, and the abstract whenever the record carries one (`include_abstract` drops it from both surfaces at once)
|
|
382
393
|
- [ ] bioRxiv API wrapping: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
|
|
383
394
|
- [ ] 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)
|
|
384
395
|
- [ ] bioRxiv API wrapping: tests include at least one sparse payload case with omitted upstream fields
|
package/Dockerfile
CHANGED
|
@@ -5,16 +5,16 @@
|
|
|
5
5
|
# source code into JavaScript, and prepares the production assets.
|
|
6
6
|
#
|
|
7
7
|
# Pinned to $BUILDPLATFORM rather than the target platform: `bun run build` emits
|
|
8
|
-
# JavaScript, and only `dist/` crosses into the production stage
|
|
9
|
-
#
|
|
10
|
-
#
|
|
11
|
-
#
|
|
8
|
+
# JavaScript, and only `dist/` crosses into the production stage. Built for the
|
|
9
|
+
# target instead, the non-native leg of a `--platform linux/amd64,linux/arm64`
|
|
10
|
+
# build runs under QEMU, where bun >= 1.4 aborts with a JavaScriptCore allocator
|
|
11
|
+
# assertion and fails the multi-arch push.
|
|
12
12
|
#
|
|
13
13
|
# The constraint this assumes: the build stage produces platform-independent
|
|
14
14
|
# output. A stage that compiles a native addon needs the target-arch toolchain
|
|
15
15
|
# and cannot cross-compile this way — drop the flag there.
|
|
16
16
|
# ==============================================================================
|
|
17
|
-
FROM --platform=$BUILDPLATFORM oven/bun:1.4.
|
|
17
|
+
FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS build
|
|
18
18
|
|
|
19
19
|
WORKDIR /usr/src/app
|
|
20
20
|
|
|
@@ -34,59 +34,105 @@ RUN bun run build
|
|
|
34
34
|
|
|
35
35
|
|
|
36
36
|
# ==============================================================================
|
|
37
|
-
# Production Stage
|
|
37
|
+
# Production Dependencies Stage
|
|
38
38
|
#
|
|
39
|
-
#
|
|
40
|
-
#
|
|
41
|
-
#
|
|
39
|
+
# Installs the production dependency tree for the target platform. Every step
|
|
40
|
+
# here can run JavaScript — bunfig.toml's security scanner runs as a Bun
|
|
41
|
+
# program, and so do the OTel and musl-prune scripts — so the stage runs on
|
|
42
|
+
# $BUILDPLATFORM and cross-installs with `--os`/`--cpu`, which pick each
|
|
43
|
+
# platform-specific optional dependency (native bindings) for the target. Only
|
|
44
|
+
# `node_modules` leaves this stage.
|
|
45
|
+
#
|
|
46
|
+
# A clean image rather than `FROM build`: the build stage's node_modules holds
|
|
47
|
+
# devDependencies.
|
|
42
48
|
# ==============================================================================
|
|
43
|
-
FROM oven/bun:1.4.
|
|
49
|
+
FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS deps
|
|
44
50
|
|
|
45
51
|
WORKDIR /usr/src/app
|
|
46
52
|
|
|
47
|
-
#
|
|
48
|
-
#
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
#
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
#
|
|
60
|
-
|
|
53
|
+
# Copy dependency manifests. `bunfig.toml` rides along so every install below
|
|
54
|
+
# passes its release-age gate and security scanner, as a local install does.
|
|
55
|
+
COPY package.json bun.lock bunfig.toml ./
|
|
56
|
+
|
|
57
|
+
# The scanner bunfig.toml names is a devDependency, and Bun installs a missing
|
|
58
|
+
# scanner through the same production-filtered install, which omits it and
|
|
59
|
+
# aborts. Seed it from the build stage's full install instead. Remove this line,
|
|
60
|
+
# and the `rm` at the end of this stage, if bunfig.toml stops naming a scanner.
|
|
61
|
+
COPY --from=build /usr/src/app/node_modules/@socketsecurity/bun-security-scanner ./node_modules/@socketsecurity/bun-security-scanner
|
|
62
|
+
|
|
63
|
+
# Docker names the target architecture `amd64`/`arm64`; Bun's `--cpu` takes
|
|
64
|
+
# `x64`/`arm64`. Mapped once here, read by both installs below. `oven/bun`
|
|
65
|
+
# publishes only these two architectures, so any other target fails here.
|
|
66
|
+
ARG TARGETOS
|
|
67
|
+
ARG TARGETARCH
|
|
68
|
+
RUN case "$TARGETARCH" in \
|
|
69
|
+
amd64) echo x64 ;; \
|
|
70
|
+
arm64) echo arm64 ;; \
|
|
71
|
+
*) echo "Unsupported TARGETARCH '$TARGETARCH': expected amd64 or arm64" >&2; exit 1 ;; \
|
|
72
|
+
esac > .bun-cpu
|
|
61
73
|
|
|
62
74
|
# Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
|
|
63
75
|
# that are not needed in the final production image.
|
|
64
76
|
# `--omit=peer` drops the framework's optional peer tiers (test runner, service
|
|
65
77
|
# SDKs, parsers) that Bun would otherwise auto-install. Anything this server
|
|
66
78
|
# actually imports belongs in its own `dependencies`, so nothing needed at
|
|
67
|
-
# runtime is lost.
|
|
68
|
-
# install re-resolves the graph and pulls every optional peer back in.
|
|
79
|
+
# runtime is lost.
|
|
69
80
|
RUN --mount=type=cache,target=/root/.bun/install/cache \
|
|
70
|
-
bun install --production --omit=peer --frozen-lockfile --ignore-scripts
|
|
81
|
+
bun install --production --omit=peer --frozen-lockfile --ignore-scripts \
|
|
82
|
+
--os="$TARGETOS" --cpu="$(cat .bun-cpu)"
|
|
71
83
|
|
|
72
84
|
# Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
|
|
73
|
-
#
|
|
74
|
-
# with: docker build --build-arg OTEL_ENABLED=
|
|
85
|
+
# Installed by default. Omit them for a leaner image at build time
|
|
86
|
+
# with: docker build --build-arg OTEL_ENABLED=false
|
|
87
|
+
# The script reads the list and each range from the installed framework's
|
|
88
|
+
# `peerDependencies` and passes the target flags on to its `bun install`.
|
|
89
|
+
COPY scripts/install-otel.ts ./scripts/
|
|
75
90
|
ARG OTEL_ENABLED=true
|
|
76
91
|
RUN --mount=type=cache,target=/root/.bun/install/cache \
|
|
77
92
|
if [ "$OTEL_ENABLED" = "true" ]; then \
|
|
78
|
-
bun
|
|
79
|
-
@opentelemetry/instrumentation-http \
|
|
80
|
-
@opentelemetry/exporter-metrics-otlp-http \
|
|
81
|
-
@opentelemetry/exporter-trace-otlp-http \
|
|
82
|
-
@opentelemetry/instrumentation-pino \
|
|
83
|
-
@opentelemetry/resources \
|
|
84
|
-
@opentelemetry/sdk-metrics \
|
|
85
|
-
@opentelemetry/sdk-node \
|
|
86
|
-
@opentelemetry/sdk-trace-node \
|
|
87
|
-
@opentelemetry/semantic-conventions; \
|
|
93
|
+
bun scripts/install-otel.ts --os="$TARGETOS" --cpu="$(cat .bun-cpu)"; \
|
|
88
94
|
fi
|
|
89
95
|
|
|
96
|
+
# `--os`/`--cpu` have no libc counterpart, so a native dependency published in
|
|
97
|
+
# glibc and musl variants installs both. The runtime image is Debian (glibc)
|
|
98
|
+
# and never loads the musl copy; the script deletes every package whose own
|
|
99
|
+
# `libc` admits only musl. It follows every install, since a later
|
|
100
|
+
# `bun install` restores what it removes.
|
|
101
|
+
COPY scripts/prune-musl-packages.ts ./scripts/
|
|
102
|
+
RUN bun scripts/prune-musl-packages.ts
|
|
103
|
+
|
|
104
|
+
# The seeded scanner served only the installs above; keep it out of the image.
|
|
105
|
+
RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
# ==============================================================================
|
|
109
|
+
# Production Stage
|
|
110
|
+
#
|
|
111
|
+
# This stage creates a minimal, optimized, and secure image for running the
|
|
112
|
+
# application. It uses a slim base image and only includes production
|
|
113
|
+
# dependencies and build artifacts. Its only Bun invocations are HEALTHCHECK
|
|
114
|
+
# and CMD, which run on the real target at container start.
|
|
115
|
+
# ==============================================================================
|
|
116
|
+
FROM oven/bun:1.4.2-slim AS production
|
|
117
|
+
|
|
118
|
+
WORKDIR /usr/src/app
|
|
119
|
+
|
|
120
|
+
# Set the environment to production for performance.
|
|
121
|
+
ENV NODE_ENV=production
|
|
122
|
+
|
|
123
|
+
# OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
|
|
124
|
+
ARG APP_VERSION
|
|
125
|
+
LABEL org.opencontainers.image.title="@cyanheads/biorxiv-mcp-server"
|
|
126
|
+
LABEL org.opencontainers.image.description="Search and retrieve bioRxiv and medRxiv preprints — by DOI, date interval, or keyword — via MCP. STDIO or Streamable HTTP."
|
|
127
|
+
LABEL org.opencontainers.image.licenses="Apache-2.0"
|
|
128
|
+
LABEL org.opencontainers.image.version="${APP_VERSION}"
|
|
129
|
+
LABEL org.opencontainers.image.source="https://github.com/cyanheads/biorxiv-mcp-server"
|
|
130
|
+
|
|
131
|
+
# The manifest comes from the build context: the deps stage's copy was rewritten
|
|
132
|
+
# by the OTel install, and the runtime reads only its name, version, and type.
|
|
133
|
+
COPY package.json ./
|
|
134
|
+
COPY --from=deps /usr/src/app/node_modules ./node_modules
|
|
135
|
+
|
|
90
136
|
# Copy the compiled application code from the build stage
|
|
91
137
|
COPY --from=build /usr/src/app/dist ./dist
|
|
92
138
|
|
|
@@ -111,7 +157,6 @@ ENV MCP_TRANSPORT_TYPE="http"
|
|
|
111
157
|
ENV MCP_SESSION_MODE="stateless"
|
|
112
158
|
ENV MCP_LOG_LEVEL="info"
|
|
113
159
|
ENV LOGS_DIR="/var/log/biorxiv-mcp-server"
|
|
114
|
-
ENV MCP_FORCE_CONSOLE_LOGGING="true"
|
|
115
160
|
|
|
116
161
|
# Expose the port the server listens on
|
|
117
162
|
EXPOSE ${MCP_HTTP_PORT}
|