# Agent Protocol **Server:** @cyanheads/crossref-mcp-server **Version:** 0.4.4 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15` **Engines:** Bun ≥1.4.0, Node ≥24.0.0 **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1 **Zod:** ^4.6.7 > **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. --- ## What's Next? When the user asks what to do next or needs direction, suggest relevant options based on current project state: 1. **Re-run the `setup` skill** — ensures CLAUDE.md, skills, structure, and metadata are populated and up to date with the current codebase 2. **Run the `design-mcp-server` skill** — if the tool/resource surface hasn't been mapped yet, work through domain design 3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-app-tool`, `add-resource`, `add-prompt` skills 4. **Add services** — scaffold domain service integrations using the `add-service` skill 5. **Add tests** — scaffold tests for existing definitions using the `add-test` skill 6. **Field-test definitions** — exercise tools/resources/prompts with real inputs using the `field-test` skill, get a report of issues and pain points 7. **Run `devcheck`** — lint, format, typecheck, and security audit 8. **Run the `security-pass` skill** — audit handlers for MCP-specific security gaps: output injection, scope blast radius, input sinks, tenant isolation 9. **Run the `polish-docs-meta` skill** — finalize README, CHANGELOG, metadata, and agent protocol for shipping 10. **Run the `maintenance` skill** — investigate changelogs, adopt upstream changes, and sync skills after `bun update --latest` Tailor suggestions to what's actually missing or stale — don't recite the full list every time. --- ## Domain crossref-mcp-server wraps the [Crossref REST API](https://api.crossref.org/) to expose canonical scholarly metadata for ~188 million registered works (journal articles, books, book chapters, conference papers, preprints, datasets, components). It is the authoritative source for DOI-registered metadata — titles, authors, affiliations, abstracts (where deposited), licenses, full-text links, funder acknowledgements, and outgoing reference lists. **Pairs with:** pubmed-mcp-server (biomedical abstracts/MeSH), openalex-mcp-server (citation graphs, topics, analytics), arxiv-mcp-server (preprints — their DOIs resolve through Crossref), biorxiv-mcp-server (preprints — same). ### Key domain constraints - **Polite-pool `mailto` is optional but recommended.** Every Crossref request includes `User-Agent: crossref-mcp-server/ (mailto:)` when set; the not-found registry lookup to `https://doi.org` sends the bare `crossref-mcp-server/` without the mailto. Without it, the server starts but logs a warning and uses the anonymous pool with stricter rate limits. Polite-pool access requires no token — just the email in the header. - **No incoming citations.** Crossref does not expose which works cite a given DOI. Redirect to OpenAlex for citation counts or citation graphs. - **Abstract coverage is incomplete.** Abstracts are deposited voluntarily; many records — especially older works and books — have none. - **Reference list coverage varies.** Outgoing references are only present for publisher participants; pre-2000 literature has low coverage. - **Offset paging is capped at ~10K** on `/works` and on both works sub-resources (100K on the `/journals` and `/funders` name searches). Deep paging requires `cursor=*` on the first request, then chaining `next-cursor` tokens; the name-search routes do not accept a cursor. Cursor and offset cannot be combined. - **A cursor walk is ended by an empty page, never by upstream.** Crossref's `next-cursor` is a search-after key (it decodes to `,` and changes on every page), and the last partial page of a list still carries one, so a token's presence never means more records remain. Every cursor surface withholds its continuation token once a page comes back empty — Crossref currently sends none on that page, but has handed back the token that produced it before. - **A cursor cannot carry a publication-date sort.** Crossref refuses `published`, `published-print`, `published-online`, and `issued` beside `cursor` (`sort-criteria-incompatible-with-cursor`), and a walk with no sort runs oldest-registered first. The journal and funder works lists therefore walk a `works_cursor` by `sort=created&order=desc` (newest registered first) and keep `sort=published&order=desc` on offset pages; `crossref_search_works` passes the caller's `sort` and `order` through — a refusal comes back as `sort_cursor_conflict` — except on a cursor walk with a query term and no `sort`, which it sends as `sort=score` without `order` (a no-sort walk carries no ranking, Crossref ignores `order` without `sort`, and `score&order=asc` inverts the ranking). A filter-only walk and offset pages get no default sort. - **`select=` works on `/works` (search) only.** It is not supported on `/works/{doi}` (single-fetch). `crossref_get_references` fetches the full record and extracts `reference[]` client-side. - **Filter keys use hyphens.** e.g. `has-abstract`, `has-references`, `has-full-text`, `from-pub-date`. No `is_open_access` filter exists — use `license.url` with a Creative Commons license URL for open-access content. `directory:DOAJ` passes Crossref's validator but every request carrying it is answered with HTTP 500, so no surface recommends it. - **A DOI is accepted wrapped in its resolver.** `https://doi.org/…`, `https://dx.doi.org/…`, and `doi:…` each name exactly one DOI, so `normalizeDoi` in the service unwraps them and every DOI-bearing input admits them. Crossref's own paths take the bare DOI, so the unwrap happens at the head of the handler and everything below it — request path, logs, `doi_not_found` message and `data.doi` — reads the bare form. --- ## Core Rules - **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. - **Use `ctx.log`** for request-scoped logging. No `console` calls. - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly. - **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. - **Secrets in env vars only** — never hardcoded. - **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. - **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. --- ## Patterns ### Tool ```ts import { tool, z } from '@cyanheads/mcp-ts-core'; import { getCrossrefService } from '@/services/crossref/crossref-service.js'; export const getWorkTool = tool('crossref_get_work', { description: 'Resolve a DOI to its full Crossref metadata record.', annotations: { readOnlyHint: true, idempotentHint: true }, input: z.object({ doi: z .string() .regex(/^(?:https?:\/\/(?:dx\.)?doi\.org\/|doi:)?10\.\d{4,9}\/\S+$/i) .describe('DOI in the format "10.NNNN/suffix", e.g. "10.1038/nature12373". A resolver-wrapped form is accepted and unwrapped.'), }), output: z.object({ doi: z.string().describe('Canonical DOI'), title: z.string().describe('Work title'), type: z.string().describe('Work type (e.g. journal-article, book-chapter)'), authors: z.array(z.object({ given: z.string().optional().describe('Given name'), family: z.string().optional().describe('Family name'), })).describe('Author list'), isReferencedByCount: z.number().describe('Incoming citation count (works citing this DOI)'), }), errors: [ { reason: 'doi_not_found', code: JsonRpcErrorCode.NotFound, when: 'Valid DOI format but no Crossref record', recovery: 'Verify the DOI or use crossref_search_works to find similar works.' }, ], async handler(input, ctx) { const doi = normalizeDoi(input.doi); ctx.log.info('Executing crossref_get_work', { doi }); const svc = getCrossrefService(); const work = await svc.getWork(doi, ctx); if (!work) { throw ctx.fail('doi_not_found', `No record for DOI ${doi}`); } return work; }, format: (result) => [{ type: 'text', text: `**${result.title}**\nDOI: ${result.doi} | Type: ${result.type} | Cited by: ${result.isReferencedByCount}`, }], }); ``` ### Server config ```ts // src/config/server-config.ts — lazy-parsed, separate from framework config import { z } from '@cyanheads/mcp-ts-core'; import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config'; const ServerConfigSchema = z.object({ mailto: z.string().email().optional().describe('Contact email embedded in the polite-pool User-Agent header'), baseUrl: z.string().url().default('https://api.crossref.org').describe('Crossref API base URL'), timeoutMs: z.coerce.number().min(1000).max(60000).default(10000).describe('Per-request timeout in ms'), }); let _config: z.infer | undefined; export function getServerConfig() { _config ??= parseEnvConfig(ServerConfigSchema, { mailto: 'CROSSREF_MAILTO', baseUrl: 'CROSSREF_BASE_URL', timeoutMs: 'CROSSREF_TIMEOUT_MS', }); return _config; } ``` `parseEnvConfig` maps Zod schema paths → env var names so validation errors name the actual variable (`CROSSREF_MAILTO`) not the path (`mailto`). Throws `ConfigurationError`, printed as a clean startup banner. For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("false")` is `true`, so a coerced flag can't be disabled through the environment. `z.stringbool()` parses `true/false/1/0/yes/no/on/off` and rejects anything else, so `=false` actually disables. ### Server instructions `createApp({ instructions })` — optional server-level orientation, sent to clients on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set. ### Session posture and shutdown `createApp({ sessionMode })` declares the HTTP session posture in `src/` instead of leaving it to a deployment's `MCP_SESSION_MODE`, which still wins whenever it carries a meaningful value (an empty string and an unsubstituted `${…}` placeholder read as unset and fall through to the option). This server declares `'stateless'`: no tool asks the caller for input mid-handler, so no handler needs a session to come back to. A server that does call `ctx.requestInput` adds `require: 'stateful'`, which fails startup with a `ConfigurationError` rather than serving a mode in which a 2025-era HTTP client can never answer. Stdio is never refused. `createApp({ teardown })` is the `setup()` counterpart — release a watcher, socket, or non-`unref()`'d timer there. It runs after the transport stops and before the logger closes, on every shutdown path, and a signal-triggered shutdown then exits the process explicitly (0, or 1 if a step never settles within the framework's 10 s ceiling). Not declared here: `CrossrefService` holds nothing past a request, and its per-request timeout timer is cleared in a `finally`. --- ## Context Handlers receive a unified `ctx` object. Key properties used in this server: | Property | Description | |:---------|:------------| | `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. | | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any JSON-serializable value; reads return its JSON form (a `Date` comes back as an ISO string). | | `ctx.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present. | | `ctx.inputs` | The request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped` — limited to what the client declared (`elicitation` and its form/url modes, `sampling`, `roots`). Client-supplied: a consent gate trusts only a `ctx.state` record it stored when it asked, bound to the operation, caller, and target (see the `api-context` skill). | | `ctx.clientCapabilities` | What the client declared for this request, `undefined` when no view exists. Decides whether to ask for optional context (e.g. roots); never a reason to skip a consent prompt. | | `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). | | `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. | | `ctx.signal` | `AbortSignal` for cancellation. | | `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. | | `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. | --- ## Errors Handlers throw — the framework catches, classifies, and formats. **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 )`. Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it; every entry in `src/services/crossref/upstream-errors.ts` carries it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring. ```ts import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors'; errors: [ { reason: 'doi_not_found', code: JsonRpcErrorCode.NotFound, when: 'Valid DOI format but no Crossref record', recovery: 'Verify the DOI or use crossref_search_works to find similar works.' }, ], async handler(input, ctx) { const doi = normalizeDoi(input.doi); const work = await svc.getWork(doi, ctx); if (!work) { throw ctx.fail('doi_not_found', `No record for DOI ${doi}`, { doi }); } return work; } ``` **Fallback (no contract entry fits):** throw via factories or plain `Error`. ```ts // Error factories — explicit code import { notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors'; throw notFound('No record for DOI', { doi }); throw serviceUnavailable('Crossref API unavailable', {}, { cause: err }); ``` **Keep the upstream request URL and response body off `error.data`.** It reaches the client as `structuredContent.error.data`, and `CROSSREF_BASE_URL` is operator-configurable, so a deployment pointed at a private mirror would hand that hostname — plus every query string this server builds — to every caller on every failure. `httpErrorFromResponse` omits the URL by default (`includeUrl` stays unpassed), no throw site adds it back, and `CrossrefService.request` logs it once per failed call through the Pino-only `logger` instead. `ctx.log` is not an alternative: it is dual-sink and ships to the client as `notifications/message`. The body stays off for a different reason: a Crossref 5xx body is a Java exception with a stack excerpt, which gives the caller nothing to act on, so every `httpErrorFromResponse` call passes `captureBody: false` and keeps only the status and a readable message. **Crossref's rejections of caller input are declared reasons.** A 400, and a 404 whose body is `cursor-invalid`, map on Crossref's own rejection `type` onto the entries beside `UPSTREAM_ERROR_CONTRACT` in `upstream-errors.ts`: `unknown_filter` (`filter-not-available`, with `data.suggestion` when Crossref lists the hyphenated key as valid), `sort_cursor_conflict`, `invalid_cursor`, and `invalid_parameter` for any other type or a body that does not parse. `data.rejected` lists every entry as `{ type, value }` and the reason follows the first; a blank filter value never reaches Crossref to be rejected — `crossref_search_works` drops it first. Any other 404 passes through untouched for the handlers' `*_not_found` reasons. An `issn` filter value Crossref cannot read — no run of seven digits and a check character once everything but digits and `X` is stripped — is refused before the request as `invalid_parameter`, since Crossref answers one with a 500 that would read as an outage; every spelling Crossref does read (`0028–0836`, `ISSN 0028-0836`) goes through as written. `crossref_search_works` declares all four; the journal and funder tools declare `invalid_cursor` and `invalid_parameter`. See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all factories, and the contract reference. --- ## Structure ```text src/ index.ts # createApp() entry point config/ server-config.ts # CROSSREF_MAILTO, CROSSREF_BASE_URL, CROSSREF_TIMEOUT_MS services/ crossref/ crossref-service.ts # HTTP client, polite-pool User-Agent, retry, pagination html-entities.ts # HTML5 named character reference table + single-pass decode link-text.ts # A link element's text, read once per closer, for the href check mathml.ts # MathML region → TeX annotation, else linear notation types.ts # Crossref domain types (Work, Reference, Journal, Funder) upstream-errors.ts # Upstream/transport error contract + throw-site factory mcp-server/ tools/ blank-input.ts # nonBlank / isBlank — a blank optional string reads as omitted markdown-text.ts # mdText / mdTextAtLineStart — the content[] escape metadata-coverage.ts # Coverage schema, projection, and renderer — member and journal tools page-size.ts # clampPageSize — a page size above its per-call cap is clamped with a notice registration-agency.ts # notFoundDetail — not-found text branched on the DOI registry's answer work-locators.ts # volume / issue / page / articleNumber — fields, projection, line work-updates.ts # updatedBy / updateTo — fields, projection, line tools/definitions/ get-work.tool.ts # crossref_get_work get-references.tool.ts # crossref_get_references search-works.tool.ts # crossref_search_works search-journals.tool.ts # crossref_search_journals search-funders.tool.ts # crossref_search_funders get-member.tool.ts # crossref_get_member get-prefix.tool.ts # crossref_get_prefix ``` --- ## Naming | What | Convention | Example | |:-----|:-----------|:--------| | Files | kebab-case with suffix | `get-work.tool.ts` | | Tool/resource/prompt names | snake_case | `crossref_get_work` | | Directories | kebab-case | `src/services/crossref/` | | Descriptions | Single string or template literal, no `+` concatenation | `'Resolve a DOI to its full Crossref metadata record.'` | --- ## Skills 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. **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. Available skills: | Skill | Purpose | |:------|:--------| | `setup` | Post-init project orientation | | `design-mcp-server` | Design tool surface, resources, and services for a new server | | `add-tool` | Scaffold a new tool definition | | `add-app-tool` | Scaffold an MCP App tool + paired UI resource | | `add-resource` | Scaffold a new resource definition | | `add-prompt` | Scaffold a new prompt definition | | `add-service` | Scaffold a new service integration | | `add-test` | Scaffold test file for a tool, resource, or service | | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues | | `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions | | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation | | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase | | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping | | `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 | | `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 | | `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` | | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs | | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents | | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI | | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI | | `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns | | `api-auth` | Auth modes, scopes, JWT/OAuth | | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in | | `api-config` | AppConfig, parseConfig, env vars | | `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input | | `api-errors` | McpError, JsonRpcErrorCode, error patterns | | `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` | | `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in | | `api-services` | LLM, Speech, Graph services | | `api-testing` | createMockContext, test patterns | | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers | | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules | | `api-workers` | Cloudflare Workers runtime | **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. When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-05-21`). --- ## Commands **Runtime:** Scripts use Bun's native TypeScript execution — `bun run ` is the standard invocation. `npm run ` also works (npm delegates to bun). | Command | Purpose | |:--------|:--------| | `bun run build` | Compile TypeScript | | `bun run rebuild` | Clean + build | | `bun run clean` | Remove build artifacts | | `bun run devcheck` | Lint + format + typecheck + security + changelog sync | | `bun run tree` | Generate directory structure doc | | `bun run format` | Auto-fix formatting (safe fixes only) | | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior | | `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) | | `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) | | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) | | `bun run list-skills` | Print the skill registry | | `bun run start:stdio` | Production mode (stdio) | | `bun run start:http` | Production mode (HTTP) | | `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` | | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) | | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install | | `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 `, then `bun dedupe` | | `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update `, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` | **CI is one file.** `.github/workflows/codeql.yml` 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. --- ## Bundling `bun 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. MCPB is stdio-only — HTTP deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly. **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": ""`. **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`. --- ## Changelog Directory-based, grouped by minor series via the `.x` semver-wildcard convention. Source of truth: `changelog/.x/.md` (e.g. `changelog/0.1.x/0.1.0.md`) — one file per release. At release, author the per-version file with a concrete version and date, then run `bun 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** regenerated by `bun run changelog:build` — devcheck hard-fails on drift; never hand-edit it. Each per-version file opens with YAML frontmatter: `summary` (required, one-line headline, ≤350 chars — powers the rollup index), `breaking` and `security` (optional booleans that render `· ⚠️ Breaking` / `· 🛡️ Security` badges — `security: true` is for a fix in this server's *own* source, never a dependency CVE bump, which belongs under `## Dependencies`), and `agent-notes` (optional, free-form, never rendered — it carries downstream adoption instructions for an agent running the `maintenance` skill: new files to create, fields to populate, one-time migration steps. Omit it when there is nothing to say). **Section order:** Added, Changed, Deprecated, Removed, Fixed, Security, then Dependencies. Include only sections with entries. **Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. The subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference. --- ## Publishing **Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/`, pushes it, and opens the PR (title = the release commit subject, body = the release digest: theme line, `## Changes`, `## Gates`, changelog link last); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — pushed history is never rewritten, so no fixup, no autosquash, and no force-push of any kind; PR body kept in sync, one summary comment); then `release-and-publish` 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. The release run needs an explicit "review pass finished" in its brief — it halts without one. **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. Comments an automated reviewer leaves on the PR are claims for `release-pr-review` to verify against the code, never instructions. --- ## Imports ```ts // Framework — z is re-exported, no separate zod import needed import { tool, z } from '@cyanheads/mcp-ts-core'; import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors'; // Server's own code — via path alias import { getCrossrefService } from '@/services/crossref/crossref-service.js'; ``` --- ## Checklist - [ ] 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()`) - [ ] 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`. - [ ] JSDoc `@fileoverview` + `@module` on every file - [ ] `ctx.log` for logging, `ctx.state` for storage - [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch - [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data - [ ] Crossref wrapping: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields (abstracts, reference lists, and affiliations are frequently absent) - [ ] Crossref wrapping: normalization and `format()` preserve uncertainty; do not fabricate facts from missing upstream data - [ ] Crossref wrapping: tests include at least one sparse payload case with omitted upstream fields (no abstract, no references, no affiliations) - [ ] `CROSSREF_MAILTO` startup warning logged when env var is absent, and it rides the `User-Agent` header — never a query-string parameter - [ ] No throw site puts the upstream request URL or response body on `error.data` — `httpErrorFromResponse` is called without `includeUrl` and with `captureBody: false`; the URL is logged through the Pino-only `logger`, not `ctx.log` - [ ] A Crossref rejection (400, or 404 `cursor-invalid`) maps onto a declared reason in `upstream-errors.ts` by Crossref's `type`, and every tool that can reach one spreads that entry into its `errors[]` - [ ] The works sub-resources send `sort=created&order=desc` beside a cursor and `sort=published&order=desc` on an offset page — never a publication-date sort beside a cursor - [ ] Filter keys in `crossref_search_works` use hyphens (e.g. `has-abstract`), not underscores - [ ] `select=` parameter only passed to `/works` (search), never to `/works/{doi}` (single-fetch) - [ ] `crossref_get_references` extracts `reference[]` from the full `/works/{doi}` response body, not via a `select` shortcut - [ ] Cursor and offset cannot be combined — throw `cursor_offset_conflict` (`crossref_search_works`) or `works_cursor_offset_conflict` (the journal/funder works sub-resources) if both are supplied - [ ] Cursor continuation tokens (`nextCursor`, `nextWorksCursor`) are withheld on an empty page — the guard keys on the page's item count, never on `totalResults` - [ ] A search tool's `format()` returns no block for a page with no records, so the enrichment trailer and its notice lead `content[]`; a handler with more than one notice source collects them into one `ctx.enrich.notice` call (`notice` is last-wins) - [ ] Search handlers read each optional string input through `nonBlank` at their head, and a page that dropped blanks down to no search criterion carries the unfiltered-listing notice - [ ] `crossref_search_works.fields` admits only the select names the summary projects — a name joins the enum together with its output field and its `format()` line - [ ] Registered in `createApp()` arrays (directly or via barrel exports) - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing` - [ ] `.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 - [ ] `.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 - [ ] `.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.