Changelog

All notable changes to this project. Each entry links to its full per-version file in changelog/.

1.8.0 — 2026-10-26

Publishes the arxiv-guide Agent Skill, served over MCP as skill://arxiv-guide/SKILL.md and shipped in the npm package, Docker image, and .mcpb, and adopts mcp-ts-core 0.13.18: the HTTP per-request memory leak fixed in 0.13.17, and a .mcpb that no longer carries source, a local database, or node-gyp build files.

1.7.2 — 2026-10-25

content[] from arxiv_search_papers, arxiv_get_metadata, and arxiv_read_paper reads back through a CommonMark parse as structuredContent carries it. Mirror schema v5 repairs stored apostrophes and quotes, and searches over several category groups run faster.

1.7.1 — 2026-10-23

arxiv_search_papers reads mirror queries with arXiv's grammar and sends forms the mirror cannot answer as arXiv does to the live API. Term-less mirror searches are index-driven under schema v4, with a lower-bound total. An unparseable PDF fails pdf_extraction_failed.

1.7.0 — 2026-10-21 · ⚠️ Breaking

arxiv_read_paper extracts PDF text in a worker thread and now fails Timeout when extraction outlasts ARXIV_READ_TIMEOUT_MS. Mirror query errors and queries the mirror cannot answer as arXiv does go live; a hung arXiv API no longer times out reads the mirror can answer.

1.6.1 — 2026-10-18

Moves mirror searches off the request thread, gives arxiv_read_paper one read deadline (ARXIV_READ_TIMEOUT_MS), makes the server's mirror connection query-only with one migrating writer at a time, and fixes the lookup and read paths around outages, stalled bodies, and superseded old-style versions.

1.6.0 — 2026-10-17 · ⚠️ Breaking

Renames arxiv_search to arxiv_search_papers (no alias), adds a section outline to arxiv_read_paper, runs every ID input through one parser, and bounds mirror searches and refreshes. Adopts mcp-ts-core ^0.13.15.

1.5.4 — 2026-10-04

Adopts mcp-ts-core 0.13.7–0.13.12 — tool errors carry a request id, declared recovery hints reach callers without per-throw forwarding, an integer sent for a string parameter is accepted, and the Docker image builds multi-arch without emulation.

1.5.3 — 2026-09-19

Adopts mcp-ts-core 0.13.1-0.13.6 — sessionMode is now declared as stateless in src/index.ts, tool errors close with a machine-readable reason/retryable suffix, argument handling tolerates client-added keys and case-style aliases, and upstream fetch errors no longer carry the request URL.

1.5.2 — 2026-09-13 · ⚠️ Breaking

Adopts mcp-ts-core 0.13.0 — the framework skill tree moves to framework-skills/ so an installing agent no longer inherits it, and the Bun floor rises to 1.4.0. Mirror and live arxiv_search are now held to identical results by an offline contract test.

1.5.1 — 2026-08-22 · ⚠️ Breaking

Adopts MCP SDK v2 with strict top-level tool inputs and 2026-07-28 HTTP negotiation; arxiv://categories advertises a public 24-hour cache hint.

1.5.0 — 2026-07-27

arxiv_search's cat: query operand now expands the same way on both search paths, co:/jr: prefixes resolve on the mirror, and query cat: composes with the category parameter the way arXiv does (#36, #37); mirror schema v3 rebuilds its full-text index automatically in place

1.4.0 — 2026-07-27 · ⚠️ Breaking

arxiv_read_paper falls back to PDF-text extraction when no HTML render exists, accepts max_characters: null for whole-paper reads, and no longer fails the whole chain on an ar5iv outage (#23, #24, #38)

1.3.1 — 2026-07-26

Fix arxiv_search's effective_query echo to include applied filters, accept bare archive category codes, and add submitted_from/submitted_to date-window filtering past the pagination ceiling (#20, #27, #32)

1.3.0 — 2026-07-26

Classify arXiv responses by HTTP status before content-type, distinguish mirror version-misses from not_in_arxiv, fix rate-limit recovery hints and abstract_url versioning, and reject failed mirror refreshes instead of resolving them (#9, #29, #30, #31, #34, #35)

1.2.16 — 2026-07-26

Fix silent version substitution in metadata batch lookup, mirror fallback, and whitespace-only ID validation (#25, #26, #28, #33); adopt mcp-ts-core 0.11.0

1.2.15 — 2026-06-20

Adopt @cyanheads/mcp-ts-core 0.10.7–0.10.9: devcheck fresh-scaffold guards, dependency-specifier guard, plugin-manifest packaging checks, ctx.content collector, DuckDB SQL-gate fixes; skill + script re-sync

1.2.14 — 2026-06-15

Adopt @cyanheads/mcp-ts-core 0.10.6: server identity name/title, arxiv_search truncation disclosure, env booleans via z.stringbool(), MCPB bundle cleaner

1.2.13 — 2026-06-02

Adopt @cyanheads/mcp-ts-core 0.9.21: per-request log context fix, secret redaction in fetchWithTimeout, withRetry fail-fast on non-retryable errors

1.2.12 — 2026-06-01

Scheduled mirror refresh runs in a child process — harvest SQLite writes no longer block the request event loop

1.2.11 — 2026-05-31

Incremental and failed mirror refreshes no longer drop arxiv_search to the rate-limited live API

1.2.10 — 2026-05-30

arxiv_search and arxiv_list_categories surface query echoes, true result totals, and empty-result guidance in a typed enrichment block

1.2.9 — 2026-05-29

mirror schema v2: ISO 8601 date normalization for chronological sort (#18), index-backed category filter via junction table (#19)

1.2.8 — 2026-05-28

mcp-ts-core ^0.9.6 → ^0.9.13: 413 body cap, HTTP session-init gate, quieter client-error logging, GET /mcp keywords

1.2.7 — 2026-05-26

Mirror fallback when live API fails: search recency bypass and readContent metadata paths now recover gracefully instead of surfacing upstream errors.

1.2.6 — 2026-05-23

mcp-ts-core ^0.9.1 → ^0.9.6. Error factories in harvester (McpError → validationError/notFound). manifest.json and .mcpbignore scaffolded for MCPB bundle support. Skills synced. fast-xml-parser unpinned.

1.2.5 — 2026-05-22

Mirror translator's cat: extraction no longer leaves dangling boolean operators or empty ( ) groups inside parens (#14). New cleanupDanglingOps post-pass collapses empty groups and drops orphaned operators to a fixed point, covering all six failing shapes from the issue.

1.2.4 — 2026-05-22

Mirror query translator inserts explicit AND at every parenthesis boundary so all: expansions and user-typed groups stop emitting FTS5-invalid expressions. Defense-in-depth catch in ArxivService.searchMirror rethrows any leaked fts5: SQLiteError as validationError with the original query and recovery hint.

1.2.3 — 2026-05-21

Dockerfile production stage writes a minimal tsconfig.json mapping @/* → ./dist/* so Bun resolves the path alias the mirror scripts import through. v1.2.2 shipped the scripts but Bun couldn't resolve @/config/server-config.js. Final piece for an end-to-end deployable mirror.

1.2.2 — 2026-05-21

Ship the mirror:* scripts in the published artifacts. v1.2.0 added scripts/arxiv-mirror-{init,refresh,verify}.ts but omitted them from the Docker production stage and the npm files array — bun run mirror:init failed with Module not found inside the container and in npm-installed copies. Runtime code unchanged; packaging only.

1.2.1 — 2026-05-21

Dockerfile build stage adds --ignore-scripts to bun install so better-sqlite3's node-gyp native build doesn't fail in the oven/bun:1.3 base image (no python3/make/g++). Runtime is Bun-only and uses bun:sqlite, so the compiled binary is never loaded — skipping it is strictly an improvement. No source changes.

1.2.0 — 2026-05-21

Optional OAI-PMH metadata mirror for arxiv_search and arxiv_get_metadata — local SQLite + FTS5 eliminates per-IP rate-limit exposure. Opt-in via ARXIV_MIRROR_ENABLED=true and bun run mirror:init (~4.4h cold harvest). Falls back to the live API on incomplete harvest or lookup miss; arxiv_read_paper still uses the live API.

0.1.19 — 2026-05-18

Field-test fixes from issues #4 — #10: arxiv_get_metadata preserves input order; arxiv_read_paper honors version suffix in HTML URLs and collapses MathML to dollar-delimited LaTeX (2-3× shrink); category suggestions rank by edit distance; rate-limit cooldown grows geometrically (5s → 10s → 20s → 30s capped) per consecutive hit.

0.1.18 — 2026-05-16

Adopt server-level instructions from @cyanheads/mcp-ts-core 0.9.x — spec-compliant clients now forward arXiv tool orientation to the model on every initialize. Framework refresh 0.8.19 → 0.9.1 (portability lint family, Workers nodejs_compat boot fix, SSRF hardening, changelog summary cap 250 → 350 chars).

0.1.17 — 2026-05-08

Fix retry storm on AbortSignal.timeout — connection-layer arXiv throttle now classified as Timeout (non-retryable) instead of ServiceUnavailable (retryable), cutting caller-visible latency from 60-90s to 15s. Framework refresh 0.8.15 → 0.8.19.

0.1.16 — 2026-05-05

Error-contract conformance pass — every non-baseline throw on every API-using surface now carries a typed contract entry and resolves its recovery hint at runtime. Bumps mcp-ts-core 0.8.7 → 0.8.15.

0.1.15 — 2026-04-30

arxiv_read_paper adds start offset for chunk-by-chunk pagination on long papers; HTML cleaner preserves ltx_section/title structural markers; description clarifies arxiv.org/html → ar5iv fallback (no PDF auto-extract)

0.1.14 — 2026-04-30 · ⚠️ Breaking

Bump @cyanheads/mcp-ts-core 0.7.5 → 0.8.7; typed error contracts on every tool/resource; arxiv_get_metadata adopts partialResult; fixes arxiv_search retry-storm on rate-limit (#8) — fail-fast + Retry-After cooldown + User-Agent

0.1.13 — 2026-04-27

Bump @cyanheads/mcp-ts-core 0.6.17 → 0.7.5; arxiv_search validates categories with near-match suggestions and parens-scopes multi-word queries to prevent category leakage; arxiv_read_paper strips LaTeXML noise (3-4× shrinkage)

0.1.12 — 2026-04-24

Bump @cyanheads/mcp-ts-core 0.6.16 → 0.6.17 (HTTP transport hardening) and adopt upstream CLAUDE.md guidance on external API wrapping and format() parity

0.1.11 — 2026-04-24

Fail fast on permanent 4xx from arXiv API, and harden arxiv_search / arxiv_read_paper input schemas to reject values arXiv would return 400/500 for

0.1.10 — 2026-04-24

Framework refresh to @cyanheads/mcp-ts-core 0.6.16 — adopted directory-based changelog, recursive describe-on-fields lint fixes, synced skills/scripts

0.1.9 — 2026-04-20

Framework refresh to @cyanheads/mcp-ts-core 0.5.3 — format-parity fixes across tools, parseEnvConfig for better env-var validation errors

0.1.8 — 2026-04-19

Tool/resource quality improvements aligned with new framework skill patterns, plus a dependency refresh to mcp-ts-core 0.3.7

0.1.7 — 2026-03-30

Public hosted instance at arxiv.caseyjhand.com/mcp, README tagline rewrite, npm/Docker badges, funding links

0.1.6 — 2026-03-30

arxiv_read_paper max_characters defaults to 100k, strips HTML head/boilerplate before truncation, descriptive input validation

0.1.5 — 2026-03-30

Search reliability — raw-colon field prefixes instead of percent-encoded, better empty-result messaging, mcp-ts-core 0.2.10

0.1.4 — 2026-03-30

mcp-ts-core 0.2.9 refresh, description cleanup (no string concat), Map.groupBy() modernization

0.1.3 — 2026-03-29

Comprehensive test suite (9 files, all tools/resources/services covered); finalized TypeScript build and Vitest config

0.1.2 — 2026-03-28

Full MCP surface implemented — 4 tools, 2 resources, ArxivService with rate-limited request queue and HTML fallback chain

0.1.1 — 2026-03-28

Project metadata, documentation, and packaging finalized for initial publish — README, LICENSE, scoped package name

0.1.0 — 2026-03-28

Initial release — scaffolded from @cyanheads/mcp-ts-core with full MCP surface design for arXiv paper search, metadata, and content reading