@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.
- package/AGENTS.md +26 -36
- package/CLAUDE.md +26 -36
- package/Dockerfile +6 -3
- package/README.md +65 -34
- package/changelog/0.1.x/0.1.2.md +29 -0
- package/changelog/0.1.x/0.1.3.md +34 -0
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/mcp-server/resources/definitions/index.d.ts +15 -5
- package/dist/mcp-server/resources/definitions/index.d.ts.map +1 -1
- package/dist/mcp-server/resources/definitions/inspire-literature.resource.d.ts +15 -5
- 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 +56 -3
- package/dist/mcp-server/tools/definitions/export-citations.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/export-citations.tool.js +121 -24
- package/dist/mcp-server/tools/definitions/export-citations.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-citation-summary.tool.d.ts +8 -4
- package/dist/mcp-server/tools/definitions/get-citation-summary.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-citation-summary.tool.js +77 -22
- 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 +31 -10
- package/dist/mcp-server/tools/definitions/get-paper.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-paper.tool.js +139 -47
- package/dist/mcp-server/tools/definitions/get-paper.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +83 -15
- package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/list-reference.tool.js +33 -9
- 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 +9 -9
- 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 +6 -3
- package/dist/mcp-server/tools/definitions/search-experiments.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-hepdata.tool.d.ts +2 -2
- package/dist/mcp-server/tools/definitions/search-hepdata.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-hepdata.tool.js +14 -12
- package/dist/mcp-server/tools/definitions/search-hepdata.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-literature.tool.d.ts +3 -3
- package/dist/mcp-server/tools/definitions/search-literature.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-literature.tool.js +30 -16
- package/dist/mcp-server/tools/definitions/search-literature.tool.js.map +1 -1
- package/dist/mcp-server/tools/inputs.d.ts +23 -5
- package/dist/mcp-server/tools/inputs.d.ts.map +1 -1
- package/dist/mcp-server/tools/inputs.js +88 -10
- package/dist/mcp-server/tools/inputs.js.map +1 -1
- package/dist/services/inspire/identifiers.d.ts +17 -6
- package/dist/services/inspire/identifiers.d.ts.map +1 -1
- package/dist/services/inspire/identifiers.js +28 -7
- package/dist/services/inspire/identifiers.js.map +1 -1
- package/dist/services/inspire/inspire-service.d.ts +79 -18
- package/dist/services/inspire/inspire-service.d.ts.map +1 -1
- package/dist/services/inspire/inspire-service.js +297 -49
- package/dist/services/inspire/inspire-service.js.map +1 -1
- package/dist/services/inspire/markup-to-text.d.ts +32 -0
- package/dist/services/inspire/markup-to-text.d.ts.map +1 -0
- package/dist/services/inspire/markup-to-text.js +783 -0
- package/dist/services/inspire/markup-to-text.js.map +1 -0
- package/dist/services/inspire/normalize.d.ts +24 -6
- package/dist/services/inspire/normalize.d.ts.map +1 -1
- package/dist/services/inspire/normalize.js +100 -22
- package/dist/services/inspire/normalize.js.map +1 -1
- package/dist/services/inspire/types.d.ts +80 -8
- package/dist/services/inspire/types.d.ts.map +1 -1
- package/dist/utils/render.d.ts +34 -5
- package/dist/utils/render.d.ts.map +1 -1
- package/dist/utils/render.js +69 -16
- package/dist/utils/render.js.map +1 -1
- package/package.json +11 -11
- package/server.json +16 -24
|
@@ -10,14 +10,29 @@ import type { Context } from '@cyanheads/mcp-ts-core';
|
|
|
10
10
|
import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
|
|
11
11
|
import { type Pacer } from '@cyanheads/mcp-ts-core/utils';
|
|
12
12
|
import { type AuthorRoute } from './identifiers.js';
|
|
13
|
-
import type { AuthorSearchPage, CitationExport, CitationExportParams,
|
|
13
|
+
import type { AuthorSearchPage, CitationExport, CitationExportParams, CitationSummaryLookup, CitationSummaryParams, ExperimentSearchPage, HepdataLookup, HepdataSearchPage, HepdataSearchParams, LiteratureSearchPage, LiteratureSearchParams, PaperLookup, ResolvedAuthor, ResolvedPaper } from './types.js';
|
|
14
14
|
/** One budget per tool call, inside a 60 s client timeout. */
|
|
15
15
|
export declare const CALL_BUDGET_MS = 55000;
|
|
16
|
+
/**
|
|
17
|
+
* The citations-by-year series' own budget: one attempt's timeout. Its time grows
|
|
18
|
+
* with the matched set (0.5 s for an author, 4 s at 10,000 records, 10.5 s at
|
|
19
|
+
* 122,000; 278,875 took 25 s and 644,000 drew a 500 after 30 s) while the summary
|
|
20
|
+
* beside it stays near 0.5 s, so a broad query's series is cut here, not retried.
|
|
21
|
+
*/
|
|
22
|
+
export declare const CITATIONS_BY_YEAR_BUDGET_MS = 15000;
|
|
23
|
+
/**
|
|
24
|
+
* Past this many matched records INSPIRE takes longer than the series' budget to
|
|
25
|
+
* answer it cold (2026-10-01: 121,921 records in 10.5 s, 149,688 in 16.8 s), so
|
|
26
|
+
* the series is cut early instead of waited on.
|
|
27
|
+
*/
|
|
28
|
+
export declare const BROAD_SERIES_RECORDS = 150000;
|
|
16
29
|
/** One tool call's view of INSPIRE: its context and the deadline every request in it shares. */
|
|
17
30
|
export interface InspireCall {
|
|
18
31
|
readonly ctx: Context;
|
|
19
32
|
/** Epoch ms after which no request in this call may run. */
|
|
20
33
|
readonly deadline: number;
|
|
34
|
+
/** Abandons a request the call no longer needs; `ctx.signal` still cancels it too. */
|
|
35
|
+
readonly signal?: AbortSignal;
|
|
21
36
|
}
|
|
22
37
|
/** Constructor options; `fetch` and `pacer` are the test seams. */
|
|
23
38
|
export interface InspireServiceOptions {
|
|
@@ -30,11 +45,17 @@ export interface InspireServiceOptions {
|
|
|
30
45
|
export declare class InspireService {
|
|
31
46
|
private readonly fetchImpl;
|
|
32
47
|
private readonly pacer;
|
|
48
|
+
/**
|
|
49
|
+
* Admits citations-by-year series to the INSPIRE pacer at most
|
|
50
|
+
* `SERIES_MAX_CONCURRENT` at a time. It sets no rate of its own: each series
|
|
51
|
+
* still starts through `pacer`, which keeps the start rate and the 429 cooldown.
|
|
52
|
+
*/
|
|
53
|
+
private readonly seriesGate;
|
|
33
54
|
private readonly userAgent;
|
|
34
55
|
constructor(options: InspireServiceOptions);
|
|
35
56
|
/** Opens one tool call's budget; pass the result to every method the call makes. */
|
|
36
57
|
beginCall(ctx: Context, budgetMs?: number): InspireCall;
|
|
37
|
-
/** Releases
|
|
58
|
+
/** Releases both pacers' timers and rejects their queued waiters. */
|
|
38
59
|
dispose(): void;
|
|
39
60
|
/** One page of literature search results. */
|
|
40
61
|
searchLiterature(params: LiteratureSearchParams, call: InspireCall): Promise<LiteratureSearchPage>;
|
|
@@ -47,22 +68,47 @@ export declare class InspireService {
|
|
|
47
68
|
resolvePaper(paper: string, call: InspireCall): Promise<ResolvedPaper | undefined>;
|
|
48
69
|
/**
|
|
49
70
|
* The `get_paper` dossier: resolves the identifier, then reads the record and
|
|
50
|
-
* its HEPData availability in parallel. `
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
71
|
+
* its HEPData availability in parallel. When the `recid:N` search returns no
|
|
72
|
+
* hit, INSPIRE may have merged the record into another and kept N as a
|
|
73
|
+
* redirect, which its search does not follow: the record URL is asked where N
|
|
74
|
+
* went, and the record and availability are read again for the recid it names
|
|
75
|
+
* (`mergedFrom` then holds N), up to `MAX_MERGE_REDIRECTS` times. `undefined`
|
|
76
|
+
* when the identifier matches no record. A failed availability lookup degrades
|
|
77
|
+
* to `hepdata.status: 'lookup_failed'` — except a cancelled call or an
|
|
78
|
+
* input-class rejection, which rethrow — unless `requireHepdata` is set, when it
|
|
79
|
+
* throws its own error once the record is known to exist. Any failure of the
|
|
80
|
+
* resolve, a record read, or a redirect lookup throws.
|
|
55
81
|
*/
|
|
56
82
|
getPaper(paper: string, maxAuthors: number, call: InspireCall, options?: {
|
|
57
83
|
requireHepdata?: boolean;
|
|
84
|
+
authorOffset?: number;
|
|
58
85
|
}): Promise<PaperLookup | undefined>;
|
|
59
|
-
/**
|
|
60
|
-
|
|
86
|
+
/**
|
|
87
|
+
* Where INSPIRE sends a recid its search does not return: `GET
|
|
88
|
+
* /literature/<recid>` with redirects not followed. A merged record answers with
|
|
89
|
+
* a redirect to the record it was merged into, whose recid is returned. A recid
|
|
90
|
+
* INSPIRE does not hold (404) or has deleted (410) gives `undefined`, and so does
|
|
91
|
+
* one it serves (200) although its search returns nothing, which is logged.
|
|
92
|
+
*/
|
|
93
|
+
private mergedInto;
|
|
94
|
+
/**
|
|
95
|
+
* HEPData availability for one paper recid, from INSPIRE's `data` collection:
|
|
96
|
+
* up to `HEPDATA_RECORDS_PER_PAPER` of its data records in one request, and
|
|
97
|
+
* INSPIRE's total.
|
|
98
|
+
*/
|
|
99
|
+
getHepdataAvailability(recid: string, call: InspireCall): Promise<HepdataLookup>;
|
|
61
100
|
private degradeAvailability;
|
|
62
101
|
/**
|
|
63
|
-
* INSPIRE's citation entries for a literature query.
|
|
64
|
-
*
|
|
65
|
-
*
|
|
102
|
+
* INSPIRE's citation entries for one page of a literature query. Page 1 is one
|
|
103
|
+
* request for `size + 1` entries, truncated when the extra one came back. A
|
|
104
|
+
* later page cannot carry that probe, since INSPIRE's pages sit `size` apart: it
|
|
105
|
+
* sends `page` and `size` as given, with one `fields=control_number&size=1`
|
|
106
|
+
* search on the same query in parallel for the match total. The total sets
|
|
107
|
+
* `truncated`, and a page at or past it returns no entries, because INSPIRE
|
|
108
|
+
* answers a past-the-end page of an OR query with a leftover entry. A failed
|
|
109
|
+
* total request never fails the page: the page returns as INSPIRE sent it, with
|
|
110
|
+
* no `total`, unless the call was cancelled. Zero matches is an empty body and
|
|
111
|
+
* an empty `entries`.
|
|
66
112
|
*/
|
|
67
113
|
exportCitations(params: CitationExportParams, call: InspireCall): Promise<CitationExport>;
|
|
68
114
|
/**
|
|
@@ -77,8 +123,20 @@ export declare class InspireService {
|
|
|
77
123
|
* route) to the profile's recid and name. `undefined` when no profile matches.
|
|
78
124
|
*/
|
|
79
125
|
resolveAuthor(route: AuthorRoute, call: InspireCall): Promise<ResolvedAuthor | undefined>;
|
|
80
|
-
/**
|
|
81
|
-
|
|
126
|
+
/**
|
|
127
|
+
* INSPIRE's citation summary for a literature query under the given facet
|
|
128
|
+
* filters, and its citations-by-year series. The series facet honors `doc_type`
|
|
129
|
+
* and `subject` but ignores `earliest_date` and `exclude-self-citations`, so with
|
|
130
|
+
* a year bound or the self-citation exclusion set it is not requested (`skipped`,
|
|
131
|
+
* naming those filters). Otherwise both facets are requested in parallel, since
|
|
132
|
+
* one request keeps only its first `facet_name`; the series runs under its own
|
|
133
|
+
* 15 s budget inside the call's. A failure of the summary fails the call and
|
|
134
|
+
* abandons the series. When the summary counts more than `BROAD_SERIES_RECORDS`
|
|
135
|
+
* matches, the series is abandoned `BROAD_SERIES_CUT_MS` after the requests
|
|
136
|
+
* started unless it has landed (`too_broad`). Any other failure of the series
|
|
137
|
+
* returns the summary with the series `failed`; only a cancelled call rethrows.
|
|
138
|
+
*/
|
|
139
|
+
getCitationSummary(params: CitationSummaryParams, call: InspireCall): Promise<CitationSummaryLookup>;
|
|
82
140
|
/**
|
|
83
141
|
* Experiments, collaborations, and facilities by free text; a query of digits
|
|
84
142
|
* only is a recid (`control_number:<n>` — digits as free text match nothing).
|
|
@@ -86,12 +144,15 @@ export declare class InspireService {
|
|
|
86
144
|
searchExperiments(query: string, limit: number, call: InspireCall): Promise<ExperimentSearchPage>;
|
|
87
145
|
/** One page of HEPData records from INSPIRE's `data` collection. */
|
|
88
146
|
searchHepdata(params: HepdataSearchParams, call: InspireCall): Promise<HepdataSearchPage>;
|
|
147
|
+
/** One INSPIRE request whose body `parse` reads; see {@link InspireService.request}. */
|
|
148
|
+
private send;
|
|
89
149
|
/**
|
|
90
150
|
* One INSPIRE request inside the call's budget: retry (outside) around the
|
|
91
|
-
* pacer (inside) around fetch + status mapping, with `
|
|
92
|
-
* so an unreadable
|
|
151
|
+
* pacer (inside) around fetch + status mapping, with `read` inside the retry
|
|
152
|
+
* so an unreadable response is retried like a failed fetch. `exchange` sets the
|
|
153
|
+
* statuses returned to `read` and whether redirects are followed.
|
|
93
154
|
*/
|
|
94
|
-
private
|
|
155
|
+
private request;
|
|
95
156
|
/** One HTTP exchange; maps INSPIRE's 400 and 429 onto the shared contract reasons. */
|
|
96
157
|
private exchange;
|
|
97
158
|
}
|
|
@@ -99,6 +160,6 @@ export declare class InspireService {
|
|
|
99
160
|
export declare function initInspireService(config: AppConfig): void;
|
|
100
161
|
/** The initialized service. Throws when `initInspireService()` has not run. */
|
|
101
162
|
export declare function getInspireService(): InspireService;
|
|
102
|
-
/** Disposes the service's
|
|
163
|
+
/** Disposes the service's pacers; called from `createApp`'s `teardown()`. */
|
|
103
164
|
export declare function disposeInspireService(): void;
|
|
104
165
|
//# sourceMappingURL=inspire-service.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"inspire-service.d.ts","sourceRoot":"","sources":["../../../src/services/inspire/inspire-service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAU/D,OAAO,EAAe,KAAK,KAAK,EAAa,MAAM,8BAA8B,CAAC;AAGlF,OAAO,EACL,KAAK,WAAW,EAKjB,MAAM,kBAAkB,CAAC;
|
|
1
|
+
{"version":3,"file":"inspire-service.d.ts","sourceRoot":"","sources":["../../../src/services/inspire/inspire-service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAU/D,OAAO,EAAe,KAAK,KAAK,EAAa,MAAM,8BAA8B,CAAC;AAGlF,OAAO,EACL,KAAK,WAAW,EAKjB,MAAM,kBAAkB,CAAC;AAa1B,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EAGpB,aAAa,EACb,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,EACtB,WAAW,EAQX,cAAc,EACd,aAAa,EAEd,MAAM,YAAY,CAAC;AAMpB,8DAA8D;AAC9D,eAAO,MAAM,cAAc,QAAS,CAAC;AAMrC;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,QAAqB,CAAC;AAC9D;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,SAAU,CAAC;AAkM5C,gGAAgG;AAChG,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sFAAsF;IACtF,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAWD,mEAAmE;AACnE,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;CACjB;AAuJD,sDAAsD;AACtD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,YAAY,OAAO,EAAE,qBAAqB,EAezC;IAED,oFAAoF;IACpF,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,SAAiB,GAAG,WAAW,CAE9D;IAED,qEAAqE;IACrE,OAAO,IAAI,IAAI,CAGd;IAID,6CAA6C;IACvC,gBAAgB,CACpB,MAAM,EAAE,sBAAsB,EAC9B,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,oBAAoB,CAAC,CAoB/B;IAED;;;;;OAKG;IACG,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CA6BvF;IAED;;;;;;;;;;;;OAYG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,WAAW,EACjB,OAAO,GAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAO,GAChE,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CA0DlC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAsBlB;;;;OAIG;IACG,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAgBrF;IAED,OAAO,CAAC,mBAAmB;IAiB3B;;;;;;;;;;;OAWG;IACG,eAAe,CAAC,MAAM,EAAE,oBAAoB,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAmD9F;IAID;;;;;OAKG;IACG,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgB9F;IAED;;;OAGG;IACG,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAY9F;IAED;;;;;;;;;;;;OAYG;IACG,kBAAkB,CACtB,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,qBAAqB,CAAC,CAyFhC;IAID;;;OAGG;IACG,iBAAiB,CACrB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,oBAAoB,CAAC,CAa/B;IAID,oEAAoE;IAC9D,aAAa,CAAC,MAAM,EAAE,mBAAmB,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAmB9F;IAID,wFAAwF;IACxF,OAAO,CAAC,IAAI;IAUZ;;;;;OAKG;IACH,OAAO,CAAC,OAAO;IA6Cf,sFAAsF;YACxE,QAAQ;CAuCvB;AAMD,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAE1D;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,IAAI,cAAc,CAKlD;AAED,6EAA6E;AAC7E,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C"}
|