@cyanheads/hn-mcp-server 0.5.15 → 0.5.17

package/CLAUDE.md

@@ -1,11 +1,11 @@
 # Developer Protocol
 
 **Server:** hn-mcp-server
-**Version:** 0.5.15
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.5`
-**Engines:** Bun ≥1.3.0, Node ≥24.0.0
+**Version:** 0.5.17
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
+**Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` 2.0.0
-**Zod:** ^4.5.4
+**Zod:** ^4.6.5
 
 > **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.
 
@@ -37,6 +37,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
 - **Need input the caller didn't supply?** `return ctx.requestInput(...)` and read `ctx.inputs` when the handler is re-entered. Never `await` for user input mid-handler.
 - **Secrets in env vars only** — never hardcoded.
+- **Cut noise.** Add only what earns its place: no speculative generality, no guards for states the framework already prevents (Zod-validated params, classified errors), no abstraction until a third caller proves it, no option nothing sets.
 - **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
 
 ---
@@ -121,6 +122,21 @@ await createApp({
 
 `lint:packaging` (check 9) validates the pair against the unscoped package name.
 
+### Session posture and shutdown
+
+Two more `createApp()` options shape how the server runs rather than how it presents itself:
+
+```ts
+await createApp({
+  sessionMode: 'stateless',          // or { default: 'stateful', require: 'stateful' }
+  setup() { initHnService(); },
+});
+```
+
+`sessionMode` declares the HTTP session posture in `src/` instead of leaving it to a deployment's `MCP_SESSION_MODE`, which still wins whenever it carries a meaningful value (an empty string and an unsubstituted `${…}` placeholder read as unset and fall through to the option). Stateless is right here: no tool calls `ctx.requestInput`, so no caller ever needs a session to answer a mid-handler prompt. Add `require: 'stateful'` if one ever does — startup then fails with a `ConfigurationError` rather than serving a mode in which a 2025-era client can never answer. Stdio is never refused.
+
+`teardown(core)` is the `setup()` counterpart — release a watcher, socket, or non-`unref()`'d timer there. `initHnService()` allocates none of those (the service holds a concurrency limit and nothing else), so this server declares no `teardown`. Add one alongside any future long-lived handle.
+
 ---
 
 ## Context
@@ -129,7 +145,7 @@ Handlers receive a unified `ctx` object. Key properties:
 
 | Property | Description |
 |:---------|:------------|
-| `ctx.log` | Request-scoped dual-sink logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId; eligible messages also reach the client through MCP logging notifications. |
+| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |
 | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
 | `ctx.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present. |
 | `ctx.inputs` | Reader over a retried request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped`. Empty on the first round. |
@@ -145,7 +161,7 @@ Handlers receive a unified `ctx` object. Key properties:
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required descriptive metadata for the agent's next move (≥ 5 words, lint-validated); for the wire `data.recovery.hint` (mirrored into `content[]` text), pass explicitly at the throw site when dynamic context matters: `ctx.fail('reason', msg, { recovery: { hint: '...' } })`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Forwarding it is lint-enforced per throw site (`error-contract-recovery-unforwarded`). `severity` (`debug` / `info` / `notice` / `warning`) drops the log record for a modeled outcome below `error` — the `item_not_found` / `user_not_found` misses use `notice`; upstream faults keep `error`. Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
 
 ```ts
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -153,7 +169,8 @@ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 errors: [
   { reason: 'item_not_found', code: JsonRpcErrorCode.NotFound,
     when: 'HN reports no item exists for the given itemId.',
-    recovery: 'Verify the itemId via hn_search_content or hn_get_stories.' },
+    recovery: 'Verify the itemId via hn_search_content or hn_get_stories.',
+    severity: 'notice' },
 ],
 async handler(input, ctx) {
   const root = await hn.fetchItem(input.itemId, ctx);
@@ -184,7 +201,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`. 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`. `hn-service.ts` throws all five `upstream_*` reasons this way, 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.
 
 ---
 
@@ -222,9 +239,9 @@ src/
 
 ## Skills
 
-Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry.
+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.
 
-**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). This makes skills available as context without needing to reference `skills/` paths manually. After framework updates, run the `maintenance` skill — it re-syncs the agent directory automatically (Phase B).
+**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.
 
 Available skills:
 
@@ -233,7 +250,7 @@ Available skills:
 | `setup` | Post-init project orientation |
 | `design-mcp-server` | Design tool surface, resources, and services for a new server |
 | `add-tool` | Scaffold a new tool definition |
-| `add-app-tool` | Scaffold an MCP App tool + UI resource pair (interactive HTML UI) |
+| `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-service` | Scaffold a new service integration |
@@ -243,27 +260,28 @@ Available skills:
 | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
 | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
-| `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
-| `release-and-publish` | Push + npm + MCP Registry + GitHub Release + Docker. Picks up from `git-wrapup` |
+| `git-wrapup` | Land working-tree changes as a commit stack — version bump, changelog, verify, commit by concern, release commit on top. No tag, no push to main; opens the release PR when the project declares release PR mode |
+| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixes as ordinary commits on top of the stack, PR body kept in sync. Release PR mode only |
+| `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
-| `techniques` | Catalog of reusable response/data-shaping patterns (outline-on-overflow, etc.) |
+| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
+| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
+| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
 | `api-auth` | Auth modes, scopes, JWT/OAuth |
 | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
 | `api-config` | AppConfig, parseConfig, env vars |
 | `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input |
 | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
 | `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
-| `api-mirror` | MirrorService: persistent self-refreshing local index (SQLite+FTS5) for bulk/slow upstream datasets |
+| `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in |
 | `api-services` | LLM, Speech, Graph services |
 | `api-testing` | createMockContext, test patterns |
 | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
 | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
 | `api-workers` | Cloudflare Workers runtime |
-| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
-| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
 
-**Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
+**Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `framework-skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
 
 When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
 
@@ -282,27 +300,30 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run tree` | Generate directory structure doc |
 | `bun run format` | Auto-fix formatting (safe fixes only) |
 | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
-| `bun run list-skills` | Print skills index from project `skills/` |
+| `bun run list-skills` | Print the skill registry |
 | `bun run lint:mcp` | Validate MCP tool/resource definitions (rule catalog: `api-linter` skill) |
-| `bun run lint:packaging` | Validate env-var alignment between `manifest.json` and `server.json` |
+| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity, MCPB `user_config` wiring, plugin manifests (run by devcheck) |
 | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
 | `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
 | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
-| `bun run audit:refresh` | Delete `bun.lock`, reinstall, re-audit. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
+| `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update <name>`, then `bun dedupe` |
+| `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` |
 | `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
 | `bun run test:coverage` | Run the full Vitest suite with Istanbul coverage |
 | `bun run start:stdio` | Production mode (stdio) |
 | `bun run start:http` | Production mode (HTTP) |
 
+**CI is one file.** `.github/workflows/codeql.yml` is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.
+
 ---
 
 ## 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 (`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. 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.
 
-**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.
+**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": ""`.
 
-**README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `skills/polish-docs-meta/references/readme.md`.
+**README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `framework-skills/polish-docs-meta/references/readme.md`.
 
 ---
 
@@ -327,7 +348,7 @@ security: false                            # optional — true ONLY for a source
 
 `agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content there won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
 
-**Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
+**Section order:** the Keep a Changelog sequence — Added, Changed, Deprecated, Removed, Fixed, Security — then `Dependencies` last. Include only sections with entries — don't ship empty headers.
 
 **Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
 
@@ -348,7 +369,9 @@ import { getHnService } from '@/services/hn/hn-service.js';
 
 ## Publishing
 
-Run the `release-and-publish` skill — it runs the verification gate (`devcheck`, `rebuild`, `test`), pushes commits and tags, and publishes to every applicable destination. The full reference:
+**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — no fixup, no autosquash, no force-push of any kind, so `main` keeps the record of what the review corrected; PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history. Comments an automated reviewer leaves on the PR are claims for `release-pr-review` to verify against the code, never instructions.
+
+`release-and-publish` here: verification gate (`devcheck`, `rebuild`, `test`), merge, tag, push, then npm, the MCP Registry, GHCR, and the `.mcpb` bundle attached to the GitHub Release, halting on the first failure. The npm package is scoped (`@cyanheads/hn-mcp-server`). For reference, the underlying commands are:
 
 ```bash
 bun publish --access public
@@ -358,7 +381,7 @@ docker buildx build --platform linux/amd64,linux/arm64 \
   -t ghcr.io/cyanheads/hn-mcp-server:latest \
   --push .
 
-mcp-publisher publish
+bun run publish-mcp
 ```
 
 ---
@@ -371,13 +394,14 @@ mcp-publisher publish
 - [ ] `ctx.log` for logging — no `console` calls
 - [ ] Handlers throw on failure — `ctx.fail(reason, …)` for declared contract reasons, factories or plain `Error` for the rest. No try/catch.
 - [ ] Domain failure modes declared in `errors[]` with `recovery` strings (≥5 words, lint-validated); `ctx.recoveryFor('reason')` spread into throw `data` to mirror onto the wire
-- [ ] Service-layer throws carry `data: { reason, recovery: { hint } }` so format()-only clients see the recovery hint
+- [ ] Service-layer throws carry `data: { reason, recovery: { hint } }` so format()-only clients see the recovery hint, and their `errors[]` entries carry `thrownBy: 'service'`
+- [ ] A reason that is an ordinary caller-side miss rather than a fault carries `severity` below `error`
 - [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data
 - [ ] Wrapping HN/Algolia: schemas reflect real upstream sparsity (HN omits fields freely); `format()` preserves uncertainty rather than fabricating from missing data
 - [ ] Tests cover at least one sparse payload case per tool that wraps upstream items
 - [ ] Tests use `createMockContext({ errors: tool.errors })` when the test exercises `ctx.fail`
 - [ ] Registered in `createApp()` tools array
-- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = package name; `interface.shortDescription` from `package.json` description
-- [ ] `.codex-plugin/mcp.json` updated — server name key matches `package.json` name; env vars added for any required API keys
-- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry with server name key, env vars for any required API keys
+- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description
+- [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable (API key, contact email, instance URL) is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset
+- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.<option>}"` — mirror the `user_config` block in `manifest.json`. Never write `"KEY": ""` into `env`
 - [ ] `bun run devcheck` passes

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.5.15-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.0.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.3.0-f9f1e1.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.5.17-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.0.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>
 
@@ -27,76 +27,73 @@
 
 ---
 
-## Tools
+## Overview
 
-Four read-only tools for accessing Hacker News data:
+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 and comments by type, author, date, or score. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
 
-| Tool Name | Description |
-|:----------|:------------|
-| `hn_get_stories` | Fetch stories from an HN feed (top, new, best, ask, show, jobs) with pagination. |
-| `hn_get_thread` | Get an item and its comment tree as a threaded discussion with depth/count controls. |
-| `hn_get_user` | Fetch a user profile with karma, about, and optionally a page of their submissions. |
-| `hn_search_content` | Search stories and comments via Algolia with type, author, date, and score filters. |
+### Tools
 
-### `hn_get_stories`
+| Tool | Description |
+|:---|:---|
+| `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 |
+| `hn_get_user` | Fetch a user profile with karma, about, and optionally a page of resolved submissions |
+| `hn_search_content` | Search stories and comments via Algolia, filterable by type, author, date range, and minimum points |
 
-Fetch stories from any HN feed with pagination support.
+## Capability reference
 
-- Six feed types: `top`, `new`, `best`, `ask`, `show`, `jobs`
-- Configurable count (1–100, default 30) and offset for pagination
-- Returns enriched story objects with title, URL, score, author, comment count, and body text
+### `hn_get_stories` <sub>tool</sub>
 
----
+- Six feed types: `top`, `new`, `best`, `ask`, `show`, `jobs`; `count` (1–100, default 30) and `offset` for pagination
+- 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`, `hasMore`, and a `notice` explaining empty pages (empty feed, offset past end, or every item on the page deleted/flagged)
 
-### `hn_get_thread`
+---
 
-Retrieve an item and its full comment tree via ranked breadth-first traversal.
+### `hn_get_thread` <sub>tool</sub>
 
-- Depth control (0–10, default 3) — depth 0 doubles as a single-item lookup
-- Comment limit (1–200, default 50) caps total comments across all levels
-- Breadth-first traversal preserves HN's ranking order
-- Flat comment list with `depth`/`parentId` for tree reconstruction
+- `itemId` plus `depth` (0–10, default 3; 0 returns the item with no comments) and `maxComments` (1–200, default 50) capping the total across all levels
+- Breadth-first traversal ranked like HN — top-ranked top-level comments resolve first, replies fill in only after the level above is exhausted
+- 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
+- `notice` reports deleted/dead comments omitted during traversal and, when `totalLoaded` is below `totalAvailable`, the hint to raise `maxComments`/`depth`
 
 ---
 
-### `hn_get_user`
-
-Fetch a user profile with optional submission resolution.
+### `hn_get_user` <sub>tool</sub>
 
-- Profile includes karma, creation date, and about text (HTML stripped)
-- Optionally resolves submissions into full items, up to 50 per page
-- `submissionOffset` pages through a long history; enrichment echoes the applied offset and the offset to request next
-- Submission resolution filters out dead/deleted items
+- `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
+- Profile includes karma, creation date, and about text (HTML stripped); submissions filter out dead/deleted items
+- Enrichment echoes `submissionOffset` and the offset to send next, or a notice when the requested offset is past the end of the history
 
 ---
 
-### `hn_search_content`
+### `hn_search_content` <sub>tool</sub>
 
-Full-text search via the Algolia HN Search API.
-
-- Filter by content type: `story`, `comment`, `ask_hn`, `show_hn`, `front_page`
-- Filter by author, date range (ISO 8601), and minimum points
-- Sort by relevance or date
-- Pagination with page/count controls
+- Free-text `query` plus `tags` (`story`/`comment`/`ask_hn`/`show_hn`/`front_page`), `author`, `dateRange` (ISO 8601), and `minPoints` filters; `sort` by relevance or date; `count` (1–50, default 30) and `page` for pagination
 - `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
 
 ## Features
 
-Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core):
-
-- Declarative tool definitions — single file per tool, framework handles registration and validation
-- Unified error handling across all tools
-- Structured logging with request correlation
-- Runs locally (stdio/HTTP) from the same codebase
+Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.
 
 HN-specific:
 
-- Server-level `instructions` orientation forwarded to LLM clients on `initialize` — item types, ID reuse across tools, case-sensitive usernames, and field sparsity expectations
-- Concurrent batch fetching with configurable parallelism for item resolution
-- HTML entity decoding and tag stripping with code block and link preservation
-- No API keys required — HN APIs are public
+- Two upstream APIs: HN's Firebase API for feeds, items, and users; Algolia's HN Search API for full-text search
+- Concurrent batch fetching with configurable parallelism for item resolution (`HN_CONCURRENCY_LIMIT`)
+- HTML entity decoding and tag stripping, preserving code blocks and links
+- 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
 
-## Getting Started
+Agent-friendly output:
+
+- Graceful partial failure — `hn_get_thread` counts deleted and dead comments dropped during traversal and surfaces the count in `notice` rather than silently shrinking the result; `hn_get_stories` and `hn_get_user` filter dead/deleted items the same way
+- Discriminated output contracts — typed error reasons (`item_not_found`, `upstream_rate_limited`, `upstream_html`, …) with per-reason recovery text, and a `depth`/`parentId` pair on every comment so callers reconstruct the tree without guessing nesting
+- Pagination provenance — every paged tool echoes the offset it used (`offset`, `submissionOffset`, `page`) plus the exact next-offset value in `notice`, so an agent can resume a listing 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
+
+## Getting started
 
 ### Public Hosted Instance
 
@@ -171,7 +168,7 @@ Or with Docker:
 
 ### Prerequisites
 
-- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js >= 24)
+- [Bun v1.4.0](https://bun.sh/) or higher (or Node.js >= 24)
 
 ### Installation
 
@@ -191,55 +188,68 @@ All configuration is via environment variables. No API keys required — HN APIs
 | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
 | `MCP_HTTP_PORT` | HTTP server port. | `3010` |
 | `MCP_HTTP_HOST` | HTTP server host. | `localhost` |
-| `MCP_SESSION_MODE` | HTTP session handling: `auto`, `stateful`, or `stateless`. `auto` resolves to `stateful`. The published Docker image and `.env.example` pin `stateless`. | `auto` |
+| `MCP_SESSION_MODE` | HTTP session handling: `stateful`, `stateless`, or `auto` (resolves to `stateful`). The server declares `stateless` in source, and the published Docker image and `.env.example` set it too; a meaningful env value still overrides. | `stateless` |
 | `MCP_LOG_LEVEL` | Log level: `debug`, `info`, `notice`, `warning`, `error`. | `info` |
 | `LOGS_DIR` | Directory for log files (Node.js only). | `<project-root>/logs` |
 
-## Running the Server
+See [`.env.example`](./.env.example) for the full list of optional overrides.
 
-### Local Development
+## Running the server
 
-```sh
-MCP_TRANSPORT_TYPE=stdio bun --watch src/index.ts   # Dev mode (stdio, auto-reload)
-MCP_TRANSPORT_TYPE=http bun --watch src/index.ts    # Dev mode (HTTP, auto-reload)
-bun run test                                         # Run test suite
-bun run devcheck                                     # Lint + format + typecheck + audit
-```
+### Local development
 
-### Production
+- **Dev mode (auto-reload):**
 
-```sh
-bun run build
-bun run start:stdio     # or start:http
-```
+  ```sh
+  MCP_TRANSPORT_TYPE=stdio bun --watch src/index.ts   # stdio
+  MCP_TRANSPORT_TYPE=http bun --watch src/index.ts    # HTTP
+  ```
+
+- **Build and run:**
+
+  ```sh
+  bun run rebuild
+  bun run start:stdio   # or start:http
+  ```
+
+- **Run checks and tests:**
+
+  ```sh
+  bun run devcheck   # Lint, format, typecheck, security
+  bun run test       # Vitest test suite
+  ```
 
 ### Docker
 
 ```sh
 docker build -t hn-mcp-server .
-docker run -p 3010:3010 hn-mcp-server
+docker run --rm -p 3010:3010 hn-mcp-server
 ```
 
-## Project Structure
+The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/hn-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.
+
+## Project structure
 
 | Directory | Purpose |
 |:----------|:--------|
-| `src/index.ts` | `createApp()` entry point. |
-| `src/config/` | Server-specific env var parsing with Zod. |
-| `src/services/hn/` | HN Firebase + Algolia API client and domain types. |
+| `src/index.ts` | `createApp()` entry point — registers tools and inits the HN service. |
+| `src/config/` | Server-specific environment variable parsing and validation with Zod. |
 | `src/mcp-server/tools/definitions/` | Tool definitions (`*.tool.ts`). |
+| `src/services/hn/` | HN Firebase + Algolia API client and domain types. |
+| `tests/` | Unit and integration tests mirroring `src/`. |
 
-## Development Guide
+## Development guide
 
 See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
 
 - Handlers throw, framework catches — no `try/catch` in tool logic
 - Use `ctx.log` for request-scoped logging
 - All tools are read-only — no auth scopes required
+- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
 
 ## Contributing
 
-Issues and pull requests are welcome. Run checks before submitting:
+Issues are welcome. Run checks before submitting:
 
 ```sh
 bun run devcheck

package/changelog/0.5.x/0.5.16.md

@@ -0,0 +1,29 @@
+---
+summary: "Adopted mcp-ts-core ^0.13.0 (blank/unsubstituted env vars now read as unset, dev skills moved to framework-skills/) plus a matching HN_CONCURRENCY_LIMIT fix and routine dependency bumps"
+breaking: false
+security: false
+---
+
+# 0.5.16 — 2026-09-13
+
+## Changed
+
+- **Development skills moved from `skills/` to `framework-skills/`** ([cyanheads/mcp-ts-core#428](https://github.com/cyanheads/mcp-ts-core/issues/428)) — installing this server's `.claude-plugin`/`.codex-plugin` no longer hands these authoring skills to every agent that installs it.
+- A rejected tool call's error now also carries `structuredContent.error` (code `-32602`) alongside the existing `Invalid arguments for tool …` text ([cyanheads/mcp-ts-core#377](https://github.com/cyanheads/mcp-ts-core/issues/377)).
+- `manifest.json`'s `mcp_config.env` now references `${user_config.HN_CONCURRENCY_LIMIT}` / `${user_config.MCP_LOG_LEVEL}`, the form MCPB hosts substitute.
+- A trailing slash on `MCP_PUBLIC_URL` no longer doubles in the HTTP landing page and `/.well-known/mcp.json` links, and the landing page's curl snippet now sends a handshake `initialize` accepts ([cyanheads/mcp-ts-core#395](https://github.com/cyanheads/mcp-ts-core/issues/395)).
+- Minor/internal: `engines.bun` floor raised to `>=1.4.0`; new `audit:fix` script (`bun audit fix`); the `fast-uri`/`qs` `overrides` block removed now that the framework's `@modelcontextprotocol/ext-apps` dependency no longer pulls `@modelcontextprotocol/sdk` 1.x; GitHub issue forms gained assignee/secondary-label guidance and a security-advisory contact link; `.claude-plugin/plugin.json` gained `$schema` and `keywords`.
+
+## Fixed
+
+- **`HN_CONCURRENCY_LIMIT` now reads a blank value or an unsubstituted `${user_config.HN_CONCURRENCY_LIMIT}` placeholder as unset**, falling back to the default of 10, via mcp-ts-core's `parseEnvConfig` ([cyanheads/mcp-ts-core#427](https://github.com/cyanheads/mcp-ts-core/issues/427)). Previously an empty value failed validation. Validation errors now name `HN_CONCURRENCY_LIMIT`.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` `^0.12.5` → `^0.13.0`
+- `zod` `^4.5.4` → `^4.6.1`
+- `vitest` / `@vitest/coverage-istanbul` `^4.1.11` → `^5.0.0`
+- `@biomejs/biome` `^2.5.11` → `^2.5.13`
+- `@types/node` `^26.4.0` → `^26.5.1`
+- `ignore` `^7.0.8` → `^7.0.9`
+- `tsc-alias` `^1.9.3` → `^1.9.4`

package/changelog/0.5.x/0.5.17.md

@@ -0,0 +1,34 @@
+---
+summary: "Adopted mcp-ts-core ^0.13.6: the server declares stateless session mode in source, argument rejections carry a reason and a schema-derived recovery hint, and tool errors close with their reason and retryable status."
+breaking: false
+security: false
+---
+
+# 0.5.17 — 2026-09-19
+
+## Added
+
+- **`.github/workflows/codeql.yml`** — the one GitHub Actions workflow this server carries; runs only while the repo's CodeQL default setup stays off.
+- **`devcheck.config.json` gains a `lint` key** ([cyanheads/mcp-ts-core#388](https://github.com/cyanheads/mcp-ts-core/issues/388)), ready to carry a `truncationAllowlist` declaration read by `lint:mcp`.
+- **The npm package now ships `AGENTS.md`** alongside `CLAUDE.md`.
+
+## Changed
+
+- **`createApp({ sessionMode: 'stateless' })` declares the HTTP session posture in source** ([cyanheads/mcp-ts-core#376](https://github.com/cyanheads/mcp-ts-core/issues/376)). With `MCP_SESSION_MODE` unset, the server now resolves `stateless` from its own `createApp({ sessionMode: 'stateless' })` declaration instead of the schema default `auto` (which resolves to `stateful`); an explicit `MCP_SESSION_MODE` value still overrides it. The Docker image and `.env.example` already set `stateless` — the README env row's default now matches.
+- **`SIGTERM`/`SIGINT` now end the process explicitly** ([cyanheads/mcp-ts-core#435](https://github.com/cyanheads/mcp-ts-core/issues/435)) — exit `0` once shutdown settles, `1` if the 10s ceiling fires.
+- **An argument rejection carries `data.reason: "invalid_arguments"` and a schema-derived `Recovery:` hint** naming the tool's accepted keys ([cyanheads/mcp-ts-core#445](https://github.com/cyanheads/mcp-ts-core/issues/445), [cyanheads/mcp-ts-core#378](https://github.com/cyanheads/mcp-ts-core/issues/378)); a required field omitted from an enum now renders as missing rather than as a wrong choice. An unknown key is still rejected — never dropped or ignored.
+- **Tool arguments pass a pre-validation step before schema parsing** ([cyanheads/mcp-ts-core#452](https://github.com/cyanheads/mcp-ts-core/issues/452), [cyanheads/mcp-ts-core#453](https://github.com/cyanheads/mcp-ts-core/issues/453), [cyanheads/mcp-ts-core#234](https://github.com/cyanheads/mcp-ts-core/issues/234)) — a fixed list of client-added keys is dropped, a case-folded undeclared key matching exactly one declared key is rewritten to it, and a JSON-stringified array is repaired once after a failed parse. Advertised `inputSchema`/`outputSchema` are unchanged.
+- **A tool error's text now closes with `(reason <reason>)`**, plus ` · retryable` / ` · not retryable` when the entry declares `retryable` ([cyanheads/mcp-ts-core#458](https://github.com/cyanheads/mcp-ts-core/issues/458)).
+- **`hn_get_thread`'s `item_not_found` and `hn_get_user`'s `user_not_found` declare `severity: 'notice'`** ([cyanheads/mcp-ts-core#380](https://github.com/cyanheads/mcp-ts-core/issues/380)) — a lookup miss now logs at `notice` instead of `error`; the wire envelope is unchanged.
+- `.env.example`'s `MCP_SESSION_MODE` comment explains the stateless/stateful tradeoff instead of stating only the default; the README row documents the new source default.
+- CLAUDE.md's `## Publishing` section documents the full gated release-PR flow (`git-wrapup` → `release-pr-review` → `release-and-publish`), replacing the single-skill pointer.
+- Minor/internal: all four tools' `upstream_*` service-thrown error reasons carry `thrownBy: 'service'` ([cyanheads/mcp-ts-core#462](https://github.com/cyanheads/mcp-ts-core/issues/462)); 22 `framework-skills/` files and 6 framework scripts (`build.ts`, `clean.ts`, `clean-mcpb.ts`, `devcheck.ts`, `lint-mcp.ts`, `lint-packaging.ts`) re-synced to their current mcp-ts-core versions.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.0 → ^0.13.6
+- `zod` ^4.6.1 → ^4.6.5
+- `@biomejs/biome` ^2.5.13 → ^2.5.14
+- `@types/node` ^26.5.1 → ^26.6.1
+- `vitest` / `@vitest/coverage-istanbul` ^5.0.0 → ^5.0.1
+- `tsc-alias` ^1.9.4 → ^1.9.5

package/changelog/template.md

@@ -6,8 +6,8 @@
 
 # Required. One-line GitHub Release-style headline. 350 character cap — a
 # ceiling, not a target. Default short and scannable. Don't pad, don't stitch
-# unrelated changes with commas/semicolons into an inventory — pick the
-# headline, like a tag's theme line. Quotes required: unquoted YAML treats
+# unrelated changes with commas/semicolons into an inventory — pick the one
+# headline the release is about. Quotes required: unquoted YAML treats
 # `: ` inside the value as a key separator and fails GitHub's strict parser.
 summary: ""
 
@@ -117,30 +117,13 @@ security: false
   in that unrelated item's metadata.
 
   TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
-  via `gh release create --notes-from-tag`. The tag is a derivative of this
-  changelog entry — a condensed, scannable version, not a copy. Format:
-
-    <theme — omit version number, GitHub prepends it>
-                                                          ← blank line
-    <1-2 sentence context: what this release does>
-                                                          ← blank line
-    Dependency bumps:                                     ← section header
-                                                          ← blank line
-    - `@cyanheads/mcp-ts-core` ^0.9.1 → ^0.9.6          ← bullet
-                                                          ← blank line
-    Changed:                                              ← only sections with entries
-                                                          ← blank line
-    - `format()` output includes `query` in text mode
-                                                          ← blank line
-    Added:
-                                                          ← blank line
-    - `manifest.json` scaffolded for MCPB bundle support
-    - Install badges (Claude Desktop, Cursor, VS Code)
-                                                          ← blank line
-    <N> tests pass; `bun run devcheck` clean.             ← footer
-
-  Never a flat comma-separated string. Always structured markdown with
-  sections. The tag must scan well as a rendered GitHub Release page.
+  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.
 -->
 
 ## Added

package/dist/config/server-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAgBH,wBAAgB,eAAe;;EAK9B"}
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiBH,wBAAgB,eAAe;;EAK9B"}

package/dist/config/server-config.js

@@ -3,6 +3,7 @@
  * @module config/server-config
  */
 import { z } from '@cyanheads/mcp-ts-core';
+import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
 const ServerConfigSchema = z.object({
     concurrencyLimit: z.coerce
         .number()
@@ -14,8 +15,8 @@ const ServerConfigSchema = z.object({
 });
 let _config;
 export function getServerConfig() {
-    _config ??= ServerConfigSchema.parse({
-        concurrencyLimit: process.env.HN_CONCURRENCY_LIMIT,
+    _config ??= parseEnvConfig(ServerConfigSchema, {
+        concurrencyLimit: 'HN_CONCURRENCY_LIMIT',
     });
     return _config;
 }