@cyanheads/openalex-mcp-server 0.7.7 → 0.7.9

package/AGENTS.md

@@ -1,9 +1,11 @@
-# Agent Protocol
+# Developer Protocol
 
 **Server:** openalex-mcp-server
-**Version:** 0.7.7
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.11.0`
+**Version:** 0.7.9
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.3`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
+**MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
+**Zod:** ^4.4.3
 
 > **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.
 
@@ -67,7 +69,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 - **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.
-- **Check `ctx.elicit`** for presence before calling.
+- **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.
 - **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.
 
@@ -145,11 +147,13 @@ Handlers receive a unified `ctx` object. Key properties:
 
 | Property | Description |
 |:---------|:------------|
-| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
-| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
-| `ctx.elicit` | Ask user for structured input. **Check for presence first:** `if (ctx.elicit) { ... }` |
+| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino and client-visible `notifications/message`. |
+| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
+| `ctx.requestInput` | Suspend and ask the caller for more input with `return ctx.requestInput(...)`; the handler is re-entered with answers. |
+| `ctx.inputs` | Reader over a retried request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped`. |
+| `ctx.enrich` | Success-path agent context for notices, query echoes, totals, and truncation disclosure. Reaches both client response surfaces. |
+| `ctx.content` | Non-text content blocks appended to `content[]`; never enters `structuredContent`. |
 | `ctx.signal` | `AbortSignal` for cancellation. Passed to `fetch()` in the OpenAlex service. |
-| `ctx.progress` | Task progress (present when `task: true`) — `.setTotal(n)`, `.increment()`, `.update(message)`. |
 | `ctx.fail` | Typed throw keyed by a declared `errors[]` contract — `ctx.fail(reason, msg?, data?)`. Auto-populates `data.reason` and resolves `code` from the contract. |
 | `ctx.recoveryFor` | Opt-in resolver returning `{ recovery: { hint } }` for a declared reason. Spread into `data` at throw site to surface contract recovery on the wire. |
 | `ctx.requestId` | Unique request ID. |
@@ -247,8 +251,8 @@ Available skills:
 | `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 LLM-facing definition language (voice, leaks, recovery, sparsity, structure) across tools/resources/prompts |
-| `security-pass` | Audit handlers for MCP-specific security gaps: output injection, scope blast radius, input sinks, tenant isolation |
+| `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
+| `security-pass` | Audit the 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 |
 | `techniques` | Reusable response/data-shaping patterns — overflow handling, payload shaping, retrieval |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
@@ -261,7 +265,7 @@ Available skills:
 | `api-auth` | Auth modes, scopes, JWT/OAuth |
 | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper — Tier 3 opt-in |
 | `api-config` | AppConfig, parseConfig, env vars |
-| `api-context` | Context interface, logger, state, progress |
+| `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-services` | LLM, Speech, Graph services |

package/CLAUDE.md

@@ -1,9 +1,11 @@
-# Agent Protocol
+# Developer Protocol
 
 **Server:** openalex-mcp-server
-**Version:** 0.7.7
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.11.0`
+**Version:** 0.7.9
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.3`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
+**MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
+**Zod:** ^4.4.3
 
 > **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.
 
@@ -67,7 +69,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 - **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.
-- **Check `ctx.elicit`** for presence before calling.
+- **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.
 - **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.
 
@@ -145,11 +147,13 @@ Handlers receive a unified `ctx` object. Key properties:
 
 | Property | Description |
 |:---------|:------------|
-| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
-| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
-| `ctx.elicit` | Ask user for structured input. **Check for presence first:** `if (ctx.elicit) { ... }` |
+| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino and client-visible `notifications/message`. |
+| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
+| `ctx.requestInput` | Suspend and ask the caller for more input with `return ctx.requestInput(...)`; the handler is re-entered with answers. |
+| `ctx.inputs` | Reader over a retried request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped`. |
+| `ctx.enrich` | Success-path agent context for notices, query echoes, totals, and truncation disclosure. Reaches both client response surfaces. |
+| `ctx.content` | Non-text content blocks appended to `content[]`; never enters `structuredContent`. |
 | `ctx.signal` | `AbortSignal` for cancellation. Passed to `fetch()` in the OpenAlex service. |
-| `ctx.progress` | Task progress (present when `task: true`) — `.setTotal(n)`, `.increment()`, `.update(message)`. |
 | `ctx.fail` | Typed throw keyed by a declared `errors[]` contract — `ctx.fail(reason, msg?, data?)`. Auto-populates `data.reason` and resolves `code` from the contract. |
 | `ctx.recoveryFor` | Opt-in resolver returning `{ recovery: { hint } }` for a declared reason. Spread into `data` at throw site to surface contract recovery on the wire. |
 | `ctx.requestId` | Unique request ID. |
@@ -247,8 +251,8 @@ Available skills:
 | `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 LLM-facing definition language (voice, leaks, recovery, sparsity, structure) across tools/resources/prompts |
-| `security-pass` | Audit handlers for MCP-specific security gaps: output injection, scope blast radius, input sinks, tenant isolation |
+| `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
+| `security-pass` | Audit the 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 |
 | `techniques` | Reusable response/data-shaping patterns — overflow handling, payload shaping, retrieval |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
@@ -261,7 +265,7 @@ Available skills:
 | `api-auth` | Auth modes, scopes, JWT/OAuth |
 | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper — Tier 3 opt-in |
 | `api-config` | AppConfig, parseConfig, env vars |
-| `api-context` | Context interface, logger, state, progress |
+| `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-services` | LLM, Speech, Graph services |

package/Dockerfile

@@ -4,7 +4,7 @@
 # This stage installs all dependencies (including dev), builds the TypeScript
 # source code into JavaScript, and prepares the production assets.
 # ==============================================================================
-FROM oven/bun:1.3.14 AS build
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.0 AS build
 
 WORKDIR /usr/src/app
 
@@ -30,7 +30,7 @@ RUN bun run build
 # application. It uses a slim base image and only includes production
 # dependencies and build artifacts.
 # ==============================================================================
-FROM oven/bun:1.3.14-slim AS production
+FROM oven/bun:1.4.0-slim AS production
 
 WORKDIR /usr/src/app
 
@@ -48,9 +48,10 @@ LABEL org.opencontainers.image.licenses="Apache-2.0"
 COPY package.json bun.lock ./
 
 # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
-# that are not needed in the final production image.
+# that are not needed in the final production image. `--omit=peer` keeps the
+# framework's optional peer tiers out; imported peers belong in dependencies.
 RUN --mount=type=cache,target=/root/.bun/install/cache \
-    bun install --production --frozen-lockfile --ignore-scripts
+    bun install --production --omit=peer --frozen-lockfile --ignore-scripts
 
 # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
 # These are not bundled by default to keep the base image lean. Enable at build time
@@ -58,7 +59,7 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
 ARG OTEL_ENABLED=true
 RUN --mount=type=cache,target=/root/.bun/install/cache \
     if [ "$OTEL_ENABLED" = "true" ]; then \
-      bun add --omit=dev --ignore-scripts @hono/otel \
+      bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
         @opentelemetry/instrumentation-http \
         @opentelemetry/exporter-metrics-otlp-http \
         @opentelemetry/exporter-trace-otlp-http \

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.7.7-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/openalex-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/openalex-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/openalex-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.7.9-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/openalex-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/openalex-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/openalex-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -43,7 +43,7 @@ Five tools for querying the [OpenAlex](https://openalex.org) academic research c
 
 Primary discovery and lookup tool. Covers all OpenAlex entity types (works, authors, sources, institutions, topics, keywords, publishers, funders).
 
-- Retrieve a single entity by ID (OpenAlex ID, DOI, ORCID, ROR, PMID, PMCID, ISSN). `id` takes precedence: search criteria passed alongside it are not applied, and the response says which ones were dropped rather than echoing them back as though they ran
+- Retrieve a single entity by ID (OpenAlex ID, DOI, ORCID, ROR, PMID, PMCID, ISSN). `id` takes precedence: search criteria passed alongside it are not applied, and the response says which ones were dropped rather than echoing them back as though they ran. The search-only validations (semantic page cap, `sample` with `cursor`, `seed` without `sample`) are skipped too — a lookup is never rejected over parameters it ignores
 - Keyword search with boolean operators, quoted phrases, wildcards, and fuzzy matching
 - Exact and AI semantic search modes
 - Rich filter syntax: AND across fields, OR within fields (`us|gb`), NOT (`!us`), ranges (`2020-2024`), comparisons (`>100`)

package/changelog/0.1.x/0.1.0.md

@@ -0,0 +1,21 @@
+---
+summary: "Initial release. MCP server for the OpenAlex academic research catalog (270M+ works, 90M+ authors, 100K+ sources) with 3 tools, 2 prompts, and dual stdio/HTTP transports"
+breaking: false
+---
+
+# 0.1.0 — 2026-03-24
+
+Initial release. MCP server for querying the [OpenAlex](https://openalex.org) academic research catalog (270M+ works, 90M+ authors, 100K+ sources).
+
+## Added
+
+- **`openalex_search_entities` tool** — Search, filter, sort, or retrieve by ID across all 8 entity types (works, authors, sources, institutions, topics, keywords, publishers, funders). Supports keyword, exact, and semantic search modes with boolean operators, wildcards, and cursor pagination. Field selection via `select` for payload control.
+- **`openalex_analyze_trends` tool** — Group-by aggregation for trend and distribution analysis. Supports grouping by publication year, open access status, institution, country, topic, and other fields with optional filters.
+- **`openalex_resolve_name` tool** — Name-to-OpenAlex-ID resolution via autocomplete. Returns up to 10 matches with disambiguation hints. Accepts partial names, DOIs, ORCIDs, and ROR IDs.
+- **`openalex_literature_review` prompt** — Guided systematic literature search workflow: entity resolution, multi-strategy search, citation tracing, landscape analysis, and synthesis.
+- **`openalex_research_landscape` prompt** — Quantitative research landscape analysis: volume trends, top contributors, open access rates, funding sources, and emerging fronts.
+- **OpenAlex API service** — Typed client with automatic ID normalization (DOI, ORCID, ROR, PMID, PMCID, ISSN, OpenAlex URLs), abstract reconstruction from inverted indices, filter string building, and cancellation support via `AbortSignal`.
+- **Server configuration** — Zod-validated config with `OPENALEX_API_KEY` (required) and `OPENALEX_BASE_URL` (optional, defaults to `https://api.openalex.org`).
+- **Dual transport** — Stdio and streamable HTTP transports via `@cyanheads/mcp-ts-core`.
+- **Docker support** — Multi-stage Dockerfile for containerized deployment.
+- **Agent protocol** — `CLAUDE.md` with domain context, tool surface, patterns, and skills for AI agent integration.

package/changelog/0.1.x/0.1.1.md

@@ -0,0 +1,27 @@
+---
+summary: "README, LICENSE, docs/tree.md; package.json metadata filled in; server.json OpenAlex env vars declared; Dockerfile OCI labels; echo placeholder tests removed"
+breaking: false
+---
+
+# 0.1.1 — 2026-03-24
+
+## Added
+
+- README with full tool/prompt documentation, configuration reference, and getting started guide
+- Apache 2.0 LICENSE file
+- `bunfig.toml` for Bun runtime configuration
+- `docs/tree.md` directory structure documentation
+
+## Changed
+
+- Filled in package.json metadata: description, mcpName, keywords, author, homepage, bugs, repository URL, bun engine requirement, packageManager field
+- Updated server.json with name (`io.github.cyanheads/openalex-mcp-server`), description, repository URL, and `OPENALEX_API_KEY` env var declarations
+- Updated CLAUDE.md examples to use real OpenAlex tool/prompt patterns instead of generic placeholders
+- Updated Dockerfile OCI labels with description and source URL
+- Updated `.env.example` with OpenAlex-specific environment variables
+- Expanded devcheck.config.json ignore list (`tsx`, `depcheck`)
+- Added `depcheck` to devDependencies
+
+## Removed
+
+- Placeholder echo test files (`echo.tool.test.ts`, `echo.prompt.test.ts`, `echo.resource.test.ts`)

package/changelog/0.2.x/0.2.0.md

@@ -0,0 +1,24 @@
+---
+summary: "Full unit test suite for all three tools and the OpenAlex service; API auth changed from api_key to mailto (polite pool convention); sort direction syntax fixed"
+breaking: false
+---
+
+# 0.2.0 — 2026-03-24
+
+## Added
+
+- Full test suite: unit tests for all 3 tools (`search-entities`, `analyze-trends`, `resolve-name`) and the OpenAlex service (ID normalization, filter building, abstract reconstruction, search modes, error handling)
+- `OPENALEX_BASE_URL` env var declaration in `server.json` for both stdio and HTTP transports
+- `.min(1)` validation on `openalex_resolve_name` query parameter
+
+## Fixed
+
+- Changed API auth parameter from `api_key` to `mailto` (OpenAlex polite pool convention)
+- Sort direction translation: `-field` prefix now correctly maps to `field:desc` (OpenAlex API syntax)
+- Semantic search no longer sends cursor pagination params (unsupported by the API)
+- `openalex_analyze_trends` now surfaces `next_cursor` from the API response
+
+## Changed
+
+- Improved API error messages: parses JSON error bodies to surface the `message` field instead of raw status text
+- Updated `openalex_search_entities` description and `select` guidance to call out institutions (~20KB) alongside works (~70KB) as large entities

package/changelog/0.2.x/0.2.1.md

@@ -0,0 +1,12 @@
+---
+summary: "Explicit 404 handling in API client; non-JSON error response bodies sanitized (HTML stripped, truncated to 200 chars); next_cursor normalized to null when missing"
+breaking: false
+---
+
+# 0.2.1 — 2026-03-24
+
+## Fixed
+
+- Explicit 404 handling in API client — throws `serviceUnavailable` with path context instead of a generic error
+- Sanitize non-JSON error response bodies — strip HTML tags and truncate to 200 chars
+- Normalize `next_cursor` to `null` when missing from search results (prevents `undefined` leaking to callers)

package/changelog/0.2.x/0.2.2.md

@@ -0,0 +1,25 @@
+---
+summary: "Literature review prompt adapts strategy to scope; 404s throw notFound() instead of serviceUnavailable(); group-by queries always send cursor (defaults to * for first page)"
+breaking: false
+---
+
+# 0.2.2 — 2026-03-24
+
+## Improved
+
+- Literature review prompt now adapts search strategy based on scope (narrow vs broad)
+- Research landscape prompt instructs agents to resolve funder IDs to human-readable names
+- `openalex_analyze_trends` cursor description now notes that paginated groups are sorted by key, not by count
+- `openalex_search_entities` format output includes publication year, citation count, and DOI when available
+
+## Fixed
+
+- 404 errors now throw `notFound()` instead of `serviceUnavailable()` — correct HTTP semantics
+- Group-by queries always send cursor (defaults to `*` for first page) — fixes missing first-page results
+- Updated test assertion to match revised error message format
+
+## Changed
+
+- Bumped dev dependencies: `@biomejs/biome` 2.4.8, `tsx` 4.21, `typescript` 6.0.2, `vitest` 4.1.1
+- Fixed `bun test` → `bun run test` in CLAUDE.md commands table
+- Updated `docs/tree.md` to reflect test file structure

package/changelog/0.2.x/0.2.3.md

@@ -0,0 +1,17 @@
+---
+summary: "openalex_analyze_trends sorts groups by count descending and caps display at 50; cursor pagination only sent when explicitly provided; cross-entity autocomplete filters to known entity types"
+breaking: false
+---
+
+# 0.2.3 — 2026-03-24
+
+## Improved
+
+- `openalex_analyze_trends` format output now sorts groups by count descending and caps display at 50 with a truncation note
+- `openalex_search_entities` exact search mode description clarified — notes quoted phrases for multi-word exact match
+- `openalex_resolve_name` description narrowed to DOI-only direct lookup (removed incorrect ORCID/ROR claims)
+
+## Fixed
+
+- Cursor pagination only sent when explicitly provided — boolean `group_by` fields (`is_retracted`, `has_orcid`, etc.) reject cursor entirely
+- Cross-entity autocomplete now filters results to known entity types — prevents unusable types (`country`, `license`, etc.) from reaching callers

package/changelog/0.2.x/0.2.4.md

@@ -0,0 +1,10 @@
+---
+summary: "API client retries transient failures (429, 500, 502, 503, 504) with exponential backoff — up to 3 attempts before surfacing the error"
+breaking: false
+---
+
+# 0.2.4 — 2026-03-24
+
+## Improved
+
+- API client retries transient failures (429, 500, 502, 503, 504) with exponential backoff — up to 3 attempts before surfacing the error

package/changelog/0.2.x/0.2.5.md

@@ -0,0 +1,12 @@
+---
+summary: "Clarifies README storage backend description; removes unused STORAGE_PROVIDER_TYPE env var; reformats retryable status code condition for readability"
+breaking: false
+---
+
+# 0.2.5 — 2026-03-24
+
+## Changed
+
+- Clarified README storage backend description — notes framework capability without implying server usage
+- Removed unused `STORAGE_PROVIDER_TYPE` env var from README configuration table
+- Reformatted retryable status code condition in API client for readability

package/changelog/0.2.x/0.2.6.md

@@ -0,0 +1,11 @@
+---
+summary: "Adds idempotentHint: true to all three tools; adds publishing section to CLAUDE.md with npm and GHCR release commands"
+breaking: false
+---
+
+# 0.2.6 — 2026-03-24
+
+## Changed
+
+- Added `idempotentHint: true` annotation to all three tools — signals to clients that repeated calls with the same input produce the same result
+- Added publishing section to CLAUDE.md with npm and GHCR release commands

package/changelog/0.2.x/0.2.7.md

@@ -0,0 +1,10 @@
+---
+summary: "Unifies package description across README, package.json, server.json, and Dockerfile to a shorter consistent form"
+breaking: false
+---
+
+# 0.2.7 — 2026-03-24
+
+## Changed
+
+- Unified package description across README, package.json, server.json, and Dockerfile to a shorter, consistent form

package/changelog/0.2.x/0.2.8.md

@@ -0,0 +1,15 @@
+---
+summary: "Default select fields per entity type — searches now return curated subsets, preventing 20-70KB-per-record payloads from overwhelming context windows"
+breaking: false
+---
+
+# 0.2.8 — 2026-03-24
+
+## Added
+
+- Default `select` fields per entity type — search queries now return a curated subset of fields automatically, preventing 20-70KB-per-record responses from overwhelming context windows
+- Source journal name (`primary_location.source.display_name`) included in `openalex_search_entities` formatted text output
+
+## Changed
+
+- `select` parameter description updated — searches apply sensible defaults; pass `select` to override. Single-entity lookups by ID still return full records unless `select` is specified.

package/changelog/0.2.x/0.2.9.md

@@ -0,0 +1,21 @@
+---
+summary: "Rich structured markdown output for openalex_search_entities and openalex_resolve_name; adds report-issue-framework and report-issue-local skills; framework bump to ^0.2.3"
+breaking: false
+---
+
+# 0.2.9 — 2026-03-28
+
+## Added
+
+- Rich structured markdown format output for `openalex_search_entities` — renders identifiers, metrics, open access status, topics, authors, abstracts, and institution affiliations in organized sections
+- Rich structured format output for `openalex_resolve_name` — renders citations, works count, external IDs, and disambiguation hints
+- `report-issue-framework` and `report-issue-local` skills for filing issues against the framework and server repos
+- `LOGS_DIR` env var documented in README configuration table
+
+## Changed
+
+- `openalex_analyze_trends` format now shows key alongside display_name when they differ
+- `polish-docs-meta` skill updated with GitHub repo metadata sync steps and description propagation guidance
+- Bumped `@cyanheads/mcp-ts-core` ^0.1.28 → ^0.2.3
+- Bumped `@biomejs/biome` ^2.4.8 → ^2.4.9, `vitest` ^4.1.1 → ^4.1.2
+- Updated CLAUDE.md example code to reflect new format pattern with content-complete comments

package/changelog/0.3.x/0.3.0.md

@@ -0,0 +1,10 @@
+---
+summary: "Framework bump @cyanheads/mcp-ts-core ^0.2.3 → ^0.2.8"
+breaking: false
+---
+
+# 0.3.0 — 2026-03-28
+
+## Changed
+
+- Bumped `@cyanheads/mcp-ts-core` ^0.2.3 → ^0.2.8

package/changelog/0.3.x/0.3.1.md

@@ -0,0 +1,17 @@
+---
+summary: "Framework bump to ^0.2.10; adds funding links and public hosted server URL; refreshes add-tool, add-resource, and design-mcp-server skills"
+breaking: false
+---
+
+# 0.3.1 — 2026-03-30
+
+## Changed
+
+- Bumped `@cyanheads/mcp-ts-core` ^0.2.8 → ^0.2.10
+- Bumped `@biomejs/biome` ^2.4.9 → ^2.4.10
+- Added author email and funding links to package.json
+- Added `remotes` array with public hosted server URL to server.json
+- Updated `add-tool` skill (v1.1): expanded `format()` guidance, added Tool Response Design section (batch input, partial success, empty results, error classification, context budget)
+- Updated `add-resource` skill (v1.1): added tool coverage guidance for resource-only data
+- Updated `design-mcp-server` skill (v2.1): live API probing, tool-first design philosophy, batch input design, error design, convenience shortcuts, resilience planning
+- Minor formatting fixes in `analyze-trends.tool.ts` and `search-entities.tool.ts`

package/changelog/0.3.x/0.3.2.md

@@ -0,0 +1,28 @@
+---
+summary: "Framework bump to ^0.3.5; retries empty/HTML/malformed JSON responses; analyze_trends paginates cleanly; adds add-app-tool skill"
+breaking: false
+---
+
+# 0.3.2 — 2026-04-14
+
+## Added
+
+- `add-app-tool` skill for scaffolding MCP App tool/resource pairs with interactive UI guidance
+
+## Changed
+
+- Bumped `@cyanheads/mcp-ts-core` ^0.2.10 → ^0.3.5
+- Bumped dev dependencies: `@biomejs/biome` ^2.4.10 → ^2.4.12, `@types/node` ^25.5.0 → ^25.6.0, `vitest` ^4.1.2 → ^4.1.4
+- Refreshed `bun.lock` for the framework and toolchain update
+- Synced the project `skills/` directory with the latest framework and maintenance-skill guidance
+- Refreshed scaffolding, testing, workers, field-test, docs-polish, and migration skills to match current `@cyanheads/mcp-ts-core` patterns
+- Expanded skill guidance around content-complete `format()` output, MCP App UI packaging, and updated verification workflows
+- `openalex_search_entities` now formats unexpected selected fields generically, including structured JSON values, instead of dropping them from the MCP text output
+- `openalex_analyze_trends` now renders every group on the current page and adds an explicit pagination hint when more groups are available
+- The OpenAlex service now uses framework request utilities for timeout-aware retries and normalized request context
+
+## Fixed
+
+- Empty, HTML, and malformed JSON responses from the OpenAlex API are now treated as upstream failures and retried before surfacing an error
+- Upstream 404s wrapped by the framework now normalize back to `notFound()` responses
+- Expanded tests for retry handling, abort behavior during backoff, generic field rendering, and paginated trend formatting

package/changelog/0.3.x/0.3.3.md

@@ -0,0 +1,18 @@
+---
+summary: "Generic field rendering in openalex_search_entities; abstracts returned as plaintext; OpenAlex 4xx responses now map to specific MCP error classes"
+breaking: false
+---
+
+# 0.3.3 — 2026-04-15
+
+## Changed
+
+- `openalex_search_entities` now renders every returned field generically in MCP text output, humanizes field labels, and surfaces `next_cursor` directly in the results header
+- Abstracts reconstructed from `abstract_inverted_index` are now returned as plaintext while dropping the raw inverted index to keep responses smaller
+- Refreshed README feature notes and regenerated `docs/tree.md` to match the current repository state
+
+## Fixed
+
+- Invalid `select` field requests now surface OpenAlex's validation message, including the list of valid fields for that entity type
+- OpenAlex 4xx responses now map to specific MCP error classes (`invalidParams`, `notFound`, `rateLimited`, etc.) while preserving upstream messages
+- Expanded tests for generic field rendering, cursor formatting, abstract normalization, and upstream error handling behavior

package/changelog/0.4.x/0.4.0.md

@@ -0,0 +1,23 @@
+---
+summary: "Framework bump to ^0.5.3; rewrites tool format() bodies to satisfy the new format-parity linter so content[] now carries every output-schema field"
+breaking: false
+---
+
+# 0.4.0 — 2026-04-20
+
+## Changed
+
+- Bumped `@cyanheads/mcp-ts-core` ^0.3.5 → ^0.5.3 and `typescript` ^6.0.2 → ^6.0.3
+- Regenerated `bun.lock` from scratch against current caret ranges
+- Rewrote tool `format()` bodies to satisfy the new framework `format-parity` linter: every terminal field in each tool's `output` schema now appears in the rendered `content[]` text
+  - `openalex_analyze_trends` now surfaces `meta.count`, `meta.groups_count`, and the `next_cursor` value
+  - `openalex_search_entities` header now includes `per_page` alongside the total count
+  - `openalex_resolve_name` always renders `works_count` (including a `n/a works` branch for null)
+- Replaced `.toLocaleString()` on linted numeric fields with raw digits so the linter's sentinel-injection matcher passes
+- Synced `skills/` from the framework: `add-tool` 1.3 → 1.6, `design-mcp-server` 2.2 → 2.4, `maintenance` 1.2 → 1.3, `setup` 1.2 → 1.3, `polish-docs-meta` 1.3 → 1.4, `field-test` 1.1 → 1.2, `api-config` 1.1 → 1.2
+- Expanded the `CLAUDE.md` / `AGENTS.md` checklist with the upstream additions (form-client guards, `format()` parity, OpenAlex-wrapping invariants); added `add-app-tool`, `report-issue-framework`, and `report-issue-local` to the skills table
+- `AGENTS.md` now mirrors `CLAUDE.md` verbatim so both agent entry points stay in lockstep
+
+## Fixed
+
+- Tool output no longer diverges between `structuredContent` (programmatic) and `content[]` (LLM-visible) surfaces — both carry the full payload the output schema declares

package/changelog/0.5.x/0.5.0.md

@@ -0,0 +1,23 @@
+---
+summary: "Adds HTTP landing page and SEP-1649 Server Card via @cyanheads/mcp-ts-core 0.6.x, plus sourceUrl overrides; syncs skills and adds api-linter + release-and-publish"
+breaking: false
+---
+
+# 0.5.0 — 2026-04-23
+
+## Added
+
+- HTTP landing page at `/` and SEP-1649 Server Card at `/.well-known/mcp.json` — both surfaces ship automatically via `@cyanheads/mcp-ts-core` 0.6.x and are configured through a new `landing` block in `createApp()`
+- `landing.envExample` surfaces `OPENALEX_API_KEY` in the STDIO JSON connect snippet and Claude CLI `--env` flags
+- `landing.repoRoot` enables the auto-derived GitHub footer cluster (Changelog · release · Issues · Source · npm)
+- `landing.links` for OpenAlex and OpenAlex API Docs
+- `sourceUrl` override on all 3 tools and 2 prompts so each landing-page card links to the actual definition file (filenames drop the `openalex-` prefix, so the framework's snake→kebab auto-derivation would 404)
+- `MCP_PUBLIC_URL` documented in `.env.example` for TLS-terminating reverse-proxy deployments
+
+## Changed
+
+- Bumped `@cyanheads/mcp-ts-core` ^0.5.3 → ^0.6.10, `@biomejs/biome` ^2.4.12 → ^2.4.13, `vitest` ^4.1.4 → ^4.1.5
+- Regenerated `bun.lock` against current caret ranges
+- Synced `skills/` from the framework: `add-tool` 1.6 → 1.8, `design-mcp-server` 2.4 → 2.7, `polish-docs-meta` 1.4 → 1.7, `setup` 1.3 → 1.5, `maintenance` 1.3 → 1.4, plus `add-app-tool`, `add-prompt`, `add-resource`, `add-service`, `api-context`, `api-services`, `api-utils`, `field-test` to their current versions
+- Added new `api-linter` (1.0) and `release-and-publish` (2.0) skills and refreshed `.claude/skills/` + `.agents/skills/` agent directories
+- `CLAUDE.md`: added `api-linter` and `release-and-publish` to the skills table; Publishing section now points at the `release-and-publish` skill; note that the `maintenance` skill auto-syncs agent skill directories (Phase B)

package/changelog/0.6.x/0.6.0.md

@@ -0,0 +1,28 @@
+---
+summary: "Framework bump to ^0.6.17, directory-based changelog, cleaner field rendering in search_entities (no comma-years, uppercased acronyms), security-pass skill surfaced"
+breaking: false
+---
+
+# 0.6.0 — 2026-04-24
+
+Picks up 7 patches of `@cyanheads/mcp-ts-core` (0.6.10 → 0.6.17), adopts the directory-based changelog convention, and resolves two visible render issues in `openalex_search_entities` that surfaced during field testing.
+
+## Added
+
+- **Directory-based changelog** under `changelog/<major.minor>.x/<version>.md` (18 migrated entries + `template.md` format reference). `CHANGELOG.md` is now a nav index regenerated by `bun run changelog:build`; `bun run changelog:check` runs in `devcheck`.
+- `package.json` scripts `changelog:build` and `changelog:check`.
+- **`security-pass` skill** (v1.1) — 8-axis MCP server audit — synced in from the framework and surfaced in the agent protocol `What's Next?` sequence (between `devcheck` and `polish-docs-meta`) and the skills table.
+- Three new framework scripts: `scripts/build-changelog.ts`, `scripts/check-docs-sync.ts`, `scripts/check-skills-sync.ts`.
+
+## Changed
+
+- Bumped `@cyanheads/mcp-ts-core` `^0.6.10` → `^0.6.17` (no breaking changes across 7 patch releases).
+- `openalex_search_entities` field rendering — dropped `.toLocaleString()` on integers (publication years no longer render as `2,007`; counts render as `23473` instead of `23,473`, consistent with CLAUDE.md's own anti-`toLocaleString` guidance on linted numbers).
+- `openalex_search_entities` field labels — added an `ACRONYMS` set (`apc`, `doi`, `fwci`, `id`, `issn`, `oa`, `orcid`, `pmcid`, `pmid`, `ror`, `url`) so `toFieldLabel` renders `**DOI:**`, `**ORCID:**`, `**ID:**` instead of the title-cased `Doi`/`Orcid`/`Id`.
+- All three tools now have `.describe()` on their array-element `z.object(...)` shapes — required by the `describe-on-fields` linter rule that became recursive in framework 0.6.16.
+- Synced framework scripts (`devcheck.ts`, `lint-mcp.ts`, `tree.ts`) and skills (`field-test` 1.3 → 2.0, `report-issue-framework` and `report-issue-local` 1.1 → 1.2, `maintenance` 1.4 force-resync now includes Phase C for scripts sync).
+- `CLAUDE.md` / `AGENTS.md` resynced, version field corrected, and security-pass surfaced.
+
+## Fixed
+
+- `describe-on-fields` lint warnings in `openalex_search_entities`, `openalex_analyze_trends`, and `openalex_resolve_name` — the recursive rule in framework 0.6.16 now flags array-element objects that lack `.describe()`.

package/changelog/0.6.x/0.6.1.md

@@ -0,0 +1,15 @@
+---
+summary: "Framework bump to ^0.7.0 — flattened ZodError messages, locale-aware format-parity linter, devcheck crash fix on single-file changelog projects"
+breaking: false
+---
+
+# 0.6.1 — 2026-04-24
+
+Picks up `@cyanheads/mcp-ts-core` 0.7.0 and the skill/script updates that ship with it. No behavior changes in this server's handlers — this is a maintenance release.
+
+## Changed
+
+- Bumped `@cyanheads/mcp-ts-core` `^0.6.17` → `^0.7.0` (no breaking changes).
+- `CLAUDE.md` / `AGENTS.md` — removed the stale `.toLocaleString()` caveat in the tool-pattern comment and Checklist. Framework 0.7.0's `format-parity` linter is now locale-aware: digit-group separators (commas, periods, spaces, narrow no-break, Arabic thousands) are stripped before sentinel matching, so `.toLocaleString()` is safe on linted numeric fields. Compact/scientific forms still fail by construction.
+- Resynced framework skills: `api-linter` (1.0 → 1.1 — `describe-on-fields` recursion table), `maintenance` (1.4 → 1.5 — direct framework-update adoption, tiered cost/benefit for third-party), `release-and-publish` (2.0 → 2.1 — transient-failure retry protocol), `report-issue-framework` (1.2 → 1.3), `report-issue-local` (1.2 → 1.3). Label restructuring in the issue skills splits primary (required, pick one) from secondary (optional, stackable) — matches the new `regression`/`performance`/`security`/`breaking-change` labels in the framework repo.
+- Resynced framework scripts: `scripts/build-changelog.ts` and `scripts/devcheck.ts` — picks up [#51](https://github.com/cyanheads/mcp-ts-core/issues/51) fix for the devcheck crash on single-file `CHANGELOG.md` projects. No impact on this server (which uses the directory-based changelog), but keeps the scripts content-identical to upstream.

package/changelog/0.6.x/0.6.10.md

@@ -0,0 +1,21 @@
+---
+summary: "Adopt @cyanheads/mcp-ts-core ^0.8.19 → ^0.9.1; surface server-level `instructions` on the MCP initialize response so clients can forward catalog orientation to the model."
+breaking: false
+security: false
+---
+
+# 0.6.10 — 2026-05-16
+
+Picks up [`@cyanheads/mcp-ts-core` 0.9.0 + 0.9.1](https://github.com/cyanheads/mcp-ts-core/blob/main/CHANGELOG.md). 0.9.0 was framework-breaking (Workers `nodejs_compat` boot fix, cross-vendor JSON Schema portability lint family, build-time-only lint gate), but the changes here are additive — none of this server's Zod schemas use the now-flagged `format` values (`z.url()`, `z.cuid()`, etc.).
+
+## Added
+
+- **`instructions`** on `createApp()` ([cyanheads/mcp-ts-core#91](https://github.com/cyanheads/mcp-ts-core/issues/91)) — server-level orientation included on every `initialize` response. Spec-compliant clients forward it to the model as session-level system context, so the "resolve names before filtering" rule and the entity-type catalog no longer have to be duplicated into every tool description.
+
+## Maintenance
+
+- `@cyanheads/mcp-ts-core` `^0.8.19 → ^0.9.1`.
+- `@biomejs/biome` `^2.4.14 → ^2.4.15`, `@types/node` `^25.6.2 → ^25.8.0`, `tsx` `^4.21.0 → ^4.22.0`, `vitest` `^4.1.5 → ^4.1.6` (devDeps).
+- Framework-synced skills: `api-linter` (+302 lines — portability lint family, error contract structural/conformance rules, landing config rules, handler body rules), `api-auth`, `api-config`, `api-errors`, `api-workers`, `add-tool`, `design-mcp-server`, `field-test`, `polish-docs-meta`, `security-pass`, `tool-defs-analysis`.
+- Framework-synced scripts: `scripts/devcheck.ts` `bun outdated` parser reads markdown index `[1]` (not `[0]`) and strips the trailing `(dev|peer|prod|optional)` workspace marker; `scripts/build-changelog.ts` summary cap `250 → 350` chars (mirrored in `changelog/template.md`).
+- `README.md` — `OTEL_ENABLED` row links to the framework's telemetry docs.