@cyanheads/cern-inspire-mcp-server 0.1.3 → 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 (61) hide show
  1. package/AGENTS.md +31 -18
  2. package/CLAUDE.md +31 -18
  3. package/Dockerfile +5 -3
  4. package/README.md +59 -119
  5. package/changelog/0.2.x/0.2.0.md +35 -0
  6. package/dist/index.js +1 -0
  7. package/dist/index.js.map +1 -1
  8. package/dist/mcp-server/resources/definitions/index.d.ts +8 -0
  9. package/dist/mcp-server/resources/definitions/index.d.ts.map +1 -1
  10. package/dist/mcp-server/resources/definitions/inspire-literature.resource.d.ts +8 -0
  11. package/dist/mcp-server/resources/definitions/inspire-literature.resource.d.ts.map +1 -1
  12. package/dist/mcp-server/resources/definitions/inspire-literature.resource.js +1 -1
  13. package/dist/mcp-server/resources/definitions/inspire-literature.resource.js.map +1 -1
  14. package/dist/mcp-server/tools/definitions/export-citations.tool.d.ts +2 -2
  15. package/dist/mcp-server/tools/definitions/export-citations.tool.d.ts.map +1 -1
  16. package/dist/mcp-server/tools/definitions/export-citations.tool.js +14 -21
  17. package/dist/mcp-server/tools/definitions/export-citations.tool.js.map +1 -1
  18. package/dist/mcp-server/tools/definitions/get-citation-summary.tool.js +4 -4
  19. package/dist/mcp-server/tools/definitions/get-citation-summary.tool.js.map +1 -1
  20. package/dist/mcp-server/tools/definitions/get-paper.tool.d.ts +17 -1
  21. package/dist/mcp-server/tools/definitions/get-paper.tool.d.ts.map +1 -1
  22. package/dist/mcp-server/tools/definitions/get-paper.tool.js +53 -22
  23. package/dist/mcp-server/tools/definitions/get-paper.tool.js.map +1 -1
  24. package/dist/mcp-server/tools/definitions/index.d.ts +93 -85
  25. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  26. package/dist/mcp-server/tools/definitions/list-reference.tool.js +1 -1
  27. package/dist/mcp-server/tools/definitions/list-reference.tool.js.map +1 -1
  28. package/dist/mcp-server/tools/definitions/search-authors.tool.d.ts.map +1 -1
  29. package/dist/mcp-server/tools/definitions/search-authors.tool.js +7 -3
  30. package/dist/mcp-server/tools/definitions/search-authors.tool.js.map +1 -1
  31. package/dist/mcp-server/tools/definitions/search-experiments.tool.d.ts.map +1 -1
  32. package/dist/mcp-server/tools/definitions/search-experiments.tool.js +17 -10
  33. package/dist/mcp-server/tools/definitions/search-experiments.tool.js.map +1 -1
  34. package/dist/mcp-server/tools/definitions/search-hepdata.tool.d.ts +1 -1
  35. package/dist/mcp-server/tools/definitions/search-hepdata.tool.d.ts.map +1 -1
  36. package/dist/mcp-server/tools/definitions/search-hepdata.tool.js +8 -6
  37. package/dist/mcp-server/tools/definitions/search-hepdata.tool.js.map +1 -1
  38. package/dist/mcp-server/tools/definitions/search-literature.tool.d.ts +1 -1
  39. package/dist/mcp-server/tools/definitions/search-literature.tool.d.ts.map +1 -1
  40. package/dist/mcp-server/tools/definitions/search-literature.tool.js +9 -7
  41. package/dist/mcp-server/tools/definitions/search-literature.tool.js.map +1 -1
  42. package/dist/mcp-server/tools/inputs.d.ts +1 -1
  43. package/dist/mcp-server/tools/inputs.d.ts.map +1 -1
  44. package/dist/mcp-server/tools/inputs.js +15 -3
  45. package/dist/mcp-server/tools/inputs.js.map +1 -1
  46. package/dist/services/inspire/inspire-service.d.ts +10 -3
  47. package/dist/services/inspire/inspire-service.d.ts.map +1 -1
  48. package/dist/services/inspire/inspire-service.js +48 -34
  49. package/dist/services/inspire/inspire-service.js.map +1 -1
  50. package/dist/services/inspire/normalize.d.ts.map +1 -1
  51. package/dist/services/inspire/normalize.js +15 -0
  52. package/dist/services/inspire/normalize.js.map +1 -1
  53. package/dist/services/inspire/types.d.ts +20 -4
  54. package/dist/services/inspire/types.d.ts.map +1 -1
  55. package/dist/utils/render.d.ts +6 -4
  56. package/dist/utils/render.d.ts.map +1 -1
  57. package/dist/utils/render.js +8 -4
  58. package/dist/utils/render.js.map +1 -1
  59. package/package.json +9 -8
  60. package/server.json +3 -3
  61. 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`
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.3.1
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,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
31
 
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.
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.
33
33
 
34
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.
35
35
 
@@ -39,9 +39,11 @@ Conventions every definition follows:
39
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.
40
40
  - **Never request `email_addresses`.** INSPIRE's terms bar collecting them in bulk; the author `fields` list leaves them out.
41
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
- - **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.
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.
43
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.
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).
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).
45
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.
46
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'`.
47
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.
@@ -99,18 +101,18 @@ export const getPaperTool = tool('cern_inspire_get_paper', {
99
101
  input: z.object({
100
102
  paper: paperInput, // shared input: recid, arXiv ID, DOI, or URL forms, normalized in preprocess
101
103
  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.',
104
+ 'Most contributors to list (nonnegative integer, default 25; above 500 uses 500). The upstream contributor count is in authorCount.',
103
105
  ),
104
106
  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.',
107
+ 'Zero-based position in the normalized available contributor list; use nextAuthorOffset to continue.',
106
108
  ),
107
109
  }),
108
110
  output: paperDossierSchema, // also the inspire://literature/{recid} resource's output
109
111
  enrichment: {
110
- truncated: z.boolean().describe('True when available authors remain after this page.'),
111
- 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.'),
112
114
  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.'),
115
+ notice: z.string().optional().describe('Guidance when the contributor list was capped or HEPData availability could not be checked.'),
114
116
  },
115
117
  errors: [
116
118
  {
@@ -204,6 +206,7 @@ await createApp({
204
206
  title: 'cern-inspire-mcp-server', // display identity is the machine name; lint:packaging checks the pair
205
207
  tools: allToolDefinitions,
206
208
  resources: allResourceDefinitions,
209
+ skills: 'skills',
207
210
  instructions: 'cern-inspire-mcp-server reads INSPIRE-HEP (inspirehep.net), …', // abridged
208
211
  setup(core) {
209
212
  initInspireService(core.config); // the User-Agent carries core.config.mcpServerVersion
@@ -309,7 +312,7 @@ src/
309
312
  types.ts # Raw upstream and normalized domain types
310
313
  vocabulary.ts # Document types, subjects, citation-bucket ranges
311
314
  utils/
312
- 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
313
316
  tests/
314
317
  fixtures/ # INSPIRE bodies, service harness, shared failure suite, result readers
315
318
  tools/ resources/ services/ shared/ # Suites mirroring src/
@@ -332,9 +335,18 @@ docs/
332
335
 
333
336
  ## Skills
334
337
 
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.
338
+ Two skill trees live at the project root, written for different readers:
336
339
 
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.
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.
348
+
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.
338
350
 
339
351
  Available skills:
340
352
 
@@ -346,6 +358,7 @@ Available skills:
346
358
  | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
347
359
  | `add-resource` | Scaffold a new resource definition |
348
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 |
349
362
  | `add-service` | Scaffold a new service integration |
350
363
  | `add-test` | Scaffold test file for a tool, resource, or service |
351
364
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
@@ -415,7 +428,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
415
428
 
416
429
  ## Bundling
417
430
 
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.
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.
419
432
 
420
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": ""`.
421
434
 
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`
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.3.1
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,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
31
 
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.
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.
33
33
 
34
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.
35
35
 
@@ -39,9 +39,11 @@ Conventions every definition follows:
39
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.
40
40
  - **Never request `email_addresses`.** INSPIRE's terms bar collecting them in bulk; the author `fields` list leaves them out.
41
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
- - **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.
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.
43
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.
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).
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).
45
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.
46
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'`.
47
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.
@@ -99,18 +101,18 @@ export const getPaperTool = tool('cern_inspire_get_paper', {
99
101
  input: z.object({
100
102
  paper: paperInput, // shared input: recid, arXiv ID, DOI, or URL forms, normalized in preprocess
101
103
  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.',
104
+ 'Most contributors to list (nonnegative integer, default 25; above 500 uses 500). The upstream contributor count is in authorCount.',
103
105
  ),
104
106
  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.',
107
+ 'Zero-based position in the normalized available contributor list; use nextAuthorOffset to continue.',
106
108
  ),
107
109
  }),
108
110
  output: paperDossierSchema, // also the inspire://literature/{recid} resource's output
109
111
  enrichment: {
110
- truncated: z.boolean().describe('True when available authors remain after this page.'),
111
- 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.'),
112
114
  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.'),
115
+ notice: z.string().optional().describe('Guidance when the contributor list was capped or HEPData availability could not be checked.'),
114
116
  },
115
117
  errors: [
116
118
  {
@@ -204,6 +206,7 @@ await createApp({
204
206
  title: 'cern-inspire-mcp-server', // display identity is the machine name; lint:packaging checks the pair
205
207
  tools: allToolDefinitions,
206
208
  resources: allResourceDefinitions,
209
+ skills: 'skills',
207
210
  instructions: 'cern-inspire-mcp-server reads INSPIRE-HEP (inspirehep.net), …', // abridged
208
211
  setup(core) {
209
212
  initInspireService(core.config); // the User-Agent carries core.config.mcpServerVersion
@@ -309,7 +312,7 @@ src/
309
312
  types.ts # Raw upstream and normalized domain types
310
313
  vocabulary.ts # Document types, subjects, citation-bucket ranges
311
314
  utils/
312
- 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
313
316
  tests/
314
317
  fixtures/ # INSPIRE bodies, service harness, shared failure suite, result readers
315
318
  tools/ resources/ services/ shared/ # Suites mirroring src/
@@ -332,9 +335,18 @@ docs/
332
335
 
333
336
  ## Skills
334
337
 
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.
338
+ Two skill trees live at the project root, written for different readers:
336
339
 
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.
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.
348
+
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.
338
350
 
339
351
  Available skills:
340
352
 
@@ -346,6 +358,7 @@ Available skills:
346
358
  | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
347
359
  | `add-resource` | Scaffold a new resource definition |
348
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 |
349
362
  | `add-service` | Scaffold a new service integration |
350
363
  | `add-test` | Scaffold test file for a tool, resource, or service |
351
364
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
@@ -415,7 +428,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
415
428
 
416
429
  ## Bundling
417
430
 
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.
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.
419
432
 
420
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": ""`.
421
434
 
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