@cyanheads/hn-mcp-server 0.5.16 → 0.5.18
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +407 -0
- package/CLAUDE.md +31 -10
- package/README.md +79 -66
- package/changelog/0.5.x/0.5.17.md +34 -0
- package/changelog/0.5.x/0.5.18.md +24 -0
- package/changelog/template.md +7 -7
- package/dist/index.js +2 -1
- package/dist/index.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-stories.tool.d.ts +5 -0
- package/dist/mcp-server/tools/definitions/get-stories.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-stories.tool.js +25 -8
- package/dist/mcp-server/tools/definitions/get-stories.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-thread.tool.d.ts +6 -0
- package/dist/mcp-server/tools/definitions/get-thread.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-thread.tool.js +31 -10
- package/dist/mcp-server/tools/definitions/get-thread.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-user.tool.d.ts +6 -0
- package/dist/mcp-server/tools/definitions/get-user.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-user.tool.js +7 -1
- package/dist/mcp-server/tools/definitions/get-user.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-content.tool.d.ts +28 -2
- package/dist/mcp-server/tools/definitions/search-content.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-content.tool.js +176 -45
- package/dist/mcp-server/tools/definitions/search-content.tool.js.map +1 -1
- package/dist/services/hn/hn-service.d.ts +13 -2
- package/dist/services/hn/hn-service.d.ts.map +1 -1
- package/dist/services/hn/hn-service.js +20 -4
- package/dist/services/hn/hn-service.js.map +1 -1
- package/package.json +9 -8
- package/server.json +3 -3
package/README.md
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
|
|
8
8
|
<div align="center">
|
|
9
9
|
|
|
10
|
-
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/hn-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/hn-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
|
|
11
11
|
|
|
12
12
|
</div>
|
|
13
13
|
|
|
@@ -27,76 +27,76 @@
|
|
|
27
27
|
|
|
28
28
|
---
|
|
29
29
|
|
|
30
|
-
##
|
|
30
|
+
## Overview
|
|
31
31
|
|
|
32
|
-
|
|
32
|
+
Feeds, threads, and profiles from the Hacker News Firebase API and Algolia Search API. Browse ranked feeds, read full comment threads, look up user profiles, and search stories, comments, polls, and jobs by keyword or by type, author, parent story, date, or score. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
|
|
33
33
|
|
|
34
|
-
|
|
35
|
-
|:----------|:------------|
|
|
36
|
-
| `hn_get_stories` | Fetch stories from an HN feed (top, new, best, ask, show, jobs) with pagination. |
|
|
37
|
-
| `hn_get_thread` | Get an item and its comment tree as a threaded discussion with depth/count controls. |
|
|
38
|
-
| `hn_get_user` | Fetch a user profile with karma, about, and optionally a page of their submissions. |
|
|
39
|
-
| `hn_search_content` | Search stories and comments via Algolia with type, author, date, and score filters. |
|
|
34
|
+
### Tools
|
|
40
35
|
|
|
41
|
-
|
|
36
|
+
| Tool | Description |
|
|
37
|
+
|:---|:---|
|
|
38
|
+
| `hn_get_stories` | Fetch stories from an HN feed (top, new, best, ask, show, jobs), with title, URL, score, author, and comment count |
|
|
39
|
+
| `hn_get_thread` | Get an item and its comment tree as a threaded discussion, with depth and comment-count controls |
|
|
40
|
+
| `hn_get_user` | Fetch a user profile with karma, about, and optionally a page of resolved submissions |
|
|
41
|
+
| `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 |
|
|
42
42
|
|
|
43
|
-
|
|
43
|
+
## Capability reference
|
|
44
44
|
|
|
45
|
-
|
|
46
|
-
- Configurable count (1–100, default 30) and offset for pagination
|
|
47
|
-
- Returns enriched story objects with title, URL, score, author, comment count, and body text
|
|
45
|
+
### `hn_get_stories` <sub>tool</sub>
|
|
48
46
|
|
|
49
|
-
|
|
47
|
+
- Six feed types: `top`, `new`, `best`, `ask`, `show`, `jobs`; `count` (1–100, default 30) and `offset` for pagination
|
|
48
|
+
- 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
|
|
49
|
+
- 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
|
|
50
50
|
|
|
51
|
-
|
|
51
|
+
---
|
|
52
52
|
|
|
53
|
-
|
|
53
|
+
### `hn_get_thread` <sub>tool</sub>
|
|
54
54
|
|
|
55
|
-
-
|
|
56
|
-
-
|
|
57
|
-
-
|
|
58
|
-
-
|
|
55
|
+
- `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
|
|
56
|
+
- Breadth-first traversal ranked like HN — top-ranked top-level comments resolve first, replies fill in only after the level above is exhausted
|
|
57
|
+
- 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
|
|
58
|
+
- `notice` reports deleted/dead comments omitted during traversal and, when `totalLoaded` is below `totalAvailable`, the hint to raise `maxComments`/`depth`; `truncated` is set only when `maxComments` stopped the traversal with comments left, not when a thread loads in full at exactly the cap
|
|
59
59
|
|
|
60
60
|
---
|
|
61
61
|
|
|
62
|
-
### `hn_get_user`
|
|
63
|
-
|
|
64
|
-
Fetch a user profile with optional submission resolution.
|
|
62
|
+
### `hn_get_user` <sub>tool</sub>
|
|
65
63
|
|
|
66
|
-
-
|
|
67
|
-
-
|
|
68
|
-
- `submissionOffset`
|
|
69
|
-
- Submission resolution filters out dead/deleted items
|
|
64
|
+
- `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
|
|
65
|
+
- Profile includes karma, creation date, and about text (HTML stripped); submissions filter out dead/deleted items
|
|
66
|
+
- Enrichment echoes `submissionOffset` and the offset to send next, or a notice when the requested offset is past the end of the history
|
|
70
67
|
|
|
71
68
|
---
|
|
72
69
|
|
|
73
|
-
### `hn_search_content`
|
|
70
|
+
### `hn_search_content` <sub>tool</sub>
|
|
74
71
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
-
|
|
78
|
-
-
|
|
79
|
-
- Sort by relevance or date
|
|
80
|
-
- Pagination with page/count controls
|
|
72
|
+
- Free-text `query` plus `tags` (`story`/`comment`/`poll`/`job`/`ask_hn`/`show_hn`/`front_page`), `author`, `storyId`, `dateRange`, and `minPoints` filters; `sort` by relevance or date; `count` (1–50, default 30) and `page` for pagination
|
|
73
|
+
- `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`
|
|
74
|
+
- `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`
|
|
75
|
+
- `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`
|
|
81
76
|
- `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
|
|
77
|
+
- Highlight metadata (`highlights.title`, `highlights.text`, `matchedWords`) shows which terms matched and where
|
|
78
|
+
- Enrichment reports `totalHits`, `page`, and the actual reachable `totalPages` — not derived from `totalHits`, since broad queries report far more hits than Algolia will serve. While more pages remain, `truncated` is set and `notice` names the next `page`; a page past the end gets a notice naming the last valid page (or `page: 0` past Algolia's 1,000-hit ceiling)
|
|
82
79
|
|
|
83
80
|
## Features
|
|
84
81
|
|
|
85
|
-
Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core):
|
|
86
|
-
|
|
87
|
-
- Declarative tool definitions — single file per tool, framework handles registration and validation
|
|
88
|
-
- Unified error handling across all tools
|
|
89
|
-
- Structured logging with request correlation
|
|
90
|
-
- Runs locally (stdio/HTTP) from the same codebase
|
|
82
|
+
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.
|
|
91
83
|
|
|
92
84
|
HN-specific:
|
|
93
85
|
|
|
94
|
-
-
|
|
95
|
-
- Concurrent batch fetching with configurable parallelism for item resolution
|
|
96
|
-
- HTML entity decoding and tag stripping
|
|
97
|
-
-
|
|
86
|
+
- Two upstream APIs: HN's Firebase API for feeds, items, and users; Algolia's HN Search API for full-text search
|
|
87
|
+
- Concurrent batch fetching with configurable parallelism for item resolution (`HN_CONCURRENCY_LIMIT`)
|
|
88
|
+
- HTML entity decoding and tag stripping, preserving code blocks and links
|
|
89
|
+
- Server-level `instructions` forwarded to LLM clients on `initialize` — item types, ID reuse across tools, case-sensitive usernames, field sparsity
|
|
90
|
+
- No API keys required — both upstream APIs are public
|
|
98
91
|
|
|
99
|
-
|
|
92
|
+
Agent-friendly output:
|
|
93
|
+
|
|
94
|
+
- 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
|
|
95
|
+
- 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
|
|
96
|
+
- 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
|
|
97
|
+
- 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
|
|
98
|
+
|
|
99
|
+
## Getting started
|
|
100
100
|
|
|
101
101
|
### Public Hosted Instance
|
|
102
102
|
|
|
@@ -191,51 +191,64 @@ All configuration is via environment variables. No API keys required — HN APIs
|
|
|
191
191
|
| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
|
|
192
192
|
| `MCP_HTTP_PORT` | HTTP server port. | `3010` |
|
|
193
193
|
| `MCP_HTTP_HOST` | HTTP server host. | `localhost` |
|
|
194
|
-
| `MCP_SESSION_MODE` | HTTP session handling: `
|
|
194
|
+
| `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` |
|
|
195
195
|
| `MCP_LOG_LEVEL` | Log level: `debug`, `info`, `notice`, `warning`, `error`. | `info` |
|
|
196
196
|
| `LOGS_DIR` | Directory for log files (Node.js only). | `<project-root>/logs` |
|
|
197
197
|
|
|
198
|
-
|
|
198
|
+
See [`.env.example`](./.env.example) for the full list of optional overrides.
|
|
199
199
|
|
|
200
|
-
|
|
200
|
+
## Running the server
|
|
201
201
|
|
|
202
|
-
|
|
203
|
-
MCP_TRANSPORT_TYPE=stdio bun --watch src/index.ts # Dev mode (stdio, auto-reload)
|
|
204
|
-
MCP_TRANSPORT_TYPE=http bun --watch src/index.ts # Dev mode (HTTP, auto-reload)
|
|
205
|
-
bun run test # Run test suite
|
|
206
|
-
bun run devcheck # Lint + format + typecheck + audit
|
|
207
|
-
```
|
|
202
|
+
### Local development
|
|
208
203
|
|
|
209
|
-
|
|
204
|
+
- **Dev mode (auto-reload):**
|
|
210
205
|
|
|
211
|
-
```sh
|
|
212
|
-
bun
|
|
213
|
-
bun
|
|
214
|
-
```
|
|
206
|
+
```sh
|
|
207
|
+
MCP_TRANSPORT_TYPE=stdio bun --watch src/index.ts # stdio
|
|
208
|
+
MCP_TRANSPORT_TYPE=http bun --watch src/index.ts # HTTP
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
- **Build and run:**
|
|
212
|
+
|
|
213
|
+
```sh
|
|
214
|
+
bun run rebuild
|
|
215
|
+
bun run start:stdio # or start:http
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
- **Run checks and tests:**
|
|
219
|
+
|
|
220
|
+
```sh
|
|
221
|
+
bun run devcheck # Lint, format, typecheck, security
|
|
222
|
+
bun run test # Vitest test suite
|
|
223
|
+
```
|
|
215
224
|
|
|
216
225
|
### Docker
|
|
217
226
|
|
|
218
227
|
```sh
|
|
219
228
|
docker build -t hn-mcp-server .
|
|
220
|
-
docker run -p 3010:3010 hn-mcp-server
|
|
229
|
+
docker run --rm -p 3010:3010 hn-mcp-server
|
|
221
230
|
```
|
|
222
231
|
|
|
223
|
-
|
|
232
|
+
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.
|
|
233
|
+
|
|
234
|
+
## Project structure
|
|
224
235
|
|
|
225
236
|
| Directory | Purpose |
|
|
226
237
|
|:----------|:--------|
|
|
227
|
-
| `src/index.ts` | `createApp()` entry point. |
|
|
228
|
-
| `src/config/` | Server-specific
|
|
229
|
-
| `src/services/hn/` | HN Firebase + Algolia API client and domain types. |
|
|
238
|
+
| `src/index.ts` | `createApp()` entry point — registers tools and inits the HN service. |
|
|
239
|
+
| `src/config/` | Server-specific environment variable parsing and validation with Zod. |
|
|
230
240
|
| `src/mcp-server/tools/definitions/` | Tool definitions (`*.tool.ts`). |
|
|
241
|
+
| `src/services/hn/` | HN Firebase + Algolia API client and domain types. |
|
|
242
|
+
| `tests/` | Unit and integration tests mirroring `src/`. |
|
|
231
243
|
|
|
232
|
-
## Development
|
|
244
|
+
## Development guide
|
|
233
245
|
|
|
234
246
|
See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
|
|
235
247
|
|
|
236
248
|
- Handlers throw, framework catches — no `try/catch` in tool logic
|
|
237
249
|
- Use `ctx.log` for request-scoped logging
|
|
238
250
|
- All tools are read-only — no auth scopes required
|
|
251
|
+
- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
|
|
239
252
|
|
|
240
253
|
## Contributing
|
|
241
254
|
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
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."
|
|
3
|
+
breaking: false
|
|
4
|
+
security: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 0.5.17 — 2026-09-19
|
|
8
|
+
|
|
9
|
+
## Added
|
|
10
|
+
|
|
11
|
+
- **`.github/workflows/codeql.yml`** — the one GitHub Actions workflow this server carries; runs only while the repo's CodeQL default setup stays off.
|
|
12
|
+
- **`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`.
|
|
13
|
+
- **The npm package now ships `AGENTS.md`** alongside `CLAUDE.md`.
|
|
14
|
+
|
|
15
|
+
## Changed
|
|
16
|
+
|
|
17
|
+
- **`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.
|
|
18
|
+
- **`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.
|
|
19
|
+
- **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.
|
|
20
|
+
- **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.
|
|
21
|
+
- **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)).
|
|
22
|
+
- **`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.
|
|
23
|
+
- `.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.
|
|
24
|
+
- 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.
|
|
25
|
+
- 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.
|
|
26
|
+
|
|
27
|
+
## Dependencies
|
|
28
|
+
|
|
29
|
+
- `@cyanheads/mcp-ts-core` ^0.13.0 → ^0.13.6
|
|
30
|
+
- `zod` ^4.6.1 → ^4.6.5
|
|
31
|
+
- `@biomejs/biome` ^2.5.13 → ^2.5.14
|
|
32
|
+
- `@types/node` ^26.5.1 → ^26.6.1
|
|
33
|
+
- `vitest` / `@vitest/coverage-istanbul` ^5.0.0 → ^5.0.1
|
|
34
|
+
- `tsc-alias` ^1.9.4 → ^1.9.5
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
---
|
|
2
|
+
summary: "hn_search_content gains filter-only and story-scoped search plus ISO 8601 date validation and minPoints guarding against unscored types; the feed, thread, and search tools now distinguish terminal pages from truncation."
|
|
3
|
+
breaking: false
|
|
4
|
+
security: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 0.5.18 — 2026-09-23
|
|
8
|
+
|
|
9
|
+
## Added
|
|
10
|
+
|
|
11
|
+
- **`hn_search_content.storyId`** restricts results to one discussion — the id of a story or poll root, sent as a `story_<id>` tag ANDed with the other filters. Pair with `tags: "comment"` to search within a thread. ([#22](https://github.com/cyanheads/hn-mcp-server/issues/22))
|
|
12
|
+
- **`hn_search_content.query` is now optional** when at least one filter (`tags`, `author`, `storyId`, `minPoints`, or a `dateRange` bound) is set, enabling filter-only searches — list Ask HN, Show HN, polls, or jobs on their own. No query and no filter fails with `missing_query_or_filter`. ([#22](https://github.com/cyanheads/hn-mcp-server/issues/22))
|
|
13
|
+
- **`hn_search_content.tags` gains `poll` and `job`.** ([#22](https://github.com/cyanheads/hn-mcp-server/issues/22))
|
|
14
|
+
|
|
15
|
+
## Fixed
|
|
16
|
+
|
|
17
|
+
- **`hn_get_stories`, `hn_get_thread`, and `hn_search_content` no longer report terminal pages as truncated.** `truncated` now tracks whether more results are retrievable, and its `notice` names the next `offset` (stories) or `page` (search), or for a thread how to get past `maxComments`, suggesting a larger cap only below its maximum. A search page past the end gets an exhausted-page notice instead of the broaden-keywords hint. ([#17](https://github.com/cyanheads/hn-mcp-server/issues/17))
|
|
18
|
+
- **`hn_search_content.dateRange` validates real ISO 8601 calendar instants.** Bounds accept `YYYY`, `YYYY-MM`, `YYYY-MM-DD`, or a date-time with an optional `Z`/`±hh:mm` offset; calendar-invalid values (`2024-02-30`) and non-ISO strings are rejected before any upstream call, and an offset-less date-time now reads as UTC instead of the host's local time zone. An empty `dateRange`, or `start` not before `end`, fails with `invalid_date_range`. ([#21](https://github.com/cyanheads/hn-mcp-server/issues/21))
|
|
19
|
+
- **`hn_search_content.minPoints` combined with `tags: "comment"` or `"job"` fails with `min_points_unscored_type`** instead of silently returning zero hits — Algolia stores no points on either record type. ([#28](https://github.com/cyanheads/hn-mcp-server/issues/28))
|
|
20
|
+
- **`hn_get_user.username` and `hn_search_content`'s `query`/`author` name the trim in their blank-input message** instead of Zod's default "Too small" length error. ([#24](https://github.com/cyanheads/hn-mcp-server/issues/24))
|
|
21
|
+
|
|
22
|
+
## Dependencies
|
|
23
|
+
|
|
24
|
+
- `@types/node` ^26.6.1 → ^26.6.2
|
package/changelog/template.md
CHANGED
|
@@ -6,8 +6,8 @@
|
|
|
6
6
|
|
|
7
7
|
# Required. One-line GitHub Release-style headline. 350 character cap — a
|
|
8
8
|
# ceiling, not a target. Default short and scannable. Don't pad, don't stitch
|
|
9
|
-
# unrelated changes with commas/semicolons into an inventory — pick the
|
|
10
|
-
# headline
|
|
9
|
+
# unrelated changes with commas/semicolons into an inventory — pick the one
|
|
10
|
+
# headline the release is about. Quotes required: unquoted YAML treats
|
|
11
11
|
# `: ` inside the value as a key separator and fails GitHub's strict parser.
|
|
12
12
|
summary: ""
|
|
13
13
|
|
|
@@ -119,11 +119,11 @@ security: false
|
|
|
119
119
|
TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
|
|
120
120
|
via `gh release create --notes-from-tag`. It is a condensed digest of this
|
|
121
121
|
entry, never a copy, and its format is owned by the `release-and-publish`
|
|
122
|
-
skill (step 4, "Create the annotated tag"):
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
122
|
+
skill (step 4, "Create the annotated tag"): a short subject line without the
|
|
123
|
+
version, flat headline bullets — no Keep-a-Changelog section headers, no
|
|
124
|
+
gates line — at most one deps line, issue backlinks, and the changelog link
|
|
125
|
+
last. In release-PR mode the `git-wrapup` skill authors those bullets as the
|
|
126
|
+
PR body's `## Changes` and the tag copies them.
|
|
127
127
|
-->
|
|
128
128
|
|
|
129
129
|
## Added
|
package/dist/index.js
CHANGED
|
@@ -13,8 +13,9 @@ await createApp({
|
|
|
13
13
|
name: 'hn-mcp-server',
|
|
14
14
|
title: 'hn-mcp-server',
|
|
15
15
|
tools: [getStories, getThread, getUser, searchHn],
|
|
16
|
-
instructions: 'Use the hn_* tools to access Hacker News via the Firebase API and Algolia search: ranked feeds
|
|
16
|
+
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.',
|
|
17
17
|
landing: { requireAuth: false },
|
|
18
|
+
sessionMode: 'stateless',
|
|
18
19
|
setup() {
|
|
19
20
|
initHnService();
|
|
20
21
|
},
|
package/dist/index.js.map
CHANGED
|
@@ -1 +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,
|
|
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"}
|
|
@@ -34,30 +34,35 @@ export declare const getStories: import("@cyanheads/mcp-ts-core").ToolDefinition
|
|
|
34
34
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
35
35
|
readonly when: "The HN API answered with a 4xx status other than 429 — it rejected the request as built.";
|
|
36
36
|
readonly recovery: "Check the input values against this schema; the same input fails identically.";
|
|
37
|
+
readonly thrownBy: "service";
|
|
37
38
|
}, {
|
|
38
39
|
readonly reason: "upstream_rate_limited";
|
|
39
40
|
readonly code: JsonRpcErrorCode.RateLimited;
|
|
40
41
|
readonly when: "The HN API answered with HTTP 429.";
|
|
41
42
|
readonly recovery: "Wait several seconds before retrying, and call this tool less often.";
|
|
42
43
|
readonly retryable: true;
|
|
44
|
+
readonly thrownBy: "service";
|
|
43
45
|
}, {
|
|
44
46
|
readonly reason: "upstream_unavailable";
|
|
45
47
|
readonly code: JsonRpcErrorCode.ServiceUnavailable;
|
|
46
48
|
readonly when: "The HN API answered with a 5xx status.";
|
|
47
49
|
readonly recovery: "Retry after a short delay; no input change helps while the upstream is down.";
|
|
48
50
|
readonly retryable: true;
|
|
51
|
+
readonly thrownBy: "service";
|
|
49
52
|
}, {
|
|
50
53
|
readonly reason: "upstream_html";
|
|
51
54
|
readonly code: JsonRpcErrorCode.ServiceUnavailable;
|
|
52
55
|
readonly when: "The HN API served an HTML error page with a 200 status, which it does under rate limiting or maintenance.";
|
|
53
56
|
readonly recovery: "Retry after a brief delay; the upstream is throttling or in maintenance.";
|
|
54
57
|
readonly retryable: true;
|
|
58
|
+
readonly thrownBy: "service";
|
|
55
59
|
}, {
|
|
56
60
|
readonly reason: "upstream_malformed";
|
|
57
61
|
readonly code: JsonRpcErrorCode.ServiceUnavailable;
|
|
58
62
|
readonly when: "The HN API answered with a 200 status and a body that is not JSON.";
|
|
59
63
|
readonly recovery: "Retry after a brief delay; no input change helps while the upstream serves this.";
|
|
60
64
|
readonly retryable: true;
|
|
65
|
+
readonly thrownBy: "service";
|
|
61
66
|
}], {
|
|
62
67
|
readonly total: z.ZodNumber;
|
|
63
68
|
readonly offset: z.ZodNumber;
|
|
@@ -1 +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;
|
|
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;AAYjE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqOrB,CAAC"}
|
|
@@ -5,6 +5,8 @@
|
|
|
5
5
|
import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
6
6
|
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
7
7
|
import { extractDomain, filterLiveItems, getHnService, normalizeUrl, stripHtml, } from '../../../services/hn/hn-service.js';
|
|
8
|
+
/** Largest page `count` accepts, mirrored in the input schema. */
|
|
9
|
+
const MAX_COUNT = 100;
|
|
8
10
|
export const getStories = tool('hn_get_stories', {
|
|
9
11
|
description: 'Fetch stories from an HN feed (top, new, best, ask, show, jobs), with title, URL, score, author, and comment count for each story.',
|
|
10
12
|
annotations: { readOnlyHint: true },
|
|
@@ -14,6 +16,7 @@ export const getStories = tool('hn_get_stories', {
|
|
|
14
16
|
code: JsonRpcErrorCode.InvalidParams,
|
|
15
17
|
when: 'The HN API answered with a 4xx status other than 429 — it rejected the request as built.',
|
|
16
18
|
recovery: 'Check the input values against this schema; the same input fails identically.',
|
|
19
|
+
thrownBy: 'service',
|
|
17
20
|
},
|
|
18
21
|
{
|
|
19
22
|
reason: 'upstream_rate_limited',
|
|
@@ -21,6 +24,7 @@ export const getStories = tool('hn_get_stories', {
|
|
|
21
24
|
when: 'The HN API answered with HTTP 429.',
|
|
22
25
|
recovery: 'Wait several seconds before retrying, and call this tool less often.',
|
|
23
26
|
retryable: true,
|
|
27
|
+
thrownBy: 'service',
|
|
24
28
|
},
|
|
25
29
|
{
|
|
26
30
|
reason: 'upstream_unavailable',
|
|
@@ -28,6 +32,7 @@ export const getStories = tool('hn_get_stories', {
|
|
|
28
32
|
when: 'The HN API answered with a 5xx status.',
|
|
29
33
|
recovery: 'Retry after a short delay; no input change helps while the upstream is down.',
|
|
30
34
|
retryable: true,
|
|
35
|
+
thrownBy: 'service',
|
|
31
36
|
},
|
|
32
37
|
{
|
|
33
38
|
reason: 'upstream_html',
|
|
@@ -35,6 +40,7 @@ export const getStories = tool('hn_get_stories', {
|
|
|
35
40
|
when: 'The HN API served an HTML error page with a 200 status, which it does under rate limiting or maintenance.',
|
|
36
41
|
recovery: 'Retry after a brief delay; the upstream is throttling or in maintenance.',
|
|
37
42
|
retryable: true,
|
|
43
|
+
thrownBy: 'service',
|
|
38
44
|
},
|
|
39
45
|
{
|
|
40
46
|
reason: 'upstream_malformed',
|
|
@@ -42,6 +48,7 @@ export const getStories = tool('hn_get_stories', {
|
|
|
42
48
|
when: 'The HN API answered with a 200 status and a body that is not JSON.',
|
|
43
49
|
recovery: 'Retry after a brief delay; no input change helps while the upstream serves this.',
|
|
44
50
|
retryable: true,
|
|
51
|
+
thrownBy: 'service',
|
|
45
52
|
},
|
|
46
53
|
],
|
|
47
54
|
input: z.object({
|
|
@@ -52,7 +59,7 @@ export const getStories = tool('hn_get_stories', {
|
|
|
52
59
|
.number()
|
|
53
60
|
.int()
|
|
54
61
|
.min(1)
|
|
55
|
-
.max(
|
|
62
|
+
.max(MAX_COUNT)
|
|
56
63
|
.default(30)
|
|
57
64
|
.describe('Number of stories to return. Larger counts take longer.'),
|
|
58
65
|
offset: z
|
|
@@ -111,13 +118,13 @@ export const getStories = tool('hn_get_stories', {
|
|
|
111
118
|
truncated: z
|
|
112
119
|
.boolean()
|
|
113
120
|
.optional()
|
|
114
|
-
.describe('True when
|
|
121
|
+
.describe('True when more stories remain beyond this page (hasMore). Absent on the last page of the feed.'),
|
|
115
122
|
shown: z.number().optional().describe('Number of stories returned on this page.'),
|
|
116
123
|
cap: z.number().optional().describe('The count cap that was applied.'),
|
|
117
124
|
notice: z
|
|
118
125
|
.string()
|
|
119
126
|
.optional()
|
|
120
|
-
.describe('
|
|
127
|
+
.describe('Agent guidance: the offset to pass for the next page while more stories remain, or why a page came back empty — offset past the end of the feed, an empty feed, or every item on the page deleted or flagged. Absent on the last page of a non-empty result.'),
|
|
121
128
|
},
|
|
122
129
|
async handler(input, ctx) {
|
|
123
130
|
const hn = getHnService();
|
|
@@ -143,12 +150,22 @@ export const getStories = tool('hn_get_stories', {
|
|
|
143
150
|
});
|
|
144
151
|
ctx.log.info('Fetched stories', { feed: input.feed, count: stories.length });
|
|
145
152
|
const total = feedIds.length;
|
|
146
|
-
const
|
|
153
|
+
const nextOffset = input.offset + input.count;
|
|
154
|
+
const hasMore = nextOffset < total;
|
|
147
155
|
ctx.enrich({ total, offset: input.offset, hasMore });
|
|
148
|
-
|
|
149
|
-
|
|
156
|
+
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.`;
|
|
157
|
+
if (hasMore) {
|
|
158
|
+
const raiseCount = input.count < MAX_COUNT ? `, or raise count (max ${MAX_COUNT})` : '';
|
|
159
|
+
const nextPage = `Pass offset: ${nextOffset} for the next page${raiseCount}.`;
|
|
160
|
+
ctx.enrich.truncated({
|
|
161
|
+
shown: stories.length,
|
|
162
|
+
cap: input.count,
|
|
163
|
+
guidance: stories.length === 0
|
|
164
|
+
? `${deadPageMessage} ${nextPage}`
|
|
165
|
+
: `Showing items ${input.offset + 1}–${nextOffset} of ${total} in the ${input.feed} feed. ${nextPage}`,
|
|
166
|
+
});
|
|
150
167
|
}
|
|
151
|
-
if (stories.length === 0) {
|
|
168
|
+
else if (stories.length === 0) {
|
|
152
169
|
if (total === 0) {
|
|
153
170
|
ctx.enrich.notice(`${input.feed} feed is empty.`);
|
|
154
171
|
}
|
|
@@ -156,7 +173,7 @@ export const getStories = tool('hn_get_stories', {
|
|
|
156
173
|
ctx.enrich.notice(`Offset ${input.offset} is past the end of the ${input.feed} feed (${total} item${total === 1 ? '' : 's'}). Reset offset below ${total}.`);
|
|
157
174
|
}
|
|
158
175
|
else {
|
|
159
|
-
ctx.enrich.notice(
|
|
176
|
+
ctx.enrich.notice(deadPageMessage);
|
|
160
177
|
}
|
|
161
178
|
}
|
|
162
179
|
return {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"get-stories.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-stories.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EACL,aAAa,EACb,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,SAAS,GACV,MAAM,6BAA6B,CAAC;AAErC,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAC,gBAAgB,EAAE;IAC/C,WAAW,EACT,oIAAoI;IACtI,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;IACnC,MAAM,EAAE;QACN;YACE,MAAM,EAAE,mBAAmB;YAC3B,IAAI,EAAE,gBAAgB,CAAC,aAAa;YACpC,IAAI,EAAE,0FAA0F;YAChG,QAAQ,EAAE,+EAA+E;
|
|
1
|
+
{"version":3,"file":"get-stories.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-stories.tool.ts"],"names":[],"mappings":"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"}
|
|
@@ -35,35 +35,41 @@ export declare const getThread: import("@cyanheads/mcp-ts-core").ToolDefinition<
|
|
|
35
35
|
readonly code: JsonRpcErrorCode.NotFound;
|
|
36
36
|
readonly when: "HN reports no item exists for the given itemId.";
|
|
37
37
|
readonly recovery: "Verify the itemId via hn_search_content or a feed listing from hn_get_stories.";
|
|
38
|
+
readonly severity: "notice";
|
|
38
39
|
}, {
|
|
39
40
|
readonly reason: "upstream_rejected";
|
|
40
41
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
41
42
|
readonly when: "The HN API answered with a 4xx status other than 429 — it rejected the request as built.";
|
|
42
43
|
readonly recovery: "Check the input values against this schema; the same input fails identically.";
|
|
44
|
+
readonly thrownBy: "service";
|
|
43
45
|
}, {
|
|
44
46
|
readonly reason: "upstream_rate_limited";
|
|
45
47
|
readonly code: JsonRpcErrorCode.RateLimited;
|
|
46
48
|
readonly when: "The HN API answered with HTTP 429.";
|
|
47
49
|
readonly recovery: "Wait several seconds before retrying, and call this tool less often.";
|
|
48
50
|
readonly retryable: true;
|
|
51
|
+
readonly thrownBy: "service";
|
|
49
52
|
}, {
|
|
50
53
|
readonly reason: "upstream_unavailable";
|
|
51
54
|
readonly code: JsonRpcErrorCode.ServiceUnavailable;
|
|
52
55
|
readonly when: "The HN API answered with a 5xx status.";
|
|
53
56
|
readonly recovery: "Retry after a short delay; no input change helps while the upstream is down.";
|
|
54
57
|
readonly retryable: true;
|
|
58
|
+
readonly thrownBy: "service";
|
|
55
59
|
}, {
|
|
56
60
|
readonly reason: "upstream_html";
|
|
57
61
|
readonly code: JsonRpcErrorCode.ServiceUnavailable;
|
|
58
62
|
readonly when: "The HN API served an HTML error page with a 200 status, which it does under rate limiting or maintenance.";
|
|
59
63
|
readonly recovery: "Retry after a brief delay; the upstream is throttling or in maintenance.";
|
|
60
64
|
readonly retryable: true;
|
|
65
|
+
readonly thrownBy: "service";
|
|
61
66
|
}, {
|
|
62
67
|
readonly reason: "upstream_malformed";
|
|
63
68
|
readonly code: JsonRpcErrorCode.ServiceUnavailable;
|
|
64
69
|
readonly when: "The HN API answered with a 200 status and a body that is not JSON.";
|
|
65
70
|
readonly recovery: "Retry after a brief delay; no input change helps while the upstream serves this.";
|
|
66
71
|
readonly retryable: true;
|
|
72
|
+
readonly thrownBy: "service";
|
|
67
73
|
}], {
|
|
68
74
|
readonly totalLoaded: z.ZodNumber;
|
|
69
75
|
readonly totalAvailable: z.ZodOptional<z.ZodNumber>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"get-thread.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-thread.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;
|
|
1
|
+
{"version":3,"file":"get-thread.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-thread.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAMjE,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4UpB,CAAC"}
|