@cyanheads/cern-inspire-mcp-server 0.1.1 → 0.1.3

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 (73) hide show
  1. package/AGENTS.md +26 -36
  2. package/CLAUDE.md +26 -36
  3. package/Dockerfile +6 -3
  4. package/README.md +65 -34
  5. package/changelog/0.1.x/0.1.2.md +29 -0
  6. package/changelog/0.1.x/0.1.3.md +34 -0
  7. package/dist/index.js +1 -1
  8. package/dist/index.js.map +1 -1
  9. package/dist/mcp-server/resources/definitions/index.d.ts +15 -5
  10. package/dist/mcp-server/resources/definitions/index.d.ts.map +1 -1
  11. package/dist/mcp-server/resources/definitions/inspire-literature.resource.d.ts +15 -5
  12. package/dist/mcp-server/resources/definitions/inspire-literature.resource.d.ts.map +1 -1
  13. package/dist/mcp-server/resources/definitions/inspire-literature.resource.js +1 -1
  14. package/dist/mcp-server/resources/definitions/inspire-literature.resource.js.map +1 -1
  15. package/dist/mcp-server/tools/definitions/export-citations.tool.d.ts +56 -3
  16. package/dist/mcp-server/tools/definitions/export-citations.tool.d.ts.map +1 -1
  17. package/dist/mcp-server/tools/definitions/export-citations.tool.js +121 -24
  18. package/dist/mcp-server/tools/definitions/export-citations.tool.js.map +1 -1
  19. package/dist/mcp-server/tools/definitions/get-citation-summary.tool.d.ts +8 -4
  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 +77 -22
  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 +31 -10
  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 +139 -47
  26. package/dist/mcp-server/tools/definitions/get-paper.tool.js.map +1 -1
  27. package/dist/mcp-server/tools/definitions/index.d.ts +83 -15
  28. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  29. package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts.map +1 -1
  30. package/dist/mcp-server/tools/definitions/list-reference.tool.js +33 -9
  31. package/dist/mcp-server/tools/definitions/list-reference.tool.js.map +1 -1
  32. package/dist/mcp-server/tools/definitions/search-authors.tool.d.ts.map +1 -1
  33. package/dist/mcp-server/tools/definitions/search-authors.tool.js +9 -9
  34. package/dist/mcp-server/tools/definitions/search-authors.tool.js.map +1 -1
  35. package/dist/mcp-server/tools/definitions/search-experiments.tool.d.ts.map +1 -1
  36. package/dist/mcp-server/tools/definitions/search-experiments.tool.js +6 -3
  37. package/dist/mcp-server/tools/definitions/search-experiments.tool.js.map +1 -1
  38. package/dist/mcp-server/tools/definitions/search-hepdata.tool.d.ts +2 -2
  39. package/dist/mcp-server/tools/definitions/search-hepdata.tool.d.ts.map +1 -1
  40. package/dist/mcp-server/tools/definitions/search-hepdata.tool.js +14 -12
  41. package/dist/mcp-server/tools/definitions/search-hepdata.tool.js.map +1 -1
  42. package/dist/mcp-server/tools/definitions/search-literature.tool.d.ts +3 -3
  43. package/dist/mcp-server/tools/definitions/search-literature.tool.d.ts.map +1 -1
  44. package/dist/mcp-server/tools/definitions/search-literature.tool.js +30 -16
  45. package/dist/mcp-server/tools/definitions/search-literature.tool.js.map +1 -1
  46. package/dist/mcp-server/tools/inputs.d.ts +23 -5
  47. package/dist/mcp-server/tools/inputs.d.ts.map +1 -1
  48. package/dist/mcp-server/tools/inputs.js +88 -10
  49. package/dist/mcp-server/tools/inputs.js.map +1 -1
  50. package/dist/services/inspire/identifiers.d.ts +17 -6
  51. package/dist/services/inspire/identifiers.d.ts.map +1 -1
  52. package/dist/services/inspire/identifiers.js +28 -7
  53. package/dist/services/inspire/identifiers.js.map +1 -1
  54. package/dist/services/inspire/inspire-service.d.ts +79 -18
  55. package/dist/services/inspire/inspire-service.d.ts.map +1 -1
  56. package/dist/services/inspire/inspire-service.js +297 -49
  57. package/dist/services/inspire/inspire-service.js.map +1 -1
  58. package/dist/services/inspire/markup-to-text.d.ts +32 -0
  59. package/dist/services/inspire/markup-to-text.d.ts.map +1 -0
  60. package/dist/services/inspire/markup-to-text.js +783 -0
  61. package/dist/services/inspire/markup-to-text.js.map +1 -0
  62. package/dist/services/inspire/normalize.d.ts +24 -6
  63. package/dist/services/inspire/normalize.d.ts.map +1 -1
  64. package/dist/services/inspire/normalize.js +100 -22
  65. package/dist/services/inspire/normalize.js.map +1 -1
  66. package/dist/services/inspire/types.d.ts +80 -8
  67. package/dist/services/inspire/types.d.ts.map +1 -1
  68. package/dist/utils/render.d.ts +34 -5
  69. package/dist/utils/render.d.ts.map +1 -1
  70. package/dist/utils/render.js +69 -16
  71. package/dist/utils/render.js.map +1 -1
  72. package/package.json +11 -11
  73. package/server.json +16 -24
package/AGENTS.md CHANGED
@@ -1,11 +1,11 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** cern-inspire-mcp-server
4
- **Version:** 0.1.1
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.10`
4
+ **Version:** 0.1.3
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
6
6
  **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` ^2.1.0
8
- **Zod:** ^4.6.5
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
8
+ **Zod:** ^4.6.7
9
9
 
10
10
  > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
11
11
 
@@ -20,23 +20,28 @@ Eight read-only tools and one resource over INSPIRE-HEP's keyless REST API (`htt
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
- | `/literature` with `format=` (`bibtex`, `latex-eu`, `latex-us`) | `cern_inspire_export_citations` |
24
- | `/literature/facets` (`facet_name=citation-summary`) | `cern_inspire_get_citation_summary` |
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` |
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` |
25
26
  | `/authors` | `cern_inspire_search_authors`, author resolution in `cern_inspire_get_citation_summary` |
26
27
  | `/experiments` | `cern_inspire_search_experiments` |
27
28
  | `/data` | `cern_inspire_search_hepdata`, the `hepdata` block of `cern_inspire_get_paper` |
28
29
 
29
30
  `cern_inspire_list_reference` serves static tables and makes no upstream call. There are no prompts.
30
31
 
31
- `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`), `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.
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
+
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.
32
35
 
33
36
  Conventions every definition follows:
34
37
 
35
38
  - **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.
36
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.
37
40
  - **Never request `email_addresses`.** INSPIRE's terms bar collecting them in bulk; the author `fields` list leaves them out.
38
- - **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.
39
- - **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. `structuredContent` keeps each string as received, apart from Unicode tag characters, which the service drops at decode.
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.
43
+ - **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).
40
45
  - **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.
41
46
  - **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'`.
42
47
  - **No fabrication.** A field INSPIRE leaves out stays absent (`firstAuthor`, `ongoing`, `averageCitations`), and `format()` prints "Not available" or "not recorded" rather than a guess.
@@ -93,13 +98,16 @@ export const getPaperTool = tool('cern_inspire_get_paper', {
93
98
  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
94
99
  input: z.object({
95
100
  paper: paperInput, // shared input: recid, arXiv ID, DOI, or URL forms, normalized in preprocess
96
- max_authors: blankAsUnset(z.number().int().min(0).max(500).default(25)).describe(
97
- 'Most authors to list (0–500, default 25). The full count is always in authorCount.',
101
+ 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.',
103
+ ),
104
+ 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.',
98
106
  ),
99
107
  }),
100
108
  output: paperDossierSchema, // also the inspire://literature/{recid} resource's output
101
109
  enrichment: {
102
- truncated: z.boolean().describe('True when the author list was capped at max_authors.'),
110
+ truncated: z.boolean().describe('True when available authors remain after this page.'),
103
111
  shown: z.number().describe('Number of authors listed.'),
104
112
  cap: z.number().describe('The max_authors cap applied.'),
105
113
  notice: z.string().optional().describe('Guidance when the author list was capped or HEPData availability could not be checked.'),
@@ -115,27 +123,8 @@ export const getPaperTool = tool('cern_inspire_get_paper', {
115
123
  // inspire_rate_limited, pacer_shed, upstream_unreadable: declared inline, thrownBy: 'service'
116
124
  ],
117
125
 
118
- async handler(input, ctx) {
119
- ctx.enrich({ truncated: false, shown: 0, cap: input.max_authors }); // required enrichment first
120
-
121
- const inspire = getInspireService();
122
- const lookup = await inspire.getPaper(input.paper, input.max_authors, inspire.beginCall(ctx));
123
- if (!lookup) {
124
- throw ctx.fail('paper_not_found', `No INSPIRE literature record matches "${inline(input.paper)}".`, {
125
- paper: input.paper,
126
- });
127
- }
128
- const { paper, authorsInRecord } = lookup;
129
- ctx.enrich({ shown: paper.authors.length });
130
- if (authorsInRecord > input.max_authors) {
131
- ctx.enrich.truncated({
132
- shown: paper.authors.length,
133
- cap: input.max_authors,
134
- guidance: `Showing ${paper.authors.length} of ${authorsInRecord} authors; raise max_authors (up to 500) to list more.`,
135
- });
136
- }
137
- return paper;
138
- },
126
+ // See get-paper.tool.ts for the handler: clamp the budget to 500, apply
127
+ // author_offset after normalization, and compose paging, merge and HEPData notices.
139
128
 
140
129
  // format() is the content[] twin of structuredContent: every output field renders,
141
130
  // and every upstream string passes through inline() / quote() / printUrl().
@@ -220,7 +209,7 @@ await createApp({
220
209
  initInspireService(core.config); // the User-Agent carries core.config.mcpServerVersion
221
210
  },
222
211
  teardown() {
223
- disposeInspireService(); // releases the pacer's timer and rejects queued waiters
212
+ disposeInspireService(); // releases both pacers' timers and rejects queued waiters
224
213
  },
225
214
  });
226
215
  ```
@@ -315,11 +304,12 @@ src/
315
304
  inspire/
316
305
  inspire-service.ts # InspireService: pacer, per-call budget, retries, param allowlist, field lists
317
306
  identifiers.ts # Paper and author identifier normalization and routing (matchedAs)
307
+ markup-to-text.ts # Publisher HTML/JATS/MathML and entities in titles and abstracts → text
318
308
  normalize.ts # Raw INSPIRE records → output shapes; absent fields stay absent
319
309
  types.ts # Raw upstream and normalized domain types
320
310
  vocabulary.ts # Document types, subjects, citation-bucket ranges
321
311
  utils/
322
- render.ts # inline / cell / quote / fenced / printUrl / atLineStart for upstream text in format() and error messages
312
+ render.ts # inline / cell / quote / fenced / printUrl / atLineStart / callerEcho for upstream and caller text in format(), notices, and error messages
323
313
  tests/
324
314
  fixtures/ # INSPIRE bodies, service harness, shared failure suite, result readers
325
315
  tools/ resources/ services/ shared/ # Suites mirroring src/
@@ -462,7 +452,7 @@ security: false # optional — true ONLY for a source
462
452
 
463
453
  ## Publishing
464
454
 
465
- **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
455
+ **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the release digest: theme line, `## Changes`, `## Gates`, changelog link last); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
466
456
 
467
457
  ---
468
458
 
package/CLAUDE.md CHANGED
@@ -1,11 +1,11 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** cern-inspire-mcp-server
4
- **Version:** 0.1.1
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.10`
4
+ **Version:** 0.1.3
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
6
6
  **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` ^2.1.0
8
- **Zod:** ^4.6.5
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
8
+ **Zod:** ^4.6.7
9
9
 
10
10
  > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
11
11
 
@@ -20,23 +20,28 @@ Eight read-only tools and one resource over INSPIRE-HEP's keyless REST API (`htt
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
- | `/literature` with `format=` (`bibtex`, `latex-eu`, `latex-us`) | `cern_inspire_export_citations` |
24
- | `/literature/facets` (`facet_name=citation-summary`) | `cern_inspire_get_citation_summary` |
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` |
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` |
25
26
  | `/authors` | `cern_inspire_search_authors`, author resolution in `cern_inspire_get_citation_summary` |
26
27
  | `/experiments` | `cern_inspire_search_experiments` |
27
28
  | `/data` | `cern_inspire_search_hepdata`, the `hepdata` block of `cern_inspire_get_paper` |
28
29
 
29
30
  `cern_inspire_list_reference` serves static tables and makes no upstream call. There are no prompts.
30
31
 
31
- `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`), `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.
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
+
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.
32
35
 
33
36
  Conventions every definition follows:
34
37
 
35
38
  - **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.
36
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.
37
40
  - **Never request `email_addresses`.** INSPIRE's terms bar collecting them in bulk; the author `fields` list leaves them out.
38
- - **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.
39
- - **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. `structuredContent` keeps each string as received, apart from Unicode tag characters, which the service drops at decode.
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.
43
+ - **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).
40
45
  - **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.
41
46
  - **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'`.
42
47
  - **No fabrication.** A field INSPIRE leaves out stays absent (`firstAuthor`, `ongoing`, `averageCitations`), and `format()` prints "Not available" or "not recorded" rather than a guess.
@@ -93,13 +98,16 @@ export const getPaperTool = tool('cern_inspire_get_paper', {
93
98
  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
94
99
  input: z.object({
95
100
  paper: paperInput, // shared input: recid, arXiv ID, DOI, or URL forms, normalized in preprocess
96
- max_authors: blankAsUnset(z.number().int().min(0).max(500).default(25)).describe(
97
- 'Most authors to list (0–500, default 25). The full count is always in authorCount.',
101
+ 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.',
103
+ ),
104
+ 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.',
98
106
  ),
99
107
  }),
100
108
  output: paperDossierSchema, // also the inspire://literature/{recid} resource's output
101
109
  enrichment: {
102
- truncated: z.boolean().describe('True when the author list was capped at max_authors.'),
110
+ truncated: z.boolean().describe('True when available authors remain after this page.'),
103
111
  shown: z.number().describe('Number of authors listed.'),
104
112
  cap: z.number().describe('The max_authors cap applied.'),
105
113
  notice: z.string().optional().describe('Guidance when the author list was capped or HEPData availability could not be checked.'),
@@ -115,27 +123,8 @@ export const getPaperTool = tool('cern_inspire_get_paper', {
115
123
  // inspire_rate_limited, pacer_shed, upstream_unreadable: declared inline, thrownBy: 'service'
116
124
  ],
117
125
 
118
- async handler(input, ctx) {
119
- ctx.enrich({ truncated: false, shown: 0, cap: input.max_authors }); // required enrichment first
120
-
121
- const inspire = getInspireService();
122
- const lookup = await inspire.getPaper(input.paper, input.max_authors, inspire.beginCall(ctx));
123
- if (!lookup) {
124
- throw ctx.fail('paper_not_found', `No INSPIRE literature record matches "${inline(input.paper)}".`, {
125
- paper: input.paper,
126
- });
127
- }
128
- const { paper, authorsInRecord } = lookup;
129
- ctx.enrich({ shown: paper.authors.length });
130
- if (authorsInRecord > input.max_authors) {
131
- ctx.enrich.truncated({
132
- shown: paper.authors.length,
133
- cap: input.max_authors,
134
- guidance: `Showing ${paper.authors.length} of ${authorsInRecord} authors; raise max_authors (up to 500) to list more.`,
135
- });
136
- }
137
- return paper;
138
- },
126
+ // See get-paper.tool.ts for the handler: clamp the budget to 500, apply
127
+ // author_offset after normalization, and compose paging, merge and HEPData notices.
139
128
 
140
129
  // format() is the content[] twin of structuredContent: every output field renders,
141
130
  // and every upstream string passes through inline() / quote() / printUrl().
@@ -220,7 +209,7 @@ await createApp({
220
209
  initInspireService(core.config); // the User-Agent carries core.config.mcpServerVersion
221
210
  },
222
211
  teardown() {
223
- disposeInspireService(); // releases the pacer's timer and rejects queued waiters
212
+ disposeInspireService(); // releases both pacers' timers and rejects queued waiters
224
213
  },
225
214
  });
226
215
  ```
@@ -315,11 +304,12 @@ src/
315
304
  inspire/
316
305
  inspire-service.ts # InspireService: pacer, per-call budget, retries, param allowlist, field lists
317
306
  identifiers.ts # Paper and author identifier normalization and routing (matchedAs)
307
+ markup-to-text.ts # Publisher HTML/JATS/MathML and entities in titles and abstracts → text
318
308
  normalize.ts # Raw INSPIRE records → output shapes; absent fields stay absent
319
309
  types.ts # Raw upstream and normalized domain types
320
310
  vocabulary.ts # Document types, subjects, citation-bucket ranges
321
311
  utils/
322
- render.ts # inline / cell / quote / fenced / printUrl / atLineStart for upstream text in format() and error messages
312
+ render.ts # inline / cell / quote / fenced / printUrl / atLineStart / callerEcho for upstream and caller text in format(), notices, and error messages
323
313
  tests/
324
314
  fixtures/ # INSPIRE bodies, service harness, shared failure suite, result readers
325
315
  tools/ resources/ services/ shared/ # Suites mirroring src/
@@ -462,7 +452,7 @@ security: false # optional — true ONLY for a source
462
452
 
463
453
  ## Publishing
464
454
 
465
- **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
455
+ **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the release digest: theme line, `## Changes`, `## Gates`, changelog link last); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
466
456
 
467
457
  ---
468
458
 
package/Dockerfile CHANGED
@@ -14,7 +14,7 @@
14
14
  # output. A stage that compiles a native addon needs the target-arch toolchain
15
15
  # and cannot cross-compile this way — drop the flag there.
16
16
  # ==============================================================================
17
- FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS build
17
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.3 AS build
18
18
 
19
19
  WORKDIR /usr/src/app
20
20
 
@@ -46,7 +46,7 @@ RUN bun run build
46
46
  # A clean image rather than `FROM build`: the build stage's node_modules holds
47
47
  # devDependencies.
48
48
  # ==============================================================================
49
- FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS deps
49
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.3 AS deps
50
50
 
51
51
  WORKDIR /usr/src/app
52
52
 
@@ -93,6 +93,9 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
93
93
  bun scripts/install-otel.ts --os="$TARGETOS" --cpu="$(cat .bun-cpu)"; \
94
94
  fi
95
95
 
96
+ COPY scripts/prune-musl-packages.ts ./scripts/
97
+ RUN bun scripts/prune-musl-packages.ts
98
+
96
99
  # The seeded scanner served only the installs above; keep it out of the image.
97
100
  RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
98
101
 
@@ -105,7 +108,7 @@ RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
105
108
  # dependencies and build artifacts. Its only Bun invocations are HEALTHCHECK
106
109
  # and CMD, which run on the real target at container start.
107
110
  # ==============================================================================
108
- FROM oven/bun:1.4.2-slim AS production
111
+ FROM oven/bun:1.4.3-slim AS production
109
112
 
110
113
  WORKDIR /usr/src/app
111
114
 
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
 
8
8
  <div align="center">
9
9
 
10
- [![Version](https://img.shields.io/badge/Version-0.1.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/cern-inspire-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.1.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/cern-inspire-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/cern-inspire-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
10
+ [![Version](https://img.shields.io/badge/Version-0.1.3-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/cern-inspire-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.3.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/cern-inspire-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/cern-inspire-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.3-blueviolet.svg?style=flat-square)](https://bun.sh/)
11
11
 
12
12
  </div>
13
13
 
@@ -19,11 +19,19 @@
19
19
 
20
20
  </div>
21
21
 
22
+ <div align="center">
23
+
24
+ **Public Hosted Server:** [https://cern-inspire.caseyjhand.com/mcp](https://cern-inspire.caseyjhand.com/mcp)
25
+
26
+ </div>
27
+
22
28
  ---
23
29
 
24
30
  ## Overview
25
31
 
26
- High-energy-physics literature from INSPIRE-HEP, including its index of HEPData measurement records. Search papers, authors, and experiments, read a paper's full record, compute citation summaries and h-indices, export BibTeX or LaTeX entries, and find the HEPData record that holds a paper's numerical tables. Runs as a stdio process or a local Streamable HTTP server.
32
+ High-energy-physics literature from INSPIRE-HEP, including its index of HEPData measurement records. Search papers, authors, and experiments, read a paper's full record, compute citation summaries, h-indices, and citations per year, export BibTeX or LaTeX entries, and find the HEPData record that holds a paper's numerical tables. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
33
+
34
+ Literature search, citation summaries, and citation export reject empty recognized field clauses (`a:` or `a: not`) as `invalid_query`; give each field a value (`a Witten`). Other syntax goes to INSPIRE without complete grammar validation.
27
35
 
28
36
  ### Tools
29
37
 
@@ -33,7 +41,7 @@ High-energy-physics literature from INSPIRE-HEP, including its index of HEPData
33
41
  | `cern_inspire_get_paper` | Fetch one paper's full record by recid, arXiv ID, or DOI, with its HEPData availability |
34
42
  | `cern_inspire_export_citations` | Export INSPIRE's BibTeX or LaTeX `\bibitem` entries for the papers a query selects |
35
43
  | `cern_inspire_search_authors` | Find physicist profiles by name, BAI, ORCID, INSPIRE ID, or author recid |
36
- | `cern_inspire_get_citation_summary` | h-index, citation totals, and citation buckets for one author or any literature query |
44
+ | `cern_inspire_get_citation_summary` | h-index, citation totals, citation buckets, and citations per year for one author or any literature query |
37
45
  | `cern_inspire_search_experiments` | Find experiments, collaborations, and facilities, with a query that selects their papers |
38
46
  | `cern_inspire_search_hepdata` | Find HEPData measurement records by process, observable, energy, or collaboration |
39
47
  | `cern_inspire_list_reference` | Decode query syntax, identifier forms, filter values, citation buckets, and HEPData DOIs |
@@ -50,40 +58,44 @@ The same record is reachable through `cern_inspire_get_paper` for clients that d
50
58
 
51
59
  ### `cern_inspire_search_literature` <sub>tool</sub>
52
60
 
53
- - INSPIRE query syntax or free text, with `sort` (`relevance`, `mostrecent`, `mostcited`), `document_types` and `subjects` (up to 4 values each, all of which must hold), and `year_from` / `year_to`; `size` 1–100 (default 10), paged by `page`
54
- - Only the first 10,000 results of a query are reachable: `page × size` beyond that fails as `beyond_result_window`, and a reversed year range as `invalid_year_range`
55
- - Hits carry `recid`, title, first author, date, citation counts, arXiv ID, DOI, publication, and a 300-character abstract snippet; `totalCount`, `nextPage`, and `appliedFilters` come back with the page, and a `notice` flags any query matching over 100,000 records
61
+ - INSPIRE query syntax or free text, with `sort` (`relevance`, `mostrecent`, `mostcited`), `document_types` and `subjects` (up to 4 values each, all must hold), and `year_from` / `year_to`; `size` 1–100 (default 10), paged by `page`
62
+ - Only the first 10,000 results of a query are reachable: `page × size` beyond that fails as `beyond_result_window`; a reversed year range fails as `invalid_year_range`
63
+ - Hits carry `recid`, title, first author, date, citation counts, arXiv ID, DOI, publication, and a 300-character abstract snippet; the page also returns `totalCount`, `nextPage`, and `appliedFilters`, and a `notice` flags queries matching over 100,000 records
56
64
 
57
65
  ---
58
66
 
59
67
  ### `cern_inspire_get_paper` <sub>tool</sub>
60
68
 
61
- - `paper` takes a recid, arXiv ID, DOI, inspirehep.net literature URL, or HEPData `ins<recid>` / hepdata.net record URL; `resolvedAs` names the form that matched, and a miss fails as `paper_not_found`
62
- - `max_authors` 0–500 (default 25) caps the author list; `authorCount` always gives the full number
63
- - `hepdata.status` is `available`, `none`, or `lookup_failed`, with `recordDoi`, `latestVersion`, `tableCount`, and `hepdataUrl` when available; `citingQuery` and `referencesQuery` feed `cern_inspire_search_literature`
69
+ - `paper` takes a recid, arXiv ID, DOI, inspirehep.net literature URL, or HEPData `ins<recid>` / hepdata.net `record/ins<recid>` URL; `resolvedAs` names the form that matched, and a miss fails as `paper_not_found`. A recid INSPIRE has merged into another record (older citations and HEPData `ins` links still carry such recids) returns the record INSPIRE redirects it to, with `mergedFrom` naming the recid asked for and a notice. A numbered hepdata.net record link, or a HEPData DOI no paper carries, names a HEPData record rather than a paper: its error gives the `cern_inspire_search_hepdata` query whose `paperRecids` reach the paper
70
+ - `max_authors` is a nonnegative integer (default 25); budgets above 500 use 500 with a notice. `author_offset` (default 0) pages through the available authors in record order; pass `nextAuthorOffset` to continue. `authorCount` retains INSPIRE's full count
71
+ - `hepdata.status` is `available`, `none`, or `lookup_failed`, with `recordDoi`, `latestVersion`, `tableCount`, and `hepdataUrl` (the hepdata.net page of that record number) when available; a paper with more than one HEPData record lists the rest in `hepdata.otherRecords`, with a notice; `citingQuery` and `referencesQuery` feed `cern_inspire_search_literature`
64
72
 
65
73
  ---
66
74
 
67
75
  ### `cern_inspire_export_citations` <sub>tool</sub>
68
76
 
69
- - Any literature query (`recid:451647 or arxiv:1207.7214` for named papers); `format` is `bibtex` (default), `latex-eu`, or `latex-us`; `size` 1–50 (default 10)
70
- - Entries arrive verbatim from INSPIRE, each with its `texkey`; `truncated` is set when more papers matched than `size`
77
+ - `document_types`, `subjects`, `year_from`, and `year_to` select the same set as literature search; multiple values AND together. `appliedFilters` echoes the selection on every page, including empty pages. Reversed years fail as `invalid_year_range` before any request
78
+
79
+ - Any literature query (`recid:451647 or arxiv:1207.7214` for named papers); `format` is `bibtex` (default), `latex-eu`, or `latex-us`; `sort` as in search; `size` 1–50 (default 10) per page, paged by `page` up to the first 10,000 matches (beyond that, `beyond_result_window`)
80
+ - Entries arrive verbatim from INSPIRE, each with its `texkey`; `truncated` is set when more matched papers follow the page, `nextPage` with it while the next page is within the 10,000-result window, and a page past the last returns no entries with a notice naming the last page
71
81
 
72
82
  ---
73
83
 
74
84
  ### `cern_inspire_search_authors` <sub>tool</sub>
75
85
 
76
86
  - A name or one identifier (BAI, ORCID, INSPIRE ID, author recid); `limit` 1–25 (default 5)
77
- - `matchedAs` reports the route: `orcid`, `inspire_id`, `bai`, and `recid` match exactly, while `name` runs a free-text search whose ranked candidates are returned for the caller to choose from
78
- - Profiles carry `recid`, `bai`, ORCID, positions, advisors, arXiv categories, awards, and a `literatureQuery` selecting the person's papers
87
+ - `matchedAs` is `orcid`, `inspire_id`, `bai`, or `recid` (exact match), or `name` (free-text search returning ranked candidates to choose from)
88
+ - Profiles carry `recid`, `bai`, ORCID, positions (with an `institutionRecid` that `affid:N` takes for the institution's papers), advisors, arXiv categories, awards, and a `literatureQuery` selecting the person's papers
79
89
 
80
90
  ---
81
91
 
82
92
  ### `cern_inspire_get_citation_summary` <sub>tool</sub>
83
93
 
84
- - Exactly one of `author` (BAI, ORCID, INSPIRE ID, or author recid) or `query` (any literature query); otherwise `missing_target`, and a name passed as `author` fails as `author_not_identifier`
85
- - `document_types`, `subjects`, and `year_from` / `year_to` narrow every figure; `exclude_self_citations` recounts without self-citations
94
+ - Exactly one of `author` (BAI, ORCID, INSPIRE ID, or author recid) or `query` (any literature query, such as `affid:902725` for an institution's papers); otherwise `missing_target`, and a name passed as `author` fails as `author_not_identifier`
95
+ - `document_types` and `subjects` narrow every figure; `year_from` / `year_to` narrow the summary, and `exclude_self_citations` drops self-citations from it
86
96
  - h-index, citation totals and averages, and paper counts in the buckets `0`, `1–9`, `10–49`, `50–99`, `100–249`, `250–499`, `500+`, each for all citeable and for published papers
97
+ - `citationsByYear`: citations received per year (the citing record's year, self-citations included, every matched record), ascending, with no row for a year without citations; left out, with a notice, under `year_from`, `year_to`, or `exclude_self_citations`, which INSPIRE's per-year series cannot apply, when INSPIRE does not return it, and for a query matching more than about 150,000 records, which INSPIRE cannot count in time, unless INSPIRE answers within about 2 s (a series it has cached); the call then returns in about 2 s
98
+ - An unfiltered call spends two of the pacer's request starts (three with `author`, which is resolved first); with `year_from`, `year_to`, or `exclude_self_citations` set, one (two). The per-year request holds one of the pacer's four in-flight slots for as long as INSPIRE takes (up to 15 s), so at most two per-year series run at once and other calls keep at least two slots
87
99
 
88
100
  ---
89
101
 
@@ -97,21 +109,21 @@ The same record is reachable through `cern_inspire_get_paper` for clients that d
97
109
  ### `cern_inspire_search_hepdata` <sub>tool</sub>
98
110
 
99
111
  - Free text or INSPIRE syntax over HEPData submissions (`collaborations.value:LHCb`, `literature.control_number:<recid>`); `sort` is `relevance` or `mostrecent`; `size` 1–50 (default 10), within the same 10,000-result window
100
- - Records carry `paperRecids`, collaborations, keywords (reactions, observables, centre-of-mass energies), `recordDoi`, `latestVersion`, `tableCount`, and `hepdataUrl`; table values are not returned
112
+ - Records carry `paperRecids`, collaborations, keywords (reactions, observables, centre-of-mass energies), `recordDoi`, `latestVersion`, `tableCount`, and `hepdataUrl` (each record's own hepdata.net page); table values are not returned
101
113
 
102
114
  ---
103
115
 
104
116
  ### `cern_inspire_list_reference` <sub>tool</sub>
105
117
 
106
118
  - `topic`: `search_syntax`, `identifiers`, `document_types`, `subjects`, `citation_buckets`, or `hepdata`
107
- - Static `term` / `meaning` / `example` entries with no upstream call
119
+ - Static `term` / `meaning` / `example` entries; no upstream call
108
120
 
109
121
  ---
110
122
 
111
123
  ### `inspire://literature/{recid}` <sub>resource</sub>
112
124
 
113
- - The `cern_inspire_get_paper` dossier for one recid as `application/json`, listing the first 25 authors
114
- - Takes a recid only; use the tool for arXiv IDs, DOIs, or a higher author cap
125
+ - The `cern_inspire_get_paper` dossier as `application/json`, listing the first 25 authors
126
+ - Takes a recid only and returns the first 25 authors at `authorOffset:0`; use the tool for arXiv IDs, DOIs, or further author pages. A merged recid serves the surviving record, with `mergedFrom`
115
127
 
116
128
  ## Features
117
129
 
@@ -119,34 +131,53 @@ Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): s
119
131
 
120
132
  INSPIRE-specific:
121
133
 
122
- - One process-wide pacer under INSPIRE's published 15 requests per 5 s: 12 request starts per 5 s, at most 4 in flight, and a shared cooldown after a 429 that starts at 5 s and doubles on each consecutive 429, up to 30 s
134
+ - One process-wide pacer under INSPIRE's published limit of 15 requests per 5 s: 12 request starts per 5 s, at most 4 in flight (no more than 2 of them slow citations-per-year requests), and a shared cooldown after a 429 that starts at 5 s and doubles on each consecutive 429, up to 30 s
123
135
  - One 55 s budget per tool call covers queue wait, up to 2 retries, and every request the call makes; a request that can't start in time fails at once as `pacer_shed` with a `retryAfter`
124
- - JSON requests select only the fields a tool returns, under an 8 MiB response ceiling and a strict query-parameter allowlist, since INSPIRE silently ignores parameters it doesn't know; author email addresses are never requested
125
- - Forgiving inputs: paper identifiers accept an `arXiv:` or `doi:` prefix, a version suffix, an arxiv.org, doi.org, or inspirehep.net URL, and HEPData's `ins<recid>`; author identifiers accept an orcid.org URL; `document_types` and `subjects` take an array or a comma-joined string in any case
136
+ - Requests select only the fields a tool returns, under an 8 MiB response ceiling; author email addresses are never requested
137
+ - Forgiving inputs: paper identifiers accept `arXiv:` / `doi:` prefixes, version suffixes, arxiv.org, doi.org, or inspirehep.net URLs, and HEPData's `ins<recid>`, a recid INSPIRE has merged away is followed to the surviving record, and every documented spelling passes a client's validation against the advertised schema; author identifiers accept an orcid.org URL
126
138
 
127
139
  Agent-friendly output:
128
140
 
129
- - Chainable identifiers: hits carry `recid`, author profiles and experiments carry a ready `literatureQuery`, and `cern_inspire_get_paper` returns `citingQuery` and `referencesQuery`, so the next call needs no query building
141
+ - Chainable identifiers: hits carry `recid`, author profiles and experiments carry a ready `literatureQuery`, and `cern_inspire_get_paper` returns `citingQuery` and `referencesQuery`
130
142
  - Query echo and paging state: `totalCount`, `truncated` / `shown` / `cap`, `nextPage`, `appliedFilters`, and `effectiveQuery`, plus a `notice` with next-step text on empty, capped, or suspiciously broad results
131
- - Discriminated fields: `hepdata.status`, `resolvedAs`, `matchedAs`, and `target.kind` let callers branch on data, and typed failure reasons (`paper_not_found`, `author_not_found`, `beyond_result_window`, `inspire_rate_limited`) each carry a recovery hint
132
- - No fabrication: a field INSPIRE leaves out stays absent and prints as "Not available" or "not recorded"; upstream strings are escaped in the text output and kept verbatim in `structuredContent`
143
+ - Discriminated fields: `hepdata.status`, `resolvedAs`, `matchedAs`, and `target.kind` let callers branch on data; typed failure reasons (`paper_not_found`, `author_not_found`, `beyond_result_window`, `inspire_rate_limited`) each carry a recovery hint
144
+ - No fabrication: a field INSPIRE leaves out stays absent and prints as "Not available" or "not recorded"
145
+ - Titles and abstracts as text: publisher HTML, JATS, and MathML become plain text (`σ_γ`, `^{23}Na(n,γ)`) on every tool that returns titles or abstracts and on the resource, with LaTeX left as published; citation export entries stay verbatim, and other upstream strings reach `structuredContent` as INSPIRE sends them, less any invisible Unicode tag characters, which are dropped. The text output escapes them all, leaving identifiers such as DOIs and texkeys copyable as written
133
146
 
134
147
  ## Data and licensing
135
148
 
136
149
  - INSPIRE-HEP metadata is mostly CC0 under INSPIRE's [terms of use](https://inspirehep.net/help/knowledge-base/terms-of-use/); credit INSPIRE when you reuse it.
137
150
  - HEPData records are CC0; cite the HEPData record DOI (`recordDoi`) when you reuse the data.
138
- - INSPIRE allows 15 requests per 5 seconds per address, and the server paces its own requests under that limit.
139
151
  - This is an independent project, not affiliated with or endorsed by INSPIRE-HEP, HEPData, or CERN.
140
152
 
141
153
  ## Known limitations
142
154
 
143
- - **No HEPData table values.** hepdata.net's bot challenge refuses the server's User-Agent, so tools that read hepdata.net directly are deferred. `cern_inspire_get_paper` and `cern_inspire_search_hepdata` return the record DOI and the hepdata.net page where the values are read.
144
- - **Malformed INSPIRE syntax doesn't fail.** An unparsed operator widens or empties the match instead; zero hits or a very large `totalCount` usually means a syntax slip (`cern_inspire_list_reference` topic `search_syntax`).
155
+ - **No HEPData table values.** hepdata.net's bot challenge refuses the server's User-Agent, so the server never calls it. `cern_inspire_get_paper` and `cern_inspire_search_hepdata` return the record DOI and the hepdata.net page where the values are read.
156
+ - **Malformed INSPIRE syntax doesn't fail.** An unparsed operator widens or empties the match; zero hits or a very large `totalCount` usually means a syntax slip (`cern_inspire_list_reference` topic `search_syntax`).
145
157
  - **10,000-result window.** Only the first 10,000 results of a query are reachable; narrow the query to reach the rest.
146
- - **One request queue per process, one rate limit per address.** Every caller of a server process shares one queue under INSPIRE's 15 requests per 5 s, so on a shared deployment one client's burst can delay or shed everyone else's calls with a retryable rate-limit error. A hosted deployment needs a per-client rate limit in front of `/mcp`, and should run one replica per egress IP, since INSPIRE counts requests per address; a per-caller share inside the server waits on the framework ([cyanheads/mcp-ts-core#618](https://github.com/cyanheads/mcp-ts-core/issues/618)).
158
+ - **Shared request queue.** All callers of one server process share one queue under INSPIRE's 15 requests per 5 s per address, so a burst can delay or shed other calls with a retryable rate-limit error.
147
159
 
148
160
  ## Getting started
149
161
 
162
+ ### Public Hosted Instance
163
+
164
+ A public instance is available at `https://cern-inspire.caseyjhand.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP:
165
+
166
+ ```json
167
+ {
168
+ "mcpServers": {
169
+ "cern-inspire-mcp-server": {
170
+ "type": "streamable-http",
171
+ "url": "https://cern-inspire.caseyjhand.com/mcp"
172
+ }
173
+ }
174
+ }
175
+ ```
176
+
177
+ Every caller of the hosted instance shares one INSPIRE request budget of 12 request starts per 5 seconds. For sustained use, run your own instance.
178
+
179
+ ### Self-Hosted / Local
180
+
150
181
  Add the following to your MCP client configuration file. No API key is needed.
151
182
 
152
183
  ```json
@@ -279,13 +310,13 @@ See [`.env.example`](./.env.example) for the full list of framework overrides.
279
310
 
280
311
  | Directory | Purpose |
281
312
  |:---|:---|
282
- | `src/index.ts` | `createApp()` entry point: registers the tools and resource, sets the server instructions, starts and disposes the INSPIRE service. |
283
- | `src/mcp-server/tools` | Tool definitions (`*.tool.ts`), eight tools, plus shared input schemas (`inputs.ts`). |
284
- | `src/mcp-server/resources` | Resource definitions. The literature record resource. |
285
- | `src/services/inspire` | INSPIRE service: request pacer, per-call budget, retries, identifier routing, normalization, and the controlled vocabularies. |
313
+ | `src/index.ts` | `createApp()` entry point: registers tools and resource, sets server instructions, starts and disposes the INSPIRE service. |
314
+ | `src/mcp-server/tools` | Tool definitions (`*.tool.ts`) and shared input schemas (`inputs.ts`). |
315
+ | `src/mcp-server/resources` | The literature record resource. |
316
+ | `src/services/inspire` | INSPIRE service: pacer, per-call budget, retries, identifier routing, normalization, controlled vocabularies. |
286
317
  | `src/services/http` | Bounded fetch: per-attempt timeout and response byte ceiling. |
287
318
  | `src/utils` | Escaping for upstream text in tool output and error messages (`render.ts`). |
288
- | `tests/` | Vitest suites for the tools, resource, services, and shared helpers, with INSPIRE response fixtures. |
319
+ | `tests/` | Vitest suites with INSPIRE response fixtures. |
289
320
  | `docs/design.md` | Tool surface, verified INSPIRE behavior, design decisions, and the deferred HEPData-direct tools. |
290
321
 
291
322
  ## Development guide
@@ -0,0 +1,29 @@
1
+ ---
2
+ summary: "Titles and abstracts arrive as plain text, HEPData record links open the record they describe, citation exports page past 50 entries, and citation summaries add citations per year."
3
+ breaking: false
4
+ security: false
5
+ ---
6
+
7
+ # 0.1.2 — 2026-10-02
8
+
9
+ ## Added
10
+
11
+ - **`page` on `cern_inspire_export_citations`** — exports sets larger than one `size`, up to the first 10,000 matches (`beyond_result_window` past that); output gains `page` and enrichment gains `nextPage`. A later page adds one parallel match-total request. ([#8](https://github.com/cyanheads/cern-inspire-mcp-server/issues/8))
12
+ - **`citationsByYear` on `cern_inspire_get_citation_summary`** — citations received per year, from a parallel `citations-by-year` facet request (at most 2 in flight). Omitted with a notice under `year_from`, `year_to`, or `exclude_self_citations`, when INSPIRE does not return it, and past about 150,000 matched records unless INSPIRE answers within 2 s. ([#10](https://github.com/cyanheads/cern-inspire-mcp-server/issues/10))
13
+ - **`hepdata.otherRecords` on `cern_inspire_get_paper`** — a paper's other HEPData records, in ascending record number; the availability lookup reads up to 10, and a notice names them. ([#6](https://github.com/cyanheads/cern-inspire-mcp-server/issues/6))
14
+ - **Affiliation queries** — `cern_inspire_list_reference` documents `aff NAME`, `affid:N`, and the institution recid; `institutionRecid`, `institutions[].recid`, and the citation-summary `query` point at `affid:N`. ([#9](https://github.com/cyanheads/cern-inspire-mcp-server/issues/9))
15
+ - **Public hosted endpoint** — `https://cern-inspire.caseyjhand.com/mcp` (Streamable HTTP), listed in the README and in `server.json` `remotes`.
16
+
17
+ ## Changed
18
+
19
+ - **Bare-words hint in `cern_inspire_search_literature`** — INSPIRE's affiliation operators (`aff`, `af`, `affil`, `affiliation`, `inst`, `institution`) and hyphenated fields such as `affiliation-id:` count as field operators. ([#9](https://github.com/cyanheads/cern-inspire-mcp-server/issues/9))
20
+ - **`upstream_unreadable` recovery** on `cern_inspire_export_citations`, `cern_inspire_search_literature`, and `cern_inspire_search_hepdata` — says to wait a minute and retry with the same page and size, not a smaller size, which would shift a paged caller's results.
21
+
22
+ ## Fixed
23
+
24
+ - **Titles and abstracts as text** — publisher HTML, JATS, MathML, and entities in INSPIRE and HEPData titles and abstracts convert to plain text (`markupToText()`) in `structuredContent` and `content[]`; LaTeX stays as published and export entries stay verbatim. Rendered text escapes `*`, `~`, and `_` outside a word. ([#7](https://github.com/cyanheads/cern-inspire-mcp-server/issues/7))
25
+ - **`hepdataUrl`** is `https://www.hepdata.net/record/<N>` from the HEPData record DOI (`/record/ins<recid>` only when the DOI names no number), so it opens the record whose DOI and table count it reports. ([#6](https://github.com/cyanheads/cern-inspire-mcp-server/issues/6))
26
+ - **Merged recids** — `cern_inspire_get_paper` and `inspire://literature/{recid}` follow INSPIRE's redirect to the surviving record instead of failing `paper_not_found`, with the new `mergedFrom` field and a notice. ([#13](https://github.com/cyanheads/cern-inspire-mcp-server/issues/13))
27
+ - **`paper` input schema** — advertises no `pattern` (checked in a refinement), so schema-validating clients accept the documented prefixed and URL spellings; facet descriptions document only the enum array. A HEPData record URL or DOI passed as `paper` gets the `cern_inspire_search_hepdata` route to its paper. ([#11](https://github.com/cyanheads/cern-inspire-mcp-server/issues/11))
28
+ - **`hepdataRecid` label** — `cern_inspire_search_hepdata` text prints it as the HEPData record number, not a recid, and its description routes `cern_inspire_get_paper` to `paperRecids`. ([#11](https://github.com/cyanheads/cern-inspire-mcp-server/issues/11))
29
+ - **Placeholders and echoes** — notices and recovery hints spell placeholders as uppercase words (`"t WORDS"`, `"a NAME"`), never `<…>`; caller echoes (`callerEcho()`) and identifier values (`identifier()`) print as written, with `<` neutralized only where it could open markup. ([#12](https://github.com/cyanheads/cern-inspire-mcp-server/issues/12))