@cyanheads/hn-mcp-server 0.5.21 → 0.6.0

package/AGENTS.md

@@ -1,11 +1,11 @@
 # Developer Protocol
 
 **Server:** hn-mcp-server
-**Version:** 0.5.21
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.12`
+**Version:** 0.6.0
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
-**MCP SDK:** `@modelcontextprotocol/server` 2.2.0
-**Zod:** ^4.6.5
+**MCP SDK:** `@modelcontextprotocol/server` 2.4.0
+**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.
 
@@ -48,7 +48,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 
 ```ts
 import { tool, z } from '@cyanheads/mcp-ts-core';
-import { getHnService, settlePage, normalizeUrl, stripHtml } from '@/services/hn/hn-service.js';
+import { CALL_BUDGET_MS, getHnService, settlePage, normalizeUrl, stripHtml } from '@/services/hn/hn-service.js';
 
 export const getStories = tool('hn_get_stories', {
   description: 'Fetch stories from an HN feed (top, new, best, ask, show, jobs).',
@@ -70,10 +70,12 @@ export const getStories = tool('hn_get_stories', {
 
   async handler(input, ctx) {
     const hn = getHnService();
-    const feedIds = await hn.fetchFeed(input.feed, ctx);
+    // One time budget for the feed and every item fetch after it.
+    const deadline = Date.now() + CALL_BUDGET_MS;
+    const feedIds = await hn.fetchFeed(input.feed, ctx, deadline);
     const sliced = feedIds.slice(input.offset, input.offset + input.count);
     // Live items plus the IDs whose fetch failed; throws when every item failed.
-    const { items, failedIds } = settlePage(await hn.fetchItems(sliced, ctx));
+    const { items, failedIds } = settlePage(await hn.fetchItems(sliced, ctx, deadline));
     if (failedIds.length > 0) ctx.enrich({ failedIds });
     ctx.log.info('Fetched stories', { feed: input.feed, count: items.length });
     return { stories: items.map(/* ... */), feed: input.feed, total: feedIds.length };
@@ -218,6 +220,9 @@ src/
       types.ts                          # HN domain types
   mcp-server/
     tools/markdown-escape.ts           # format() boundary: escape titles, quote bodies
+    tools/response-budget.ts           # 64,000-byte budget per response surface: measure both surfaces, largest shared body cut, code-point cut
+    tools/served-at-cap.ts             # notice sentence for a size input served at its per-call cap
+    tools/thread-cursor.ts             # hn_get_thread cursor codec: packed frontier, JSON format still decoded
     tools/definitions/
       get-stories.tool.ts              # hn_get_stories — Fetch stories from an HN feed
       get-thread.tool.ts               # hn_get_thread — Get item + comment tree
@@ -240,9 +245,18 @@ src/
 
 ## 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.
+Two skill trees live at the project root, written for different readers:
 
-**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.
+| Tree | For | Written by |
+|:-----|:----|:-----------|
+| `framework-skills/` | The agent developing this server — framework skills (`metadata.audience: external`) plus any development-time skills of the server's own | `init` and the `maintenance` sync (framework skills); you (your own) |
+| `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | You, deliberately, with the `add-skill` skill. Absent by default; usually none is needed |
+
+Development skills are modular instructions. 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. Their 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 them to every agent that installs it.
+
+A published skill in root `skills/` reaches plugin installs and the `.mcpb` bundle as-is, ships in the npm package and the Docker image, and reaches MCP clients when the server opts in with `createApp({ skills: 'skills' })`. `lint:packaging` validates the tree.
+
+**Agent skill directory:** Copy `framework-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:
 
@@ -254,6 +268,7 @@ Available skills:
 | `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-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |
 | `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 |
@@ -320,7 +335,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ## 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.
+`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. `mcpb pack` reads `.mcpbignore`, not `.gitignore`, so every root path the bundle must not ship — source, tests, docs, caches, logs, agent docs, plugin manifests, gitignored and local-only files such as `claude-plans/` — needs a root-anchored line there (`/docs/`, never `docs/`, which also strips `node_modules/*/docs/`); `lint:packaging` names each missing or unanchored line. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips four classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/` at a package's root, and any `SKILL.md`); platform-specific native bindings; node-gyp build output beside a `binding.gyp`; and the framework's build-only files. The agent-doc selector is anchored at each package root in both `clean-mcpb.ts` and `lint-packaging.ts` — a local divergence from the synced scripts until cyanheads/mcp-ts-core#794 ships — because MCP SDK 2.4 ships runtime code at `@modelcontextprotocol/{server,core}/dist/ext/skills/`, and the upstream selector strips it and breaks the bundle's startup. Re-apply it after a script resync; `tests/scripts/bundle-agent-docs.test.ts` fails if it is lost. MCPB is stdio-only — HTTP deployments are unaffected.
 
 **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": ""`.
 
@@ -378,6 +393,7 @@ import { getHnService } from '@/services/hn/hn-service.js';
 bun publish --access public
 
 docker buildx build --platform linux/amd64,linux/arm64 \
+  --build-arg APP_VERSION=<version> \
   -t ghcr.io/cyanheads/hn-mcp-server:<version> \
   -t ghcr.io/cyanheads/hn-mcp-server:latest \
   --push .

package/CLAUDE.md

@@ -1,11 +1,11 @@
 # Developer Protocol
 
 **Server:** hn-mcp-server
-**Version:** 0.5.21
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.12`
+**Version:** 0.6.0
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
-**MCP SDK:** `@modelcontextprotocol/server` 2.2.0
-**Zod:** ^4.6.5
+**MCP SDK:** `@modelcontextprotocol/server` 2.4.0
+**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.
 
@@ -48,7 +48,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 
 ```ts
 import { tool, z } from '@cyanheads/mcp-ts-core';
-import { getHnService, settlePage, normalizeUrl, stripHtml } from '@/services/hn/hn-service.js';
+import { CALL_BUDGET_MS, getHnService, settlePage, normalizeUrl, stripHtml } from '@/services/hn/hn-service.js';
 
 export const getStories = tool('hn_get_stories', {
   description: 'Fetch stories from an HN feed (top, new, best, ask, show, jobs).',
@@ -70,10 +70,12 @@ export const getStories = tool('hn_get_stories', {
 
   async handler(input, ctx) {
     const hn = getHnService();
-    const feedIds = await hn.fetchFeed(input.feed, ctx);
+    // One time budget for the feed and every item fetch after it.
+    const deadline = Date.now() + CALL_BUDGET_MS;
+    const feedIds = await hn.fetchFeed(input.feed, ctx, deadline);
     const sliced = feedIds.slice(input.offset, input.offset + input.count);
     // Live items plus the IDs whose fetch failed; throws when every item failed.
-    const { items, failedIds } = settlePage(await hn.fetchItems(sliced, ctx));
+    const { items, failedIds } = settlePage(await hn.fetchItems(sliced, ctx, deadline));
     if (failedIds.length > 0) ctx.enrich({ failedIds });
     ctx.log.info('Fetched stories', { feed: input.feed, count: items.length });
     return { stories: items.map(/* ... */), feed: input.feed, total: feedIds.length };
@@ -218,6 +220,9 @@ src/
       types.ts                          # HN domain types
   mcp-server/
     tools/markdown-escape.ts           # format() boundary: escape titles, quote bodies
+    tools/response-budget.ts           # 64,000-byte budget per response surface: measure both surfaces, largest shared body cut, code-point cut
+    tools/served-at-cap.ts             # notice sentence for a size input served at its per-call cap
+    tools/thread-cursor.ts             # hn_get_thread cursor codec: packed frontier, JSON format still decoded
     tools/definitions/
       get-stories.tool.ts              # hn_get_stories — Fetch stories from an HN feed
       get-thread.tool.ts               # hn_get_thread — Get item + comment tree
@@ -240,9 +245,18 @@ src/
 
 ## 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.
+Two skill trees live at the project root, written for different readers:
 
-**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.
+| Tree | For | Written by |
+|:-----|:----|:-----------|
+| `framework-skills/` | The agent developing this server — framework skills (`metadata.audience: external`) plus any development-time skills of the server's own | `init` and the `maintenance` sync (framework skills); you (your own) |
+| `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | You, deliberately, with the `add-skill` skill. Absent by default; usually none is needed |
+
+Development skills are modular instructions. 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. Their 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 them to every agent that installs it.
+
+A published skill in root `skills/` reaches plugin installs and the `.mcpb` bundle as-is, ships in the npm package and the Docker image, and reaches MCP clients when the server opts in with `createApp({ skills: 'skills' })`. `lint:packaging` validates the tree.
+
+**Agent skill directory:** Copy `framework-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:
 
@@ -254,6 +268,7 @@ Available skills:
 | `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-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |
 | `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 |
@@ -320,7 +335,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ## 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.
+`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. `mcpb pack` reads `.mcpbignore`, not `.gitignore`, so every root path the bundle must not ship — source, tests, docs, caches, logs, agent docs, plugin manifests, gitignored and local-only files such as `claude-plans/` — needs a root-anchored line there (`/docs/`, never `docs/`, which also strips `node_modules/*/docs/`); `lint:packaging` names each missing or unanchored line. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips four classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/` at a package's root, and any `SKILL.md`); platform-specific native bindings; node-gyp build output beside a `binding.gyp`; and the framework's build-only files. The agent-doc selector is anchored at each package root in both `clean-mcpb.ts` and `lint-packaging.ts` — a local divergence from the synced scripts until cyanheads/mcp-ts-core#794 ships — because MCP SDK 2.4 ships runtime code at `@modelcontextprotocol/{server,core}/dist/ext/skills/`, and the upstream selector strips it and breaks the bundle's startup. Re-apply it after a script resync; `tests/scripts/bundle-agent-docs.test.ts` fails if it is lost. MCPB is stdio-only — HTTP deployments are unaffected.
 
 **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": ""`.
 
@@ -378,6 +393,7 @@ import { getHnService } from '@/services/hn/hn-service.js';
 bun publish --access public
 
 docker buildx build --platform linux/amd64,linux/arm64 \
+  --build-arg APP_VERSION=<version> \
   -t ghcr.io/cyanheads/hn-mcp-server:<version> \
   -t ghcr.io/cyanheads/hn-mcp-server:latest \
   --push .

package/Dockerfile

@@ -14,7 +14,7 @@
 # output. A stage that compiles a native addon needs the target-arch toolchain
 # and cannot cross-compile this way — drop the flag there.
 # ==============================================================================
-FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS build
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS build
 
 WORKDIR /usr/src/app
 
@@ -29,6 +29,11 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
 # Copy the rest of the source code
 COPY . .
 
+# The skills a server publishes (`createApp({ skills: 'skills' })`) are read at
+# runtime from the application root. Created when the project has none, so the
+# production stage's copy below holds with or without one.
+RUN mkdir -p skills
+
 # Build the application
 RUN bun run build
 
@@ -46,7 +51,7 @@ RUN bun run build
 # A clean image rather than `FROM build`: the build stage's node_modules holds
 # devDependencies.
 # ==============================================================================
-FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS deps
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS deps
 
 WORKDIR /usr/src/app
 
@@ -114,7 +119,7 @@ RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
 # dependencies and build artifacts. Its only Bun invocations are HEALTHCHECK
 # and CMD, which run on the real target at container start.
 # ==============================================================================
-FROM oven/bun:1.4.2-slim AS production
+FROM oven/bun:1.4.4-slim AS production
 
 WORKDIR /usr/src/app
 
@@ -124,7 +129,7 @@ ENV NODE_ENV=production
 # OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
 ARG APP_VERSION
 LABEL org.opencontainers.image.title="hn-mcp-server"
-LABEL org.opencontainers.image.description="MCP server for Hacker News — feeds, threads, users, and search via Firebase and Algolia APIs"
+LABEL org.opencontainers.image.description="MCP server for Hacker News: feeds, threads, users, and search via Firebase and Algolia APIs"
 LABEL org.opencontainers.image.source="https://github.com/cyanheads/hn-mcp-server"
 LABEL org.opencontainers.image.licenses="Apache-2.0"
 LABEL org.opencontainers.image.version="${APP_VERSION}"
@@ -136,6 +141,7 @@ COPY --from=deps /usr/src/app/node_modules ./node_modules
 
 # Copy the compiled application code from the build stage
 COPY --from=build /usr/src/app/dist ./dist
+COPY --from=build /usr/src/app/skills ./skills
 
 # The 'oven/bun' image already provides a non-root user named 'bun'.
 # We will use this existing user for enhanced security.

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.5.21-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/hn-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-2.2.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/hn-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/hn-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->=1.4.0-f9f1e1.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.6.0-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/hn-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-2.4.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/hn-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/hn-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->=1.4.0-f9f1e1.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -29,7 +29,7 @@
 
 ## Overview
 
-Feeds, threads, and profiles from the Hacker News Firebase API and Algolia Search API. Browse ranked feeds, read full comment threads, look up user profiles, and search stories, comments, polls, and jobs by keyword or by type, author, parent story, date, or score. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
+Hacker News feeds, threads, and profiles. Browse ranked feeds, read full comment threads, look up users, and search stories, comments, polls, and jobs by keyword, author, date, or score.
 
 ### Tools
 
@@ -40,48 +40,60 @@ Feeds, threads, and profiles from the Hacker News Firebase API and Algolia Searc
 | `hn_get_user` | Fetch a user profile with karma, about, and optionally a page of resolved submissions |
 | `hn_search_content` | Search stories, comments, polls, and jobs via Algolia by keyword, by filters alone, or both — type, author, parent story, date range, and minimum points |
 
+### Agent skill
+
+| Skill | Description |
+|:---|:---|
+| [`hn-guide`](skills/hn-guide/SKILL.md) | How to find a link's thread, search without Algolia's fuzzy matches, read large comment trees in full, and search what one user said. Served over MCP as `skill://hn-guide/SKILL.md` and shipped in the npm package |
+
 ## Capability reference
 
 ### `hn_get_stories` <sub>tool</sub>
 
-- Six feed types: `top`, `new`, `best`, `ask`, `show`, `jobs`; `count` (1–100, default 30) and `offset` for pagination
+- Six feed types: `top`, `new`, `best`, `ask`, `show`, `jobs`; `count` (default 30) and `offset` for pagination. One call serves at most 100 stories; a `count` up to 1,000 is served at 100, with a `notice` naming the next `offset`
 - Returns id, type, title, url, domain, score, author, timestamp, comment count, and body text — each field omitted (not null) when HN doesn't provide it
 - Enrichment reports `total`, `offset`, and `hasMore`; while more stories remain, `truncated` is set and `notice` names the next `offset`, and a `notice` explains empty pages (empty feed, offset past end, or every item on the page deleted/flagged). The last page carries no truncation
-- Items whose fetch failed after retries are listed in `failedIds` with a `notice` naming the retry; a page where every item failed returns the classified upstream error instead of an empty list
+- Items whose fetch failed after retries, or ran past the call's 50-second time budget, are listed in `failedIds` with a `notice` naming the retry; a page where every item failed returns the classified upstream error instead of an empty list
 
 ---
 
 ### `hn_get_thread` <sub>tool</sub>
 
-- `itemId` plus `depth` (0–10, default 3; 0 returns the item with no comments) and `maxComments` (1–200, default 50) capping one response across all levels, alongside a fixed 64,000-byte text budget that cuts only between comments
+- `itemId` plus `depth` (default 3; 0 returns the item with no comments) and `maxComments` (default 50) capping one response across all levels, alongside a fixed 64,000-byte budget on each response surface (all `content[]` text, `nextCursor` included, and the `structuredContent` JSON) that cuts only between comments and always returns a page's first comment whole. One call resolves at most 10 levels and 200 comments; a `depth` up to 100 is served at 10 and a `maxComments` up to 1,000 at 200, with a `notice` naming the comment to pass as `itemId` or the `nextCursor` that reaches the rest
 - Breadth-first traversal ranked like HN — top-ranked top-level comments resolve first, replies fill in only after the level above is exhausted
-- Resumable: a response stopped by `maxComments`, the byte budget, or an upstream rate limit returns `nextCursor`; passing it back as `cursor` with the same `itemId` continues at the next unseen comment. The cursor carries the unvisited comments themselves, so re-ranked replies cannot shift it, and the server keeps no session state. A cursor passed with a different `itemId` fails with `invalid_cursor`
-- The root carries its relationships and state: `parent` for a comment, `poll` for a poll option, `parts` and resolved `options` (text and votes, at every depth) for a poll, and `deleted`/`dead` markers. The `content[]` heading names the type — a title, `Comment by <author>`, `Poll option by <author> on poll <id>` — and marks a deleted or dead root
-- Flat comment list carries `depth`/`parentId` for tree reconstruction, plus `childCount` and an `isOp` flag when the comment author matches the root item's author
-- `truncated` and `truncationReason` (`count`, `size`, `rate_limited`, or `depth` when replies lie below the depth limit) are set only while comments remain unread — never on a terminal page, including a thread that loads in full at exactly the cap. `notice` reports deleted/dead comments omitted during traversal and the next step: the cursor, or a larger `depth` or a comment id as `itemId`
-- Comments and poll options whose fetch failed after retries are listed in `failedIds`, and `notice` names them with the retry; failed comments ride in `nextCursor`, so paging on retries them rather than skipping them. The root item is still returned, and a failure is never passed off as a `maxComments`/`depth` limit
+- Resumable: a response stopped by `maxComments`, the byte budget, an upstream rate limit, or the call's 50-second time budget returns `nextCursor`; passing it back as `cursor` with the same `itemId` continues at the next unseen comment. The cursor carries the unvisited comments themselves, so re-ranked replies cannot shift it, and the server keeps no session state. A cursor the tool did not issue, an altered one, or one passed with a different `itemId` fails with `invalid_cursor`
+- The root carries its relationships and state: `parent` and `storyId` (the story or poll the discussion belongs to) for a comment, `poll` for a poll option, `parts` and resolved `options` (text and votes, at every depth) for a poll, and `deleted`/`dead` markers. The `content[]` heading names the type — a title, `Comment by <author>`, `Poll option by <author> on poll <id>` — and marks a deleted or dead root
+- Flat comment list carries `depth`/`parentId` for tree reconstruction, plus `childCount` and an `isOp` flag when the comment author submitted the thread's story — on a comment root, the story at `storyId`, never the comment's own author. Dead and deleted comments are left out, but their live replies are still returned at their true `depth`, with `parentId` naming the omitted comment
+- `truncated` and `truncationReason` (`count`, `size`, `rate_limited`, `time`, or `depth` when replies lie below the depth limit) are set only while comments remain unread — never on a terminal page, including a thread that loads in full at exactly the cap. `notice` reports deleted/dead comments omitted during traversal and the next step: the cursor, or a larger `depth` or a comment id as `itemId`, naming by ID any omitted comment whose replies the depth limit cut
+- Comments and poll options whose fetch failed after retries or ran past the call's time budget are listed in `failedIds`, and `notice` names them with the retry; failed comments ride in `nextCursor`, so paging on retries them rather than skipping them. The root item is still returned, and a failure is never passed off as a `maxComments`/`depth` limit
 
 ---
 
 ### `hn_get_user` <sub>tool</sub>
 
-- `username` is case-sensitive and trimmed; `includeSubmissions` (default false) resolves recent submissions, with `submissionCount` (1–50, default 10) and `submissionOffset` paging through a long history
+- `username` is case-sensitive and trimmed; `includeSubmissions` (default false) resolves recent submissions, with `submissionCount` (default 10) and `submissionOffset` paging through a long history. One call resolves at most 50 submissions; a `submissionCount` up to 1,000 is served at 50, with a `notice` naming the next `submissionOffset`
 - Profile includes karma, creation date, and about text (HTML stripped); submissions filter out dead/deleted items
 - A comment submission carries its `parent` and a poll-option submission its `poll`, so either links back to what it answered
 - Enrichment echoes `submissionOffset` and the offset to send next, or a notice when the requested offset is past the end of the history
-- Submissions whose fetch failed after retries are listed in `failedIds` with a `notice` naming the retry; a window where every submission failed returns the classified upstream error
+- Submissions whose fetch failed after retries, or that the call's 50-second time budget cut, are listed in `failedIds` with a `notice` naming the retry (and the budget, when it cut them); a window where every submission failed returns the classified upstream error — `Timeout` when the budget cut them all
+- Each response surface is held to a fixed 64,000-byte budget: an over-budget page keeps every submission and cuts the longest bodies to one shared length, flagging each with `textTruncated` and pointing to `hn_get_thread` for the whole text
 
 ---
 
 ### `hn_search_content` <sub>tool</sub>
 
-- Free-text `query` plus `tags` (`story`/`comment`/`poll`/`job`/`ask_hn`/`show_hn`/`front_page`), `author`, `storyId`, `dateRange`, and `minPoints` filters; `sort` by relevance or date; `count` (1–50, default 30) and `page` for pagination
+- Free-text `query` — typo-tolerant, with the last term also matching as a prefix; wrap a term in double quotes to match it exactly and put `-` before one to exclude it — plus `tags` (`story`/`comment`/`poll`/`job`/`ask_hn`/`show_hn`/`front_page`), `author` (the exact, case-sensitive username), `storyId`, `dateRange`, and `minPoints` filters; `sort` by relevance or date; `count` (default 30) and `page` for pagination. One call serves at most 50 hits; a `count` up to 1,000 is served as the page of 50 starting at the requested page's first hit, with a `notice` naming the `count: 50` page to pass next; a non-zero `page` whose first hit begins no page of 50 fails with `count_page_unaligned`, naming a `count` and `page` that start there and, when that count is under 25, the page of 50 that holds that hit
+- `tags: "front_page"` is the front page right now (about 30 stories), never past front pages; for an earlier window, use `tags: "story"` with `dateRange` and `minPoints`
 - `query` is optional when a filter is set — list Ask HN, Show HN, polls, or jobs on their own, or pass a story's `storyId` with `tags: "comment"` to search within one thread. No query and no filter fails with `missing_query_or_filter`
+- To check whether a page was discussed, pass its URL alone as `query`: the leading `http://`, `https://`, or `www.` is dropped before searching, so submissions under either scheme, with or without `www.`, all match. The output `query` and the notice show what was searched
 - `dateRange` bounds take ISO 8601 (`YYYY`, `YYYY-MM`, `YYYY-MM-DD`, or a date-time with optional offset), read as UTC and both exclusive; an empty or out-of-order range fails with `invalid_date_range`
 - `minPoints` applies to stories and polls — comments and jobs carry no points, so pairing it with `tags: "comment"` or `"job"` fails with `min_points_unscored_type`
-- `view: "compact"` drops the two body-text fields (`text`, `highlights.text`), which otherwise repeat a long comment twice per hit — pass a hit id to `hn_get_thread` to read the body
-- Highlight metadata (`highlights.title`, `highlights.text`, `matchedWords`) shows which terms matched and where
-- Enrichment reports `totalHits`, `page`, and the actual reachable `totalPages` — not derived from `totalHits`, since broad queries report far more hits than Algolia will serve. While more pages remain, `truncated` is set and `notice` names the next `page`; a page past the end gets a notice naming the last valid page (or `page: 0` past Algolia's 1,000-hit ceiling)
+- `view: "compact"` drops the two body-text fields (`text`, `highlights.text`), which otherwise repeat a long comment twice per hit — pass a hit id to `hn_get_thread` to read the body. In `full`, a page over 64,000 bytes per response surface drops `highlights.text` from every hit (`highlightsTextOmitted`), then cuts the longest bodies to one shared length (`textTruncated`, with an `hn_get_thread` pointer) — every hit stays
+- Each hit carries its `type` (`story`, `comment`, `poll`, `pollopt`, `job`) when Algolia records one. Untagged searches also return poll options, which carry only an id, author, vote count, and date — `hn_get_thread` reads an option's text and poll. A poll hit has no `storyId`; its own `id` is the discussion root
+- Job descriptions come back as `text`, though keywords don't search them
+- Highlight metadata (`highlights.title`, `highlights.text`, `matchedWords`) shows which terms matched and where; `highlights.text` is the matched body in full with `<em>` markers
+- Enrichment echoes the applied `criteria` — each filter set (`author` trimmed, `dateRange` as the exclusive UTC bounds applied, to the second), plus `sort`, `count`, and `view` with defaults filled — so a saved result says what it answers
+- Enrichment reports `totalHits`, `page`, and the actual reachable `totalPages` — not derived from `totalHits`, since broad queries report far more hits than Algolia will serve. `totalHitsExact: false` marks `totalHits` as an estimate, and `reachableHits: 1000` marks a search that matches more than Algolia's 1,000-hit ceiling; the last page of such a search gets a notice naming the ceiling and narrower `dateRange` windows to reach the rest. While more pages remain, `truncated` is set and `notice` names the next `page`; a page past the end gets a notice naming the last valid page (or `page: 0` past the ceiling)
 
 ## Features
 
@@ -97,10 +109,10 @@ HN-specific:
 
 Agent-friendly output:
 
-- Graceful partial failure — an item whose fetch fails after retries is reported by ID in `failedIds`, apart from deleted, dead, or nonexistent items, rather than silently shrinking the result; `hn_get_thread` also counts the deleted and dead comments it drops, and a rate-limited item stops the batch instead of sending every remaining item through its own retry ladder
+- Graceful partial failure — an item whose fetch fails after retries is reported by ID in `failedIds`, apart from deleted, dead, or nonexistent items, rather than silently shrinking the result; each `hn_get_thread`, `hn_get_stories`, and `hn_get_user` call runs under one 50-second time budget, so hung fetches cannot hold it past an MCP client's 60-second timeout; `hn_get_thread` also counts the deleted and dead comments it drops, and a rate-limited item stops the batch instead of sending every remaining item through its own retry ladder
 - Discriminated output contracts — typed error reasons (`item_not_found`, `upstream_rate_limited`, `upstream_html`, …) with per-reason recovery text (a rate limit passes on the upstream's `Retry-After` as `retryAfter`), and a `depth`/`parentId` pair on every comment so callers reconstruct the tree without guessing nesting
-- Pagination provenance — every paged listing echoes the offset it used (`offset`, `submissionOffset`, `page`) plus the exact next-offset value in `notice`, and `hn_get_thread` returns a self-contained `nextCursor`, so an agent can resume without recomputing state
-- Response shaping — HTML stripping, URL normalization, and domain extraction remove upstream markup noise; `hn_search_content`'s `view: "compact"` drops the two body-text fields that otherwise duplicate a hit's full text
+- Pagination provenance — every paged listing echoes the offset it used (`offset`, `submissionOffset`, `page`) plus the exact next-offset value in `notice`, `hn_search_content` also echoes the `criteria` it searched with, and `hn_get_thread` returns a self-contained `nextCursor`, so an agent can resume without recomputing state
+- Response shaping — HTML stripping, URL normalization, and domain extraction remove upstream markup noise; `hn_search_content`'s `view: "compact"` drops the two body-text fields that otherwise duplicate a hit's full text, and a 64,000-byte budget on each response surface cuts the longest bodies of an over-budget page
 - Fenced upstream text — in `content[]`, every line of a body is block-quoted and titles are escaped only where they could break the surrounding Markdown, so a comment cannot pass for a server-authored line
 
 ## Getting started

package/changelog/0.5.x/0.5.22.md

@@ -0,0 +1,45 @@
+---
+summary: "hn_get_thread returns live replies below dead and deleted comments, marks OP against the story's author on comment roots, and issues packed cursors; hn_search_content discloses estimated totals, echoes its criteria, and types its hits; an over-cap count is served at the cap."
+breaking: false
+security: false
+---
+
+# 0.5.22 — 2026-10-18
+
+## Changed
+
+- **`hn_get_thread` adds `item.storyId`**: a comment root names the story or poll its discussion belongs to, rendered as `story:<id>` in `content[]`. Absent when the story could not be found; `notice` says why. (#42)
+- **`hn_search_content` adds `criteria`**: the applied filters plus `sort`, `count`, and `view` with defaults filled, `author` trimmed and `dateRange` as the exclusive UTC bounds sent, echoed in `structuredContent` and as a `**criteria:**` line in `content[]`. (#35)
+- **`hn_search_content` adds `totalHitsExact` and `reachableHits`**: `totalHitsExact: false` marks `totalHits` as an estimate, and `reachableHits: 1000` marks a search matching more than Algolia serves; the last reachable page's `notice` names the ceiling and narrower `dateRange` windows. (#34)
+- **`hn_search_content` hits carry `type`**: `story`, `comment`, `poll`, `pollopt`, or `job`, when Algolia records one. A poll option renders as `Poll option by <author>` pointing to `hn_get_thread`. (#41)
+- **Over-cap inputs are served at the cap instead of rejected**: `hn_get_stories` `count` up to 1,000 at 100, `hn_get_user` `submissionCount` up to 1,000 at 50, `hn_get_thread` `depth` up to 100 at 10 and `maxComments` up to 1,000 at 200, `hn_search_content` `count` up to 1,000 at 50. `cap` reports the value served and `notice` names the lever for the rest. Values above those ceilings are still rejected. (#45)
+- **`hn_search_content` serves an over-cap `count` from the requested page's first hit**: the search runs as page `page × count / 50` at 50, and `page`, `totalPages`, and `criteria.count` describe that page of 50. (#45)
+- **`hn_search_content` adds the error reason `count_page_unaligned`**: a `count` above 50 with a non-zero `page` whose first hit begins no page of 50 fails with it, naming a `count` and `page` that start at that hit. (#45)
+- **`hn_get_thread` `nextCursor` is packed**: a base64url varint encoding that also carries the resolved story. Cursors issued by earlier releases still resume, and a cursor longer than 150,000 characters is rejected as `invalid_cursor`. (#43)
+- **`hn_get_thread` rejects a cursor it did not issue** with the declared `invalid_cursor` reason, so the rejection logs at `notice` with the reason attached. (#36)
+- **`hn_search_content` drops a leading `http://`, `https://`, or `www.` from a query that is a URL alone**, so submissions under either scheme, with or without `www.`, match. The output `query` and `notice` show what was searched. (#38)
+- **`hn_search_content` job descriptions** (`job_text`) are returned as `text`; they are not keyword-searched or highlighted. (#41)
+- **`hn_search_content` names the `author` casing rule** when an author-filtered first page is empty: `author` is an exact, case-sensitive match. (#39)
+- **`hn_search_content` scopes `tags: "front_page"`** in the `notice` on an empty first page or whenever `dateRange` is set: it is the current front page only, with `tags: "story"` plus `dateRange` and `minPoints` as the alternative. (#40)
+- **`hn_search_content` escapes the query** in the `content[]` heading and no-results line. (#35)
+- **Framework sync**: `framework-skills/` synced to 0.13.15, `.env.example` lists `LOG_LLM_INTERACTIONS`, and the `check-framework-antipatterns.ts` patterns use POSIX space classes.
+- **Tests**: worst-case timing checks measure the test thread's CPU time instead of wall clock. (#44)
+
+## Fixed
+
+- **`hn_get_thread` returns live replies below dead and deleted comments** at their true `depth`, with `parentId` naming the omitted comment. The comment stays out of `comments[]` and in the notice's counts; where the depth limit cuts its replies, `notice` names it by ID to pass as `itemId`. (#33)
+- **`descendants` and `totalAvailable` are described as live-comment counts** in `hn_get_stories`, `hn_get_user`, and `hn_get_thread`. (#33)
+- **`isOp` on a comment root marks replies by the story's author**, where it marked the root comment's author. The lookup follows at most 64 parent links and ends 20 seconds after the call starts. (#42)
+- **A caller abort during a retry's backoff ends a `fetchItems` batch** instead of recording a failed slot. (#42)
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.12 → ^0.13.15 (0.13.13: error envelopes drop `data.rootCause` and filesystem storage errors name the key, not the storage root; 0.13.14: tool-argument pre-validation repairs numeric and boolean strings, lone strings for arrays, and null optionals; 0.13.15: DuckDB canvases run with external access off and ZodError `data.issues` is bounded)
+- `@modelcontextprotocol/server` 2.2.0 → 2.3.1 (transitive)
+- `pino-pretty` ^13.1.3 → ^13.2.0
+- `zod` ^4.6.5 → ^4.6.7
+- Dev: `@types/node` ^26.6.4 → ^26.6.5
+- Dev: `@vitest/coverage-istanbul` ^5.0.3 → ^5.0.5
+- Dev: `ignore` ^7.0.11 → ^7.0.12
+- Dev: `vitest` ^5.0.3 → ^5.0.5
+- `packageManager` bun@1.4.2 → bun@1.4.3; Docker base images `oven/bun` 1.4.2 → 1.4.3

package/changelog/0.6.x/0.6.0.md

@@ -0,0 +1,38 @@
+---
+summary: "hn_search_content, hn_get_user, and hn_get_thread hold each response surface to 64,000 bytes; hn_get_thread, hn_get_stories, and hn_get_user run under one 50-second time budget; the hn-guide agent skill is served as a skill:// resource."
+breaking: false
+security: false
+---
+
+# 0.6.0 — 2026-10-28
+
+## Added
+
+- **Published `hn-guide` Agent Skill**: `resources/list` now lists `skill://hn-guide/SKILL.md` and `resources/templates/list` lists the `skill://{+path}` template, served through mcp-ts-core 0.13.18's `createApp({ skills })`. The skill also ships in the npm package and the Docker image.
+- **Root `plugin.json` and `mcp.json`**: the Agent Plugins 1.0.0 manifest pair, alongside the Claude and Codex plugin overlays.
+
+## Changed
+
+- **`hn_search_content` `query` description** documents typo tolerance, prefix matching on the last term, `"quoted"` exact terms, and `-` exclusion. `highlights.text` is described as the matched body in full, not a snippet.
+- **Framework rendering in `content[]`** (mcp-ts-core 0.13.16–0.13.18): error text and trailer text gain Markdown escapes, every line of a `notice` is block-quoted, and string trailer values such as `nextCursor` and `truncationReason` render as code spans. `structuredContent` is unchanged.
+- **`.mcpb` bundle** leaves out repo-local root paths and build-only package files; the agent-doc strip is anchored at each package root so MCP SDK 2.4's `dist/ext/skills/` stays in the bundle.
+- **Framework sync**: `framework-skills/` synced to 0.13.18 (adds `add-skill`), `scripts/` and `.github/ISSUE_TEMPLATE/bug_report.yml` resynced, and `bunfig.toml` `minimumReleaseAge` is 1 day (was 3).
+
+## Fixed
+
+- **`hn_search_content` holds the `full` view to 64,000 bytes** on all of `content[]` and on `structuredContent`, each. An over-budget page drops `highlights.text` from every hit (`highlightsTextOmitted: true`), then cuts the longest `text` bodies to one shared limit (`textTruncated: true`, with an `hn_get_thread` pointer in `content[]`). Every hit stays, and `notice` names the budget and the cut ids. (#46)
+- **`hn_get_user` holds a submissions page to the same 64,000 bytes per surface**: the longest submission bodies are cut to one shared limit and flagged `textTruncated`, every submission stays, and `user.about` is never cut. (#49)
+- **`hn_get_thread` counts the whole response against its `size` stop**: `content[]` text with the trailer and `nextCursor`, and the `structuredContent` JSON, are each held to 64,000 bytes. A page's first comment is still returned whole. (#50)
+- **`hn_get_thread`, `hn_get_stories`, and `hn_get_user` run under one 50-second time budget** counted from the call's start. A fetch the budget cuts or leaves unstarted is listed in `failedIds` and `notice` names the budget; `hn_get_thread` stops with `truncationReason: "time"` and a `nextCursor`, and a stories or user call where the budget cuts every fetch fails with `Timeout`. (#47)
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.15 → ^0.13.18 (0.13.16: Markdown-escaped error and trailer text; 0.13.17: `@modelcontextprotocol/server` 2.4; 0.13.18: `createApp({ skills })`, code-span trailer values)
+- `@modelcontextprotocol/server` 2.3.1 → 2.4.0 (via the framework)
+- `@modelcontextprotocol/core` 2.3.1 → 2.4.0 (transitive)
+- `@opentelemetry/api` 1.9.1 → 1.10.0 (transitive)
+- `jose` 6.2.12 → 6.2.13 (transitive)
+- Dev: `@biomejs/biome` ^2.5.15 → ^2.6.3
+- Dev: `ignore` ^7.0.12 → ^7.0.14
+- Dev: `tsc-alias` ^1.9.7 → ^1.9.9
+- `packageManager` bun@1.4.3 → bun@1.4.4; Docker base images `oven/bun` 1.4.3 → 1.4.4

package/dist/index.js

@@ -16,6 +16,7 @@ await createApp({
     instructions: 'Use the hn_* tools to access Hacker News via the Firebase API and Algolia search: ranked feeds; search by keyword, by type/author/story/date/score filters alone, or both; user profiles; and items with their comment trees. Items are addressed by integer ID, reused across tools and item types (story, comment, job, poll, pollopt); passing a comment id to hn_get_thread drills into that subtree. Usernames are case-sensitive; HN sparsely populates fields, so treat absent values as unknown.',
     landing: { requireAuth: false },
     sessionMode: 'stateless',
+    skills: 'skills',
     setup() {
         initHnService();
     },

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,oDAAoD,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,MAAM,mDAAmD,CAAC;AAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,iDAAiD,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,MAAM,uDAAuD,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,eAAe;IACrB,KAAK,EAAE,eAAe;IACtB,KAAK,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC;IACjD,YAAY,EACV,0eAA0e;IAC5e,OAAO,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE;IAC/B,WAAW,EAAE,WAAW;IACxB,KAAK;QACH,aAAa,EAAE,CAAC;IAClB,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,oDAAoD,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,MAAM,mDAAmD,CAAC;AAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,iDAAiD,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,MAAM,uDAAuD,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,eAAe;IACrB,KAAK,EAAE,eAAe;IACtB,KAAK,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC;IACjD,YAAY,EACV,0eAA0e;IAC5e,OAAO,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE;IAC/B,WAAW,EAAE,WAAW;IACxB,MAAM,EAAE,QAAQ;IAChB,KAAK;QACH,aAAa,EAAE,CAAC;IAClB,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/get-stories.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-stories.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-stories.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAcjE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8PrB,CAAC"}
+{"version":3,"file":"get-stories.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-stories.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAoBjE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+QrB,CAAC"}

package/dist/mcp-server/tools/definitions/get-stories.tool.js

@@ -5,9 +5,12 @@
 import { tool, z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { escapeInline, quoteBody } from '../markdown-escape.js';
-import { decodeHtmlEntities, extractDomain, getHnService, normalizeUrl, settlePage, stripHtml, } from '../../../services/hn/hn-service.js';
-/** Largest page `count` accepts, mirrored in the input schema. */
-const MAX_COUNT = 100;
+import { servedAtCap } from '../served-at-cap.js';
+import { CALL_BUDGET_MS, decodeHtmlEntities, extractDomain, getHnService, normalizeUrl, settlePage, stripHtml, timeBudgetCutSentence, } from '../../../services/hn/hn-service.js';
+/** Most stories one call serves; a larger `count` is served at this cap. */
+const COUNT_CAP = 100;
+/** Largest `count` accepted; anything above it is rejected. */
+const COUNT_CEILING = 1000;
 export const getStories = tool('hn_get_stories', {
     description: 'Fetch stories from an HN feed (top, new, best, ask, show, jobs), with title, URL, score, author, and comment count for each story.',
     annotations: { readOnlyHint: true },
@@ -60,9 +63,9 @@ export const getStories = tool('hn_get_stories', {
             .number()
             .int()
             .min(1)
-            .max(MAX_COUNT)
+            .max(COUNT_CEILING)
             .default(30)
-            .describe('Number of stories to return. Larger counts take longer.'),
+            .describe(`Number of stories to return, at most ${COUNT_CAP} per call. A larger value is served at ${COUNT_CAP}, and the notice names the offset for the next page. Larger counts take longer.`),
         offset: z
             .number()
             .int()
@@ -100,7 +103,10 @@ export const getStories = tool('hn_get_stories', {
                 .number()
                 .optional()
                 .describe('Unix timestamp when provided by HN. Omitted when unknown.'),
-            descendants: z.number().optional().describe('Total comment count. Absent for jobs.'),
+            descendants: z
+                .number()
+                .optional()
+                .describe("HN's count of live comments in the thread (descendants); dead and deleted comments are not counted. Absent for jobs."),
             text: z
                 .string()
                 .optional()
@@ -121,24 +127,31 @@ export const getStories = tool('hn_get_stories', {
             .optional()
             .describe('True when more stories remain beyond this page (hasMore). Absent on the last page of the feed.'),
         shown: z.number().optional().describe('Number of stories returned on this page.'),
-        cap: z.number().optional().describe('The count cap that was applied.'),
+        cap: z
+            .number()
+            .optional()
+            .describe(`The count value served: as passed, or ${COUNT_CAP} when count was above that cap.`),
         failedIds: z
             .array(z.number())
             .optional()
-            .describe('IDs on this page whose fetch failed after retries. They are not deleted or missing and may load on a later call: retry the page with the same offset, or pass an ID to hn_get_thread to fetch that story alone. Absent when every item on the page loaded.'),
+            .describe(`IDs on this page whose fetch failed after retries or ran past the call's ${CALL_BUDGET_MS / 1000}-second time budget. They are not deleted or missing and may load on a later call: retry the page with the same offset, or pass an ID to hn_get_thread to fetch that story alone. Absent when every item on the page loaded.`),
         notice: z
             .string()
             .optional()
-            .describe('Agent guidance: the offset to pass for the next page while more stories remain, the IDs that failed to load and how to retry them, or why a page came back empty — offset past the end of the feed, an empty feed, or every item on the page deleted or flagged. Absent on the last page of a non-empty result with no failed IDs.'),
+            .describe(`Agent guidance: the offset to pass for the next page while more stories remain, the IDs that failed to load and how to retry them (naming the call's ${CALL_BUDGET_MS / 1000}-second time budget when it cut them), or why a page came back empty — offset past the end of the feed, an empty feed, or every item on the page deleted or flagged — noting when count was served at its per-call cap. Absent on the last page of a non-empty result with no failed IDs.`),
     },
     enrichmentTrailer: {
         failedIds: { render: (ids) => `**Failed to load:** ${(ids ?? []).join(', ')}` },
     },
     async handler(input, ctx) {
         const hn = getHnService();
-        const feedIds = await hn.fetchFeed(input.feed, ctx);
-        const sliced = feedIds.slice(input.offset, input.offset + input.count);
-        const { items, failedIds } = settlePage(await hn.fetchItems(sliced, ctx));
+        /** One budget for the feed and every item fetch after it. */
+        const deadline = Date.now() + CALL_BUDGET_MS;
+        const feedIds = await hn.fetchFeed(input.feed, ctx, deadline);
+        const count = Math.min(input.count, COUNT_CAP);
+        const sliced = feedIds.slice(input.offset, input.offset + count);
+        const slots = await hn.fetchItems(sliced, ctx, deadline);
+        const { items, failedIds } = settlePage(slots);
         const stories = items.map((item) => {
             const url = normalizeUrl(item.url);
             const domain = extractDomain(url);
@@ -161,7 +174,7 @@ export const getStories = tool('hn_get_stories', {
             failed: failedIds.length,
         });
         const total = feedIds.length;
-        const nextOffset = input.offset + input.count;
+        const nextOffset = input.offset + count;
         const hasMore = nextOffset < total;
         ctx.enrich({
             total,
@@ -171,18 +184,19 @@ export const getStories = tool('hn_get_stories', {
         });
         const deadPageMessage = `No live stories on this page of the ${input.feed} feed (offset:${input.offset}, total:${total}). Items may have been deleted or flagged.`;
         const failureMessage = failedIds.length > 0
-            ? `Could not fetch ${failedIds.length} of ${sliced.length} items on this page (id${failedIds.length === 1 ? '' : 's'} ${failedIds.join(', ')}). Retry with offset: ${input.offset}, or pass an id as itemId to hn_get_thread to fetch that story alone.`
+            ? `Could not fetch ${failedIds.length} of ${sliced.length} items on this page (id${failedIds.length === 1 ? '' : 's'} ${failedIds.join(', ')}).${timeBudgetCutSentence(slots)} Retry with offset: ${input.offset}, or pass an id as itemId to hn_get_thread to fetch that story alone.`
             : undefined;
         if (hasMore) {
-            const raiseCount = input.count < MAX_COUNT ? `, or raise count (max ${MAX_COUNT})` : '';
+            const raiseCount = input.count < COUNT_CAP ? `, or raise count (max ${COUNT_CAP})` : '';
             const nextPage = `Pass offset: ${nextOffset} for the next page${raiseCount}.`;
             const pageStatus = stories.length === 0 && !failureMessage
                 ? deadPageMessage
                 : `Showing items ${input.offset + 1}–${nextOffset} of ${total} in the ${input.feed} feed.`;
+            const overCap = input.count > COUNT_CAP ? servedAtCap('count', input.count, COUNT_CAP) : '';
             ctx.enrich.truncated({
                 shown: stories.length,
-                cap: input.count,
-                guidance: [pageStatus, failureMessage, nextPage].filter(Boolean).join(' '),
+                cap: count,
+                guidance: [pageStatus, overCap, failureMessage, nextPage].filter(Boolean).join(' '),
             });
         }
         else if (stories.length === 0) {