@cyanheads/cern-inspire-mcp-server 0.1.1
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 +504 -0
- package/CLAUDE.md +504 -0
- package/Dockerfile +177 -0
- package/LICENSE +201 -0
- package/README.md +311 -0
- package/changelog/0.1.x/0.1.0.md +9 -0
- package/changelog/0.1.x/0.1.1.md +22 -0
- package/changelog/template.md +151 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +23 -0
- package/dist/index.js.map +1 -0
- package/dist/mcp-server/resources/definitions/index.d.ts +106 -0
- package/dist/mcp-server/resources/definitions/index.d.ts.map +1 -0
- package/dist/mcp-server/resources/definitions/index.js +7 -0
- package/dist/mcp-server/resources/definitions/index.js.map +1 -0
- package/dist/mcp-server/resources/definitions/inspire-literature.resource.d.ts +110 -0
- package/dist/mcp-server/resources/definitions/inspire-literature.resource.d.ts.map +1 -0
- package/dist/mcp-server/resources/definitions/inspire-literature.resource.js +69 -0
- package/dist/mcp-server/resources/definitions/inspire-literature.resource.js.map +1 -0
- package/dist/mcp-server/tools/definitions/export-citations.tool.d.ts +65 -0
- package/dist/mcp-server/tools/definitions/export-citations.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/export-citations.tool.js +120 -0
- package/dist/mcp-server/tools/definitions/export-citations.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/get-citation-summary.tool.d.ts +159 -0
- package/dist/mcp-server/tools/definitions/get-citation-summary.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/get-citation-summary.tool.js +262 -0
- package/dist/mcp-server/tools/definitions/get-citation-summary.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/get-paper.tool.d.ts +195 -0
- package/dist/mcp-server/tools/definitions/get-paper.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/get-paper.tool.js +356 -0
- package/dist/mcp-server/tools/definitions/get-paper.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/index.d.ts +675 -0
- package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/index.js +23 -0
- package/dist/mcp-server/tools/definitions/index.js.map +1 -0
- package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts +33 -0
- package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/list-reference.tool.js +312 -0
- package/dist/mcp-server/tools/definitions/list-reference.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/search-authors.tool.d.ts +92 -0
- package/dist/mcp-server/tools/definitions/search-authors.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/search-authors.tool.js +298 -0
- package/dist/mcp-server/tools/definitions/search-authors.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/search-experiments.tool.d.ts +80 -0
- package/dist/mcp-server/tools/definitions/search-experiments.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/search-experiments.tool.js +223 -0
- package/dist/mcp-server/tools/definitions/search-experiments.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/search-hepdata.tool.d.ts +81 -0
- package/dist/mcp-server/tools/definitions/search-hepdata.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/search-hepdata.tool.js +225 -0
- package/dist/mcp-server/tools/definitions/search-hepdata.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/search-literature.tool.d.ts +127 -0
- package/dist/mcp-server/tools/definitions/search-literature.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/search-literature.tool.js +331 -0
- package/dist/mcp-server/tools/definitions/search-literature.tool.js.map +1 -0
- package/dist/mcp-server/tools/inputs.d.ts +80 -0
- package/dist/mcp-server/tools/inputs.d.ts.map +1 -0
- package/dist/mcp-server/tools/inputs.js +100 -0
- package/dist/mcp-server/tools/inputs.js.map +1 -0
- package/dist/services/http/fetch-bounded.d.ts +45 -0
- package/dist/services/http/fetch-bounded.d.ts.map +1 -0
- package/dist/services/http/fetch-bounded.js +79 -0
- package/dist/services/http/fetch-bounded.js.map +1 -0
- package/dist/services/inspire/identifiers.d.ts +55 -0
- package/dist/services/inspire/identifiers.d.ts.map +1 -0
- package/dist/services/inspire/identifiers.js +98 -0
- package/dist/services/inspire/identifiers.js.map +1 -0
- package/dist/services/inspire/inspire-service.d.ts +104 -0
- package/dist/services/inspire/inspire-service.d.ts.map +1 -0
- package/dist/services/inspire/inspire-service.js +525 -0
- package/dist/services/inspire/inspire-service.js.map +1 -0
- package/dist/services/inspire/normalize.d.ts +30 -0
- package/dist/services/inspire/normalize.d.ts.map +1 -0
- package/dist/services/inspire/normalize.js +438 -0
- package/dist/services/inspire/normalize.js.map +1 -0
- package/dist/services/inspire/types.d.ts +505 -0
- package/dist/services/inspire/types.d.ts.map +1 -0
- package/dist/services/inspire/types.js +8 -0
- package/dist/services/inspire/types.js.map +1 -0
- package/dist/services/inspire/vocabulary.d.ts +22 -0
- package/dist/services/inspire/vocabulary.d.ts.map +1 -0
- package/dist/services/inspire/vocabulary.js +68 -0
- package/dist/services/inspire/vocabulary.js.map +1 -0
- package/dist/utils/render.d.ts +40 -0
- package/dist/utils/render.d.ts.map +1 -0
- package/dist/utils/render.js +112 -0
- package/dist/utils/render.js.map +1 -0
- package/package.json +112 -0
- package/server.json +100 -0
package/AGENTS.md
ADDED
|
@@ -0,0 +1,504 @@
|
|
|
1
|
+
# Developer Protocol
|
|
2
|
+
|
|
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`
|
|
6
|
+
**Engines:** Bun ≥1.4.0, Node ≥24.0.0
|
|
7
|
+
**MCP SDK:** `@modelcontextprotocol/server` ^2.1.0
|
|
8
|
+
**Zod:** ^4.6.5
|
|
9
|
+
|
|
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
|
+
|
|
12
|
+
> **Read the design next:** `docs/design.md` records the tool surface, the input and output shapes, the INSPIRE API behavior verified live, the service's pacing and retry table, the design decisions, and the deferred HEPData-direct tools. Update it when the surface or a decision changes.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## Domain
|
|
17
|
+
|
|
18
|
+
Eight read-only tools and one resource over INSPIRE-HEP's keyless REST API (`https://inspirehep.net/api`). HEPData is reached only through INSPIRE's `data` collection; no request goes to hepdata.net, whose bot challenge refuses the server's User-Agent (design § Design Decisions #1). So the server reads no table values: `cern_inspire_get_paper` and `cern_inspire_search_hepdata` report each HEPData record's DOI, latest version, table count, and hepdata.net link.
|
|
19
|
+
|
|
20
|
+
| Upstream path | Used by |
|
|
21
|
+
|:--------------|:--------|
|
|
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` |
|
|
25
|
+
| `/authors` | `cern_inspire_search_authors`, author resolution in `cern_inspire_get_citation_summary` |
|
|
26
|
+
| `/experiments` | `cern_inspire_search_experiments` |
|
|
27
|
+
| `/data` | `cern_inspire_search_hepdata`, the `hepdata` block of `cern_inspire_get_paper` |
|
|
28
|
+
|
|
29
|
+
`cern_inspire_list_reference` serves static tables and makes no upstream call. There are no prompts.
|
|
30
|
+
|
|
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
|
+
|
|
33
|
+
Conventions every definition follows:
|
|
34
|
+
|
|
35
|
+
- **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
|
+
- **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
|
+
- **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.
|
|
40
|
+
- **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
|
+
- **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
|
+
- **No fabrication.** A field INSPIRE leaves out stays absent (`firstAuthor`, `ongoing`, `averageCitations`), and `format()` prints "Not available" or "not recorded" rather than a guess.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## What's Next?
|
|
47
|
+
|
|
48
|
+
When the user asks what's next or needs direction, suggest options based on the current project state. Common next steps:
|
|
49
|
+
|
|
50
|
+
1. **Re-run the `setup` skill** — ensures CLAUDE.md, skills, structure, and metadata are populated and up to date with the current codebase
|
|
51
|
+
2. **Run the `design-mcp-server` skill** — if the tool/resource surface hasn't been mapped yet, work through domain design
|
|
52
|
+
3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-app-tool`, `add-resource`, `add-prompt` skills
|
|
53
|
+
4. **Add services** — scaffold domain service integrations using the `add-service` skill
|
|
54
|
+
5. **Add tests** — scaffold tests for existing definitions using the `add-test` skill
|
|
55
|
+
6. **Field-test definitions** — exercise tools/resources/prompts with real inputs using the `field-test` skill, get a report of issues and pain points
|
|
56
|
+
7. **Run `devcheck`** — lint, format, typecheck, and security audit
|
|
57
|
+
8. **Run the `security-pass` skill** — audit handlers for MCP-specific security gaps: output injection, scope blast radius, input sinks, tenant isolation
|
|
58
|
+
9. **Run the `polish-docs-meta` skill** — finalize README, CHANGELOG, metadata, and agent protocol for shipping
|
|
59
|
+
10. **Run the `maintenance` skill** — investigate changelogs, adopt upstream changes, and sync skills after `bun update --latest`
|
|
60
|
+
|
|
61
|
+
Tailor suggestions to what's actually missing or stale — don't recite the full list every time.
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Core Rules
|
|
66
|
+
|
|
67
|
+
- **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
|
|
68
|
+
- **Use `ctx.log`** for request-scoped logging. No `console` calls.
|
|
69
|
+
- **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
|
|
70
|
+
- **Need input the caller didn't supply?** `return ctx.requestInput(...)` and read `ctx.inputs` when the handler is re-entered. Never `await` for user input mid-handler.
|
|
71
|
+
- **Secrets in env vars only** — never hardcoded.
|
|
72
|
+
- **Cut noise.** Add only what earns its place: no speculative generality, no guards for states the framework already prevents (Zod-validated params, classified errors), no abstraction until a third caller proves it, no option nothing sets.
|
|
73
|
+
- **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## Patterns
|
|
78
|
+
|
|
79
|
+
### Tool
|
|
80
|
+
|
|
81
|
+
`cern_inspire_get_paper`, condensed (`src/mcp-server/tools/definitions/get-paper.tool.ts`):
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
85
|
+
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
86
|
+
import { blankAsUnset, paperInput } from '@/mcp-server/tools/inputs.js';
|
|
87
|
+
import { inline } from '@/utils/render.js';
|
|
88
|
+
import { getInspireService } from '@/services/inspire/inspire-service.js';
|
|
89
|
+
|
|
90
|
+
export const getPaperTool = tool('cern_inspire_get_paper', {
|
|
91
|
+
title: 'Get INSPIRE paper',
|
|
92
|
+
description: "Fetch one paper's full INSPIRE-HEP record by recid, arXiv ID, or DOI: …", // abridged
|
|
93
|
+
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
|
|
94
|
+
input: z.object({
|
|
95
|
+
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.',
|
|
98
|
+
),
|
|
99
|
+
}),
|
|
100
|
+
output: paperDossierSchema, // also the inspire://literature/{recid} resource's output
|
|
101
|
+
enrichment: {
|
|
102
|
+
truncated: z.boolean().describe('True when the author list was capped at max_authors.'),
|
|
103
|
+
shown: z.number().describe('Number of authors listed.'),
|
|
104
|
+
cap: z.number().describe('The max_authors cap applied.'),
|
|
105
|
+
notice: z.string().optional().describe('Guidance when the author list was capped or HEPData availability could not be checked.'),
|
|
106
|
+
},
|
|
107
|
+
errors: [
|
|
108
|
+
{
|
|
109
|
+
reason: 'paper_not_found',
|
|
110
|
+
code: JsonRpcErrorCode.NotFound,
|
|
111
|
+
when: 'The recid, arXiv ID, or DOI matches no INSPIRE literature record.',
|
|
112
|
+
recovery: 'Find the record with cern_inspire_search_literature using title words, an author, or the arXiv number, then call cern_inspire_get_paper with its recid.',
|
|
113
|
+
severity: 'notice',
|
|
114
|
+
},
|
|
115
|
+
// inspire_rate_limited, pacer_shed, upstream_unreadable: declared inline, thrownBy: 'service'
|
|
116
|
+
],
|
|
117
|
+
|
|
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
|
+
},
|
|
139
|
+
|
|
140
|
+
// format() is the content[] twin of structuredContent: every output field renders,
|
|
141
|
+
// and every upstream string passes through inline() / quote() / printUrl().
|
|
142
|
+
format: (paper) => [{ type: 'text', text: renderPaperDossier(paper) }],
|
|
143
|
+
});
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
### Resource
|
|
147
|
+
|
|
148
|
+
`inspire://literature/{recid}` (`src/mcp-server/resources/definitions/inspire-literature.resource.ts`) serves the same dossier through the same service call:
|
|
149
|
+
|
|
150
|
+
```ts
|
|
151
|
+
import { resource, z } from '@cyanheads/mcp-ts-core';
|
|
152
|
+
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
153
|
+
import { paperDossierSchema } from '@/mcp-server/tools/definitions/get-paper.tool.js';
|
|
154
|
+
import { getInspireService } from '@/services/inspire/inspire-service.js';
|
|
155
|
+
|
|
156
|
+
const RESOURCE_MAX_AUTHORS = 25; // cern_inspire_get_paper's default
|
|
157
|
+
|
|
158
|
+
export const inspireLiteratureResource = resource('inspire://literature/{recid}', {
|
|
159
|
+
name: 'inspire_literature',
|
|
160
|
+
title: 'INSPIRE literature record',
|
|
161
|
+
description: 'One INSPIRE-HEP literature record by recid, as the cern_inspire_get_paper dossier in JSON: …', // abridged
|
|
162
|
+
mimeType: 'application/json',
|
|
163
|
+
params: z.object({
|
|
164
|
+
recid: z.string().regex(/^\d{1,9}$/).describe('INSPIRE literature record ID (recid), e.g. 451647.'),
|
|
165
|
+
}),
|
|
166
|
+
output: paperDossierSchema,
|
|
167
|
+
cacheHint: { ttlMs: 3_600_000, cacheScope: 'public' },
|
|
168
|
+
errors: [
|
|
169
|
+
{
|
|
170
|
+
reason: 'paper_not_found',
|
|
171
|
+
code: JsonRpcErrorCode.NotFound,
|
|
172
|
+
when: 'The recid matches no INSPIRE literature record.',
|
|
173
|
+
recovery: 'Find the record with cern_inspire_search_literature using title words, an author, or the arXiv number, then call cern_inspire_get_paper with its recid.',
|
|
174
|
+
},
|
|
175
|
+
// inspire_rate_limited, pacer_shed, upstream_unreadable: declared inline, thrownBy: 'service'
|
|
176
|
+
],
|
|
177
|
+
|
|
178
|
+
async handler(params, ctx) {
|
|
179
|
+
const inspire = getInspireService();
|
|
180
|
+
const lookup = await inspire.getPaper(params.recid, RESOURCE_MAX_AUTHORS, inspire.beginCall(ctx));
|
|
181
|
+
if (!lookup) {
|
|
182
|
+
throw ctx.fail('paper_not_found', `No INSPIRE literature record has recid ${params.recid}.`, {
|
|
183
|
+
recid: params.recid,
|
|
184
|
+
});
|
|
185
|
+
}
|
|
186
|
+
return lookup.paper;
|
|
187
|
+
},
|
|
188
|
+
});
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### Server config
|
|
192
|
+
|
|
193
|
+
The server has no env vars of its own: INSPIRE is keyless, and the pacer limits, call budget, and byte ceiling are constants in `inspire-service.ts`. There is no `src/config/`. A new env var lands on every one of these surfaces in the same change:
|
|
194
|
+
|
|
195
|
+
| Surface | What it needs |
|
|
196
|
+
|:--------|:--------------|
|
|
197
|
+
| `src/config/server-config.ts` (new) | A lazily parsed Zod schema read through `parseEnvConfig` from `@cyanheads/mcp-ts-core/config`, so errors name the variable; `z.stringbool()` for booleans, never `z.coerce.boolean()` |
|
|
198
|
+
| `.env.example` | The variable under `# ── Server-specific`, with a comment and its default, replacing the "None." note |
|
|
199
|
+
| `server.json` | `environmentVariables[]` in both package entries, `isRequired` matching what INSPIRE actually requires |
|
|
200
|
+
| `manifest.json` | A `user_config` entry (`title`, `type`, `"default": ""` unless required) wired into `mcp_config.env` as `"X": "${user_config.X}"` |
|
|
201
|
+
| `.claude-plugin/plugin.json` | A `userConfig` entry referenced from `env` as `"X": "${user_config.X}"` |
|
|
202
|
+
| `.codex-plugin/mcp.json` | The name in `env_vars`; never `"X": ""` in `env` |
|
|
203
|
+
| `README.md` | A Configuration table row, and the "no settings of its own" sentence above it |
|
|
204
|
+
| `docs/design.md` and this file | § Config in the design, and the Domain section's "no server-specific env var" line |
|
|
205
|
+
|
|
206
|
+
`lint:packaging` (run by `devcheck`) checks the name parity between `server.json` and `manifest.json` and the `${user_config.X}` wiring; the rest is by hand.
|
|
207
|
+
|
|
208
|
+
### Server entry point
|
|
209
|
+
|
|
210
|
+
`src/index.ts`:
|
|
211
|
+
|
|
212
|
+
```ts
|
|
213
|
+
await createApp({
|
|
214
|
+
name: 'cern-inspire-mcp-server',
|
|
215
|
+
title: 'cern-inspire-mcp-server', // display identity is the machine name; lint:packaging checks the pair
|
|
216
|
+
tools: allToolDefinitions,
|
|
217
|
+
resources: allResourceDefinitions,
|
|
218
|
+
instructions: 'cern-inspire-mcp-server reads INSPIRE-HEP (inspirehep.net), …', // abridged
|
|
219
|
+
setup(core) {
|
|
220
|
+
initInspireService(core.config); // the User-Agent carries core.config.mcpServerVersion
|
|
221
|
+
},
|
|
222
|
+
teardown() {
|
|
223
|
+
disposeInspireService(); // releases the pacer's timer and rejects queued waiters
|
|
224
|
+
},
|
|
225
|
+
});
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
- No `description`: the framework serves `package.json`'s.
|
|
229
|
+
- `instructions` is mirrored in `docs/design.md` § Server Instructions with its character count. Change both together.
|
|
230
|
+
- No `sessionMode`: no handler calls `ctx.requestInput`, so the deployment picks the mode through `MCP_SESSION_MODE`, and `.env.example` and the Dockerfile set `stateless`.
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
## Context
|
|
235
|
+
|
|
236
|
+
Handlers receive a unified `ctx` object. The properties this server uses:
|
|
237
|
+
|
|
238
|
+
| Property | Description |
|
|
239
|
+
|:---------|:------------|
|
|
240
|
+
| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. The service logs through `call.ctx.log`. |
|
|
241
|
+
| `ctx.enrich` | Success-path agent context — `ctx.enrich({ … })` for declared fields, `.total()` (`totalCount`), `.truncated({ shown, cap, guidance })`, `.notice()`, `.echo()` (`effectiveQuery`). Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block. Write the required fields with neutral values before the first upstream call. |
|
|
242
|
+
| `ctx.fail` | `throw ctx.fail(reason, message, data?)` for a reason declared in the definition's `errors[]`; the framework attaches the contract's `recovery` hint. |
|
|
243
|
+
| `ctx.signal` | `AbortSignal` for cancellation. `beginCall(ctx)` carries it into `withRetry` and the pacer, so a cancelled call stops queueing and retrying. |
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
|
|
247
|
+
## Errors
|
|
248
|
+
|
|
249
|
+
Handlers throw — the framework catches, classifies, and formats.
|
|
250
|
+
|
|
251
|
+
**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. The framework puts it on the wire whenever a failure carrying that `reason` arrives without a hint — a bare `ctx.fail('reason')` or a service throw with `data: { reason }` — as `data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim; override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Every error envelope also carries `data.requestId`, the id the server's log records for that call carry, and `content[]` closes with `(reason … · request <id>)`. Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
|
|
252
|
+
|
|
253
|
+
```ts
|
|
254
|
+
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
255
|
+
|
|
256
|
+
errors: [
|
|
257
|
+
{ reason: 'no_match', code: JsonRpcErrorCode.NotFound,
|
|
258
|
+
when: 'No item matched the query',
|
|
259
|
+
recovery: 'Broaden the query or check the spelling and try again.' },
|
|
260
|
+
],
|
|
261
|
+
async handler(input, ctx) {
|
|
262
|
+
const item = await db.find(input.id);
|
|
263
|
+
if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
|
|
264
|
+
return item;
|
|
265
|
+
}
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
**Declare contracts inline on each tool.** The contract is part of the tool's public surface — one file should give the full picture. Don't extract a shared `errors[]` constant; per-tool repetition is the intended cost of locality.
|
|
269
|
+
|
|
270
|
+
**Fallback (no contract entry fits):** throw via factories or plain `Error`.
|
|
271
|
+
|
|
272
|
+
```ts
|
|
273
|
+
// Error factories — explicit code
|
|
274
|
+
import { notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
|
|
275
|
+
throw notFound('Item not found', { itemId });
|
|
276
|
+
throw serviceUnavailable('API unavailable', { url }, { cause: err });
|
|
277
|
+
|
|
278
|
+
// Plain Error — framework auto-classifies from message patterns
|
|
279
|
+
throw new Error('Item not found'); // → NotFound
|
|
280
|
+
throw new Error('Invalid query format'); // → ValidationError
|
|
281
|
+
|
|
282
|
+
// McpError — when no factory exists for the code
|
|
283
|
+
import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
284
|
+
throw new McpError(JsonRpcErrorCode.InitializationFailed, 'Connection failed', { pool: 'primary' });
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.
|
|
288
|
+
|
|
289
|
+
---
|
|
290
|
+
|
|
291
|
+
## Structure
|
|
292
|
+
|
|
293
|
+
```text
|
|
294
|
+
src/
|
|
295
|
+
index.ts # createApp(): tools, resource, instructions, service setup/teardown
|
|
296
|
+
mcp-server/
|
|
297
|
+
tools/
|
|
298
|
+
inputs.ts # Shared inputs (paper, facets, years, author ids) + appliedFilters echo
|
|
299
|
+
definitions/
|
|
300
|
+
index.ts # allToolDefinitions barrel
|
|
301
|
+
search-literature.tool.ts
|
|
302
|
+
get-paper.tool.ts # also exports paperDossierSchema, the resource's output
|
|
303
|
+
export-citations.tool.ts
|
|
304
|
+
search-authors.tool.ts
|
|
305
|
+
get-citation-summary.tool.ts
|
|
306
|
+
search-experiments.tool.ts
|
|
307
|
+
search-hepdata.tool.ts
|
|
308
|
+
list-reference.tool.ts # static vocabulary tables, no upstream call
|
|
309
|
+
resources/definitions/
|
|
310
|
+
index.ts # allResourceDefinitions barrel
|
|
311
|
+
inspire-literature.resource.ts # inspire://literature/{recid}
|
|
312
|
+
services/
|
|
313
|
+
http/
|
|
314
|
+
fetch-bounded.ts # One request: per-attempt timeout, byte ceiling, status accept-list
|
|
315
|
+
inspire/
|
|
316
|
+
inspire-service.ts # InspireService: pacer, per-call budget, retries, param allowlist, field lists
|
|
317
|
+
identifiers.ts # Paper and author identifier normalization and routing (matchedAs)
|
|
318
|
+
normalize.ts # Raw INSPIRE records → output shapes; absent fields stay absent
|
|
319
|
+
types.ts # Raw upstream and normalized domain types
|
|
320
|
+
vocabulary.ts # Document types, subjects, citation-bucket ranges
|
|
321
|
+
utils/
|
|
322
|
+
render.ts # inline / cell / quote / fenced / printUrl / atLineStart for upstream text in format() and error messages
|
|
323
|
+
tests/
|
|
324
|
+
fixtures/ # INSPIRE bodies, service harness, shared failure suite, result readers
|
|
325
|
+
tools/ resources/ services/ shared/ # Suites mirroring src/
|
|
326
|
+
docs/
|
|
327
|
+
design.md # Surface, verified upstream behavior, decisions, deferred HEPData tools
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
---
|
|
331
|
+
|
|
332
|
+
## Naming
|
|
333
|
+
|
|
334
|
+
| What | Convention | Example |
|
|
335
|
+
|:-----|:-----------|:--------|
|
|
336
|
+
| Files | kebab-case with suffix | `search-docs.tool.ts` |
|
|
337
|
+
| Tool/resource/prompt names | snake_case | `search_docs` |
|
|
338
|
+
| Directories | kebab-case | `src/services/doc-search/` |
|
|
339
|
+
| Descriptions | Single string or template literal, no `+` concatenation | `'Search items by query and filter.'` |
|
|
340
|
+
|
|
341
|
+
---
|
|
342
|
+
|
|
343
|
+
## Skills
|
|
344
|
+
|
|
345
|
+
Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
|
|
346
|
+
|
|
347
|
+
**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
|
|
348
|
+
|
|
349
|
+
Available skills:
|
|
350
|
+
|
|
351
|
+
| Skill | Purpose |
|
|
352
|
+
|:------|:--------|
|
|
353
|
+
| `setup` | Post-init project orientation |
|
|
354
|
+
| `design-mcp-server` | Design tool surface, resources, and services for a new server |
|
|
355
|
+
| `add-tool` | Scaffold a new tool definition |
|
|
356
|
+
| `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
|
|
357
|
+
| `add-resource` | Scaffold a new resource definition |
|
|
358
|
+
| `add-prompt` | Scaffold a new prompt definition |
|
|
359
|
+
| `add-service` | Scaffold a new service integration |
|
|
360
|
+
| `add-test` | Scaffold test file for a tool, resource, or service |
|
|
361
|
+
| `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
|
|
362
|
+
| `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
|
|
363
|
+
| `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
|
|
364
|
+
| `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
|
|
365
|
+
| `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
|
|
366
|
+
| `git-wrapup` | Land working-tree changes as a commit stack — version bump, changelog, verify, commit by concern, release commit on top. No tag, no push to main; opens the release PR when the project declares release PR mode |
|
|
367
|
+
| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixes as ordinary commits on top of the stack, PR body kept in sync. Release PR mode only |
|
|
368
|
+
| `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
|
|
369
|
+
| `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
|
|
370
|
+
| `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
|
|
371
|
+
| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
|
|
372
|
+
| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
|
|
373
|
+
| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
|
|
374
|
+
| `api-auth` | Auth modes, scopes, JWT/OAuth |
|
|
375
|
+
| `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
|
|
376
|
+
| `api-config` | AppConfig, parseConfig, env vars |
|
|
377
|
+
| `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input |
|
|
378
|
+
| `api-errors` | McpError, JsonRpcErrorCode, error patterns |
|
|
379
|
+
| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
|
|
380
|
+
| `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in |
|
|
381
|
+
| `api-services` | LLM, Speech, Graph services |
|
|
382
|
+
| `api-testing` | createMockContext, test patterns |
|
|
383
|
+
| `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
|
|
384
|
+
| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
|
|
385
|
+
| `api-workers` | Cloudflare Workers runtime |
|
|
386
|
+
|
|
387
|
+
**Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `framework-skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
|
|
388
|
+
|
|
389
|
+
When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
|
|
390
|
+
|
|
391
|
+
---
|
|
392
|
+
|
|
393
|
+
## Commands
|
|
394
|
+
|
|
395
|
+
**Runtime:** Scripts use Bun's native TypeScript execution — `bun run <cmd>` is the standard invocation. `npm run <cmd>` also works (npm delegates to bun).
|
|
396
|
+
|
|
397
|
+
| Command | Purpose |
|
|
398
|
+
|:--------|:--------|
|
|
399
|
+
| `bun run build` | Compile TypeScript |
|
|
400
|
+
| `bun run rebuild` | Clean + build |
|
|
401
|
+
| `bun run clean` | Remove build artifacts |
|
|
402
|
+
| `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
|
|
403
|
+
| `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update <name>`, then `bun dedupe` |
|
|
404
|
+
| `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` |
|
|
405
|
+
| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
|
|
406
|
+
| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
|
|
407
|
+
| `bun run list-skills` | Print the skill registry |
|
|
408
|
+
| `bun run tree` | Generate directory structure doc |
|
|
409
|
+
| `bun run format` | Auto-fix formatting (safe fixes only) |
|
|
410
|
+
| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
|
|
411
|
+
| `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
|
|
412
|
+
| `bun run test:coverage` | Run tests with Istanbul coverage |
|
|
413
|
+
| `bun run start` | Run the built server (transport from `MCP_TRANSPORT_TYPE`, default stdio) |
|
|
414
|
+
| `bun run start:stdio` | Production mode (stdio) |
|
|
415
|
+
| `bun run start:http` | Production mode (HTTP) |
|
|
416
|
+
| `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
|
|
417
|
+
| `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
|
|
418
|
+
| `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
|
|
419
|
+
| `bun run release:github` | Create (or repair) the GitHub Release on the current version's tag, attaching the `.mcpb` (release step) |
|
|
420
|
+
| `bun run publish-mcp` | Log in with the keychain-stored GitHub token and publish `server.json` to the MCP Registry (release step) |
|
|
421
|
+
|
|
422
|
+
**CI is one file.** `.github/workflows/codeql.yml` (scaffolded) is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.
|
|
423
|
+
|
|
424
|
+
---
|
|
425
|
+
|
|
426
|
+
## Bundling
|
|
427
|
+
|
|
428
|
+
`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
|
|
429
|
+
|
|
430
|
+
**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": ""`.
|
|
431
|
+
|
|
432
|
+
**README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `framework-skills/polish-docs-meta/references/readme.md`.
|
|
433
|
+
|
|
434
|
+
---
|
|
435
|
+
|
|
436
|
+
## Changelog
|
|
437
|
+
|
|
438
|
+
Directory-based, grouped by minor series via the `.x` semver-wildcard convention. Source of truth: `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.1.x/0.1.0.md`) — one file per release, shipped in the npm package. At release, author the per-version file with a concrete version and date, then run `npm run changelog:build` to regenerate the rollup. `changelog/template.md` is a **pristine format reference** — never edited or moved; read it for the frontmatter + section layout when scaffolding. `CHANGELOG.md` is a **navigation index** (header + link + summary per version), regenerated by `npm run changelog:build` — devcheck hard-fails on drift; never hand-edit it.
|
|
439
|
+
|
|
440
|
+
Each per-version file opens with YAML frontmatter:
|
|
441
|
+
|
|
442
|
+
```markdown
|
|
443
|
+
---
|
|
444
|
+
summary: "One-line headline, ≤350 chars" # required — powers the rollup index
|
|
445
|
+
breaking: false # optional — true flags breaking changes
|
|
446
|
+
security: false # optional — true ONLY for a source-code security fix, never a dependency CVE bump
|
|
447
|
+
---
|
|
448
|
+
|
|
449
|
+
# 0.1.0 — YYYY-MM-DD
|
|
450
|
+
...
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section — set it only for a security fix in this server's *own source code*, never for a routine dependency or transitive CVE bump (record those under `## Dependencies`). When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
|
|
454
|
+
|
|
455
|
+
`agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
|
|
456
|
+
|
|
457
|
+
**Section order:** the Keep a Changelog sequence — Added, Changed, Deprecated, Removed, Fixed, Security — then `Dependencies` last. Include only sections with entries — don't ship empty headers.
|
|
458
|
+
|
|
459
|
+
**Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
|
|
460
|
+
|
|
461
|
+
---
|
|
462
|
+
|
|
463
|
+
## Publishing
|
|
464
|
+
|
|
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.
|
|
466
|
+
|
|
467
|
+
---
|
|
468
|
+
|
|
469
|
+
## Imports
|
|
470
|
+
|
|
471
|
+
```ts
|
|
472
|
+
// Framework — z is re-exported, no separate zod import needed
|
|
473
|
+
import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
474
|
+
import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
475
|
+
|
|
476
|
+
// Server's own code — via path alias
|
|
477
|
+
import { getInspireService } from '@/services/inspire/inspire-service.js';
|
|
478
|
+
```
|
|
479
|
+
|
|
480
|
+
---
|
|
481
|
+
|
|
482
|
+
## Checklist
|
|
483
|
+
|
|
484
|
+
- [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()`)
|
|
485
|
+
- [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`). When regex/length constraints matter, use `z.union([z.literal(''), z.string().regex(...).describe(...)])` — literal variants are exempt from `describe-on-fields`.
|
|
486
|
+
- [ ] JSDoc `@fileoverview` + `@module` on every file
|
|
487
|
+
- [ ] `ctx.log` for logging, `ctx.state` for storage
|
|
488
|
+
- [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
|
|
489
|
+
- [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data
|
|
490
|
+
- [ ] If wrapping external API: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
|
|
491
|
+
- [ ] If wrapping external API: normalization and `format()` preserve uncertainty; do not fabricate facts from missing upstream data
|
|
492
|
+
- [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
|
|
493
|
+
- [ ] Registered in `createApp()` arrays (directly or via barrel exports)
|
|
494
|
+
- [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
|
|
495
|
+
- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description
|
|
496
|
+
- [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable (API key, contact email, instance URL) is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset
|
|
497
|
+
- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.<option>}"` — mirror the `user_config` block in `manifest.json`. Never write `"KEY": ""` into `env`
|
|
498
|
+
- [ ] Every INSPIRE request goes through `InspireService` with the call opened by `inspire.beginCall(ctx)`; a new upstream parameter is added to `InspireParams` / `PARAM_NAMES`, a new field to the matching `*_FIELDS` list (never `email_addresses`), and nothing is sent to hepdata.net
|
|
499
|
+
- [ ] Optional and defaulted inputs wrapped in `blankAsUnset`; paper, facet, year, and author inputs reused from `src/mcp-server/tools/inputs.ts`
|
|
500
|
+
- [ ] Required enrichment written with neutral values before the first upstream call or branch
|
|
501
|
+
- [ ] Error contract declared inline: `inspire_rate_limited`, `pacer_shed`, `upstream_unreadable` (`thrownBy: 'service'`), plus `invalid_query` when the tool sends a caller query; caller-input reasons carry `severity: 'notice'`
|
|
502
|
+
- [ ] Every upstream or caller string in `format()` passes through a `render.ts` helper
|
|
503
|
+
- [ ] Surface change mirrored in `docs/design.md`, the server instructions (`src/index.ts` and design § Server Instructions with its character count), `cern_inspire_list_reference` when vocabulary changes, and the README Overview and Capability reference
|
|
504
|
+
- [ ] `npm run devcheck` passes
|