@cyanheads/hn-mcp-server 0.5.18 → 0.5.20
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 +6 -3
- package/CLAUDE.md +6 -3
- package/README.md +15 -8
- package/changelog/0.5.x/0.5.19.md +19 -0
- package/changelog/0.5.x/0.5.20.md +23 -0
- package/dist/mcp-server/tools/definitions/get-stories.tool.d.ts +2 -1
- package/dist/mcp-server/tools/definitions/get-stories.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-stories.tool.js +37 -14
- package/dist/mcp-server/tools/definitions/get-stories.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-thread.tool.d.ts +30 -2
- package/dist/mcp-server/tools/definitions/get-thread.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-thread.tool.js +516 -174
- package/dist/mcp-server/tools/definitions/get-thread.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-user.tool.d.ts +4 -1
- package/dist/mcp-server/tools/definitions/get-user.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-user.tool.js +64 -26
- package/dist/mcp-server/tools/definitions/get-user.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-content.tool.d.ts +1 -1
- package/dist/mcp-server/tools/definitions/search-content.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-content.tool.js +41 -18
- package/dist/mcp-server/tools/definitions/search-content.tool.js.map +1 -1
- package/dist/mcp-server/tools/markdown-escape.d.ts +38 -0
- package/dist/mcp-server/tools/markdown-escape.d.ts.map +1 -0
- package/dist/mcp-server/tools/markdown-escape.js +76 -0
- package/dist/mcp-server/tools/markdown-escape.js.map +1 -0
- package/dist/services/hn/hn-service.d.ts +72 -17
- package/dist/services/hn/hn-service.d.ts.map +1 -1
- package/dist/services/hn/hn-service.js +235 -59
- package/dist/services/hn/hn-service.js.map +1 -1
- package/package.json +1 -1
- package/server.json +3 -3
package/AGENTS.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Developer Protocol
|
|
2
2
|
|
|
3
3
|
**Server:** hn-mcp-server
|
|
4
|
-
**Version:** 0.5.
|
|
4
|
+
**Version:** 0.5.20
|
|
5
5
|
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
|
|
6
6
|
**Engines:** Bun ≥1.4.0, Node ≥24.0.0
|
|
7
7
|
**MCP SDK:** `@modelcontextprotocol/server` 2.0.0
|
|
@@ -48,7 +48,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
|
|
|
48
48
|
|
|
49
49
|
```ts
|
|
50
50
|
import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
51
|
-
import { getHnService,
|
|
51
|
+
import { getHnService, settlePage, normalizeUrl, stripHtml } from '@/services/hn/hn-service.js';
|
|
52
52
|
|
|
53
53
|
export const getStories = tool('hn_get_stories', {
|
|
54
54
|
description: 'Fetch stories from an HN feed (top, new, best, ask, show, jobs).',
|
|
@@ -72,7 +72,9 @@ export const getStories = tool('hn_get_stories', {
|
|
|
72
72
|
const hn = getHnService();
|
|
73
73
|
const feedIds = await hn.fetchFeed(input.feed, ctx);
|
|
74
74
|
const sliced = feedIds.slice(input.offset, input.offset + input.count);
|
|
75
|
-
|
|
75
|
+
// Live items plus the IDs whose fetch failed; throws when every item failed.
|
|
76
|
+
const { items, failedIds } = settlePage(await hn.fetchItems(sliced, ctx));
|
|
77
|
+
if (failedIds.length > 0) ctx.enrich({ failedIds });
|
|
76
78
|
ctx.log.info('Fetched stories', { feed: input.feed, count: items.length });
|
|
77
79
|
return { stories: items.map(/* ... */), feed: input.feed, total: feedIds.length };
|
|
78
80
|
},
|
|
@@ -217,6 +219,7 @@ src/
|
|
|
217
219
|
hn-service.ts # HN Firebase + Algolia API client
|
|
218
220
|
types.ts # HN domain types
|
|
219
221
|
mcp-server/
|
|
222
|
+
tools/markdown-escape.ts # format() boundary: escape titles, quote bodies
|
|
220
223
|
tools/definitions/
|
|
221
224
|
get-stories.tool.ts # hn_get_stories — Fetch stories from an HN feed
|
|
222
225
|
get-thread.tool.ts # hn_get_thread — Get item + comment tree
|
package/CLAUDE.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Developer Protocol
|
|
2
2
|
|
|
3
3
|
**Server:** hn-mcp-server
|
|
4
|
-
**Version:** 0.5.
|
|
4
|
+
**Version:** 0.5.20
|
|
5
5
|
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
|
|
6
6
|
**Engines:** Bun ≥1.4.0, Node ≥24.0.0
|
|
7
7
|
**MCP SDK:** `@modelcontextprotocol/server` 2.0.0
|
|
@@ -48,7 +48,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
|
|
|
48
48
|
|
|
49
49
|
```ts
|
|
50
50
|
import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
51
|
-
import { getHnService,
|
|
51
|
+
import { getHnService, settlePage, normalizeUrl, stripHtml } from '@/services/hn/hn-service.js';
|
|
52
52
|
|
|
53
53
|
export const getStories = tool('hn_get_stories', {
|
|
54
54
|
description: 'Fetch stories from an HN feed (top, new, best, ask, show, jobs).',
|
|
@@ -72,7 +72,9 @@ export const getStories = tool('hn_get_stories', {
|
|
|
72
72
|
const hn = getHnService();
|
|
73
73
|
const feedIds = await hn.fetchFeed(input.feed, ctx);
|
|
74
74
|
const sliced = feedIds.slice(input.offset, input.offset + input.count);
|
|
75
|
-
|
|
75
|
+
// Live items plus the IDs whose fetch failed; throws when every item failed.
|
|
76
|
+
const { items, failedIds } = settlePage(await hn.fetchItems(sliced, ctx));
|
|
77
|
+
if (failedIds.length > 0) ctx.enrich({ failedIds });
|
|
76
78
|
ctx.log.info('Fetched stories', { feed: input.feed, count: items.length });
|
|
77
79
|
return { stories: items.map(/* ... */), feed: input.feed, total: feedIds.length };
|
|
78
80
|
},
|
|
@@ -217,6 +219,7 @@ src/
|
|
|
217
219
|
hn-service.ts # HN Firebase + Algolia API client
|
|
218
220
|
types.ts # HN domain types
|
|
219
221
|
mcp-server/
|
|
222
|
+
tools/markdown-escape.ts # format() boundary: escape titles, quote bodies
|
|
220
223
|
tools/definitions/
|
|
221
224
|
get-stories.tool.ts # hn_get_stories — Fetch stories from an HN feed
|
|
222
225
|
get-thread.tool.ts # hn_get_thread — Get item + comment tree
|
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
|
|
|
@@ -36,7 +36,7 @@ Feeds, threads, and profiles from the Hacker News Firebase API and Algolia Searc
|
|
|
36
36
|
| Tool | Description |
|
|
37
37
|
|:---|:---|
|
|
38
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 |
|
|
39
|
+
| `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 |
|
|
40
40
|
| `hn_get_user` | Fetch a user profile with karma, about, and optionally a page of resolved submissions |
|
|
41
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
|
|
|
@@ -47,15 +47,19 @@ Feeds, threads, and profiles from the Hacker News Firebase API and Algolia Searc
|
|
|
47
47
|
- Six feed types: `top`, `new`, `best`, `ask`, `show`, `jobs`; `count` (1–100, default 30) and `offset` for pagination
|
|
48
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
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
|
+
- 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
|
|
50
51
|
|
|
51
52
|
---
|
|
52
53
|
|
|
53
54
|
### `hn_get_thread` <sub>tool</sub>
|
|
54
55
|
|
|
55
|
-
- `itemId` plus `depth` (0–10, default 3; 0 returns the item with no comments) and `maxComments` (1–200, default 50) capping
|
|
56
|
+
- `itemId` plus `depth` (0–10, default 3; 0 returns the item with no comments) and `maxComments` (1–200, default 50) capping one response across all levels, alongside a fixed 64,000-byte text budget that cuts only between comments
|
|
56
57
|
- Breadth-first traversal ranked like HN — top-ranked top-level comments resolve first, replies fill in only after the level above is exhausted
|
|
58
|
+
- Resumable: a response stopped by `maxComments`, the byte budget, or an upstream rate limit returns `nextCursor`; passing it back as `cursor` with the same `itemId` continues at the next unseen comment. The cursor carries the unvisited comments themselves, so re-ranked replies cannot shift it, and the server keeps no session state. A cursor passed with a different `itemId` fails with `invalid_cursor`
|
|
59
|
+
- The root carries its relationships and state: `parent` for a comment, `poll` for a poll option, `parts` and resolved `options` (text and votes, at every depth) for a poll, and `deleted`/`dead` markers. The `content[]` heading names the type — a title, `Comment by <author>`, `Poll option by <author> on poll <id>` — and marks a deleted or dead root
|
|
57
60
|
- 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
|
-
- `
|
|
61
|
+
- `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`
|
|
62
|
+
- 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
|
|
59
63
|
|
|
60
64
|
---
|
|
61
65
|
|
|
@@ -63,7 +67,9 @@ Feeds, threads, and profiles from the Hacker News Firebase API and Algolia Searc
|
|
|
63
67
|
|
|
64
68
|
- `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
69
|
- Profile includes karma, creation date, and about text (HTML stripped); submissions filter out dead/deleted items
|
|
70
|
+
- A comment submission carries its `parent` and a poll-option submission its `poll`, so either links back to what it answered
|
|
66
71
|
- Enrichment echoes `submissionOffset` and the offset to send next, or a notice when the requested offset is past the end of the history
|
|
72
|
+
- 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
|
|
67
73
|
|
|
68
74
|
---
|
|
69
75
|
|
|
@@ -85,16 +91,17 @@ HN-specific:
|
|
|
85
91
|
|
|
86
92
|
- Two upstream APIs: HN's Firebase API for feeds, items, and users; Algolia's HN Search API for full-text search
|
|
87
93
|
- Concurrent batch fetching with configurable parallelism for item resolution (`HN_CONCURRENCY_LIMIT`)
|
|
88
|
-
- HTML
|
|
94
|
+
- 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
|
|
89
95
|
- Server-level `instructions` forwarded to LLM clients on `initialize` — item types, ID reuse across tools, case-sensitive usernames, field sparsity
|
|
90
96
|
- No API keys required — both upstream APIs are public
|
|
91
97
|
|
|
92
98
|
Agent-friendly output:
|
|
93
99
|
|
|
94
|
-
- Graceful partial failure —
|
|
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
|
|
100
|
+
- 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
|
|
101
|
+
- 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
|
|
102
|
+
- Pagination provenance — every paged listing echoes the offset it used (`offset`, `submissionOffset`, `page`) plus the exact next-offset value in `notice`, and `hn_get_thread` returns a self-contained `nextCursor`, so an agent can resume without recomputing state
|
|
97
103
|
- 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
|
|
104
|
+
- 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
|
|
98
105
|
|
|
99
106
|
## Getting started
|
|
100
107
|
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
---
|
|
2
|
+
summary: "hn_get_thread gains a resumable cursor, root relationships, and poll options; hn_get_stories/hn_get_thread/hn_get_user report failed item fetches instead of dropping them, and a 429's Retry-After now reaches the recovery hint."
|
|
3
|
+
breaking: false
|
|
4
|
+
security: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 0.5.19 — 2026-09-23
|
|
8
|
+
|
|
9
|
+
## Added
|
|
10
|
+
|
|
11
|
+
- **`hn_get_thread.cursor` / `nextCursor`** resume a traversal cut by `maxComments`, a new 64,000-byte response budget, a 1,000-item ceiling on what one call examines, or a rate limit, without skipping or repeating comments. `truncationReason` (`count`, `size`, `rate_limited`, `depth`) replaces the old raise-`maxComments`-or-`depth` guidance, and an `invalid_cursor` reason fires when a cursor is passed with a different `itemId`. ([#20](https://github.com/cyanheads/hn-mcp-server/issues/20))
|
|
12
|
+
- **`hn_get_thread`'s root** carries `parent` (comment roots), `poll` (poll-option roots), `parts` and resolved `options` (poll roots, resolved at every `depth` including `0`), and `deleted`/`dead` markers; the `content[]` heading is type-aware. `hn_get_user` submissions carry the same `parent`/`poll` links. ([#19](https://github.com/cyanheads/hn-mcp-server/issues/19))
|
|
13
|
+
- **`failedIds`** on `hn_get_stories`, `hn_get_thread`, and `hn_get_user` names items whose fetch failed after retries, apart from deleted, dead, or missing ones, with a retry notice. An `hn_get_stories` or `hn_get_user` page where every item failed now throws the classified upstream error instead of returning empty; `hn_get_thread` still returns its root. A rate-limited item stops the batch rather than sending every remaining item through its own retry ladder. ([#18](https://github.com/cyanheads/hn-mcp-server/issues/18))
|
|
14
|
+
- **A 429's `Retry-After` header** passes through unchanged as `data.retryAfter` and the recovery hint, naming the exact wait instead of a generic "several seconds". ([#26](https://github.com/cyanheads/hn-mcp-server/issues/26))
|
|
15
|
+
|
|
16
|
+
## Fixed
|
|
17
|
+
|
|
18
|
+
- **`hn_search_content.dateRange.end`** rounds a fractional second up instead of down, so an item created in that same whole second is no longer excluded.
|
|
19
|
+
- **`hn_search_content`'s `invalid_date_range` check** compares `start` and `end` as exact instants instead of truncated seconds, so two bounds within the same second are no longer rejected as out of order.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
---
|
|
2
|
+
summary: "Upstream text is fenced in content[] so a comment or highlight body can no longer pass for server-authored lines, titles are entity-decoded instead of HTML-stripped, each HN link renders once as its full URL, and typed placeholder text survives stripping."
|
|
3
|
+
breaking: false
|
|
4
|
+
security: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 0.5.20 — 2026-09-23
|
|
8
|
+
|
|
9
|
+
## Changed
|
|
10
|
+
|
|
11
|
+
- **Links in HN bodies render once, as the full href**, when the link text is the href or a `...`-truncated prefix of it (compared after entity decoding); any other link keeps `text (href)`. In highlight snippets the `<em>` markers stay on the matched characters of the href. ([#25](https://github.com/cyanheads/hn-mcp-server/issues/25))
|
|
12
|
+
|
|
13
|
+
## Fixed
|
|
14
|
+
|
|
15
|
+
- **Titles are no longer HTML-stripped**: `title`, `stories[].title`, `submissions[].title`, search `title` / `storyTitle`, and `highlights.title` are entity-decoded once and keep tag-like text such as `The <Dialog> Element`. ([#23](https://github.com/cyanheads/hn-mcp-server/issues/23))
|
|
16
|
+
- **Placeholder text is no longer rewritten by `stripHtml`**: typed `@@CODE_0@@` or `@@EM_OPEN@@` passes through unchanged, and a numeric entity past U+10FFFF decodes to U+FFFD instead of throwing. ([#30](https://github.com/cyanheads/hn-mcp-server/issues/30))
|
|
17
|
+
- **`decodeHtmlEntities` decodes only its declared named entities**: an inherited name such as `&constructor;` stays as typed instead of rendering `function Object() { [native code] }`, link hrefs included.
|
|
18
|
+
|
|
19
|
+
## Security
|
|
20
|
+
|
|
21
|
+
- **Upstream bodies in `content[]` are fenced as `> ` quotes** — item and comment text, `about`, hit text, and the highlight body — so a body line cannot pass for a comment header, heading, or the `> match —` footer, which now lists the body snippet last. ([#23](https://github.com/cyanheads/hn-mcp-server/issues/23))
|
|
22
|
+
- **A quoted body line shaped like a link reference definition has its leading `[` escaped** (`> \[1]: url`), since CommonMark applies definitions document-wide and one could turn `[1]` or `[deleted]` in server text into a link. ([#23](https://github.com/cyanheads/hn-mcp-server/issues/23))
|
|
23
|
+
- **Single-line fields are escaped at the render boundary**: titles, title highlights, and poll-option text escape only the characters that could break the surrounding Markdown and collapse line breaks to a space; usernames, URLs, and IDs stay verbatim. ([#23](https://github.com/cyanheads/hn-mcp-server/issues/23))
|
|
@@ -39,7 +39,7 @@ export declare const getStories: import("@cyanheads/mcp-ts-core").ToolDefinition
|
|
|
39
39
|
readonly reason: "upstream_rate_limited";
|
|
40
40
|
readonly code: JsonRpcErrorCode.RateLimited;
|
|
41
41
|
readonly when: "The HN API answered with HTTP 429.";
|
|
42
|
-
readonly recovery: "Wait several seconds
|
|
42
|
+
readonly recovery: "Wait the interval in retryAfter when the error carries one, otherwise several seconds, then retry and call this tool less often.";
|
|
43
43
|
readonly retryable: true;
|
|
44
44
|
readonly thrownBy: "service";
|
|
45
45
|
}, {
|
|
@@ -70,6 +70,7 @@ export declare const getStories: import("@cyanheads/mcp-ts-core").ToolDefinition
|
|
|
70
70
|
readonly truncated: z.ZodOptional<z.ZodBoolean>;
|
|
71
71
|
readonly shown: z.ZodOptional<z.ZodNumber>;
|
|
72
72
|
readonly cap: z.ZodOptional<z.ZodNumber>;
|
|
73
|
+
readonly failedIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
|
|
73
74
|
readonly notice: z.ZodOptional<z.ZodString>;
|
|
74
75
|
}>;
|
|
75
76
|
//# sourceMappingURL=get-stories.tool.d.ts.map
|
|
@@ -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;AAcjE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8PrB,CAAC"}
|
|
@@ -4,7 +4,8 @@
|
|
|
4
4
|
*/
|
|
5
5
|
import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
6
6
|
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
7
|
-
import {
|
|
7
|
+
import { escapeInline, quoteBody } from '../markdown-escape.js';
|
|
8
|
+
import { decodeHtmlEntities, extractDomain, getHnService, normalizeUrl, settlePage, stripHtml, } from '../../../services/hn/hn-service.js';
|
|
8
9
|
/** Largest page `count` accepts, mirrored in the input schema. */
|
|
9
10
|
const MAX_COUNT = 100;
|
|
10
11
|
export const getStories = tool('hn_get_stories', {
|
|
@@ -22,7 +23,7 @@ export const getStories = tool('hn_get_stories', {
|
|
|
22
23
|
reason: 'upstream_rate_limited',
|
|
23
24
|
code: JsonRpcErrorCode.RateLimited,
|
|
24
25
|
when: 'The HN API answered with HTTP 429.',
|
|
25
|
-
recovery: 'Wait several seconds
|
|
26
|
+
recovery: 'Wait the interval in retryAfter when the error carries one, otherwise several seconds, then retry and call this tool less often.',
|
|
26
27
|
retryable: true,
|
|
27
28
|
thrownBy: 'service',
|
|
28
29
|
},
|
|
@@ -121,24 +122,30 @@ export const getStories = tool('hn_get_stories', {
|
|
|
121
122
|
.describe('True when more stories remain beyond this page (hasMore). Absent on the last page of the feed.'),
|
|
122
123
|
shown: z.number().optional().describe('Number of stories returned on this page.'),
|
|
123
124
|
cap: z.number().optional().describe('The count cap that was applied.'),
|
|
125
|
+
failedIds: z
|
|
126
|
+
.array(z.number())
|
|
127
|
+
.optional()
|
|
128
|
+
.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.'),
|
|
124
129
|
notice: z
|
|
125
130
|
.string()
|
|
126
131
|
.optional()
|
|
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.'),
|
|
132
|
+
.describe('Agent guidance: the offset to pass for the next page while more stories remain, the IDs that failed to load and how to retry them, or why a page came back empty — offset past the end of the feed, an empty feed, or every item on the page deleted or flagged. Absent on the last page of a non-empty result with no failed IDs.'),
|
|
133
|
+
},
|
|
134
|
+
enrichmentTrailer: {
|
|
135
|
+
failedIds: { render: (ids) => `**Failed to load:** ${(ids ?? []).join(', ')}` },
|
|
128
136
|
},
|
|
129
137
|
async handler(input, ctx) {
|
|
130
138
|
const hn = getHnService();
|
|
131
139
|
const feedIds = await hn.fetchFeed(input.feed, ctx);
|
|
132
140
|
const sliced = feedIds.slice(input.offset, input.offset + input.count);
|
|
133
|
-
const
|
|
134
|
-
const items = filterLiveItems(rawItems);
|
|
141
|
+
const { items, failedIds } = settlePage(await hn.fetchItems(sliced, ctx));
|
|
135
142
|
const stories = items.map((item) => {
|
|
136
143
|
const url = normalizeUrl(item.url);
|
|
137
144
|
const domain = extractDomain(url);
|
|
138
145
|
return {
|
|
139
146
|
id: item.id,
|
|
140
147
|
type: item.type,
|
|
141
|
-
...(item.title && { title:
|
|
148
|
+
...(item.title && { title: decodeHtmlEntities(item.title) }),
|
|
142
149
|
...(url && { url }),
|
|
143
150
|
...(domain && { domain }),
|
|
144
151
|
...(item.score != null && { score: item.score }),
|
|
@@ -148,21 +155,34 @@ export const getStories = tool('hn_get_stories', {
|
|
|
148
155
|
...(item.text && { text: stripHtml(item.text) }),
|
|
149
156
|
};
|
|
150
157
|
});
|
|
151
|
-
ctx.log.info('Fetched stories', {
|
|
158
|
+
ctx.log.info('Fetched stories', {
|
|
159
|
+
feed: input.feed,
|
|
160
|
+
count: stories.length,
|
|
161
|
+
failed: failedIds.length,
|
|
162
|
+
});
|
|
152
163
|
const total = feedIds.length;
|
|
153
164
|
const nextOffset = input.offset + input.count;
|
|
154
165
|
const hasMore = nextOffset < total;
|
|
155
|
-
ctx.enrich({
|
|
166
|
+
ctx.enrich({
|
|
167
|
+
total,
|
|
168
|
+
offset: input.offset,
|
|
169
|
+
hasMore,
|
|
170
|
+
...(failedIds.length > 0 && { failedIds }),
|
|
171
|
+
});
|
|
156
172
|
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.`;
|
|
173
|
+
const failureMessage = failedIds.length > 0
|
|
174
|
+
? `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.`
|
|
175
|
+
: undefined;
|
|
157
176
|
if (hasMore) {
|
|
158
177
|
const raiseCount = input.count < MAX_COUNT ? `, or raise count (max ${MAX_COUNT})` : '';
|
|
159
178
|
const nextPage = `Pass offset: ${nextOffset} for the next page${raiseCount}.`;
|
|
179
|
+
const pageStatus = stories.length === 0 && !failureMessage
|
|
180
|
+
? deadPageMessage
|
|
181
|
+
: `Showing items ${input.offset + 1}–${nextOffset} of ${total} in the ${input.feed} feed.`;
|
|
160
182
|
ctx.enrich.truncated({
|
|
161
183
|
shown: stories.length,
|
|
162
184
|
cap: input.count,
|
|
163
|
-
guidance:
|
|
164
|
-
? `${deadPageMessage} ${nextPage}`
|
|
165
|
-
: `Showing items ${input.offset + 1}–${nextOffset} of ${total} in the ${input.feed} feed. ${nextPage}`,
|
|
185
|
+
guidance: [pageStatus, failureMessage, nextPage].filter(Boolean).join(' '),
|
|
166
186
|
});
|
|
167
187
|
}
|
|
168
188
|
else if (stories.length === 0) {
|
|
@@ -173,9 +193,12 @@ export const getStories = tool('hn_get_stories', {
|
|
|
173
193
|
ctx.enrich.notice(`Offset ${input.offset} is past the end of the ${input.feed} feed (${total} item${total === 1 ? '' : 's'}). Reset offset below ${total}.`);
|
|
174
194
|
}
|
|
175
195
|
else {
|
|
176
|
-
ctx.enrich.notice(deadPageMessage);
|
|
196
|
+
ctx.enrich.notice(failureMessage ?? deadPageMessage);
|
|
177
197
|
}
|
|
178
198
|
}
|
|
199
|
+
else if (failureMessage) {
|
|
200
|
+
ctx.enrich.notice(failureMessage);
|
|
201
|
+
}
|
|
179
202
|
return {
|
|
180
203
|
stories,
|
|
181
204
|
feed: input.feed,
|
|
@@ -201,8 +224,8 @@ export const getStories = tool('hn_get_stories', {
|
|
|
201
224
|
.filter(Boolean)
|
|
202
225
|
.join(' | ');
|
|
203
226
|
const url = s.url ? `\n${s.url}` : '';
|
|
204
|
-
const text = s.text ? `\n${s.text}` : '';
|
|
205
|
-
const title = s.title
|
|
227
|
+
const text = s.text ? `\n${quoteBody(s.text)}` : '';
|
|
228
|
+
const title = s.title ? escapeInline(s.title) : `[${s.type}]`;
|
|
206
229
|
const domain = s.domain ? ` (${s.domain})` : '';
|
|
207
230
|
return `[${rank}] ${title}${domain}\n${meta}${url}${text}`;
|
|
208
231
|
});
|
|
@@ -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,
|
|
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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"}
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* @fileoverview Fetch an HN item and its comment tree via ranked BFS traversal
|
|
2
|
+
* @fileoverview Fetch an HN item and its comment tree via ranked BFS traversal,
|
|
3
|
+
* resumable through a cursor that carries the unvisited frontier.
|
|
3
4
|
* @module mcp-server/tools/definitions/get-thread.tool
|
|
4
5
|
*/
|
|
5
6
|
import { z } from '@cyanheads/mcp-ts-core';
|
|
@@ -8,6 +9,7 @@ export declare const getThread: import("@cyanheads/mcp-ts-core").ToolDefinition<
|
|
|
8
9
|
itemId: z.ZodNumber;
|
|
9
10
|
depth: z.ZodDefault<z.ZodNumber>;
|
|
10
11
|
maxComments: z.ZodDefault<z.ZodNumber>;
|
|
12
|
+
cursor: z.ZodOptional<z.ZodString>;
|
|
11
13
|
}, z.core.$strip>, z.ZodObject<{
|
|
12
14
|
item: z.ZodObject<{
|
|
13
15
|
id: z.ZodNumber;
|
|
@@ -19,6 +21,18 @@ export declare const getThread: import("@cyanheads/mcp-ts-core").ToolDefinition<
|
|
|
19
21
|
text: z.ZodOptional<z.ZodString>;
|
|
20
22
|
score: z.ZodOptional<z.ZodNumber>;
|
|
21
23
|
descendants: z.ZodOptional<z.ZodNumber>;
|
|
24
|
+
parent: z.ZodOptional<z.ZodNumber>;
|
|
25
|
+
poll: z.ZodOptional<z.ZodNumber>;
|
|
26
|
+
parts: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
|
|
27
|
+
deleted: z.ZodOptional<z.ZodLiteral<true>>;
|
|
28
|
+
dead: z.ZodOptional<z.ZodLiteral<true>>;
|
|
29
|
+
options: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
30
|
+
id: z.ZodNumber;
|
|
31
|
+
text: z.ZodOptional<z.ZodString>;
|
|
32
|
+
score: z.ZodOptional<z.ZodNumber>;
|
|
33
|
+
deleted: z.ZodOptional<z.ZodLiteral<true>>;
|
|
34
|
+
dead: z.ZodOptional<z.ZodLiteral<true>>;
|
|
35
|
+
}, z.core.$strip>>>;
|
|
22
36
|
}, z.core.$strip>;
|
|
23
37
|
comments: z.ZodArray<z.ZodObject<{
|
|
24
38
|
id: z.ZodNumber;
|
|
@@ -36,6 +50,12 @@ export declare const getThread: import("@cyanheads/mcp-ts-core").ToolDefinition<
|
|
|
36
50
|
readonly when: "HN reports no item exists for the given itemId.";
|
|
37
51
|
readonly recovery: "Verify the itemId via hn_search_content or a feed listing from hn_get_stories.";
|
|
38
52
|
readonly severity: "notice";
|
|
53
|
+
}, {
|
|
54
|
+
readonly reason: "invalid_cursor";
|
|
55
|
+
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
56
|
+
readonly when: "The cursor was issued for a different itemId than the one passed with it.";
|
|
57
|
+
readonly recovery: "Pass the cursor with the same itemId it was returned for, or omit cursor to start this item from the top.";
|
|
58
|
+
readonly severity: "notice";
|
|
39
59
|
}, {
|
|
40
60
|
readonly reason: "upstream_rejected";
|
|
41
61
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
@@ -46,7 +66,7 @@ export declare const getThread: import("@cyanheads/mcp-ts-core").ToolDefinition<
|
|
|
46
66
|
readonly reason: "upstream_rate_limited";
|
|
47
67
|
readonly code: JsonRpcErrorCode.RateLimited;
|
|
48
68
|
readonly when: "The HN API answered with HTTP 429.";
|
|
49
|
-
readonly recovery: "Wait several seconds
|
|
69
|
+
readonly recovery: "Wait the interval in retryAfter when the error carries one, otherwise several seconds, then retry and call this tool less often.";
|
|
50
70
|
readonly retryable: true;
|
|
51
71
|
readonly thrownBy: "service";
|
|
52
72
|
}, {
|
|
@@ -74,8 +94,16 @@ export declare const getThread: import("@cyanheads/mcp-ts-core").ToolDefinition<
|
|
|
74
94
|
readonly totalLoaded: z.ZodNumber;
|
|
75
95
|
readonly totalAvailable: z.ZodOptional<z.ZodNumber>;
|
|
76
96
|
readonly truncated: z.ZodOptional<z.ZodBoolean>;
|
|
97
|
+
readonly truncationReason: z.ZodOptional<z.ZodEnum<{
|
|
98
|
+
count: "count";
|
|
99
|
+
depth: "depth";
|
|
100
|
+
rate_limited: "rate_limited";
|
|
101
|
+
size: "size";
|
|
102
|
+
}>>;
|
|
103
|
+
readonly nextCursor: z.ZodOptional<z.ZodString>;
|
|
77
104
|
readonly shown: z.ZodOptional<z.ZodNumber>;
|
|
78
105
|
readonly cap: z.ZodOptional<z.ZodNumber>;
|
|
106
|
+
readonly failedIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
|
|
79
107
|
readonly notice: z.ZodOptional<z.ZodString>;
|
|
80
108
|
}>;
|
|
81
109
|
//# sourceMappingURL=get-thread.tool.d.ts.map
|
|
@@ -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
|
|
1
|
+
{"version":3,"file":"get-thread.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-thread.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAsB,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAiB,gBAAgB,EAAiB,MAAM,+BAA+B,CAAC;AA0c/F,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqUpB,CAAC"}
|