@cyanheads/pubmed-mcp-server 2.10.7 → 2.10.8

package/AGENTS.md

@@ -1,8 +1,8 @@
 # Agent Protocol
 
 **Server:** @cyanheads/pubmed-mcp-server
-**Version:** 2.10.7
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.7`
+**Version:** 2.10.8
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.8`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 
 > **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.
@@ -35,6 +35,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 - **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.
 
 ---
@@ -288,8 +289,9 @@ Available skills:
 | `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 |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
-| `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
-| `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
+| `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, fixup commits autosquashed into 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` |
 | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
 | `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 |
@@ -362,7 +364,9 @@ Directory-based, grouped by minor series via the `.x` semver-wildcard convention
 
 ## Publishing
 
-Run the `release-and-publish` skill after git wrapup — it runs the verification gate (`devcheck`, `rebuild`, `test`), pushes commits and tags, and publishes to npm, the MCP Registry, GHCR, and attaches the `.mcpb` bundle to the GitHub Release, halting on the first failure. For reference, the underlying commands are:
+**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/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-pr-review` reviews and fixes on that branch (fixup commits autosquashed into the stack, `--force-with-lease` on the release branch only, 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.
+
+`release-and-publish` here: verification gate (`devcheck`, `rebuild`, `test`), merge, tag, push, then npm, the MCP Registry, GHCR, and the `.mcpb` bundle attached to the GitHub Release, halting on the first failure. For reference, the underlying commands are:
 
 ```bash
 bun publish --access public

package/CLAUDE.md

@@ -1,8 +1,8 @@
 # Agent Protocol
 
 **Server:** @cyanheads/pubmed-mcp-server
-**Version:** 2.10.7
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.7`
+**Version:** 2.10.8
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.8`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 
 > **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.
@@ -35,6 +35,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 - **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.
 
 ---
@@ -288,8 +289,9 @@ Available skills:
 | `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 |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
-| `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
-| `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
+| `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, fixup commits autosquashed into 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` |
 | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
 | `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 |
@@ -362,7 +364,9 @@ Directory-based, grouped by minor series via the `.x` semver-wildcard convention
 
 ## Publishing
 
-Run the `release-and-publish` skill after git wrapup — it runs the verification gate (`devcheck`, `rebuild`, `test`), pushes commits and tags, and publishes to npm, the MCP Registry, GHCR, and attaches the `.mcpb` bundle to the GitHub Release, halting on the first failure. For reference, the underlying commands are:
+**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/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-pr-review` reviews and fixes on that branch (fixup commits autosquashed into the stack, `--force-with-lease` on the release branch only, 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.
+
+`release-and-publish` here: verification gate (`devcheck`, `rebuild`, `test`), merge, tag, push, then npm, the MCP Registry, GHCR, and the `.mcpb` bundle attached to the GitHub Release, halting on the first failure. For reference, the underlying commands are:
 
 ```bash
 bun publish --access public

package/README.md

@@ -9,7 +9,7 @@
 
 
 
-[![Version](https://img.shields.io/badge/Version-2.10.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/pubmed-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/pubmed-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/pubmed-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.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-2.10.8-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/pubmed-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/pubmed-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/pubmed-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.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 

package/dist/mcp-server/tools/definitions/fetch-fulltext.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-fulltext.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fetch-fulltext.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAsB,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAmtB/D;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,MAAM,CAiCT;AAID,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAy0B5B,CAAC"}
+{"version":3,"file":"fetch-fulltext.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fetch-fulltext.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAsB,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAgyB/D;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,MAAM,CAiCT;AAID,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAy0B5B,CAAC"}

package/dist/mcp-server/tools/definitions/fetch-fulltext.tool.js

@@ -42,6 +42,43 @@ function filterSections(sections, sectionFilter) {
     const lowerFilter = sectionFilter.map((s) => s.toLowerCase());
     return sections.filter((s) => s.title && lowerFilter.some((f) => s.title?.toLowerCase().includes(f)));
 }
+/**
+ * Render a section subtree as text blocks, in document order: each section's
+ * heading on its own line above its text. Used for the levels past
+ * {@link MAX_SECTION_DEPTH}, which have no node of their own to live in. (#112)
+ */
+function flattenSectionText(section) {
+    const heading = section.title ? formatHeading(section.label, section.title) : undefined;
+    const block = [heading, section.text].filter(Boolean).join('\n');
+    return [...(block ? [block] : []), ...(section.subsections ?? []).flatMap(flattenSectionText)];
+}
+/**
+ * Clamp a section tree to the depth the output schema declares. A section at the
+ * deepest level absorbs its descendants into its own text instead of carrying
+ * them as subsections the schema would strip on validation — silently, from both
+ * `structuredContent` and `content[]`. Shallower trees pass through untouched.
+ * (#112)
+ */
+function clampSectionDepth(sections, depth = 1) {
+    return sections.map((section) => {
+        const subsections = section.subsections;
+        if (!subsections?.length)
+            return section;
+        if (depth < MAX_SECTION_DEPTH) {
+            return { ...section, subsections: clampSectionDepth(subsections, depth + 1) };
+        }
+        const { subsections: _dropped, ...rest } = section;
+        const tail = subsections.flatMap(flattenSectionText);
+        return { ...rest, text: [section.text, ...tail].filter(Boolean).join('\n\n') };
+    });
+}
+/**
+ * Apply the requested section/reference filters, then clamp the section tree to
+ * the depth the output schema carries. Both run here so every path producing a
+ * `pmc` article — PMC EFetch and the Europe PMC stage — shares one shape, and
+ * the budget helpers downstream count the text that will actually survive
+ * validation. (#112)
+ */
 function applyPmcFilters(article, filters) {
     let out = article;
     if (filters.sections?.length) {
@@ -54,7 +91,7 @@ function applyPmcFilters(article, filters) {
         const { references: _, ...rest } = out;
         out = rest;
     }
-    return out;
+    return { ...out, sections: clampSectionDepth(out.sections) };
 }
 /**
  * True when a `sections` filter removed every body section from an article that
@@ -110,11 +147,30 @@ function buildBodylessNotice(affectedIds) {
     return `No body text could be retrieved for ${subject} — the full-text source returned front matter and abstract only, and no later tier recovered a copy. See \`triedTiers\` on the \`unavailable\` entry for what each tier reported, and use \`pubmed_fetch_articles\` for the abstract and metadata.`;
 }
 // ─── Schemas ─────────────────────────────────────────────────────────────────
+/**
+ * How many `<sec>` levels the output schema carries as structured nodes. JATS
+ * nesting is unbounded and the parser recurses without a cap, so the schema is
+ * what decides how deep a section survives output validation — anything past it
+ * used to be dropped silently from both output surfaces (#112). Sections deeper
+ * than this are now flattened into the deepest surviving node's text instead, so
+ * no body content is lost at any depth.
+ *
+ * Two is the ceiling the tool's own contract can verify, not a guess at how deep
+ * real records nest: `format-parity`'s sentinel walker stops after 8 schema hops,
+ * and `articles[]` → the article union → `sections[]` → `subsections[]` already
+ * spends them all. A third `subsections` level puts its own elements out of the
+ * walker's reach, so `format()` parity for that subtree would ship unverified.
+ * Levels are inlined rather than expressed with `z.lazy()` regardless — a
+ * self-referential schema emits `$defs`/`$ref`, which Gemini rejects.
+ */
+const MAX_SECTION_DEPTH = 2;
 const SubsectionSchema = z
     .object({
     title: z.string().optional().describe('Subsection heading'),
     label: z.string().optional().describe('Subsection label'),
-    text: z.string().describe('Subsection body text'),
+    text: z
+        .string()
+        .describe('Subsection body text. Sections nested deeper than this level are folded in here in document order, each heading rendered on its own line above its text.'),
 })
     .describe('Article subsection');
 const SectionSchema = z
@@ -376,9 +432,28 @@ const DeferredSchema = z
 function budgetRequested(budget) {
     return budget.maxCharacters !== undefined || budget.maxCharactersPerSection !== undefined;
 }
-/** Body characters a top-level section carries — its own text plus its subsections'. */
+/** Every text field in a section subtree, in document order, own text first. */
+function sectionTextFields(section) {
+    return [section.text, ...(section.subsections ?? []).flatMap(sectionTextFields)];
+}
+/**
+ * Body characters a section carries — its own text plus every nested
+ * subsection's. Measured off {@link sectionTextFields} rather than its own walk,
+ * so the count the budget reports as `originalCharacters` is always taken over
+ * exactly the fields {@link fitFields} shortens.
+ */
 function sectionCharacters(section) {
-    return (section.text.length + (section.subsections?.reduce((n, sub) => n + sub.text.length, 0) ?? 0));
+    return sectionTextFields(section).reduce((n, text) => n + text.length, 0);
+}
+/**
+ * Rebuild a section subtree from `fitted`, consuming one entry per node in the
+ * same document order {@link sectionTextFields} produced them. `cursor` walks
+ * the flat list across the whole subtree.
+ */
+function withFittedTexts(section, fitted, cursor) {
+    const text = fitted[cursor.i++] ?? '';
+    const subsections = section.subsections?.map((sub) => withFittedTexts(sub, fitted, cursor));
+    return { ...section, text, ...(subsections && { subsections }) };
 }
 /**
  * Shorten an ordered list of text fields so their combined length fits
@@ -478,7 +553,7 @@ function applyPmcBudget(article, budget) {
     let returnedCharacters = 0;
     article.sections.forEach((section, i) => {
         const original = sizes[i] ?? 0;
-        const fitted = fitFields([section.text, ...(section.subsections?.map((sub) => sub.text) ?? [])], allowances[i] ?? 0);
+        const fitted = fitFields(sectionTextFields(section), allowances[i] ?? 0);
         const returned = fitted.reduce((sum, text) => sum + text.length, 0);
         returnedCharacters += returned;
         sectionReports.push({
@@ -491,13 +566,7 @@ function applyPmcBudget(article, budget) {
             omittedSections += 1;
             return;
         }
-        kept.push({
-            ...section,
-            text: fitted[0] ?? '',
-            ...(section.subsections && {
-                subsections: section.subsections.map((sub, j) => ({ ...sub, text: fitted[j + 1] ?? '' })),
-            }),
-        });
+        kept.push(withFittedTexts(section, fitted, { i: 0 }));
     });
     if (returnedCharacters === originalCharacters && omittedSections === 0) {
         return { article, omittedSections: 0 };
@@ -1950,20 +2019,8 @@ function formatPmcArticle(a, lines, truncation) {
         lines.push(truncationNote(truncation));
     if (a.abstract)
         lines.push(`\n#### Abstract\n${a.abstract}`);
-    for (const sec of a.sections) {
-        if (sec.title)
-            lines.push(`\n#### ${formatHeading(sec.label, sec.title)}`);
-        if (sec.text)
-            lines.push(sec.text);
-        if (sec.subsections?.length) {
-            for (const sub of sec.subsections) {
-                if (sub.title)
-                    lines.push(`\n##### ${formatHeading(sub.label, sub.title)}`);
-                if (sub.text)
-                    lines.push(sub.text);
-            }
-        }
-    }
+    for (const sec of a.sections)
+        formatSection(sec, lines, 4);
     if (a.references?.length) {
         lines.push(`\n#### References (${a.references.length})`);
         for (const ref of a.references) {
@@ -2015,6 +2072,21 @@ function formatPmcAuthor(au) {
 function formatHeading(label, title) {
     return label ? `${label} ${title}` : title;
 }
+/**
+ * Render one body section and everything nested under it, one markdown heading
+ * level per nesting level. Walks the full depth the output schema carries, so
+ * `content[]` shows every section `structuredContent` does. Headings stop
+ * deepening at `######`, the deepest markdown supports. (#112)
+ */
+function formatSection(section, lines, depth) {
+    if (section.title) {
+        lines.push(`\n${'#'.repeat(Math.min(depth, 6))} ${formatHeading(section.label, section.title)}`);
+    }
+    if (section.text)
+        lines.push(section.text);
+    for (const sub of section.subsections ?? [])
+        formatSection(sub, lines, depth + 1);
+}
 /**
  * Strip absolute URLs from chain detail strings. Upstream errors (e.g.
  * `Fetch failed for <eutils URL>. Status: 400`) leak endpoint paths and query