@cyanheads/cern-inspire-mcp-server 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/AGENTS.md +39 -39
  2. package/CLAUDE.md +39 -39
  3. package/Dockerfile +8 -3
  4. package/README.md +59 -115
  5. package/changelog/0.1.x/0.1.3.md +34 -0
  6. package/changelog/0.2.x/0.2.0.md +35 -0
  7. package/dist/index.js +2 -1
  8. package/dist/index.js.map +1 -1
  9. package/dist/mcp-server/resources/definitions/index.d.ts +10 -0
  10. package/dist/mcp-server/resources/definitions/index.d.ts.map +1 -1
  11. package/dist/mcp-server/resources/definitions/inspire-literature.resource.d.ts +10 -0
  12. package/dist/mcp-server/resources/definitions/inspire-literature.resource.d.ts.map +1 -1
  13. package/dist/mcp-server/resources/definitions/inspire-literature.resource.js +1 -1
  14. package/dist/mcp-server/resources/definitions/inspire-literature.resource.js.map +1 -1
  15. package/dist/mcp-server/tools/definitions/export-citations.tool.d.ts +48 -4
  16. package/dist/mcp-server/tools/definitions/export-citations.tool.d.ts.map +1 -1
  17. package/dist/mcp-server/tools/definitions/export-citations.tool.js +51 -25
  18. package/dist/mcp-server/tools/definitions/export-citations.tool.js.map +1 -1
  19. package/dist/mcp-server/tools/definitions/get-citation-summary.tool.d.ts +2 -2
  20. package/dist/mcp-server/tools/definitions/get-citation-summary.tool.d.ts.map +1 -1
  21. package/dist/mcp-server/tools/definitions/get-citation-summary.tool.js +10 -7
  22. package/dist/mcp-server/tools/definitions/get-citation-summary.tool.js.map +1 -1
  23. package/dist/mcp-server/tools/definitions/get-paper.tool.d.ts +22 -1
  24. package/dist/mcp-server/tools/definitions/get-paper.tool.d.ts.map +1 -1
  25. package/dist/mcp-server/tools/definitions/get-paper.tool.js +79 -23
  26. package/dist/mcp-server/tools/definitions/get-paper.tool.js.map +1 -1
  27. package/dist/mcp-server/tools/definitions/index.d.ts +146 -91
  28. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  29. package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts.map +1 -1
  30. package/dist/mcp-server/tools/definitions/list-reference.tool.js +6 -1
  31. package/dist/mcp-server/tools/definitions/list-reference.tool.js.map +1 -1
  32. package/dist/mcp-server/tools/definitions/search-authors.tool.d.ts.map +1 -1
  33. package/dist/mcp-server/tools/definitions/search-authors.tool.js +7 -3
  34. package/dist/mcp-server/tools/definitions/search-authors.tool.js.map +1 -1
  35. package/dist/mcp-server/tools/definitions/search-experiments.tool.d.ts.map +1 -1
  36. package/dist/mcp-server/tools/definitions/search-experiments.tool.js +17 -10
  37. package/dist/mcp-server/tools/definitions/search-experiments.tool.js.map +1 -1
  38. package/dist/mcp-server/tools/definitions/search-hepdata.tool.d.ts +1 -1
  39. package/dist/mcp-server/tools/definitions/search-hepdata.tool.d.ts.map +1 -1
  40. package/dist/mcp-server/tools/definitions/search-hepdata.tool.js +8 -6
  41. package/dist/mcp-server/tools/definitions/search-hepdata.tool.js.map +1 -1
  42. package/dist/mcp-server/tools/definitions/search-literature.tool.d.ts +3 -3
  43. package/dist/mcp-server/tools/definitions/search-literature.tool.d.ts.map +1 -1
  44. package/dist/mcp-server/tools/definitions/search-literature.tool.js +16 -11
  45. package/dist/mcp-server/tools/definitions/search-literature.tool.js.map +1 -1
  46. package/dist/mcp-server/tools/inputs.d.ts +6 -0
  47. package/dist/mcp-server/tools/inputs.d.ts.map +1 -1
  48. package/dist/mcp-server/tools/inputs.js +71 -0
  49. package/dist/mcp-server/tools/inputs.js.map +1 -1
  50. package/dist/services/inspire/inspire-service.d.ts +11 -3
  51. package/dist/services/inspire/inspire-service.d.ts.map +1 -1
  52. package/dist/services/inspire/inspire-service.js +58 -37
  53. package/dist/services/inspire/inspire-service.js.map +1 -1
  54. package/dist/services/inspire/normalize.d.ts +3 -2
  55. package/dist/services/inspire/normalize.d.ts.map +1 -1
  56. package/dist/services/inspire/normalize.js +23 -3
  57. package/dist/services/inspire/normalize.js.map +1 -1
  58. package/dist/services/inspire/types.d.ts +27 -7
  59. package/dist/services/inspire/types.d.ts.map +1 -1
  60. package/dist/utils/render.d.ts +6 -4
  61. package/dist/utils/render.d.ts.map +1 -1
  62. package/dist/utils/render.js +8 -4
  63. package/dist/utils/render.js.map +1 -1
  64. package/package.json +12 -11
  65. package/server.json +10 -24
  66. package/skills/cern-inspire-guide/SKILL.md +43 -0
package/AGENTS.md CHANGED
@@ -1,11 +1,11 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** cern-inspire-mcp-server
4
- **Version:** 0.1.2
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.10`
4
+ **Version:** 0.2.0
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`
6
6
  **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` ^2.1.0
8
- **Zod:** ^4.6.5
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
8
+ **Zod:** ^4.6.7
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
 
@@ -15,19 +15,21 @@
15
15
 
16
16
  ## Domain
17
17
 
18
- Eight read-only tools and one resource over INSPIRE-HEP's keyless REST API (`https://inspirehep.net/api`). HEPData is reached only through INSPIRE's `data` collection; no request goes to hepdata.net, whose bot challenge refuses the server's User-Agent (design § Design Decisions #1). So the server reads no table values: `cern_inspire_get_paper` and `cern_inspire_search_hepdata` report each HEPData record's DOI, latest version, table count, and hepdata.net link.
18
+ Eight read-only tools, one literature resource template, and one published agent skill over INSPIRE-HEP's keyless REST API (`https://inspirehep.net/api`). HEPData is reached only through INSPIRE's `data` collection; no request goes to hepdata.net, whose bot challenge refuses the server's User-Agent (design § Design Decisions #1). So the server reads no table values: `cern_inspire_get_paper` and `cern_inspire_search_hepdata` report each HEPData record's DOI, latest version, table count, and hepdata.net link.
19
19
 
20
20
  | Upstream path | Used by |
21
21
  |:--------------|:--------|
22
22
  | `/literature` (search, `fields`-selected) | `cern_inspire_search_literature`, `cern_inspire_get_paper` (arXiv and DOI resolution included), `inspire://literature/{recid}` |
23
23
  | `/literature/<recid>` (redirects not followed, after a `recid:N` search returns no hit: where INSPIRE sends a merged recid) | `cern_inspire_get_paper`, `inspire://literature/{recid}` |
24
- | `/literature` with `format=` (`bibtex`, `latex-eu`, `latex-us`), plus a `fields=control_number` search for the match total on a later page | `cern_inspire_export_citations` |
24
+ | `/literature` with `format=` (`bibtex`, `latex-eu`, `latex-us`), plus a `fields=control_number` selection check on filtered first pages and every later page | `cern_inspire_export_citations` |
25
25
  | `/literature/facets` (`facet_name=citation-summary`, plus `citations-by-year` in parallel unless a year bound or the self-citation exclusion is set) | `cern_inspire_get_citation_summary` |
26
26
  | `/authors` | `cern_inspire_search_authors`, author resolution in `cern_inspire_get_citation_summary` |
27
27
  | `/experiments` | `cern_inspire_search_experiments` |
28
28
  | `/data` | `cern_inspire_search_hepdata`, the `hepdata` block of `cern_inspire_get_paper` |
29
29
 
30
- `cern_inspire_list_reference` serves static tables and makes no upstream call. There are no prompts.
30
+ `cern_inspire_list_reference` serves static tables and makes no upstream call. There are no prompts. `skills/cern-inspire-guide/SKILL.md` ships through plugins, npm, Docker, and MCPB; `createApp({ skills: 'skills' })` serves `skills/list`, `skills/get`, `resources/directory/read`, the `skill://{+path}` template, and `skill://cern-inspire-guide/SKILL.md` in `resources/list`.
31
+
32
+ Literature search, citation summaries, and citation export reject empty standalone recognized field clauses, including empty or whitespace-only quoted values (`a:""`), before upstream I/O through the shared quote-aware `hasEmptyQueryField` guard, using `invalid_query`; value negation, groups, quoted text, metadata paths and nested colon selectors remain valid. This is not complete grammar validation. Citation export reuses search's facet/year inputs, AND semantics and `appliedFilters` echo; identical `facetParams` accompany its text page and required count lookup. Literature search verifies filtered selections and later pages; export verifies filtered first pages and later pages. The parallel `fields=control_number` count detects reference fallback through reappearing required `titles`: filtered fallback means zero selected matches, while unfiltered fallback retains its total. Pages at or beyond that total are discarded. A required count failure fails the call. Unfiltered first pages retain one request (export probes effective size + 1). Reversed year bounds fail as `invalid_year_range` before requests.
31
33
 
32
34
  `InspireService` (`src/services/inspire/inspire-service.ts`) owns every request: one process-wide pacer under INSPIRE's published 15 requests per 5 s per address (`limits: [{ requests: 12, perMs: 5_000 }]`, `maxConcurrent: 4`, a cooldown after a `429`), a series gate that lets at most two citations-by-year requests into that pacer at once (`maxConcurrent: 2`, since one holds a slot for up to 15 s), `withRetry` outside the pacer (2 retries), one 55 s budget per tool call opened by `beginCall(ctx)` and threaded through every request in the call, an 8 MiB byte ceiling through `fetchBounded` (`src/services/http/fetch-bounded.ts`), and a strict query-parameter allowlist, since INSPIRE silently ignores unknown parameters. There is no cache and no server-specific env var.
33
35
 
@@ -37,8 +39,11 @@ Conventions every definition follows:
37
39
  - **Honest User-Agent only.** `cern-inspire-mcp-server/<version> (+https://github.com/cyanheads/cern-inspire-mcp-server)`. Never add a `curl`, `Wget`, or `python-requests` token, and send nothing to hepdata.net.
38
40
  - **Never request `email_addresses`.** INSPIRE's terms bar collecting them in bulk; the author `fields` list leaves them out.
39
41
  - **Shared inputs** live in `src/mcp-server/tools/inputs.ts`: `blankAsUnset` wraps every optional or defaulted input; `paperInput`, `documentTypesInput` / `subjectsInput` (array or comma-joined string, case-folded, up to 4, values AND together), `yearFromInput` / `yearToInput`, `authorQueryInput` / `authorIdInput`, and the `formatAppliedFilters` echo. The advertised `inputSchema` must admit every spelling a description documents, and the input must parse it: `paperInput` checks its pattern in a `.refine()`, never `.regex()`, its description names the scheme on every URL form, and the facet descriptions document only the enum array (design § Design Decisions #31).
42
+ - **Contributor dossier.** `authors[]` retains optional recorded `roles` without inferring an author role; `authorCount` remains upstream `author_count`, falling back to the normalized available contributor-list length. `documents[]` carries public attached-document URL and optional filename, description, material, and fulltext; omit hidden:true and URL-less entries, preserve fulltext:false, and never download files. Select only the six `documents.*` projections (including hidden), never the whole object or attachment content.
43
+ - **Result budgets.** Positive integer size/limit inputs above their ceilings clamp with requested/effective notices, even for empty or short results: literature 100, HEPData and export 50, author and experiment search 25. Defaults and blank handling stay unchanged; zero, negative, fractional, and wrong-type inputs fail. All paging arithmetic, window checks, output size, and continuation use the effective budget.
44
+ - **Contributor paging.** `max_authors` accepts nonnegative integers (default/blank 25), clamped to 500 with a notice. `author_offset` is zero-based (default/blank 0) and slices the normalized available contributor list. Echo `authorOffset` and optional `nextAuthorOffset` on both surfaces; issue continuation only with positive progress and available contributors remaining. Never derive continuation from `authorCount`; zero budget advises a positive budget. The resource remains first 25 at offset 0.
40
45
  - **Placeholders the server writes** in a notice, an `errors[]` recovery hint, or `format()` text outside a code span are uppercase words (`"t WORDS"`, `"a NAME"`, `collaborations.value:NAME`), never `<…>`, which a client rendering markdown to HTML drops as a tag. A code span prints `<…>` as written (list_reference's `HEPData ins<recid>` term), and `.describe()` text and the server instructions reach `tools/list` and `initialize`, not rendered markdown.
41
- - **Upstream text is data.** Every upstream or caller string in `format()` goes through `inline()`, `cell()`, `quote()`, `fenced()`, or `printUrl()` from `src/utils/render.ts`, and a list item that opens with one wraps it in `atLineStart()`; outside a `quote()` or `fenced()` block, no other line opens with upstream text. A caller's own query, author, or paper identifier echoed in a notice or error message goes through `callerEcho()`, which leaves `*`, `_`, `~`, and `>` as written so the echo can be sent back, and entity-encodes only a `<` that could open a tag, comment, or autolink; an identifier value a caller copies (DOI, record DOI, report number, texkey, arXiv ID, BAI, ORCID, INSPIRE ID, other ID) goes through `identifier()`, the same rules. `structuredContent` keeps each string as received with two exceptions: the service drops Unicode tag characters at decode, and `normalize.ts` converts titles and abstracts from publisher HTML/JATS/MathML to text with `markupToText()` (LaTeX left as published).
46
+ - **Upstream text is data.** Every upstream or caller string in `format()` goes through `inline()`, `cell()`, `quote()`, `fenced()`, or `printUrl()` from `src/utils/render.ts`, and a list item that opens with one wraps it in `atLineStart()`; outside a `quote()` or `fenced()` block, no other line opens with upstream text. A caller's own query, author, or paper identifier echoed in a notice goes through `callerEcho()`, which leaves `*`, `_`, `~`, and `>` as written so the echo can be sent back, and entity-encodes only a `<` that could open a tag, comment, or autolink; an identifier value a caller copies (DOI, record DOI, report number, texkey, arXiv ID, BAI, ORCID, INSPIRE ID, other ID) goes through `identifier()`, the same rules. Error messages use `errorText()` for line/control hygiene before the framework escapes Markdown once. `structuredContent` keeps each string as received with two exceptions: the service drops Unicode tag characters at decode, and `normalize.ts` converts titles and abstracts from publisher HTML/JATS/MathML to text with `markupToText()` (LaTeX left as published).
42
47
  - **Required enrichment first.** A handler writes its required enrichment fields (`truncated` / `shown` / `cap`, `totalCount`, the echo strings) with neutral values before its first upstream call or branch, then overwrites them where the real value is known.
43
48
  - **Errors.** Every tool that reaches INSPIRE declares `inspire_rate_limited`, `pacer_shed`, and `upstream_unreadable` inline (`thrownBy: 'service'`), plus `invalid_query` when it sends a caller query; the resource declares the first three. Handler-side reasons (`paper_not_found`, `beyond_result_window`, `invalid_year_range`, `missing_target`, `author_not_identifier`, `author_not_found`) are thrown through `ctx.fail`, and tools mark caller-input reasons `severity: 'notice'`.
44
49
  - **No fabrication.** A field INSPIRE leaves out stays absent (`firstAuthor`, `ongoing`, `averageCitations`), and `format()` prints "Not available" or "not recorded" rather than a guess.
@@ -95,16 +100,19 @@ export const getPaperTool = tool('cern_inspire_get_paper', {
95
100
  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
96
101
  input: z.object({
97
102
  paper: paperInput, // shared input: recid, arXiv ID, DOI, or URL forms, normalized in preprocess
98
- max_authors: blankAsUnset(z.number().int().min(0).max(500).default(25)).describe(
99
- 'Most authors to list (0–500, default 25). The full count is always in authorCount.',
103
+ max_authors: blankAsUnset(z.number().int().min(0).default(25)).describe(
104
+ 'Most contributors to list (nonnegative integer, default 25; above 500 uses 500). The upstream contributor count is in authorCount.',
105
+ ),
106
+ author_offset: blankAsUnset(z.number().int().min(0).default(0)).describe(
107
+ 'Zero-based position in the normalized available contributor list; use nextAuthorOffset to continue.',
100
108
  ),
101
109
  }),
102
110
  output: paperDossierSchema, // also the inspire://literature/{recid} resource's output
103
111
  enrichment: {
104
- truncated: z.boolean().describe('True when the author list was capped at max_authors.'),
105
- shown: z.number().describe('Number of authors listed.'),
112
+ truncated: z.boolean().describe('True when available contributors remain after this page.'),
113
+ shown: z.number().describe('Number of contributors listed.'),
106
114
  cap: z.number().describe('The max_authors cap applied.'),
107
- notice: z.string().optional().describe('Guidance when the author list was capped or HEPData availability could not be checked.'),
115
+ notice: z.string().optional().describe('Guidance when the contributor list was capped or HEPData availability could not be checked.'),
108
116
  },
109
117
  errors: [
110
118
  {
@@ -117,27 +125,8 @@ export const getPaperTool = tool('cern_inspire_get_paper', {
117
125
  // inspire_rate_limited, pacer_shed, upstream_unreadable: declared inline, thrownBy: 'service'
118
126
  ],
119
127
 
120
- async handler(input, ctx) {
121
- ctx.enrich({ truncated: false, shown: 0, cap: input.max_authors }); // required enrichment first
122
-
123
- const inspire = getInspireService();
124
- const lookup = await inspire.getPaper(input.paper, input.max_authors, inspire.beginCall(ctx));
125
- if (!lookup) {
126
- throw ctx.fail('paper_not_found', `No INSPIRE literature record matches "${inline(input.paper)}".`, {
127
- paper: input.paper,
128
- });
129
- }
130
- const { paper, authorsInRecord } = lookup;
131
- ctx.enrich({ shown: paper.authors.length });
132
- if (authorsInRecord > input.max_authors) {
133
- ctx.enrich.truncated({
134
- shown: paper.authors.length,
135
- cap: input.max_authors,
136
- guidance: `Showing ${paper.authors.length} of ${authorsInRecord} authors; raise max_authors (up to 500) to list more.`,
137
- });
138
- }
139
- return paper;
140
- },
128
+ // See get-paper.tool.ts for the handler: clamp the budget to 500, apply
129
+ // author_offset after normalization, and compose paging, merge and HEPData notices.
141
130
 
142
131
  // format() is the content[] twin of structuredContent: every output field renders,
143
132
  // and every upstream string passes through inline() / quote() / printUrl().
@@ -217,6 +206,7 @@ await createApp({
217
206
  title: 'cern-inspire-mcp-server', // display identity is the machine name; lint:packaging checks the pair
218
207
  tools: allToolDefinitions,
219
208
  resources: allResourceDefinitions,
209
+ skills: 'skills',
220
210
  instructions: 'cern-inspire-mcp-server reads INSPIRE-HEP (inspirehep.net), …', // abridged
221
211
  setup(core) {
222
212
  initInspireService(core.config); // the User-Agent carries core.config.mcpServerVersion
@@ -322,7 +312,7 @@ src/
322
312
  types.ts # Raw upstream and normalized domain types
323
313
  vocabulary.ts # Document types, subjects, citation-bucket ranges
324
314
  utils/
325
- render.ts # inline / cell / quote / fenced / printUrl / atLineStart / callerEcho for upstream and caller text in format(), notices, and error messages
315
+ render.ts # Output renderers and callerEcho for format()/notices; errorText before framework error escaping
326
316
  tests/
327
317
  fixtures/ # INSPIRE bodies, service harness, shared failure suite, result readers
328
318
  tools/ resources/ services/ shared/ # Suites mirroring src/
@@ -345,9 +335,18 @@ docs/
345
335
 
346
336
  ## Skills
347
337
 
348
- 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.
338
+ Two skill trees live at the project root, written for different readers:
339
+
340
+ | Tree | For | Written by |
341
+ |:-----|:----|:-----------|
342
+ | `framework-skills/` | The agent developing this server — framework skills (`metadata.audience: external`) plus any development-time skills of the server's own | `init` and the `maintenance` sync (framework skills); you (your own) |
343
+ | `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | `cern-inspire-guide`, authored with `add-skill` |
344
+
345
+ Development skills are modular instructions. 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. Their 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 them to every agent that installs it.
346
+
347
+ A published skill in root `skills/` reaches plugin installs and the `.mcpb` bundle as-is, ships in the npm package and the Docker image, and reaches MCP clients when the server opts in with `createApp({ skills: 'skills' })`. `lint:packaging` validates the tree.
349
348
 
350
- **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.
349
+ **Agent skill directory:** Copy `framework-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.
351
350
 
352
351
  Available skills:
353
352
 
@@ -359,6 +358,7 @@ Available skills:
359
358
  | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
360
359
  | `add-resource` | Scaffold a new resource definition |
361
360
  | `add-prompt` | Scaffold a new prompt definition |
361
+ | `add-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |
362
362
  | `add-service` | Scaffold a new service integration |
363
363
  | `add-test` | Scaffold test file for a tool, resource, or service |
364
364
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
@@ -428,7 +428,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
428
428
 
429
429
  ## Bundling
430
430
 
431
- `npm 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. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
431
+ `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. `mcpb pack` reads `.mcpbignore`, not `.gitignore`, so every root path the bundle must not ship — source, tests, docs, caches, logs, agent docs, plugin manifests, gitignored local files — needs a root-anchored line there (`/docs/`, never `docs/`, which also strips `node_modules/*/docs/`); `lint:packaging` names each missing or unanchored line. Root `skills/` ships on purpose. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips four classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`); platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on; node-gyp build output beside a `binding.gyp` (`config.gypi`, Makefiles, `obj.target/`, `.deps/`, object files and debug symbols), which records the packing machine's paths — compiled `*.node` addons stay; and build-only package files — the framework's `changelog/`, `scripts/`, `templates/`, `CLAUDE.md`, `AGENTS.md`, and config bases (`biome.json`, `vitest.config.base.mjs`, `config/tsconfig.base.json`), and `better-sqlite3`'s `deps/` and `src/` C sources. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
432
432
 
433
433
  **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": ""`.
434
434
 
@@ -465,7 +465,7 @@ security: false # optional — true ONLY for a source
465
465
 
466
466
  ## Publishing
467
467
 
468
- **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `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-and-publish` then 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. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **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.
468
+ **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `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-and-publish` then 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. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **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.
469
469
 
470
470
  ---
471
471
 
package/CLAUDE.md CHANGED
@@ -1,11 +1,11 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** cern-inspire-mcp-server
4
- **Version:** 0.1.2
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.10`
4
+ **Version:** 0.2.0
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`
6
6
  **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` ^2.1.0
8
- **Zod:** ^4.6.5
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
8
+ **Zod:** ^4.6.7
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
 
@@ -15,19 +15,21 @@
15
15
 
16
16
  ## Domain
17
17
 
18
- Eight read-only tools and one resource over INSPIRE-HEP's keyless REST API (`https://inspirehep.net/api`). HEPData is reached only through INSPIRE's `data` collection; no request goes to hepdata.net, whose bot challenge refuses the server's User-Agent (design § Design Decisions #1). So the server reads no table values: `cern_inspire_get_paper` and `cern_inspire_search_hepdata` report each HEPData record's DOI, latest version, table count, and hepdata.net link.
18
+ Eight read-only tools, one literature resource template, and one published agent skill over INSPIRE-HEP's keyless REST API (`https://inspirehep.net/api`). HEPData is reached only through INSPIRE's `data` collection; no request goes to hepdata.net, whose bot challenge refuses the server's User-Agent (design § Design Decisions #1). So the server reads no table values: `cern_inspire_get_paper` and `cern_inspire_search_hepdata` report each HEPData record's DOI, latest version, table count, and hepdata.net link.
19
19
 
20
20
  | Upstream path | Used by |
21
21
  |:--------------|:--------|
22
22
  | `/literature` (search, `fields`-selected) | `cern_inspire_search_literature`, `cern_inspire_get_paper` (arXiv and DOI resolution included), `inspire://literature/{recid}` |
23
23
  | `/literature/<recid>` (redirects not followed, after a `recid:N` search returns no hit: where INSPIRE sends a merged recid) | `cern_inspire_get_paper`, `inspire://literature/{recid}` |
24
- | `/literature` with `format=` (`bibtex`, `latex-eu`, `latex-us`), plus a `fields=control_number` search for the match total on a later page | `cern_inspire_export_citations` |
24
+ | `/literature` with `format=` (`bibtex`, `latex-eu`, `latex-us`), plus a `fields=control_number` selection check on filtered first pages and every later page | `cern_inspire_export_citations` |
25
25
  | `/literature/facets` (`facet_name=citation-summary`, plus `citations-by-year` in parallel unless a year bound or the self-citation exclusion is set) | `cern_inspire_get_citation_summary` |
26
26
  | `/authors` | `cern_inspire_search_authors`, author resolution in `cern_inspire_get_citation_summary` |
27
27
  | `/experiments` | `cern_inspire_search_experiments` |
28
28
  | `/data` | `cern_inspire_search_hepdata`, the `hepdata` block of `cern_inspire_get_paper` |
29
29
 
30
- `cern_inspire_list_reference` serves static tables and makes no upstream call. There are no prompts.
30
+ `cern_inspire_list_reference` serves static tables and makes no upstream call. There are no prompts. `skills/cern-inspire-guide/SKILL.md` ships through plugins, npm, Docker, and MCPB; `createApp({ skills: 'skills' })` serves `skills/list`, `skills/get`, `resources/directory/read`, the `skill://{+path}` template, and `skill://cern-inspire-guide/SKILL.md` in `resources/list`.
31
+
32
+ Literature search, citation summaries, and citation export reject empty standalone recognized field clauses, including empty or whitespace-only quoted values (`a:""`), before upstream I/O through the shared quote-aware `hasEmptyQueryField` guard, using `invalid_query`; value negation, groups, quoted text, metadata paths and nested colon selectors remain valid. This is not complete grammar validation. Citation export reuses search's facet/year inputs, AND semantics and `appliedFilters` echo; identical `facetParams` accompany its text page and required count lookup. Literature search verifies filtered selections and later pages; export verifies filtered first pages and later pages. The parallel `fields=control_number` count detects reference fallback through reappearing required `titles`: filtered fallback means zero selected matches, while unfiltered fallback retains its total. Pages at or beyond that total are discarded. A required count failure fails the call. Unfiltered first pages retain one request (export probes effective size + 1). Reversed year bounds fail as `invalid_year_range` before requests.
31
33
 
32
34
  `InspireService` (`src/services/inspire/inspire-service.ts`) owns every request: one process-wide pacer under INSPIRE's published 15 requests per 5 s per address (`limits: [{ requests: 12, perMs: 5_000 }]`, `maxConcurrent: 4`, a cooldown after a `429`), a series gate that lets at most two citations-by-year requests into that pacer at once (`maxConcurrent: 2`, since one holds a slot for up to 15 s), `withRetry` outside the pacer (2 retries), one 55 s budget per tool call opened by `beginCall(ctx)` and threaded through every request in the call, an 8 MiB byte ceiling through `fetchBounded` (`src/services/http/fetch-bounded.ts`), and a strict query-parameter allowlist, since INSPIRE silently ignores unknown parameters. There is no cache and no server-specific env var.
33
35
 
@@ -37,8 +39,11 @@ Conventions every definition follows:
37
39
  - **Honest User-Agent only.** `cern-inspire-mcp-server/<version> (+https://github.com/cyanheads/cern-inspire-mcp-server)`. Never add a `curl`, `Wget`, or `python-requests` token, and send nothing to hepdata.net.
38
40
  - **Never request `email_addresses`.** INSPIRE's terms bar collecting them in bulk; the author `fields` list leaves them out.
39
41
  - **Shared inputs** live in `src/mcp-server/tools/inputs.ts`: `blankAsUnset` wraps every optional or defaulted input; `paperInput`, `documentTypesInput` / `subjectsInput` (array or comma-joined string, case-folded, up to 4, values AND together), `yearFromInput` / `yearToInput`, `authorQueryInput` / `authorIdInput`, and the `formatAppliedFilters` echo. The advertised `inputSchema` must admit every spelling a description documents, and the input must parse it: `paperInput` checks its pattern in a `.refine()`, never `.regex()`, its description names the scheme on every URL form, and the facet descriptions document only the enum array (design § Design Decisions #31).
42
+ - **Contributor dossier.** `authors[]` retains optional recorded `roles` without inferring an author role; `authorCount` remains upstream `author_count`, falling back to the normalized available contributor-list length. `documents[]` carries public attached-document URL and optional filename, description, material, and fulltext; omit hidden:true and URL-less entries, preserve fulltext:false, and never download files. Select only the six `documents.*` projections (including hidden), never the whole object or attachment content.
43
+ - **Result budgets.** Positive integer size/limit inputs above their ceilings clamp with requested/effective notices, even for empty or short results: literature 100, HEPData and export 50, author and experiment search 25. Defaults and blank handling stay unchanged; zero, negative, fractional, and wrong-type inputs fail. All paging arithmetic, window checks, output size, and continuation use the effective budget.
44
+ - **Contributor paging.** `max_authors` accepts nonnegative integers (default/blank 25), clamped to 500 with a notice. `author_offset` is zero-based (default/blank 0) and slices the normalized available contributor list. Echo `authorOffset` and optional `nextAuthorOffset` on both surfaces; issue continuation only with positive progress and available contributors remaining. Never derive continuation from `authorCount`; zero budget advises a positive budget. The resource remains first 25 at offset 0.
40
45
  - **Placeholders the server writes** in a notice, an `errors[]` recovery hint, or `format()` text outside a code span are uppercase words (`"t WORDS"`, `"a NAME"`, `collaborations.value:NAME`), never `<…>`, which a client rendering markdown to HTML drops as a tag. A code span prints `<…>` as written (list_reference's `HEPData ins<recid>` term), and `.describe()` text and the server instructions reach `tools/list` and `initialize`, not rendered markdown.
41
- - **Upstream text is data.** Every upstream or caller string in `format()` goes through `inline()`, `cell()`, `quote()`, `fenced()`, or `printUrl()` from `src/utils/render.ts`, and a list item that opens with one wraps it in `atLineStart()`; outside a `quote()` or `fenced()` block, no other line opens with upstream text. A caller's own query, author, or paper identifier echoed in a notice or error message goes through `callerEcho()`, which leaves `*`, `_`, `~`, and `>` as written so the echo can be sent back, and entity-encodes only a `<` that could open a tag, comment, or autolink; an identifier value a caller copies (DOI, record DOI, report number, texkey, arXiv ID, BAI, ORCID, INSPIRE ID, other ID) goes through `identifier()`, the same rules. `structuredContent` keeps each string as received with two exceptions: the service drops Unicode tag characters at decode, and `normalize.ts` converts titles and abstracts from publisher HTML/JATS/MathML to text with `markupToText()` (LaTeX left as published).
46
+ - **Upstream text is data.** Every upstream or caller string in `format()` goes through `inline()`, `cell()`, `quote()`, `fenced()`, or `printUrl()` from `src/utils/render.ts`, and a list item that opens with one wraps it in `atLineStart()`; outside a `quote()` or `fenced()` block, no other line opens with upstream text. A caller's own query, author, or paper identifier echoed in a notice goes through `callerEcho()`, which leaves `*`, `_`, `~`, and `>` as written so the echo can be sent back, and entity-encodes only a `<` that could open a tag, comment, or autolink; an identifier value a caller copies (DOI, record DOI, report number, texkey, arXiv ID, BAI, ORCID, INSPIRE ID, other ID) goes through `identifier()`, the same rules. Error messages use `errorText()` for line/control hygiene before the framework escapes Markdown once. `structuredContent` keeps each string as received with two exceptions: the service drops Unicode tag characters at decode, and `normalize.ts` converts titles and abstracts from publisher HTML/JATS/MathML to text with `markupToText()` (LaTeX left as published).
42
47
  - **Required enrichment first.** A handler writes its required enrichment fields (`truncated` / `shown` / `cap`, `totalCount`, the echo strings) with neutral values before its first upstream call or branch, then overwrites them where the real value is known.
43
48
  - **Errors.** Every tool that reaches INSPIRE declares `inspire_rate_limited`, `pacer_shed`, and `upstream_unreadable` inline (`thrownBy: 'service'`), plus `invalid_query` when it sends a caller query; the resource declares the first three. Handler-side reasons (`paper_not_found`, `beyond_result_window`, `invalid_year_range`, `missing_target`, `author_not_identifier`, `author_not_found`) are thrown through `ctx.fail`, and tools mark caller-input reasons `severity: 'notice'`.
44
49
  - **No fabrication.** A field INSPIRE leaves out stays absent (`firstAuthor`, `ongoing`, `averageCitations`), and `format()` prints "Not available" or "not recorded" rather than a guess.
@@ -95,16 +100,19 @@ export const getPaperTool = tool('cern_inspire_get_paper', {
95
100
  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
96
101
  input: z.object({
97
102
  paper: paperInput, // shared input: recid, arXiv ID, DOI, or URL forms, normalized in preprocess
98
- max_authors: blankAsUnset(z.number().int().min(0).max(500).default(25)).describe(
99
- 'Most authors to list (0–500, default 25). The full count is always in authorCount.',
103
+ max_authors: blankAsUnset(z.number().int().min(0).default(25)).describe(
104
+ 'Most contributors to list (nonnegative integer, default 25; above 500 uses 500). The upstream contributor count is in authorCount.',
105
+ ),
106
+ author_offset: blankAsUnset(z.number().int().min(0).default(0)).describe(
107
+ 'Zero-based position in the normalized available contributor list; use nextAuthorOffset to continue.',
100
108
  ),
101
109
  }),
102
110
  output: paperDossierSchema, // also the inspire://literature/{recid} resource's output
103
111
  enrichment: {
104
- truncated: z.boolean().describe('True when the author list was capped at max_authors.'),
105
- shown: z.number().describe('Number of authors listed.'),
112
+ truncated: z.boolean().describe('True when available contributors remain after this page.'),
113
+ shown: z.number().describe('Number of contributors listed.'),
106
114
  cap: z.number().describe('The max_authors cap applied.'),
107
- notice: z.string().optional().describe('Guidance when the author list was capped or HEPData availability could not be checked.'),
115
+ notice: z.string().optional().describe('Guidance when the contributor list was capped or HEPData availability could not be checked.'),
108
116
  },
109
117
  errors: [
110
118
  {
@@ -117,27 +125,8 @@ export const getPaperTool = tool('cern_inspire_get_paper', {
117
125
  // inspire_rate_limited, pacer_shed, upstream_unreadable: declared inline, thrownBy: 'service'
118
126
  ],
119
127
 
120
- async handler(input, ctx) {
121
- ctx.enrich({ truncated: false, shown: 0, cap: input.max_authors }); // required enrichment first
122
-
123
- const inspire = getInspireService();
124
- const lookup = await inspire.getPaper(input.paper, input.max_authors, inspire.beginCall(ctx));
125
- if (!lookup) {
126
- throw ctx.fail('paper_not_found', `No INSPIRE literature record matches "${inline(input.paper)}".`, {
127
- paper: input.paper,
128
- });
129
- }
130
- const { paper, authorsInRecord } = lookup;
131
- ctx.enrich({ shown: paper.authors.length });
132
- if (authorsInRecord > input.max_authors) {
133
- ctx.enrich.truncated({
134
- shown: paper.authors.length,
135
- cap: input.max_authors,
136
- guidance: `Showing ${paper.authors.length} of ${authorsInRecord} authors; raise max_authors (up to 500) to list more.`,
137
- });
138
- }
139
- return paper;
140
- },
128
+ // See get-paper.tool.ts for the handler: clamp the budget to 500, apply
129
+ // author_offset after normalization, and compose paging, merge and HEPData notices.
141
130
 
142
131
  // format() is the content[] twin of structuredContent: every output field renders,
143
132
  // and every upstream string passes through inline() / quote() / printUrl().
@@ -217,6 +206,7 @@ await createApp({
217
206
  title: 'cern-inspire-mcp-server', // display identity is the machine name; lint:packaging checks the pair
218
207
  tools: allToolDefinitions,
219
208
  resources: allResourceDefinitions,
209
+ skills: 'skills',
220
210
  instructions: 'cern-inspire-mcp-server reads INSPIRE-HEP (inspirehep.net), …', // abridged
221
211
  setup(core) {
222
212
  initInspireService(core.config); // the User-Agent carries core.config.mcpServerVersion
@@ -322,7 +312,7 @@ src/
322
312
  types.ts # Raw upstream and normalized domain types
323
313
  vocabulary.ts # Document types, subjects, citation-bucket ranges
324
314
  utils/
325
- render.ts # inline / cell / quote / fenced / printUrl / atLineStart / callerEcho for upstream and caller text in format(), notices, and error messages
315
+ render.ts # Output renderers and callerEcho for format()/notices; errorText before framework error escaping
326
316
  tests/
327
317
  fixtures/ # INSPIRE bodies, service harness, shared failure suite, result readers
328
318
  tools/ resources/ services/ shared/ # Suites mirroring src/
@@ -345,9 +335,18 @@ docs/
345
335
 
346
336
  ## Skills
347
337
 
348
- 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.
338
+ Two skill trees live at the project root, written for different readers:
339
+
340
+ | Tree | For | Written by |
341
+ |:-----|:----|:-----------|
342
+ | `framework-skills/` | The agent developing this server — framework skills (`metadata.audience: external`) plus any development-time skills of the server's own | `init` and the `maintenance` sync (framework skills); you (your own) |
343
+ | `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | `cern-inspire-guide`, authored with `add-skill` |
344
+
345
+ Development skills are modular instructions. 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. Their 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 them to every agent that installs it.
346
+
347
+ A published skill in root `skills/` reaches plugin installs and the `.mcpb` bundle as-is, ships in the npm package and the Docker image, and reaches MCP clients when the server opts in with `createApp({ skills: 'skills' })`. `lint:packaging` validates the tree.
349
348
 
350
- **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.
349
+ **Agent skill directory:** Copy `framework-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.
351
350
 
352
351
  Available skills:
353
352
 
@@ -359,6 +358,7 @@ Available skills:
359
358
  | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
360
359
  | `add-resource` | Scaffold a new resource definition |
361
360
  | `add-prompt` | Scaffold a new prompt definition |
361
+ | `add-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |
362
362
  | `add-service` | Scaffold a new service integration |
363
363
  | `add-test` | Scaffold test file for a tool, resource, or service |
364
364
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
@@ -428,7 +428,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
428
428
 
429
429
  ## Bundling
430
430
 
431
- `npm 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. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
431
+ `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. `mcpb pack` reads `.mcpbignore`, not `.gitignore`, so every root path the bundle must not ship — source, tests, docs, caches, logs, agent docs, plugin manifests, gitignored local files — needs a root-anchored line there (`/docs/`, never `docs/`, which also strips `node_modules/*/docs/`); `lint:packaging` names each missing or unanchored line. Root `skills/` ships on purpose. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips four classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`); platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on; node-gyp build output beside a `binding.gyp` (`config.gypi`, Makefiles, `obj.target/`, `.deps/`, object files and debug symbols), which records the packing machine's paths — compiled `*.node` addons stay; and build-only package files — the framework's `changelog/`, `scripts/`, `templates/`, `CLAUDE.md`, `AGENTS.md`, and config bases (`biome.json`, `vitest.config.base.mjs`, `config/tsconfig.base.json`), and `better-sqlite3`'s `deps/` and `src/` C sources. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
432
432
 
433
433
  **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": ""`.
434
434
 
@@ -465,7 +465,7 @@ security: false # optional — true ONLY for a source
465
465
 
466
466
  ## Publishing
467
467
 
468
- **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `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-and-publish` then 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. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **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.
468
+ **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `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-and-publish` then 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. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **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.
469
469
 
470
470
  ---
471
471
 
package/Dockerfile CHANGED
@@ -14,7 +14,7 @@
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.2 AS build
17
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS build
18
18
 
19
19
  WORKDIR /usr/src/app
20
20
 
@@ -28,6 +28,7 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
28
28
 
29
29
  # Copy the rest of the source code
30
30
  COPY . .
31
+ RUN mkdir -p skills
31
32
 
32
33
  # Build the application
33
34
  RUN bun run build
@@ -46,7 +47,7 @@ RUN bun run build
46
47
  # A clean image rather than `FROM build`: the build stage's node_modules holds
47
48
  # devDependencies.
48
49
  # ==============================================================================
49
- FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS deps
50
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS deps
50
51
 
51
52
  WORKDIR /usr/src/app
52
53
 
@@ -93,6 +94,9 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
93
94
  bun scripts/install-otel.ts --os="$TARGETOS" --cpu="$(cat .bun-cpu)"; \
94
95
  fi
95
96
 
97
+ COPY scripts/prune-musl-packages.ts ./scripts/
98
+ RUN bun scripts/prune-musl-packages.ts
99
+
96
100
  # The seeded scanner served only the installs above; keep it out of the image.
97
101
  RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
98
102
 
@@ -105,7 +109,7 @@ RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
105
109
  # dependencies and build artifacts. Its only Bun invocations are HEALTHCHECK
106
110
  # and CMD, which run on the real target at container start.
107
111
  # ==============================================================================
108
- FROM oven/bun:1.4.2-slim AS production
112
+ FROM oven/bun:1.4.4-slim AS production
109
113
 
110
114
  WORKDIR /usr/src/app
111
115
 
@@ -127,6 +131,7 @@ COPY --from=deps /usr/src/app/node_modules ./node_modules
127
131
 
128
132
  # Copy the compiled application code from the build stage
129
133
  COPY --from=build /usr/src/app/dist ./dist
134
+ COPY --from=build /usr/src/app/skills ./skills
130
135
 
131
136
  # Mirror CLI (MirrorService adopters only — Tier 3, opt-in):
132
137
  # Copy your mirror lifecycle scripts and emit a runtime tsconfig so Bun resolves