@cyanheads/hn-mcp-server 0.5.22 → 0.6.1

package/AGENTS.md

@@ -1,10 +1,10 @@
 # Developer Protocol
 
 **Server:** hn-mcp-server
-**Version:** 0.5.22
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
-**Engines:** Bun ≥1.4.0, Node ≥24.0.0
-**MCP SDK:** `@modelcontextprotocol/server` 2.3.1
+**Version:** 0.6.1
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.22`
+**Engines:** Bun ≥1.4.4, Node ≥24.0.0
+**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 };
@@ -201,7 +203,7 @@ import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 throw new McpError(JsonRpcErrorCode.DatabaseError, 'Connection failed', { pool: 'primary' });
 ```
 
-**Service-layer:** services don't have `ctx.fail`, but can carry the contract reason via `data: { reason: 'X' }` on a factory throw. The auto-classifier preserves `data` on the wire so clients see the same `error.data.reason` they'd see from `ctx.fail`, and the framework fills the contract's `recovery` for a throw that carries none. `hn-service.ts` throws all five `upstream_*` reasons this way, each with an explicit `recovery: { hint }` that overrides the contract text with runtime context (the upstream's name, the `Retry-After` wait), so each of their `errors[]` entries carries `thrownBy: 'service'` — `error-contract-unthrown` reads the handler body alone and would otherwise flag them as dead. See framework CLAUDE.md and `api-errors` skill for the full auto-classification table and all factories.
+**Service-layer:** services don't have `ctx.fail`, but can carry the contract reason via `data: { reason: 'X' }` on a factory throw. The auto-classifier preserves `data` on the wire so clients see the same `error.data.reason` they'd see from `ctx.fail`, and the framework fills the contract's `recovery` for a throw that carries none. `hn-service.ts` throws five `upstream_*` reasons this way, each with an explicit `recovery: { hint }` that overrides the contract text with runtime context (the upstream's name, the `Retry-After` wait), plus `upstream_no_response` (a stories or user page on which every item failed, most often with no answer from the API), which carries no hint, so the contract's `recovery` fills it, and the declared `retry_deadline_exceeded` (`hn_get_stories`, `hn_get_user`, `hn_get_thread`). Each of their `errors[]` entries carries `thrownBy: 'service'` — `error-contract-unthrown` reads the handler body alone and would otherwise flag them as dead. See framework CLAUDE.md and `api-errors` skill for the full auto-classification table and all factories.
 
 ---
 
@@ -218,6 +220,7 @@ 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/
@@ -242,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:
 
@@ -256,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 |
@@ -322,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. Root `skills/` ships on purpose. 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/`, `AGENTS.md`, and `CLAUDE.md` 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 matches only at a package root because a `skills/` deeper in a package is runtime code: MCP SDK 2.4 ships its Skills extension at `@modelcontextprotocol/{server,core}/dist/ext/skills/`, which the framework imports at startup. `tests/scripts/bundle-agent-docs.test.ts` pins that selector in both `clean-mcpb.ts` and `lint-packaging.ts`, so a script resync that would strip the SDK's modules fails the suite. 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": ""`.
 

package/CLAUDE.md

@@ -1,10 +1,10 @@
 # Developer Protocol
 
 **Server:** hn-mcp-server
-**Version:** 0.5.22
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
-**Engines:** Bun ≥1.4.0, Node ≥24.0.0
-**MCP SDK:** `@modelcontextprotocol/server` 2.3.1
+**Version:** 0.6.1
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.22`
+**Engines:** Bun ≥1.4.4, Node ≥24.0.0
+**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 };
@@ -201,7 +203,7 @@ import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 throw new McpError(JsonRpcErrorCode.DatabaseError, 'Connection failed', { pool: 'primary' });
 ```
 
-**Service-layer:** services don't have `ctx.fail`, but can carry the contract reason via `data: { reason: 'X' }` on a factory throw. The auto-classifier preserves `data` on the wire so clients see the same `error.data.reason` they'd see from `ctx.fail`, and the framework fills the contract's `recovery` for a throw that carries none. `hn-service.ts` throws all five `upstream_*` reasons this way, each with an explicit `recovery: { hint }` that overrides the contract text with runtime context (the upstream's name, the `Retry-After` wait), so each of their `errors[]` entries carries `thrownBy: 'service'` — `error-contract-unthrown` reads the handler body alone and would otherwise flag them as dead. See framework CLAUDE.md and `api-errors` skill for the full auto-classification table and all factories.
+**Service-layer:** services don't have `ctx.fail`, but can carry the contract reason via `data: { reason: 'X' }` on a factory throw. The auto-classifier preserves `data` on the wire so clients see the same `error.data.reason` they'd see from `ctx.fail`, and the framework fills the contract's `recovery` for a throw that carries none. `hn-service.ts` throws five `upstream_*` reasons this way, each with an explicit `recovery: { hint }` that overrides the contract text with runtime context (the upstream's name, the `Retry-After` wait), plus `upstream_no_response` (a stories or user page on which every item failed, most often with no answer from the API), which carries no hint, so the contract's `recovery` fills it, and the declared `retry_deadline_exceeded` (`hn_get_stories`, `hn_get_user`, `hn_get_thread`). Each of their `errors[]` entries carries `thrownBy: 'service'` — `error-contract-unthrown` reads the handler body alone and would otherwise flag them as dead. See framework CLAUDE.md and `api-errors` skill for the full auto-classification table and all factories.
 
 ---
 
@@ -218,6 +220,7 @@ 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/
@@ -242,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:
 
@@ -256,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 |
@@ -322,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. Root `skills/` ships on purpose. 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/`, `AGENTS.md`, and `CLAUDE.md` 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 matches only at a package root because a `skills/` deeper in a package is runtime code: MCP SDK 2.4 ships its Skills extension at `@modelcontextprotocol/{server,core}/dist/ext/skills/`, which the framework imports at startup. `tests/scripts/bundle-agent-docs.test.ts` pins that selector in both `clean-mcpb.ts` and `lint-packaging.ts`, so a script resync that would strip the SDK's modules fails the suite. 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": ""`.
 

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.3 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.3 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.3-slim AS production
+FROM oven/bun:1.4.4-slim AS production
 
 WORKDIR /usr/src/app
 
@@ -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.22-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.3.1-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.1-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.4-f9f1e1.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -38,7 +38,13 @@ Hacker News feeds, threads, and profiles. Browse ranked feeds, read full comment
 | `hn_get_stories` | Fetch stories from an HN feed (top, new, best, ask, show, jobs), with title, URL, score, author, and comment count |
 | `hn_get_thread` | Get an item and its comment tree as a threaded discussion, with depth and comment-count controls and a cursor to page through long threads |
 | `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 |
+| `hn_search_content` | Search stories, comments, polls, and jobs via Algolia by keyword, by filters alone, or both — type, author, parent story, date range, minimum points, and minimum comment count |
+
+### 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
 
@@ -47,19 +53,19 @@ Hacker News feeds, threads, and profiles. Browse ranked feeds, read full comment
 - 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 error of its dominant cause instead of an empty list: `upstream_rate_limited` when any item was rate-limited, otherwise the most frequent declared upstream reason, or `upstream_no_response` (`Timeout`) when no answer from the HN API at all was the most common failure
 
 ---
 
 ### `hn_get_thread` <sub>tool</sub>
 
-- `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 text budget that cuts only between comments. 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
+- `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 the tool did not issue, an altered one, or one passed with a different `itemId` fails with `invalid_cursor`
+- 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`, 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 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
+- `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
 
 ---
 
@@ -69,22 +75,26 @@ Hacker News feeds, threads, and profiles. Browse ranked feeds, read full comment
 - 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 error of its dominant cause, as `hn_get_stories` does, with `upstream_no_response` (`Timeout`) when no answer was the most common failure, the budget cutting them all included
+- A final window whose submissions are all dead, deleted, or absent gets a `notice` saying so, with the `submissionOffset` and `total`
+- 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` (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
+- 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`, `minPoints`, and `minComments` 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
+- `minComments` applies to stories and polls the same way: any value, 0 included, excludes comments, jobs, and poll options, so an untagged search returns only stories and polls, and pairing it with `tags: "comment"` or `"job"` fails with `min_comments_unscored_type`. It filters; it does not sort
+- A comment hit carries `parentId` (its story's id for a top-level comment, otherwise the parent comment's id, which `hn_get_thread` reads) and, when its story links out, `storyUrl`; in `content[]` the meta line shows `parent:<id>` and the story link sits on its own line
+- `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
+- 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)
 
@@ -98,14 +108,14 @@ HN-specific:
 - Concurrent batch fetching with configurable parallelism for item resolution (`HN_CONCURRENCY_LIMIT`)
 - HTML bodies stripped to plain text — entities decoded once, code blocks kept verbatim, each link rendered once as its full URL — while titles, which are not HTML though some carry entities, are entity-decoded and never tag-stripped
 - Server-level `instructions` forwarded to LLM clients on `initialize` — item types, ID reuse across tools, case-sensitive usernames, field sparsity
-- No API keys required — both upstream APIs are public
+- No API keys required — both upstream APIs are public; every request identifies itself with a `User-Agent` of `hn-mcp-server/<version>` and the repository URL
 
 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`, `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
+- 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
@@ -183,7 +193,7 @@ Or with Docker:
 
 ### Prerequisites
 
-- [Bun v1.4.0](https://bun.sh/) or higher (or Node.js >= 24)
+- [Bun v1.4.4](https://bun.sh/) or higher (or Node.js >= 24)
 
 ### Installation
 

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/changelog/0.6.x/0.6.1.md

@@ -0,0 +1,34 @@
+---
+summary: "hn_search_content gains a minComments filter and parentId and storyUrl on comment hits; a stories or user page on which every item failed throws its dominant cause, with a new upstream_no_response reason when the HN API gave no answer."
+breaking: false
+security: false
+---
+
+# 0.6.1 — 2026-11-12
+
+## Added
+
+- **`hn_search_content` `minComments` filter**: an integer ≥ 0, sent to Algolia as `num_comments>=N`. It applies to stories and polls and is rejected with `tags: "comment"` or `"job"` as `min_comments_unscored_type`. (#54)
+- **`hn_search_content` comment hits carry `parentId` and `storyUrl`**: the id of the item the comment replies to (read it with `hn_get_thread`), and the link its story submitted, absent for a text post. (#53)
+- **`User-Agent` on every Firebase and Algolia request**: `hn-mcp-server/<version> (+https://github.com/cyanheads/hn-mcp-server)`.
+
+## Changed
+
+- **`hn_get_user` notice for an empty final window**: a window whose submissions are all dead, deleted, or absent now says so, with its `submissionOffset` and `total`.
+- **`hn-guide` skill 1.1**: corrects the hiring-thread posting dates and adds `minComments` guidance.
+- **Framework adoption** (mcp-ts-core 0.13.19–0.13.22): Bun ≥1.4.4 is required; on Node.js below 24 the server now exits at startup, naming the running version; `initialize`'s `serverInfo` carries `description`; a rate-limit error's trailer adds `retry after <value>`; installed as a project dependency, the server resolves its own `skills/` and logs directory; the `.mcpb` bundle no longer ships dependency-root `AGENTS.md` and `CLAUDE.md`. `framework-skills/`, `scripts/`, and `changelog/template.md` are resynced.
+
+## Fixed
+
+- **A stories or user page on which every item failed throws its dominant cause** instead of the first slot's error: a rate limit first, otherwise the most frequent declared upstream reason. When no answer from the HN API is the most common failure, it throws the new `upstream_no_response` (`Timeout`, with `data.itemCount` and `data.budgetCut`), declared on `hn_get_stories` and `hn_get_user`. (#51)
+- **`retry_deadline_exceeded` is declared** in `errors[]` on `hn_get_stories`, `hn_get_user`, and `hn_get_thread`.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.18 → ^0.13.22
+- Dev: `@biomejs/biome` ^2.6.3 → ^2.6.6
+- Dev: `@types/node` ^26.6.5 → ^26.6.6
+- Dev: `@vitest/coverage-istanbul` ^5.0.5 → ^5.1.0
+- Dev: `vitest` ^5.0.5 → ^5.1.0
+- Dev: `tsc-alias` ^1.9.9 → ^1.9.10
+- `engines.bun` >=1.4.0 → >=1.4.4

package/changelog/template.md

@@ -116,14 +116,21 @@ security: false
   resolves to whatever real item already owns 42, and timeline previews pull
   in that unrelated item's metadata.
 
+  Outside reporters: when the issue or PR came from outside the project
+  (`git-wrapup` step 5 says how to tell), thank its author in the same
+  parenthetical, profile linked by full URL for the same reason:
+
+      ([#38](https://github.com/cyanheads/mcp-ts-core/issues/38), thanks [@octocat](https://github.com/octocat)!)
+
   TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
   via `gh release create --notes-from-tag`. It is a condensed digest of this
   entry, never a copy, and its format is owned by the `release-and-publish`
   skill (step 4, "Create the annotated tag"): a short subject line without the
   version, flat headline bullets — no Keep-a-Changelog section headers, no
-  gates line — at most one deps line, issue backlinks, and the changelog link
-  last. In release-PR mode the `git-wrapup` skill authors those bullets as the
-  PR body's `## Changes` and the tag copies them.
+  gates line — at most one deps line, issue backlinks with any outside-reporter
+  thanks, and the changelog link last. In release-PR mode the `git-wrapup`
+  skill authors those bullets as the PR body's `## Changes` and the tag copies
+  them.
 -->
 
 ## Added

package/dist/index.js

@@ -13,9 +13,10 @@ await createApp({
     name: 'hn-mcp-server',
     title: 'hn-mcp-server',
     tools: [getStories, getThread, getUser, searchHn],
-    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.',
+    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/comment-count 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,wfAAwf;IAC1f,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

@@ -63,6 +63,20 @@ export declare const getStories: import("@cyanheads/mcp-ts-core").ToolDefinition
     readonly recovery: "Retry after a brief delay; no input change helps while the upstream serves this.";
     readonly retryable: true;
     readonly thrownBy: "service";
+}, {
+    readonly reason: "upstream_no_response";
+    readonly code: JsonRpcErrorCode.Timeout;
+    readonly when: "Every item on the page failed, none with HTTP 429, and no answer from the HN API was the most common failure — timed out after retries, could not connect, or ran past this call's 50-second time budget.";
+    readonly recovery: "Retry the same call after a short delay; when the time budget cut any of the items, pass a smaller count so fewer items share it.";
+    readonly retryable: true;
+    readonly thrownBy: "service";
+}, {
+    readonly reason: "retry_deadline_exceeded";
+    readonly code: JsonRpcErrorCode.Timeout;
+    readonly when: "The HN API was too slow to return the feed: its retries ran past this call's 50-second time budget.";
+    readonly recovery: "Retry the same call after a short delay; the HN API answered too slowly to finish within this call's time budget.";
+    readonly retryable: true;
+    readonly thrownBy: "service";
 }], {
     readonly total: z.ZodNumber;
     readonly offset: z.ZodNumber;

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;AAkBjE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4QrB,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiSrB,CAAC"}

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

@@ -6,7 +6,7 @@ import { tool, z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { escapeInline, quoteBody } from '../markdown-escape.js';
 import { servedAtCap } from '../served-at-cap.js';
-import { decodeHtmlEntities, extractDomain, getHnService, normalizeUrl, settlePage, stripHtml, } from '../../../services/hn/hn-service.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. */
@@ -54,6 +54,22 @@ export const getStories = tool('hn_get_stories', {
             retryable: true,
             thrownBy: 'service',
         },
+        {
+            reason: 'upstream_no_response',
+            code: JsonRpcErrorCode.Timeout,
+            when: `Every item on the page failed, none with HTTP 429, and no answer from the HN API was the most common failure — timed out after retries, could not connect, or ran past this call's ${CALL_BUDGET_MS / 1000}-second time budget.`,
+            recovery: 'Retry the same call after a short delay; when the time budget cut any of the items, pass a smaller count so fewer items share it.',
+            retryable: true,
+            thrownBy: 'service',
+        },
+        {
+            reason: 'retry_deadline_exceeded',
+            code: JsonRpcErrorCode.Timeout,
+            when: `The HN API was too slow to return the feed: its retries ran past this call's ${CALL_BUDGET_MS / 1000}-second time budget.`,
+            recovery: "Retry the same call after a short delay; the HN API answered too slowly to finish within this call's time budget.",
+            retryable: true,
+            thrownBy: 'service',
+        },
     ],
     input: z.object({
         feed: z
@@ -134,21 +150,24 @@ export const getStories = tool('hn_get_stories', {
         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 — noting when count was served at its per-call cap. 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);
+        /** 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 { items, failedIds } = settlePage(await hn.fetchItems(sliced, ctx));
+        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);
@@ -181,7 +200,7 @@ 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 < COUNT_CAP ? `, or raise count (max ${COUNT_CAP})` : '';