@cyanheads/cern-inspire-mcp-server 0.1.3 → 0.3.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 (80) hide show
  1. package/AGENTS.md +35 -20
  2. package/CLAUDE.md +35 -20
  3. package/Dockerfile +5 -3
  4. package/README.md +69 -120
  5. package/changelog/0.2.x/0.2.0.md +35 -0
  6. package/changelog/0.3.x/0.3.0.md +31 -0
  7. package/changelog/template.md +10 -3
  8. package/dist/index.js +2 -1
  9. package/dist/index.js.map +1 -1
  10. package/dist/mcp-server/resources/definitions/index.d.ts +28 -0
  11. package/dist/mcp-server/resources/definitions/index.d.ts.map +1 -1
  12. package/dist/mcp-server/resources/definitions/inspire-literature.resource.d.ts +28 -0
  13. package/dist/mcp-server/resources/definitions/inspire-literature.resource.d.ts.map +1 -1
  14. package/dist/mcp-server/resources/definitions/inspire-literature.resource.js +1 -1
  15. package/dist/mcp-server/resources/definitions/inspire-literature.resource.js.map +1 -1
  16. package/dist/mcp-server/tools/definitions/export-citations.tool.d.ts +2 -2
  17. package/dist/mcp-server/tools/definitions/export-citations.tool.d.ts.map +1 -1
  18. package/dist/mcp-server/tools/definitions/export-citations.tool.js +22 -31
  19. package/dist/mcp-server/tools/definitions/export-citations.tool.js.map +1 -1
  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 +11 -13
  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 +61 -3
  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 +136 -40
  26. package/dist/mcp-server/tools/definitions/get-paper.tool.js.map +1 -1
  27. package/dist/mcp-server/tools/definitions/index.d.ts +258 -142
  28. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  29. package/dist/mcp-server/tools/definitions/index.js +2 -0
  30. package/dist/mcp-server/tools/definitions/index.js.map +1 -1
  31. package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts.map +1 -1
  32. package/dist/mcp-server/tools/definitions/list-reference.tool.js +20 -10
  33. package/dist/mcp-server/tools/definitions/list-reference.tool.js.map +1 -1
  34. package/dist/mcp-server/tools/definitions/search-authors.tool.d.ts +17 -5
  35. package/dist/mcp-server/tools/definitions/search-authors.tool.d.ts.map +1 -1
  36. package/dist/mcp-server/tools/definitions/search-authors.tool.js +69 -25
  37. package/dist/mcp-server/tools/definitions/search-authors.tool.js.map +1 -1
  38. package/dist/mcp-server/tools/definitions/search-experiments.tool.d.ts +16 -5
  39. package/dist/mcp-server/tools/definitions/search-experiments.tool.d.ts.map +1 -1
  40. package/dist/mcp-server/tools/definitions/search-experiments.tool.js +72 -28
  41. package/dist/mcp-server/tools/definitions/search-experiments.tool.js.map +1 -1
  42. package/dist/mcp-server/tools/definitions/search-hepdata.tool.d.ts +3 -3
  43. package/dist/mcp-server/tools/definitions/search-hepdata.tool.d.ts.map +1 -1
  44. package/dist/mcp-server/tools/definitions/search-hepdata.tool.js +19 -15
  45. package/dist/mcp-server/tools/definitions/search-hepdata.tool.js.map +1 -1
  46. package/dist/mcp-server/tools/definitions/search-institutions.tool.d.ts +77 -0
  47. package/dist/mcp-server/tools/definitions/search-institutions.tool.d.ts.map +1 -0
  48. package/dist/mcp-server/tools/definitions/search-institutions.tool.js +228 -0
  49. package/dist/mcp-server/tools/definitions/search-institutions.tool.js.map +1 -0
  50. package/dist/mcp-server/tools/definitions/search-literature.tool.d.ts +1 -1
  51. package/dist/mcp-server/tools/definitions/search-literature.tool.d.ts.map +1 -1
  52. package/dist/mcp-server/tools/definitions/search-literature.tool.js +21 -20
  53. package/dist/mcp-server/tools/definitions/search-literature.tool.js.map +1 -1
  54. package/dist/mcp-server/tools/inputs.d.ts +34 -4
  55. package/dist/mcp-server/tools/inputs.d.ts.map +1 -1
  56. package/dist/mcp-server/tools/inputs.js +202 -7
  57. package/dist/mcp-server/tools/inputs.js.map +1 -1
  58. package/dist/services/http/fetch-bounded.d.ts +1 -1
  59. package/dist/services/http/fetch-bounded.js +1 -1
  60. package/dist/services/inspire/identifiers.d.ts +20 -6
  61. package/dist/services/inspire/identifiers.d.ts.map +1 -1
  62. package/dist/services/inspire/identifiers.js +30 -9
  63. package/dist/services/inspire/identifiers.js.map +1 -1
  64. package/dist/services/inspire/inspire-service.d.ts +27 -10
  65. package/dist/services/inspire/inspire-service.d.ts.map +1 -1
  66. package/dist/services/inspire/inspire-service.js +115 -47
  67. package/dist/services/inspire/inspire-service.js.map +1 -1
  68. package/dist/services/inspire/normalize.d.ts +10 -2
  69. package/dist/services/inspire/normalize.d.ts.map +1 -1
  70. package/dist/services/inspire/normalize.js +84 -1
  71. package/dist/services/inspire/normalize.js.map +1 -1
  72. package/dist/services/inspire/types.d.ts +135 -4
  73. package/dist/services/inspire/types.d.ts.map +1 -1
  74. package/dist/utils/render.d.ts +6 -4
  75. package/dist/utils/render.d.ts.map +1 -1
  76. package/dist/utils/render.js +8 -4
  77. package/dist/utils/render.js.map +1 -1
  78. package/package.json +11 -10
  79. package/server.json +3 -3
  80. package/skills/cern-inspire-guide/SKILL.md +43 -0
package/AGENTS.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** cern-inspire-mcp-server
4
- **Version:** 0.1.3
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
6
- **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
4
+ **Version:** 0.3.0
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.22`
6
+ **Engines:** Bun ≥1.4.4, Node ≥24.0.0
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
8
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.
@@ -15,21 +15,22 @@
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
+ Nine 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
+ | `/institutions` | `cern_inspire_search_institutions` |
28
29
  | `/data` | `cern_inspire_search_hepdata`, the `hepdata` block of `cern_inspire_get_paper` |
29
30
 
30
- `cern_inspire_list_reference` serves static tables and makes no upstream call. There are no prompts.
31
+ `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
 
32
- Literature search, citation summaries, and citation export reject empty standalone recognized field clauses 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 later-page count lookup. Reversed year bounds fail as `invalid_year_range` before requests. Page 1 remains one size+1 request; later page/count requests remain parallel.
33
+ Literature search, citation summaries, citation export, and HEPData search 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. The three literature-query tools (search, citation summary, export) send each arXiv clause ID without its `vN` suffix (either case), with a notice naming the rewrite (`unversionArxivIds`); `refersto:` and `citedby:` values, other fields' values, quoted phrases, regex values, URLs, and DOIs go as written. 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.
33
34
 
34
35
  `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.
35
36
 
@@ -37,11 +38,13 @@ Conventions every definition follows:
37
38
 
38
39
  - **Every INSPIRE request goes through `InspireService`**, with the call opened by `inspire.beginCall(ctx)`. Never `fetch` from a handler: pacing, the budget, retries, and error classification live in the service.
39
40
  - **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.
40
- - **Never request `email_addresses`.** INSPIRE's terms bar collecting them in bulk; the author `fields` list leaves them out.
41
+ - **Never request `email_addresses`.** INSPIRE's terms bar collecting them in bulk; contributors and supervisors are selected by projection, never whole, so `authors.emails` and `supervisors.emails` are never requested either.
41
42
  - **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
- - **Author 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 author list. Echo `authorOffset` and optional `nextAuthorOffset` on both surfaces; issue continuation only with positive progress and available authors remaining. Never derive continuation from `authorCount`; zero budget advises a positive budget. The resource remains first 25 at offset 0.
43
+ - **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. `supervisors[]` (contributor shape, through the five `supervisors.*` projections) lists every supervisor outside author paging and `authorCount`; `thesis` comes from `thesis_info` (a name-only institution is dropped when it exactly matches a linked one); `publications[]` carries `cnum`, `conferenceRecid`, and `parentRecid`, and an entry holding only these is kept.
44
+ - **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, experiment, and institution 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.
45
+ - **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.
43
46
  - **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.
44
- - **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).
47
+ - **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).
45
48
  - **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.
46
49
  - **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'`.
47
50
  - **No fabrication.** A field INSPIRE leaves out stays absent (`firstAuthor`, `ongoing`, `averageCitations`), and `format()` prints "Not available" or "not recorded" rather than a guess.
@@ -99,18 +102,18 @@ export const getPaperTool = tool('cern_inspire_get_paper', {
99
102
  input: z.object({
100
103
  paper: paperInput, // shared input: recid, arXiv ID, DOI, or URL forms, normalized in preprocess
101
104
  max_authors: blankAsUnset(z.number().int().min(0).default(25)).describe(
102
- 'Most authors to list (nonnegative integer, default 25; above 500 uses 500). The full count is always in authorCount.',
105
+ 'Most contributors to list (nonnegative integer, default 25; above 500 uses 500). The upstream contributor count is in authorCount.',
103
106
  ),
104
107
  author_offset: blankAsUnset(z.number().int().min(0).default(0)).describe(
105
- 'Zero-based position in the normalized available author list; use nextAuthorOffset to continue.',
108
+ 'Zero-based position in the normalized available contributor list; use nextAuthorOffset to continue.',
106
109
  ),
107
110
  }),
108
111
  output: paperDossierSchema, // also the inspire://literature/{recid} resource's output
109
112
  enrichment: {
110
- truncated: z.boolean().describe('True when available authors remain after this page.'),
111
- shown: z.number().describe('Number of authors listed.'),
113
+ truncated: z.boolean().describe('True when available contributors remain after this page.'),
114
+ shown: z.number().describe('Number of contributors listed.'),
112
115
  cap: z.number().describe('The max_authors cap applied.'),
113
- notice: z.string().optional().describe('Guidance when the author list was capped or HEPData availability could not be checked.'),
116
+ notice: z.string().optional().describe('Guidance when the contributor list was capped or HEPData availability could not be checked.'),
114
117
  },
115
118
  errors: [
116
119
  {
@@ -204,6 +207,7 @@ await createApp({
204
207
  title: 'cern-inspire-mcp-server', // display identity is the machine name; lint:packaging checks the pair
205
208
  tools: allToolDefinitions,
206
209
  resources: allResourceDefinitions,
210
+ skills: 'skills',
207
211
  instructions: 'cern-inspire-mcp-server reads INSPIRE-HEP (inspirehep.net), …', // abridged
208
212
  setup(core) {
209
213
  initInspireService(core.config); // the User-Agent carries core.config.mcpServerVersion
@@ -293,6 +297,7 @@ src/
293
297
  search-authors.tool.ts
294
298
  get-citation-summary.tool.ts
295
299
  search-experiments.tool.ts
300
+ search-institutions.tool.ts
296
301
  search-hepdata.tool.ts
297
302
  list-reference.tool.ts # static vocabulary tables, no upstream call
298
303
  resources/definitions/
@@ -309,7 +314,7 @@ src/
309
314
  types.ts # Raw upstream and normalized domain types
310
315
  vocabulary.ts # Document types, subjects, citation-bucket ranges
311
316
  utils/
312
- render.ts # inline / cell / quote / fenced / printUrl / atLineStart / callerEcho for upstream and caller text in format(), notices, and error messages
317
+ render.ts # Output renderers and callerEcho for format()/notices; errorText before framework error escaping
313
318
  tests/
314
319
  fixtures/ # INSPIRE bodies, service harness, shared failure suite, result readers
315
320
  tools/ resources/ services/ shared/ # Suites mirroring src/
@@ -332,9 +337,18 @@ docs/
332
337
 
333
338
  ## Skills
334
339
 
335
- 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.
340
+ Two skill trees live at the project root, written for different readers:
336
341
 
337
- **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.
342
+ | Tree | For | Written by |
343
+ |:-----|:----|:-----------|
344
+ | `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) |
345
+ | `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | `cern-inspire-guide`, authored with `add-skill` |
346
+
347
+ 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.
348
+
349
+ 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.
350
+
351
+ **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.
338
352
 
339
353
  Available skills:
340
354
 
@@ -346,6 +360,7 @@ Available skills:
346
360
  | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
347
361
  | `add-resource` | Scaffold a new resource definition |
348
362
  | `add-prompt` | Scaffold a new prompt definition |
363
+ | `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 |
349
364
  | `add-service` | Scaffold a new service integration |
350
365
  | `add-test` | Scaffold test file for a tool, resource, or service |
351
366
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
@@ -415,7 +430,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
415
430
 
416
431
  ## Bundling
417
432
 
418
- `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.
433
+ `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/`, `AGENTS.md`, and `CLAUDE.md` at a package's root, and `SKILL.md` anywhere (a `skills/` deeper in a package is runtime code and stays); 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/`, 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.
419
434
 
420
435
  **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": ""`.
421
436
 
package/CLAUDE.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** cern-inspire-mcp-server
4
- **Version:** 0.1.3
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
6
- **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
4
+ **Version:** 0.3.0
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.22`
6
+ **Engines:** Bun ≥1.4.4, Node ≥24.0.0
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
8
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.
@@ -15,21 +15,22 @@
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
+ Nine 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
+ | `/institutions` | `cern_inspire_search_institutions` |
28
29
  | `/data` | `cern_inspire_search_hepdata`, the `hepdata` block of `cern_inspire_get_paper` |
29
30
 
30
- `cern_inspire_list_reference` serves static tables and makes no upstream call. There are no prompts.
31
+ `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
 
32
- Literature search, citation summaries, and citation export reject empty standalone recognized field clauses 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 later-page count lookup. Reversed year bounds fail as `invalid_year_range` before requests. Page 1 remains one size+1 request; later page/count requests remain parallel.
33
+ Literature search, citation summaries, citation export, and HEPData search 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. The three literature-query tools (search, citation summary, export) send each arXiv clause ID without its `vN` suffix (either case), with a notice naming the rewrite (`unversionArxivIds`); `refersto:` and `citedby:` values, other fields' values, quoted phrases, regex values, URLs, and DOIs go as written. 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.
33
34
 
34
35
  `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.
35
36
 
@@ -37,11 +38,13 @@ Conventions every definition follows:
37
38
 
38
39
  - **Every INSPIRE request goes through `InspireService`**, with the call opened by `inspire.beginCall(ctx)`. Never `fetch` from a handler: pacing, the budget, retries, and error classification live in the service.
39
40
  - **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.
40
- - **Never request `email_addresses`.** INSPIRE's terms bar collecting them in bulk; the author `fields` list leaves them out.
41
+ - **Never request `email_addresses`.** INSPIRE's terms bar collecting them in bulk; contributors and supervisors are selected by projection, never whole, so `authors.emails` and `supervisors.emails` are never requested either.
41
42
  - **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
- - **Author 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 author list. Echo `authorOffset` and optional `nextAuthorOffset` on both surfaces; issue continuation only with positive progress and available authors remaining. Never derive continuation from `authorCount`; zero budget advises a positive budget. The resource remains first 25 at offset 0.
43
+ - **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. `supervisors[]` (contributor shape, through the five `supervisors.*` projections) lists every supervisor outside author paging and `authorCount`; `thesis` comes from `thesis_info` (a name-only institution is dropped when it exactly matches a linked one); `publications[]` carries `cnum`, `conferenceRecid`, and `parentRecid`, and an entry holding only these is kept.
44
+ - **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, experiment, and institution 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.
45
+ - **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.
43
46
  - **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.
44
- - **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).
47
+ - **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).
45
48
  - **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.
46
49
  - **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'`.
47
50
  - **No fabrication.** A field INSPIRE leaves out stays absent (`firstAuthor`, `ongoing`, `averageCitations`), and `format()` prints "Not available" or "not recorded" rather than a guess.
@@ -99,18 +102,18 @@ export const getPaperTool = tool('cern_inspire_get_paper', {
99
102
  input: z.object({
100
103
  paper: paperInput, // shared input: recid, arXiv ID, DOI, or URL forms, normalized in preprocess
101
104
  max_authors: blankAsUnset(z.number().int().min(0).default(25)).describe(
102
- 'Most authors to list (nonnegative integer, default 25; above 500 uses 500). The full count is always in authorCount.',
105
+ 'Most contributors to list (nonnegative integer, default 25; above 500 uses 500). The upstream contributor count is in authorCount.',
103
106
  ),
104
107
  author_offset: blankAsUnset(z.number().int().min(0).default(0)).describe(
105
- 'Zero-based position in the normalized available author list; use nextAuthorOffset to continue.',
108
+ 'Zero-based position in the normalized available contributor list; use nextAuthorOffset to continue.',
106
109
  ),
107
110
  }),
108
111
  output: paperDossierSchema, // also the inspire://literature/{recid} resource's output
109
112
  enrichment: {
110
- truncated: z.boolean().describe('True when available authors remain after this page.'),
111
- shown: z.number().describe('Number of authors listed.'),
113
+ truncated: z.boolean().describe('True when available contributors remain after this page.'),
114
+ shown: z.number().describe('Number of contributors listed.'),
112
115
  cap: z.number().describe('The max_authors cap applied.'),
113
- notice: z.string().optional().describe('Guidance when the author list was capped or HEPData availability could not be checked.'),
116
+ notice: z.string().optional().describe('Guidance when the contributor list was capped or HEPData availability could not be checked.'),
114
117
  },
115
118
  errors: [
116
119
  {
@@ -204,6 +207,7 @@ await createApp({
204
207
  title: 'cern-inspire-mcp-server', // display identity is the machine name; lint:packaging checks the pair
205
208
  tools: allToolDefinitions,
206
209
  resources: allResourceDefinitions,
210
+ skills: 'skills',
207
211
  instructions: 'cern-inspire-mcp-server reads INSPIRE-HEP (inspirehep.net), …', // abridged
208
212
  setup(core) {
209
213
  initInspireService(core.config); // the User-Agent carries core.config.mcpServerVersion
@@ -293,6 +297,7 @@ src/
293
297
  search-authors.tool.ts
294
298
  get-citation-summary.tool.ts
295
299
  search-experiments.tool.ts
300
+ search-institutions.tool.ts
296
301
  search-hepdata.tool.ts
297
302
  list-reference.tool.ts # static vocabulary tables, no upstream call
298
303
  resources/definitions/
@@ -309,7 +314,7 @@ src/
309
314
  types.ts # Raw upstream and normalized domain types
310
315
  vocabulary.ts # Document types, subjects, citation-bucket ranges
311
316
  utils/
312
- render.ts # inline / cell / quote / fenced / printUrl / atLineStart / callerEcho for upstream and caller text in format(), notices, and error messages
317
+ render.ts # Output renderers and callerEcho for format()/notices; errorText before framework error escaping
313
318
  tests/
314
319
  fixtures/ # INSPIRE bodies, service harness, shared failure suite, result readers
315
320
  tools/ resources/ services/ shared/ # Suites mirroring src/
@@ -332,9 +337,18 @@ docs/
332
337
 
333
338
  ## Skills
334
339
 
335
- 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.
340
+ Two skill trees live at the project root, written for different readers:
336
341
 
337
- **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.
342
+ | Tree | For | Written by |
343
+ |:-----|:----|:-----------|
344
+ | `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) |
345
+ | `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | `cern-inspire-guide`, authored with `add-skill` |
346
+
347
+ 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.
348
+
349
+ 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.
350
+
351
+ **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.
338
352
 
339
353
  Available skills:
340
354
 
@@ -346,6 +360,7 @@ Available skills:
346
360
  | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
347
361
  | `add-resource` | Scaffold a new resource definition |
348
362
  | `add-prompt` | Scaffold a new prompt definition |
363
+ | `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 |
349
364
  | `add-service` | Scaffold a new service integration |
350
365
  | `add-test` | Scaffold test file for a tool, resource, or service |
351
366
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
@@ -415,7 +430,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
415
430
 
416
431
  ## Bundling
417
432
 
418
- `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.
433
+ `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/`, `AGENTS.md`, and `CLAUDE.md` at a package's root, and `SKILL.md` anywhere (a `skills/` deeper in a package is runtime code and stays); 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/`, 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.
419
434
 
420
435
  **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": ""`.
421
436
 
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.3 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.3 AS deps
50
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS deps
50
51
 
51
52
  WORKDIR /usr/src/app
52
53
 
@@ -108,7 +109,7 @@ RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
108
109
  # dependencies and build artifacts. Its only Bun invocations are HEALTHCHECK
109
110
  # and CMD, which run on the real target at container start.
110
111
  # ==============================================================================
111
- FROM oven/bun:1.4.3-slim AS production
112
+ FROM oven/bun:1.4.4-slim AS production
112
113
 
113
114
  WORKDIR /usr/src/app
114
115
 
@@ -130,6 +131,7 @@ COPY --from=deps /usr/src/app/node_modules ./node_modules
130
131
 
131
132
  # Copy the compiled application code from the build stage
132
133
  COPY --from=build /usr/src/app/dist ./dist
134
+ COPY --from=build /usr/src/app/skills ./skills
133
135
 
134
136
  # Mirror CLI (MirrorService adopters only — Tier 3, opt-in):
135
137
  # Copy your mirror lifecycle scripts and emit a runtime tsconfig so Bun resolves