@mrfentmen/lobsters-mcp 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# Lobsters MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lobsters: hottest and newest stories, tags, story details, user profiles — keyless.
+
+Keyless — no signup, no API key, no environment variables.
+
+## Install
+
+```bash
+npx -y @mrfentmen/lobsters-mcp
+```
+
+Or add it to your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "lobsters-mcp": {
+      "command": "npx",
+      "args": ["-y", "@mrfentmen/lobsters-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `hottest` | Current front page |
+| `newest` | Newest submissions |
+| `by_tag` | Stories under one tag |
+| `story_detail` | One story by short id |
+| `user_info` | Profile, role and links |
+| `domain_breakdown` | Top domains and active tags |
+
+## Example
+
+```
+lobste.rs hottest (3):
+
+1. Websites Should Be Printable [66 pts, 17 comments]
+   https://brennenputh.me/blog/printable-websites/
+   css, web · zk · 2026-10-26 07:02
+```
+
+## Notes
+
+lobste.rs allows one request per second and answers throttling with a plain-text 429, which this server reports verbatim. User profiles expose identity fields only — lobste.rs publishes no karma or story counts.
+
+## Licence
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,8 @@
+export declare class LobstersError extends Error {
+}
+export declare function hottest(limit: number): Promise<string>;
+export declare function newest(limit: number): Promise<string>;
+export declare function byTag(tag: string, limit: number): Promise<string>;
+export declare function storyDetail(shortId: string): Promise<string>;
+export declare function userInfo(username: string): Promise<string>;
+export declare function domainBreakdown(limit: number): Promise<string>;

package/dist/api.js

@@ -0,0 +1,141 @@
+const BASE = "https://lobste.rs";
+export class LobstersError extends Error {
+}
+async function getJson(path, timeoutMs = 20000) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const res = await fetch(`${BASE}${path}`, {
+            signal: ctrl.signal,
+            headers: { "user-agent": "lobsters-mcp", accept: "application/json" },
+        });
+        if (res.status === 404)
+            throw new LobstersError("Not found on lobste.rs");
+        if (res.status === 403)
+            throw new LobstersError("lobste.rs refused the request");
+        if (!res.ok)
+            throw new LobstersError(`lobste.rs responded ${res.status}`);
+        return await res.json();
+    }
+    catch (e) {
+        if (e instanceof LobstersError)
+            throw e;
+        if (e.name === "AbortError")
+            throw new LobstersError("lobste.rs request timed out");
+        if (e instanceof SyntaxError)
+            throw new LobstersError("lobste.rs returned a non-JSON response");
+        throw new LobstersError(`lobste.rs request failed: ${e.message}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function toStory(s) {
+    const user = typeof s.submitter_user === "object" ? s.submitter_user?.username : s.submitter_user;
+    return {
+        short_id: String(s.short_id ?? ""),
+        title: String(s.title ?? "(untitled)"),
+        url: String(s.url ?? ""),
+        score: Number(s.score ?? 0),
+        comment_count: Number(s.comment_count ?? 0),
+        created_at: String(s.created_at ?? "").slice(0, 16).replace("T", " "),
+        submitter_user: String(user ?? "unknown"),
+        tags: Array.isArray(s.tags) ? s.tags.map(String) : [],
+        description: String(s.description_plain ?? s.description ?? "").replace(/\s+/g, " ").slice(0, 200),
+    };
+}
+function line(s, i) {
+    const prefix = typeof i === "number" ? `${i + 1}. ` : "• ";
+    const where = s.url ? s.url : `${BASE}/s/${s.short_id}`;
+    return `${prefix}${s.title} [${s.score} pts, ${s.comment_count} comments]\n   ${where}\n   ${s.tags.join(", ") || "no tags"} · ${s.submitter_user} · ${s.created_at}`;
+}
+function take(rows, limit) {
+    return rows.slice(0, limit).map(toStory);
+}
+export async function hottest(limit) {
+    const rows = await getJson("/hottest.json");
+    const stories = take(Array.isArray(rows) ? rows : [], limit);
+    if (stories.length === 0)
+        return "lobste.rs returned no stories.";
+    return [`lobste.rs hottest (${stories.length}):`, "", ...stories.map(line)].join("\n");
+}
+export async function newest(limit) {
+    const rows = await getJson("/newest.json");
+    const stories = take(Array.isArray(rows) ? rows : [], limit);
+    if (stories.length === 0)
+        return "lobste.rs returned no stories.";
+    return [`lobste.rs newest (${stories.length}):`, "", ...stories.map(line)].join("\n");
+}
+export async function byTag(tag, limit) {
+    const t = tag.trim().toLowerCase();
+    if (!/^[a-z0-9_-]{2,30}$/.test(t))
+        throw new LobstersError(`"${tag}" is not a valid tag`);
+    const rows = await getJson(`/t/${encodeURIComponent(t)}.json`);
+    const stories = take(Array.isArray(rows) ? rows : [], limit);
+    if (stories.length === 0)
+        return `No stories tagged "${tag}".`;
+    return [`Stories tagged "${tag}" (${stories.length}):`, "", ...stories.map(line)].join("\n");
+}
+export async function storyDetail(shortId) {
+    const id = shortId.trim().toLowerCase();
+    if (!/^[a-z0-9]{4,12}$/.test(id))
+        throw new LobstersError(`"${shortId}" is not a story id`);
+    const s = toStory(await getJson(`/s/${id}.json`));
+    const rows = [
+        `${s.title}`,
+        `Score ${s.score} · ${s.comment_count} comments · ${s.created_at} · by ${s.submitter_user}`,
+        `Tags: ${s.tags.join(", ") || "none"}`,
+        s.url ? `Link: ${s.url}` : "Self post",
+        `Discussion: ${BASE}/s/${s.short_id}`,
+    ];
+    if (s.description)
+        rows.push("", s.description);
+    return rows.join("\n");
+}
+export async function userInfo(username) {
+    const u = username.trim();
+    if (!/^[A-Za-z0-9_-]{2,30}$/.test(u))
+        throw new LobstersError(`"${username}" is not a valid username`);
+    const d = await getJson(`/~${encodeURIComponent(u)}.json`);
+    const profile = d.user ?? d;
+    // lobste.rs exposes identity fields only — no karma or story counts.
+    const roles = [profile.is_admin ? "admin" : "", profile.is_moderator ? "moderator" : ""].filter(Boolean);
+    return [
+        `User: ${profile.username ?? u}`,
+        `Joined: ${String(profile.created_at ?? d.created_at ?? "").slice(0, 10) || "unknown"}`,
+        `Role: ${roles.join(", ") || "member"}`,
+        `Invited by: ${profile.invited_by_user ?? "unknown"}`,
+        `GitHub: ${profile.github_username ?? "not linked"} · Mastodon: ${profile.mastodon_username ?? "not linked"}`,
+        `About: ${String(profile.about ?? d.about ?? "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim().slice(0, 500) || "no bio"}`,
+    ].join("\n");
+}
+export async function domainBreakdown(limit) {
+    const rows = await getJson("/hottest.json");
+    const stories = take(Array.isArray(rows) ? rows : [], 100);
+    if (stories.length === 0)
+        return "lobste.rs returned no stories.";
+    const counts = new Map();
+    for (const s of stories) {
+        let host = "self post";
+        try {
+            host = s.url ? new URL(s.url).hostname.replace(/^www\./, "") : "self post";
+        }
+        catch {
+            host = "unknown";
+        }
+        counts.set(host, (counts.get(host) ?? 0) + 1);
+    }
+    const top = [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, limit);
+    const tags = new Map();
+    for (const s of stories)
+        for (const t of s.tags)
+            tags.set(t, (tags.get(t) ?? 0) + 1);
+    const topTags = [...tags.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8);
+    return [
+        `Domains on the hottest page (${stories.length} stories):`,
+        "",
+        ...top.map(([host, n], i) => `${i + 1}. ${host} — ${n}`),
+        "",
+        `Active tags: ${topTags.map(([t, n]) => `${t} (${n})`).join(", ")}`,
+    ].join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("lobsters-mcp running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,64 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { byTag, domainBreakdown, hottest, LobstersError, newest, storyDetail, userInfo } from "./api.js";
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+function errorMessage(e) {
+    if (e instanceof LobstersError || e instanceof Error)
+        return `Error: ${e.message}`;
+    return `Error: ${String(e)}`;
+}
+export function createServer() {
+    const server = new McpServer({ name: "lobsters-mcp", version: "1.0.3" });
+    server.tool("hottest", "The current lobste.rs front page.", { limit: z.number().int().min(1).max(25).default(10).describe("Stories to return") }, async ({ limit }) => {
+        try {
+            return text(await hottest(limit));
+        }
+        catch (e) {
+            return text(errorMessage(e));
+        }
+    });
+    server.tool("newest", "Freshly submitted lobste.rs stories.", { limit: z.number().int().min(1).max(25).default(10).describe("Stories to return") }, async ({ limit }) => {
+        try {
+            return text(await newest(limit));
+        }
+        catch (e) {
+            return text(errorMessage(e));
+        }
+    });
+    server.tool("by_tag", "Stories under one tag, e.g. rust, ai, security, programming.", {
+        tag: z.string().min(2).describe("Tag name"),
+        limit: z.number().int().min(1).max(25).default(10).describe("Stories to return"),
+    }, async ({ tag, limit }) => {
+        try {
+            return text(await byTag(tag, limit));
+        }
+        catch (e) {
+            return text(errorMessage(e));
+        }
+    });
+    server.tool("story_detail", "One story by its short id.", { short_id: z.string().min(4).describe("Short id, e.g. olnqh2") }, async ({ short_id }) => {
+        try {
+            return text(await storyDetail(short_id));
+        }
+        catch (e) {
+            return text(errorMessage(e));
+        }
+    });
+    server.tool("user_info", "Profile, karma and activity counts for a lobste.rs user.", { username: z.string().min(2).describe("Username") }, async ({ username }) => {
+        try {
+            return text(await userInfo(username));
+        }
+        catch (e) {
+            return text(errorMessage(e));
+        }
+    });
+    server.tool("domain_breakdown", "Which sites and tags dominate the current front page.", { limit: z.number().int().min(1).max(25).default(10).describe("Domains to list") }, async ({ limit }) => {
+        try {
+            return text(await domainBreakdown(limit));
+        }
+        catch (e) {
+            return text(errorMessage(e));
+        }
+    });
+    return server;
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@mrfentmen/lobsters-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Lobsters: hottest and newest stories, tags, story details, user profiles \u2014 keyless.",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/lobsters-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrfentmen/awesome-servers.git"
+  },
+  "bin": {
+    "lobsters-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "lobsters",
+    "news",
+    "tech",
+    "hackernews",
+    "links"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}