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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/AGENTS.md +35 -20
  2. package/CLAUDE.md +35 -20
  3. package/Dockerfile +5 -3
  4. package/README.md +69 -120
  5. package/changelog/0.2.x/0.2.0.md +35 -0
  6. package/changelog/0.3.x/0.3.0.md +31 -0
  7. package/changelog/template.md +10 -3
  8. package/dist/index.js +2 -1
  9. package/dist/index.js.map +1 -1
  10. package/dist/mcp-server/resources/definitions/index.d.ts +28 -0
  11. package/dist/mcp-server/resources/definitions/index.d.ts.map +1 -1
  12. package/dist/mcp-server/resources/definitions/inspire-literature.resource.d.ts +28 -0
  13. package/dist/mcp-server/resources/definitions/inspire-literature.resource.d.ts.map +1 -1
  14. package/dist/mcp-server/resources/definitions/inspire-literature.resource.js +1 -1
  15. package/dist/mcp-server/resources/definitions/inspire-literature.resource.js.map +1 -1
  16. package/dist/mcp-server/tools/definitions/export-citations.tool.d.ts +2 -2
  17. package/dist/mcp-server/tools/definitions/export-citations.tool.d.ts.map +1 -1
  18. package/dist/mcp-server/tools/definitions/export-citations.tool.js +22 -31
  19. package/dist/mcp-server/tools/definitions/export-citations.tool.js.map +1 -1
  20. package/dist/mcp-server/tools/definitions/get-citation-summary.tool.d.ts.map +1 -1
  21. package/dist/mcp-server/tools/definitions/get-citation-summary.tool.js +11 -13
  22. package/dist/mcp-server/tools/definitions/get-citation-summary.tool.js.map +1 -1
  23. package/dist/mcp-server/tools/definitions/get-paper.tool.d.ts +61 -3
  24. package/dist/mcp-server/tools/definitions/get-paper.tool.d.ts.map +1 -1
  25. package/dist/mcp-server/tools/definitions/get-paper.tool.js +136 -40
  26. package/dist/mcp-server/tools/definitions/get-paper.tool.js.map +1 -1
  27. package/dist/mcp-server/tools/definitions/index.d.ts +258 -142
  28. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  29. package/dist/mcp-server/tools/definitions/index.js +2 -0
  30. package/dist/mcp-server/tools/definitions/index.js.map +1 -1
  31. package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts.map +1 -1
  32. package/dist/mcp-server/tools/definitions/list-reference.tool.js +20 -10
  33. package/dist/mcp-server/tools/definitions/list-reference.tool.js.map +1 -1
  34. package/dist/mcp-server/tools/definitions/search-authors.tool.d.ts +17 -5
  35. package/dist/mcp-server/tools/definitions/search-authors.tool.d.ts.map +1 -1
  36. package/dist/mcp-server/tools/definitions/search-authors.tool.js +69 -25
  37. package/dist/mcp-server/tools/definitions/search-authors.tool.js.map +1 -1
  38. package/dist/mcp-server/tools/definitions/search-experiments.tool.d.ts +16 -5
  39. package/dist/mcp-server/tools/definitions/search-experiments.tool.d.ts.map +1 -1
  40. package/dist/mcp-server/tools/definitions/search-experiments.tool.js +72 -28
  41. package/dist/mcp-server/tools/definitions/search-experiments.tool.js.map +1 -1
  42. package/dist/mcp-server/tools/definitions/search-hepdata.tool.d.ts +3 -3
  43. package/dist/mcp-server/tools/definitions/search-hepdata.tool.d.ts.map +1 -1
  44. package/dist/mcp-server/tools/definitions/search-hepdata.tool.js +19 -15
  45. package/dist/mcp-server/tools/definitions/search-hepdata.tool.js.map +1 -1
  46. package/dist/mcp-server/tools/definitions/search-institutions.tool.d.ts +77 -0
  47. package/dist/mcp-server/tools/definitions/search-institutions.tool.d.ts.map +1 -0
  48. package/dist/mcp-server/tools/definitions/search-institutions.tool.js +228 -0
  49. package/dist/mcp-server/tools/definitions/search-institutions.tool.js.map +1 -0
  50. package/dist/mcp-server/tools/definitions/search-literature.tool.d.ts +1 -1
  51. package/dist/mcp-server/tools/definitions/search-literature.tool.d.ts.map +1 -1
  52. package/dist/mcp-server/tools/definitions/search-literature.tool.js +21 -20
  53. package/dist/mcp-server/tools/definitions/search-literature.tool.js.map +1 -1
  54. package/dist/mcp-server/tools/inputs.d.ts +34 -4
  55. package/dist/mcp-server/tools/inputs.d.ts.map +1 -1
  56. package/dist/mcp-server/tools/inputs.js +202 -7
  57. package/dist/mcp-server/tools/inputs.js.map +1 -1
  58. package/dist/services/http/fetch-bounded.d.ts +1 -1
  59. package/dist/services/http/fetch-bounded.js +1 -1
  60. package/dist/services/inspire/identifiers.d.ts +20 -6
  61. package/dist/services/inspire/identifiers.d.ts.map +1 -1
  62. package/dist/services/inspire/identifiers.js +30 -9
  63. package/dist/services/inspire/identifiers.js.map +1 -1
  64. package/dist/services/inspire/inspire-service.d.ts +27 -10
  65. package/dist/services/inspire/inspire-service.d.ts.map +1 -1
  66. package/dist/services/inspire/inspire-service.js +115 -47
  67. package/dist/services/inspire/inspire-service.js.map +1 -1
  68. package/dist/services/inspire/normalize.d.ts +10 -2
  69. package/dist/services/inspire/normalize.d.ts.map +1 -1
  70. package/dist/services/inspire/normalize.js +84 -1
  71. package/dist/services/inspire/normalize.js.map +1 -1
  72. package/dist/services/inspire/types.d.ts +135 -4
  73. package/dist/services/inspire/types.d.ts.map +1 -1
  74. package/dist/utils/render.d.ts +6 -4
  75. package/dist/utils/render.d.ts.map +1 -1
  76. package/dist/utils/render.js +8 -4
  77. package/dist/utils/render.js.map +1 -1
  78. package/package.json +11 -10
  79. package/server.json +3 -3
  80. package/skills/cern-inspire-guide/SKILL.md +43 -0
@@ -0,0 +1,43 @@
1
+ ---
2
+ name: cern-inspire-guide
3
+ description: Use cern_inspire_* tools for HEP literature research, author or institution citation analysis, citation-network exploration, bibliography assembly, and finding numerical-data publications. Resolve identities, verify query scope, and distinguish publication-year filters from citation-year series before drawing conclusions.
4
+ license: Apache-2.0
5
+ metadata:
6
+ author: "cyanheads"
7
+ version: "1.1"
8
+ ---
9
+
10
+ ## Scope
11
+
12
+ INSPIRE-HEP covers high-energy-physics literature, author profiles, experiments, institutions, and publication-level HEPData records through a keyless API. Numerical table values require the returned HEPData record page; this server cannot read them.
13
+
14
+ ## Identifiers
15
+
16
+ Recids belong to separate collections. Keep each ID attached to its source: literature recids from `cern_inspire_search_literature` or `cern_inspire_get_paper`; author recids and BAIs from `cern_inspire_search_authors` or a dossier's `authors[]`/`supervisors[]`; experiment queries from `cern_inspire_search_experiments`; institution recids from `cern_inspire_search_institutions`, author positions, experiment institutions, or a dossier's `thesis.institutions[]`. A numeric paper ID is not an author or institution ID. A publication's `parentRecid` is a literature recid; `conferenceRecid` belongs to INSPIRE's conference collection.
17
+
18
+ Reuse returned `literatureQuery` values for author, experiment, and institution cohorts. For institutions, build `affid:N` only from a returned institution recid. A HEPData record DOI identifies data, not the associated literature record; follow returned paper recids for the publication.
19
+
20
+ ## Gates
21
+
22
+ 1. Resolve a person's name before attributing papers or metrics. Compare candidate profiles' affiliations, categories, and identifiers; do not select the first namesake by rank. A missing ORCID match can mean the profile has no linked ORCID: search by name before concluding the person is absent. Page on with `page` (follow `nextPage`) before concluding a namesake list lacks the person; once the surname-miss notice appears past page 1, later pages have left the queried surname, so pin the person by BAI, ORCID, or INSPIRE ID instead; extra name parts widen a name search.
23
+ 2. Inspect representative literature matches before summarizing or exporting a cohort. Check the effective query and applied filters. An unexpectedly broad or empty result can be malformed syntax despite a successful response; consult `cern_inspire_list_reference` before treating it as evidence. Multiple document types or subjects intersect; they do not form a union.
24
+ 3. Resolve an old paper ID with `cern_inspire_get_paper` before concluding a query has no matching paper, citations, or references. Merged IDs can match nothing in queries; use the surviving recid returned by the dossier.
25
+ 4. Distinguish papers published in a year range from citations received in that range. Summary year filters select the papers and leave out the yearly citation series. For citation-year questions, obtain the full series and select its returned year rows. An omitted series is unavailable, not zero; it counts citations over all matched records and need not sum to the citeable-paper total.
26
+ 5. Establish coverage before claiming a complete bibliography or literature set. Follow returned continuation signals and notices; do not keep probing until a page is empty. Literature search reports `totalCount` and `hasMore`; export uses `nextPage`, `truncated`, and notices, with no total count. Beyond the 10,000-result window, narrow the query and report the remaining coverage limit. Pages reflect a changing index: deduplication removes repeats but cannot prove that no papers were skipped.
27
+ 6. Distinguish an unsuccessful HEPData availability lookup from a negative result. Publication-level data metadata does not establish any particular table's contents or values.
28
+
29
+ ## Core chain
30
+
31
+ Resolve the paper, person, experiment, or institution → inspect the selected literature cohort → retrieve dossiers, summarize citations, or export the verified set. Keep the same query and filters when carrying a cohort between tools.
32
+
33
+ ## Workflows
34
+
35
+ **Author or institution analysis.** Resolve a person with `cern_inspire_search_authors`, inspect their returned literature query, then use `cern_inspire_get_citation_summary` for the selected profile. Resolve an institution with `cern_inspire_search_institutions`: free text returns candidates in INSPIRE's order, and a university's papers usually sit under department records whose parent is its "(main)" record. Choose by hierarchy, related records, and paper count, and page on before concluding a unit is absent. A name copied from a paper's affiliations finds its record exactly as `legacy_ICN:"NAME"`, one name per call. Each record's `affid:N` matches that record alone; join the department and main records you mean with `or`, and say which records the figures cover. `affid:N` includes linked author/supervisor affiliations, thesis institutions, and record-level affiliations, so describe that scope rather than calling it an employee-only publication count. Compare like scopes: all citeable versus published, the same publication years, and the same self-citation treatment.
36
+
37
+ **Citation networks and bibliographies.** Start with `cern_inspire_get_paper` and reuse its ready-made queries for citing papers or references; the INSPIRE operators are easy to reverse (`refersto` finds citing papers, `citedby` finds references). Inspect the set with `cern_inspire_search_literature`, then call `cern_inspire_export_citations`. For a curated shortlist, export the selected literature recids joined with `or` instead of rerunning the broad discovery query. Keep query, filters, sort, and page size fixed during pagination, and preserve any coverage notices with the bibliography.
38
+
39
+ **Measurements and numerical data.** When the paper is unknown, use `cern_inspire_search_hepdata` with the process, observable, energy, or collaboration. Follow its paper recids to `cern_inspire_get_paper` for publication context. When starting from an experiment, resolve it with `cern_inspire_search_experiments` and reuse its literature query to find the relevant paper. Return the HEPData record page for reading or downloading tables and its record DOI for citing the data; do not infer numerical results from keywords or table counts.
40
+
41
+ ## References
42
+
43
+ Call `cern_inspire_list_reference` for INSPIRE query syntax, identifier forms, document types, subjects, citation buckets, and HEPData version/DOI conventions. In particular, literature queries drop an arXiv version suffix (and say so), `refersto:`/`citedby:` take recids, not arXiv IDs, and ORCIDs resolve through author tools rather than literature queries.