@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.
- package/AGENTS.md +31 -18
- package/CLAUDE.md +31 -18
- package/Dockerfile +5 -3
- package/README.md +59 -119
- package/changelog/0.2.x/0.2.0.md +35 -0
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/mcp-server/resources/definitions/index.d.ts +8 -0
- package/dist/mcp-server/resources/definitions/index.d.ts.map +1 -1
- package/dist/mcp-server/resources/definitions/inspire-literature.resource.d.ts +8 -0
- package/dist/mcp-server/resources/definitions/inspire-literature.resource.d.ts.map +1 -1
- package/dist/mcp-server/resources/definitions/inspire-literature.resource.js +1 -1
- package/dist/mcp-server/resources/definitions/inspire-literature.resource.js.map +1 -1
- package/dist/mcp-server/tools/definitions/export-citations.tool.d.ts +2 -2
- package/dist/mcp-server/tools/definitions/export-citations.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/export-citations.tool.js +14 -21
- package/dist/mcp-server/tools/definitions/export-citations.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-citation-summary.tool.js +4 -4
- package/dist/mcp-server/tools/definitions/get-citation-summary.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-paper.tool.d.ts +17 -1
- package/dist/mcp-server/tools/definitions/get-paper.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-paper.tool.js +53 -22
- package/dist/mcp-server/tools/definitions/get-paper.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +93 -85
- package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/list-reference.tool.js +1 -1
- package/dist/mcp-server/tools/definitions/list-reference.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-authors.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-authors.tool.js +7 -3
- package/dist/mcp-server/tools/definitions/search-authors.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-experiments.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-experiments.tool.js +17 -10
- package/dist/mcp-server/tools/definitions/search-experiments.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-hepdata.tool.d.ts +1 -1
- package/dist/mcp-server/tools/definitions/search-hepdata.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-hepdata.tool.js +8 -6
- package/dist/mcp-server/tools/definitions/search-hepdata.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-literature.tool.d.ts +1 -1
- package/dist/mcp-server/tools/definitions/search-literature.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-literature.tool.js +9 -7
- package/dist/mcp-server/tools/definitions/search-literature.tool.js.map +1 -1
- package/dist/mcp-server/tools/inputs.d.ts +1 -1
- package/dist/mcp-server/tools/inputs.d.ts.map +1 -1
- package/dist/mcp-server/tools/inputs.js +15 -3
- package/dist/mcp-server/tools/inputs.js.map +1 -1
- package/dist/services/inspire/inspire-service.d.ts +10 -3
- package/dist/services/inspire/inspire-service.d.ts.map +1 -1
- package/dist/services/inspire/inspire-service.js +48 -34
- package/dist/services/inspire/inspire-service.js.map +1 -1
- package/dist/services/inspire/normalize.d.ts.map +1 -1
- package/dist/services/inspire/normalize.js +15 -0
- package/dist/services/inspire/normalize.js.map +1 -1
- package/dist/services/inspire/types.d.ts +20 -4
- package/dist/services/inspire/types.d.ts.map +1 -1
- package/dist/utils/render.d.ts +6 -4
- package/dist/utils/render.d.ts.map +1 -1
- package/dist/utils/render.js +8 -4
- package/dist/utils/render.js.map +1 -1
- package/package.json +9 -8
- package/server.json +3 -3
- 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.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.
|
|
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.
|
|
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
|
|
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`
|
|
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
|
|
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
|
-
- **
|
|
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
|
|
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
|
|
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
|
|
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
|
|
111
|
-
shown: z.number().describe('Number of
|
|
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
|
|
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 #
|
|
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
|
-
|
|
338
|
+
Two skill trees live at the project root, written for different readers:
|
|
336
339
|
|
|
337
|
-
|
|
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
|
|
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.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.
|
|
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.
|
|
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
|
|
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`
|
|
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
|
|
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
|
-
- **
|
|
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
|
|
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
|
|
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
|
|
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
|
|
111
|
-
shown: z.number().describe('Number of
|
|
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
|
|
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 #
|
|
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
|
-
|
|
338
|
+
Two skill trees live at the project root, written for different readers:
|
|
336
339
|
|
|
337
|
-
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
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
|