@cyanheads/hn-mcp-server 0.5.17 → 0.5.19
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 +5 -3
- package/CLAUDE.md +5 -3
- package/README.md +21 -12
- package/changelog/0.5.x/0.5.18.md +24 -0
- package/changelog/0.5.x/0.5.19.md +19 -0
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- 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 +48 -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 +513 -161
- 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 +55 -22
- package/dist/mcp-server/tools/definitions/get-user.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-content.tool.d.ts +24 -3
- package/dist/mcp-server/tools/definitions/search-content.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-content.tool.js +172 -46
- package/dist/mcp-server/tools/definitions/search-content.tool.js.map +1 -1
- package/dist/services/hn/hn-service.d.ts +69 -10
- package/dist/services/hn/hn-service.d.ts.map +1 -1
- package/dist/services/hn/hn-service.js +101 -23
- package/dist/services/hn/hn-service.js.map +1 -1
- package/package.json +2 -2
- 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.19
|
|
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
|
},
|
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.19
|
|
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
|
},
|
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
|
|
|
@@ -29,16 +29,16 @@
|
|
|
29
29
|
|
|
30
30
|
## Overview
|
|
31
31
|
|
|
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 and
|
|
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
34
|
### Tools
|
|
35
35
|
|
|
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
|
-
| `hn_search_content` | Search stories and
|
|
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
|
|
|
@@ -46,16 +46,20 @@ Feeds, threads, and profiles from the Hacker News Firebase API and Algolia Searc
|
|
|
46
46
|
|
|
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
|
-
- Enrichment reports `total`, `offset`, `hasMore`, and a `notice`
|
|
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
|
-
- `notice` reports deleted/dead comments omitted during traversal and,
|
|
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,16 +67,21 @@ 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
|
|
|
70
76
|
### `hn_search_content` <sub>tool</sub>
|
|
71
77
|
|
|
72
|
-
- Free-text `query` plus `tags` (`story`/`comment`/`ask_hn`/`show_hn`/`front_page`), `author`, `dateRange
|
|
78
|
+
- 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
|
|
79
|
+
- `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`
|
|
80
|
+
- `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`
|
|
81
|
+
- `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`
|
|
73
82
|
- `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
|
|
74
83
|
- Highlight metadata (`highlights.title`, `highlights.text`, `matchedWords`) shows which terms matched and where
|
|
75
|
-
- Enrichment reports `totalHits`, `page`, and the actual reachable `totalPages` — not derived from `totalHits`, since broad queries report far more hits than Algolia will serve
|
|
84
|
+
- 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)
|
|
76
85
|
|
|
77
86
|
## Features
|
|
78
87
|
|
|
@@ -88,9 +97,9 @@ HN-specific:
|
|
|
88
97
|
|
|
89
98
|
Agent-friendly output:
|
|
90
99
|
|
|
91
|
-
- Graceful partial failure —
|
|
92
|
-
- 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
|
|
93
|
-
- 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
|
|
94
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
|
|
95
104
|
|
|
96
105
|
## Getting started
|
|
@@ -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
|
|
@@ -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.
|
package/dist/index.js
CHANGED
|
@@ -13,7 +13,7 @@ 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
18
|
sessionMode: 'stateless',
|
|
19
19
|
setup() {
|
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"}
|
|
@@ -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;AAYjE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8PrB,CAAC"}
|
|
@@ -4,7 +4,9 @@
|
|
|
4
4
|
*/
|
|
5
5
|
import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
6
6
|
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
7
|
-
import { extractDomain,
|
|
7
|
+
import { extractDomain, getHnService, normalizeUrl, settlePage, 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 },
|
|
@@ -20,7 +22,7 @@ export const getStories = tool('hn_get_stories', {
|
|
|
20
22
|
reason: 'upstream_rate_limited',
|
|
21
23
|
code: JsonRpcErrorCode.RateLimited,
|
|
22
24
|
when: 'The HN API answered with HTTP 429.',
|
|
23
|
-
recovery: 'Wait several seconds
|
|
25
|
+
recovery: 'Wait the interval in retryAfter when the error carries one, otherwise several seconds, then retry and call this tool less often.',
|
|
24
26
|
retryable: true,
|
|
25
27
|
thrownBy: 'service',
|
|
26
28
|
},
|
|
@@ -57,7 +59,7 @@ export const getStories = tool('hn_get_stories', {
|
|
|
57
59
|
.number()
|
|
58
60
|
.int()
|
|
59
61
|
.min(1)
|
|
60
|
-
.max(
|
|
62
|
+
.max(MAX_COUNT)
|
|
61
63
|
.default(30)
|
|
62
64
|
.describe('Number of stories to return. Larger counts take longer.'),
|
|
63
65
|
offset: z
|
|
@@ -116,20 +118,26 @@ export const getStories = tool('hn_get_stories', {
|
|
|
116
118
|
truncated: z
|
|
117
119
|
.boolean()
|
|
118
120
|
.optional()
|
|
119
|
-
.describe('True when
|
|
121
|
+
.describe('True when more stories remain beyond this page (hasMore). Absent on the last page of the feed.'),
|
|
120
122
|
shown: z.number().optional().describe('Number of stories returned on this page.'),
|
|
121
123
|
cap: z.number().optional().describe('The count cap that was applied.'),
|
|
124
|
+
failedIds: z
|
|
125
|
+
.array(z.number())
|
|
126
|
+
.optional()
|
|
127
|
+
.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.'),
|
|
122
128
|
notice: z
|
|
123
129
|
.string()
|
|
124
130
|
.optional()
|
|
125
|
-
.describe('
|
|
131
|
+
.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.'),
|
|
132
|
+
},
|
|
133
|
+
enrichmentTrailer: {
|
|
134
|
+
failedIds: { render: (ids) => `**Failed to load:** ${(ids ?? []).join(', ')}` },
|
|
126
135
|
},
|
|
127
136
|
async handler(input, ctx) {
|
|
128
137
|
const hn = getHnService();
|
|
129
138
|
const feedIds = await hn.fetchFeed(input.feed, ctx);
|
|
130
139
|
const sliced = feedIds.slice(input.offset, input.offset + input.count);
|
|
131
|
-
const
|
|
132
|
-
const items = filterLiveItems(rawItems);
|
|
140
|
+
const { items, failedIds } = settlePage(await hn.fetchItems(sliced, ctx));
|
|
133
141
|
const stories = items.map((item) => {
|
|
134
142
|
const url = normalizeUrl(item.url);
|
|
135
143
|
const domain = extractDomain(url);
|
|
@@ -146,14 +154,37 @@ export const getStories = tool('hn_get_stories', {
|
|
|
146
154
|
...(item.text && { text: stripHtml(item.text) }),
|
|
147
155
|
};
|
|
148
156
|
});
|
|
149
|
-
ctx.log.info('Fetched stories', {
|
|
157
|
+
ctx.log.info('Fetched stories', {
|
|
158
|
+
feed: input.feed,
|
|
159
|
+
count: stories.length,
|
|
160
|
+
failed: failedIds.length,
|
|
161
|
+
});
|
|
150
162
|
const total = feedIds.length;
|
|
151
|
-
const
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
163
|
+
const nextOffset = input.offset + input.count;
|
|
164
|
+
const hasMore = nextOffset < total;
|
|
165
|
+
ctx.enrich({
|
|
166
|
+
total,
|
|
167
|
+
offset: input.offset,
|
|
168
|
+
hasMore,
|
|
169
|
+
...(failedIds.length > 0 && { failedIds }),
|
|
170
|
+
});
|
|
171
|
+
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.`;
|
|
172
|
+
const failureMessage = failedIds.length > 0
|
|
173
|
+
? `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.`
|
|
174
|
+
: undefined;
|
|
175
|
+
if (hasMore) {
|
|
176
|
+
const raiseCount = input.count < MAX_COUNT ? `, or raise count (max ${MAX_COUNT})` : '';
|
|
177
|
+
const nextPage = `Pass offset: ${nextOffset} for the next page${raiseCount}.`;
|
|
178
|
+
const pageStatus = stories.length === 0 && !failureMessage
|
|
179
|
+
? deadPageMessage
|
|
180
|
+
: `Showing items ${input.offset + 1}–${nextOffset} of ${total} in the ${input.feed} feed.`;
|
|
181
|
+
ctx.enrich.truncated({
|
|
182
|
+
shown: stories.length,
|
|
183
|
+
cap: input.count,
|
|
184
|
+
guidance: [pageStatus, failureMessage, nextPage].filter(Boolean).join(' '),
|
|
185
|
+
});
|
|
155
186
|
}
|
|
156
|
-
if (stories.length === 0) {
|
|
187
|
+
else if (stories.length === 0) {
|
|
157
188
|
if (total === 0) {
|
|
158
189
|
ctx.enrich.notice(`${input.feed} feed is empty.`);
|
|
159
190
|
}
|
|
@@ -161,9 +192,12 @@ export const getStories = tool('hn_get_stories', {
|
|
|
161
192
|
ctx.enrich.notice(`Offset ${input.offset} is past the end of the ${input.feed} feed (${total} item${total === 1 ? '' : 's'}). Reset offset below ${total}.`);
|
|
162
193
|
}
|
|
163
194
|
else {
|
|
164
|
-
ctx.enrich.notice(
|
|
195
|
+
ctx.enrich.notice(failureMessage ?? deadPageMessage);
|
|
165
196
|
}
|
|
166
197
|
}
|
|
198
|
+
else if (failureMessage) {
|
|
199
|
+
ctx.enrich.notice(failureMessage);
|
|
200
|
+
}
|
|
167
201
|
return {
|
|
168
202
|
stories,
|
|
169
203
|
feed: input.feed,
|
|
@@ -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;AAkc/F,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqUpB,CAAC"}
|