@universal-mcp-toolkit/server-hackernews 0.1.0

package/.well-known/mcp-server.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json.schemastore.org/json",
+  "name": "hackernews",
+  "title": "Hacker News MCP Server",
+  "description": "Top stories, search, and thread tools for Hacker News.",
+  "version": "0.1.0",
+  "packageName": "@universal-mcp-toolkit/server-hackernews",
+  "homepage": "https://github.com/universal-mcp-toolkit/universal-mcp-toolkit",
+  "transports": [
+    "stdio",
+    "sse"
+  ],
+  "authentication": {
+    "mode": "environment-variables",
+    "required": []
+  },
+  "capabilities": {
+    "tools": true,
+    "resources": true,
+    "prompts": true
+  },
+  "tools": [
+    "get_top_stories",
+    "search_stories",
+    "get_item_thread"
+  ],
+  "resources": [
+    "trends"
+  ],
+  "prompts": [
+    "community-digest"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 universal-mcp-toolkit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+import * as _universal_mcp_toolkit_core from '@universal-mcp-toolkit/core';
+import { ToolkitServer, ToolkitServerMetadata } from '@universal-mcp-toolkit/core';
+import { z } from 'zod';
+
+declare const metadata: ToolkitServerMetadata;
+declare const serverCard: _universal_mcp_toolkit_core.ToolkitServerCard;
+declare const storySummarySchema: z.ZodObject<{
+    id: z.ZodNumber;
+    title: z.ZodString;
+    url: z.ZodNullable<z.ZodString>;
+    author: z.ZodNullable<z.ZodString>;
+    score: z.ZodNullable<z.ZodNumber>;
+    commentCount: z.ZodNullable<z.ZodNumber>;
+    publishedAt: z.ZodNullable<z.ZodString>;
+    text: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+type HackerNewsStorySummary = z.infer<typeof storySummarySchema>;
+interface HackerNewsThreadComment {
+    id: number;
+    author: string | null;
+    text: string | null;
+    publishedAt: string | null;
+    replies: ReadonlyArray<HackerNewsThreadComment>;
+}
+declare const threadSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    title: z.ZodString;
+    url: z.ZodNullable<z.ZodString>;
+    author: z.ZodNullable<z.ZodString>;
+    score: z.ZodNullable<z.ZodNumber>;
+    commentCount: z.ZodNullable<z.ZodNumber>;
+    publishedAt: z.ZodNullable<z.ZodString>;
+    text: z.ZodNullable<z.ZodString>;
+    replies: z.ZodArray<z.ZodType<HackerNewsThreadComment, unknown, z.core.$ZodTypeInternals<HackerNewsThreadComment, unknown>>>;
+}, z.core.$strip>;
+type HackerNewsThread = z.infer<typeof threadSchema>;
+interface HackerNewsClient {
+    getTopStories(limit: number): Promise<ReadonlyArray<HackerNewsStorySummary>>;
+    searchStories(input: {
+        query: string;
+        limit: number;
+    }): Promise<ReadonlyArray<HackerNewsStorySummary>>;
+    getThread(input: {
+        itemId: number;
+        depth: number;
+        maxChildren: number;
+    }): Promise<HackerNewsThread>;
+}
+interface CreateHackerNewsServerOptions {
+    client?: HackerNewsClient;
+    env?: NodeJS.ProcessEnv;
+    fetch?: typeof fetch;
+}
+declare class HackerNewsServer extends ToolkitServer {
+    private readonly client;
+    constructor(client: HackerNewsClient);
+}
+declare function createServer(options?: CreateHackerNewsServerOptions): Promise<HackerNewsServer>;
+declare function main(argv?: readonly string[]): Promise<void>;
+
+export { type CreateHackerNewsServerOptions, type HackerNewsClient, HackerNewsServer, type HackerNewsStorySummary, type HackerNewsThread, type HackerNewsThreadComment, createServer, main, metadata, serverCard };

package/dist/index.js

@@ -0,0 +1,372 @@
+// src/index.ts
+import {
+  createServerCard,
+  defineTool,
+  ExternalServiceError,
+  loadEnv,
+  parseRuntimeOptions,
+  runToolkitServer,
+  ToolkitServer
+} from "@universal-mcp-toolkit/core";
+import { resolve } from "path";
+import { fileURLToPath } from "url";
+import { z } from "zod";
+var toolNames = ["get_top_stories", "search_stories", "get_item_thread"];
+var resourceNames = ["trends"];
+var promptNames = ["community-digest"];
+var metadata = {
+  id: "hackernews",
+  title: "Hacker News MCP Server",
+  description: "Top stories, search, and thread tools for Hacker News.",
+  version: "0.1.0",
+  packageName: "@universal-mcp-toolkit/server-hackernews",
+  homepage: "https://github.com/universal-mcp-toolkit/universal-mcp-toolkit",
+  repositoryUrl: "https://github.com/universal-mcp-toolkit/universal-mcp-toolkit",
+  documentationUrl: "https://github.com/universal-mcp-toolkit/universal-mcp-toolkit/tree/main/servers/hackernews",
+  envVarNames: [],
+  transports: ["stdio", "sse"],
+  toolNames,
+  resourceNames,
+  promptNames
+};
+var serverCard = createServerCard(metadata);
+var envShape = {
+  HACKERNEWS_API_BASE_URL: z.string().url().optional(),
+  HACKERNEWS_SEARCH_BASE_URL: z.string().url().optional()
+};
+var storySummarySchema = z.object({
+  id: z.number().int().nonnegative(),
+  title: z.string(),
+  url: z.string().nullable(),
+  author: z.string().nullable(),
+  score: z.number().int().nonnegative().nullable(),
+  commentCount: z.number().int().nonnegative().nullable(),
+  publishedAt: z.string().nullable(),
+  text: z.string().nullable()
+});
+var threadCommentSchema = z.lazy(
+  () => z.object({
+    id: z.number().int().nonnegative(),
+    author: z.string().nullable(),
+    text: z.string().nullable(),
+    publishedAt: z.string().nullable(),
+    replies: z.array(threadCommentSchema)
+  })
+);
+var threadSchema = storySummarySchema.extend({
+  replies: z.array(threadCommentSchema)
+});
+var hnItemSchema = z.object({
+  id: z.number().int().nonnegative(),
+  type: z.string().optional(),
+  title: z.string().optional(),
+  url: z.string().optional(),
+  by: z.string().optional(),
+  score: z.number().int().nonnegative().optional(),
+  descendants: z.number().int().nonnegative().optional(),
+  time: z.number().int().nonnegative().optional(),
+  text: z.string().optional(),
+  kids: z.array(z.number().int().nonnegative()).optional(),
+  deleted: z.boolean().optional(),
+  dead: z.boolean().optional()
+});
+var hnSearchResponseSchema = z.object({
+  hits: z.array(
+    z.object({
+      objectID: z.string(),
+      title: z.string().nullable().optional(),
+      url: z.string().nullable().optional(),
+      author: z.string().nullable().optional(),
+      points: z.number().int().nonnegative().nullable().optional(),
+      num_comments: z.number().int().nonnegative().nullable().optional(),
+      created_at: z.string().nullable().optional(),
+      story_text: z.string().nullable().optional()
+    })
+  )
+});
+function isHnItem(value) {
+  return value !== null;
+}
+function resolveEnv(source = process.env) {
+  return loadEnv(envShape, source);
+}
+function toNullableString(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function toNullableTimestamp(value) {
+  return typeof value === "number" ? new Date(value * 1e3).toISOString() : null;
+}
+var FetchHackerNewsClient = class {
+  apiBaseUrl;
+  searchBaseUrl;
+  fetchImpl;
+  constructor(options) {
+    this.apiBaseUrl = (options.apiBaseUrl ?? "https://hacker-news.firebaseio.com/v0").replace(/\/+$/, "");
+    this.searchBaseUrl = (options.searchBaseUrl ?? "https://hn.algolia.com/api/v1").replace(/\/+$/, "");
+    this.fetchImpl = options.fetch;
+  }
+  async getTopStories(limit) {
+    const ids = await this.fetchJson(new URL(`${this.apiBaseUrl}/topstories.json`), z.array(z.number().int().nonnegative()));
+    const items = await Promise.all(ids.slice(0, limit).map((id) => this.fetchItem(id)));
+    return items.filter((item) => isHnItem(item) && item.type === "story").map((item) => this.toStorySummary(item));
+  }
+  async searchStories(input) {
+    const url = new URL(`${this.searchBaseUrl}/search`);
+    url.searchParams.set("tags", "story");
+    url.searchParams.set("query", input.query);
+    url.searchParams.set("hitsPerPage", String(input.limit));
+    const payload = await this.fetchJson(url, hnSearchResponseSchema);
+    return payload.hits.map((hit) => ({
+      id: Number.parseInt(hit.objectID, 10),
+      title: hit.title ?? "Untitled story",
+      url: toNullableString(hit.url),
+      author: toNullableString(hit.author),
+      score: hit.points ?? null,
+      commentCount: hit.num_comments ?? null,
+      publishedAt: toNullableString(hit.created_at),
+      text: toNullableString(hit.story_text)
+    }));
+  }
+  async getThread(input) {
+    const root = await this.fetchItem(input.itemId);
+    if (!root) {
+      throw new ExternalServiceError(`Hacker News item ${input.itemId} was not found.`, {
+        statusCode: 404
+      });
+    }
+    return {
+      ...this.toStorySummary(root),
+      replies: await this.fetchReplies(root.kids ?? [], input.depth, input.maxChildren)
+    };
+  }
+  async fetchReplies(ids, depth, maxChildren) {
+    if (depth <= 0) {
+      return [];
+    }
+    const children = await Promise.all(ids.slice(0, maxChildren).map((id) => this.fetchItem(id)));
+    const comments = children.filter((item) => isHnItem(item) && item.type === "comment");
+    return Promise.all(
+      comments.map(async (comment) => ({
+        id: comment.id,
+        author: toNullableString(comment.by),
+        text: toNullableString(comment.text),
+        publishedAt: toNullableTimestamp(comment.time),
+        replies: await this.fetchReplies(comment.kids ?? [], depth - 1, maxChildren)
+      }))
+    );
+  }
+  toStorySummary(item) {
+    return {
+      id: item.id,
+      title: item.title ?? "Untitled story",
+      url: toNullableString(item.url),
+      author: toNullableString(item.by),
+      score: item.score ?? null,
+      commentCount: item.descendants ?? null,
+      publishedAt: toNullableTimestamp(item.time),
+      text: toNullableString(item.text)
+    };
+  }
+  async fetchItem(id) {
+    const url = new URL(`${this.apiBaseUrl}/item/${id}.json`);
+    const response = await this.fetchImpl(url, {
+      method: "GET",
+      headers: {
+        accept: "application/json"
+      }
+    });
+    if (!response.ok) {
+      throw new ExternalServiceError(`Hacker News request failed with status ${response.status}.`, {
+        statusCode: response.status,
+        details: await response.text()
+      });
+    }
+    const payload = await response.json();
+    if (payload === null) {
+      return null;
+    }
+    const parsed = hnItemSchema.safeParse(payload);
+    if (!parsed.success) {
+      throw new ExternalServiceError("Hacker News item returned an unexpected response shape.", {
+        details: parsed.error.flatten()
+      });
+    }
+    if (parsed.data.deleted || parsed.data.dead) {
+      return null;
+    }
+    return parsed.data;
+  }
+  async fetchJson(url, schema) {
+    const response = await this.fetchImpl(url, {
+      method: "GET",
+      headers: {
+        accept: "application/json"
+      }
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new ExternalServiceError(`Hacker News request failed with status ${response.status}.`, {
+        statusCode: response.status,
+        details: body
+      });
+    }
+    const payload = await response.json();
+    const parsed = schema.safeParse(payload);
+    if (!parsed.success) {
+      throw new ExternalServiceError("Hacker News returned an unexpected response shape.", {
+        details: parsed.error.flatten()
+      });
+    }
+    return parsed.data;
+  }
+};
+var HackerNewsServer = class extends ToolkitServer {
+  client;
+  constructor(client) {
+    super(metadata);
+    this.client = client;
+    this.registerTool(
+      defineTool({
+        name: "get_top_stories",
+        title: "Get top stories",
+        description: "Get the current top Hacker News stories.",
+        inputSchema: {
+          limit: z.number().int().min(1).max(30).default(10)
+        },
+        outputSchema: {
+          stories: z.array(storySummarySchema),
+          returned: z.number().int()
+        },
+        handler: async ({ limit }, context) => {
+          await context.log("info", "Fetching top Hacker News stories");
+          const stories = await this.client.getTopStories(limit);
+          return {
+            stories: [...stories],
+            returned: stories.length
+          };
+        },
+        renderText: ({ stories }) => stories.map((story) => `${story.title} (${story.score ?? 0} points)`).join("\n")
+      })
+    );
+    this.registerTool(
+      defineTool({
+        name: "search_stories",
+        title: "Search stories",
+        description: "Search Hacker News stories by keyword.",
+        inputSchema: {
+          query: z.string().trim().min(1),
+          limit: z.number().int().min(1).max(30).default(10)
+        },
+        outputSchema: {
+          stories: z.array(storySummarySchema),
+          returned: z.number().int()
+        },
+        handler: async ({ query, limit }, context) => {
+          await context.log("info", `Searching Hacker News for ${query}`);
+          const stories = await this.client.searchStories({ query, limit });
+          return {
+            stories: [...stories],
+            returned: stories.length
+          };
+        },
+        renderText: ({ stories, returned }) => {
+          if (returned === 0) {
+            return "No matching Hacker News stories found.";
+          }
+          return stories.map((story) => `${story.title} by ${story.author ?? "unknown"}`).join("\n");
+        }
+      })
+    );
+    this.registerTool(
+      defineTool({
+        name: "get_item_thread",
+        title: "Get item thread",
+        description: "Fetch a Hacker News story and its comment thread.",
+        inputSchema: {
+          itemId: z.number().int().nonnegative(),
+          depth: z.number().int().min(1).max(6).default(2),
+          maxChildren: z.number().int().min(1).max(50).default(20)
+        },
+        outputSchema: {
+          thread: threadSchema
+        },
+        handler: async ({ itemId, depth, maxChildren }, context) => {
+          await context.log("info", `Fetching Hacker News thread ${itemId}`);
+          return {
+            thread: await this.client.getThread({ itemId, depth, maxChildren })
+          };
+        },
+        renderText: ({ thread }) => `${thread.title} with ${thread.replies.length} top-level replies.`
+      })
+    );
+    this.registerStaticResource(
+      "trends",
+      "hackernews://trends/top",
+      {
+        title: "Top story trend resource",
+        description: "A quick snapshot of current top Hacker News stories.",
+        mimeType: "application/json"
+      },
+      async (uri) => this.createJsonResource(uri.toString(), {
+        generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        stories: await this.client.getTopStories(10)
+      })
+    );
+    this.registerPrompt(
+      "community-digest",
+      {
+        title: "Community digest prompt",
+        description: "Draft a digest of noteworthy Hacker News activity.",
+        argsSchema: {
+          theme: z.string().trim().min(1),
+          audience: z.string().trim().min(1),
+          storyCount: z.number().int().min(1).max(20).default(5)
+        }
+      },
+      async ({ theme, audience, storyCount }) => this.createTextPrompt(
+        [
+          `Prepare a Hacker News community digest for ${audience}.`,
+          `Focus on the theme "${theme}" and summarize roughly ${storyCount} stories.`,
+          "Highlight debates, notable launches, practical takeaways, and unresolved questions."
+        ].join(" ")
+      )
+    );
+  }
+};
+async function createServer(options = {}) {
+  if (options.client) {
+    return new HackerNewsServer(options.client);
+  }
+  const env = resolveEnv(options.env);
+  return new HackerNewsServer(
+    new FetchHackerNewsClient({
+      fetch: options.fetch ?? globalThis.fetch,
+      ...env.HACKERNEWS_API_BASE_URL ? { apiBaseUrl: env.HACKERNEWS_API_BASE_URL } : {},
+      ...env.HACKERNEWS_SEARCH_BASE_URL ? { searchBaseUrl: env.HACKERNEWS_SEARCH_BASE_URL } : {}
+    })
+  );
+}
+function isMainModule(metaUrl) {
+  const entry = process.argv[1];
+  return typeof entry === "string" && fileURLToPath(metaUrl) === resolve(entry);
+}
+async function main(argv = process.argv.slice(2)) {
+  const runtimeOptions = parseRuntimeOptions(argv);
+  await runToolkitServer(
+    {
+      createServer: () => createServer(),
+      serverCard
+    },
+    runtimeOptions
+  );
+}
+if (isMainModule(import.meta.url)) {
+  await main();
+}
+export {
+  HackerNewsServer,
+  createServer,
+  main,
+  metadata,
+  serverCard
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@universal-mcp-toolkit/server-hackernews",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Trending story and thread tools for Hacker News.",
+  "license": "MIT",
+  "bin": {
+    "server-hackernews": "./dist/index.js",
+    "umt-hackernews": "./dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Markgatcha/universal-mcp-toolkit.git"
+  },
+  "homepage": "https://github.com/Markgatcha/universal-mcp-toolkit#readme",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    ".well-known"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "developer-tools",
+    "typescript",
+    "hackernews",
+    "news",
+    "community",
+    "search"
+  ],
+  "dependencies": {
+    "@universal-mcp-toolkit/core": "0.1.0",
+    "zod": "^4.3.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsx watch src/index.ts",
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rimraf dist"
+  }
+}