devrant-mcp 1.0.1 → 1.0.2

package/README.md

@@ -18,3 +18,21 @@ node dist/index.js
 ```
 
 Data comes from the public devRant API.
+
+<!-- paywall -->
+## Premium tools
+
+These tools need a license key:
+
+* `rant_details`
+
+Buy a key at https://mcp-marketplace.io/server/io-github-mrfentmen-devrant-mcp and set it in your MCP client config:
+
+```json
+"env": { "MCP_LICENSE_KEY": "mcp_live_..." }
+```
+
+The key is checked against MCP Marketplace, cached for 24 hours, and keeps
+working offline once one check has succeeded. Every other tool on this server
+stays free.
+<!-- /paywall -->

package/dist/api.js

@@ -14,3 +14,164 @@ export async function rants(args) {
     return `devRant (${list.length}, showing ${Math.min(limit, list.length)}):\n` +
         list.slice(0, limit).map((r, i) => `${i + 1}. @${r.user_username ?? '?'} (${r.num_upvotes ?? 0} up, ${r.num_comments ?? 0} comments): ${(r.text ?? '').slice(0, 150)}`).join('\n');
 }
+// ---- muxE tools:
+// The one existing tool reads a page of the rants route and prints one line per
+// rant. The new ones ask two questions that page cannot answer: what is inside
+// one rant including its comment thread, and what the whole page adds up to.
+const DR_BASE = 'https://devrant.com/api/devrant';
+const DR_UA = 'mrfentmen-devrant-mcp/1.0';
+/**
+ * devRant is intermittent: the same url answers 200 and then 500 "Slim
+ * Application Error" moments later, verified live on /rants?app=3 where three
+ * consecutive calls in a row produced a 500, and on /rants/<id> where roughly
+ * every other call did. A 500 is retried a bounded number of times so a flaky
+ * upstream does not read as a broken tool.
+ */
+async function drGet(path) {
+    let lastStatus = 0;
+    for (let attempt = 1; attempt <= 3; attempt += 1) {
+        const res = await fetch(`${DR_BASE}${path}`, {
+            headers: { 'User-Agent': DR_UA, Accept: 'application/json' },
+            signal: AbortSignal.timeout(25000),
+        });
+        const raw = await res.text();
+        lastStatus = res.status;
+        if (res.status === 500) {
+            if (attempt < 3) {
+                await new Promise((resolve) => setTimeout(resolve, 1200 * attempt));
+                continue;
+            }
+            throw new Error('devRant answered 500 Slim Application Error for that request three times in a row, which it does intermittently; try again in a moment.');
+        }
+        if (res.status === 405) {
+            throw new Error('devRant refused that route with 405; only the rants list and the single rant routes are open.');
+        }
+        if (!res.ok) {
+            let why = `devRant returned ${res.status}`;
+            try {
+                const parsed = JSON.parse(raw);
+                if (typeof parsed?.error === 'string')
+                    why = `devRant said: ${parsed.error}`;
+                else if (typeof parsed?.message === 'string')
+                    why = `devRant said: ${parsed.message}`;
+            }
+            catch {
+                // the body was not the JSON envelope, so the status is all we have
+            }
+            throw new Error(why);
+        }
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            throw new Error('devRant returned a body that is not JSON.');
+        }
+    }
+    throw new Error(`devRant returned ${lastStatus} and the retries did not clear it.`);
+}
+const SORTS = ['algo', 'new', 'hot', 'top'];
+const drStamp = (seconds) => typeof seconds === 'number' && Number.isFinite(seconds) ? new Date(seconds * 1000).toISOString().slice(0, 16).replace('T', ' ') + ' UTC' : 'not reported';
+const median = (values) => {
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 ? sorted[mid] : Math.round((sorted[mid - 1] + sorted[mid]) / 2);
+};
+export async function rantDetails(args) {
+    const id = Math.floor(Number(args?.rant_id));
+    if (!Number.isInteger(id) || id <= 0)
+        throw new Error('Provide the rant id as a whole number, for example 194632.');
+    const app = Math.max(1, Math.min(Math.floor(Number(args?.app ?? 3) || 3), 9999));
+    const body = await drGet(`/rants/${id}?app=${app}`);
+    const rant = body?.rant;
+    if (!rant || typeof rant.id !== 'number')
+        throw new Error(`devRant returned no rant for id ${id}.`);
+    const comments = Array.isArray(body.comments) ? body.comments : [];
+    const lines = [
+        `Rant ${rant.id} by @${rant.user_username ?? '?'}`,
+        `  posted: ${drStamp(rant.created_time)}`,
+        `  score: ${typeof rant.score === 'number' ? rant.score.toLocaleString('en-US') : 'not reported'}`,
+        `  comments: ${typeof rant.num_comments === 'number' ? rant.num_comments.toLocaleString('en-US') : 'not reported'}`,
+        `  tags: ${Array.isArray(rant.tags) && rant.tags.length ? rant.tags.join(', ') : 'none recorded'}`,
+        `  marked special: ${rant.special === true ? 'yes' : 'no'}, edited: ${rant.edited === true ? 'yes' : 'no'}`,
+        `  author: @${rant.user_username ?? '?'} (id ${rant.user_id ?? 'not reported'}, score ${typeof rant.user_score === 'number' ? rant.user_score.toLocaleString('en-US') : 'not reported'})`,
+    ];
+    if (rant.attached_image)
+        lines.push(`  attached image: ${String(rant.attached_image).slice(0, 160)}`);
+    if (rant.link?.url)
+        lines.push(`  linked: ${rant.link.title ?? 'link'} - ${rant.link.url}`);
+    else if (Array.isArray(rant.links) && rant.links.length) {
+        lines.push(`  links in the text: ${rant.links.length}`);
+        for (const l of rant.links.slice(0, 8))
+            lines.push(`    ${l.type ?? 'link'}: ${l.url ?? 'url not reported'}`);
+        if (rant.links.length > 8)
+            lines.push(`    and ${rant.links.length - 8} more`);
+    }
+    if (rant.text)
+        lines.push(`  text: ${rant.text.replace(/\s+/g, ' ').slice(0, 800)}`);
+    if (!comments.length) {
+        lines.push('  devRant returned no comments with this rant.');
+        return lines.join('\n');
+    }
+    const ranked = [...comments].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    const scores = comments.map((c) => c.score ?? 0);
+    lines.push(`  comment thread: ${comments.length} returned, score range ${Math.min(...scores)} to ${Math.max(...scores)}, median ${median(scores)}`);
+    lines.push('  the ten highest scoring comments:');
+    for (const c of ranked.slice(0, 10)) {
+        lines.push(`    #${c.id ?? '?'} by @${c.user_username ?? '?'} (score ${c.score ?? 0}, ${drStamp(c.created_time)})`);
+        lines.push(`      ${(c.body ?? '').replace(/\s+/g, ' ').slice(0, 200)}`);
+    }
+    if (comments.length > 10)
+        lines.push(`    and ${comments.length - 10} more comment(s) not listed here`);
+    return lines.join('\n');
+}
+export async function rantDigest(args = {}) {
+    const app = Math.max(1, Math.min(Math.floor(Number(args?.app ?? 3) || 3), 9999));
+    const asked = (args?.sort ?? 'algo').trim().toLowerCase();
+    const sort = SORTS.includes(asked) ? asked : 'algo';
+    const limit = Math.max(1, Math.min(Math.floor(Number(args?.limit ?? 25) || 25), 50));
+    const body = await drGet(`/rants?app=${app}&sort=${sort}&limit=${limit}`);
+    if (body?.success === false)
+        throw new Error(`devRant said: ${body.error ?? 'the request was refused'}`);
+    const rants = Array.isArray(body.rants) ? body.rants : [];
+    if (!rants.length)
+        throw new Error(`devRant returned no rants for app ${app} with sort ${sort}.`);
+    const scores = rants.map((r) => r.score ?? 0);
+    const comments = rants.map((r) => r.num_comments ?? 0);
+    const tags = new Map();
+    const authors = new Map();
+    for (const r of rants) {
+        for (const t of Array.isArray(r.tags) ? r.tags : [])
+            tags.set(t, (tags.get(t) ?? 0) + 1);
+        const who = r.user_username ?? 'not reported';
+        authors.set(who, (authors.get(who) ?? 0) + 1);
+    }
+    const rankedTags = [...tags.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    const rankedAuthors = [...authors.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    const times = rants.map((r) => r.created_time).filter((t) => typeof t === 'number');
+    const withImage = rants.filter((r) => typeof r.attached_image === 'string' && r.attached_image).length;
+    const special = rants.filter((r) => r.special === true).length;
+    const edited = rants.filter((r) => r.edited === true).length;
+    const links = rants.reduce((a, r) => a + (Array.isArray(r.links) ? r.links.length : 0), 0);
+    const lines = [
+        `devRant page for app ${app}, sort ${sort}${sort !== asked ? ` (asked for ${asked}, which devRant does not offer, so algo was used)` : ''}:`,
+        `  rants returned: ${rants.length}`,
+        `  asked for ${limit}${rants.length < limit ? `, and devRant sent fewer, so every total below covers only the ${rants.length} it returned` : ''}`,
+        `  score: highest ${Math.max(...scores)}, median ${median(scores)}, lowest ${Math.min(...scores)}, total ${scores.reduce((a, b) => a + b, 0).toLocaleString('en-US')}`,
+        `  comments: highest ${Math.max(...comments)}, median ${median(comments)}, total ${comments.reduce((a, b) => a + b, 0).toLocaleString('en-US')}`,
+        `  with no comments at all: ${comments.filter((c) => c === 0).length}`,
+        `  marked special: ${special}, edited: ${edited}, with an attached image: ${withImage}`,
+        `  links embedded in the rant text: ${links}`,
+    ];
+    if (times.length) {
+        const newest = Math.max(...times);
+        const oldest = Math.min(...times);
+        const spanDays = Math.max(1, Math.round((newest - oldest) / 86400));
+        lines.push(`  posted between ${drStamp(oldest)} and ${drStamp(newest)}, a span of ${spanDays} day(s)`);
+    }
+    lines.push(`  distinct tags: ${rankedTags.length}`);
+    lines.push(`    ${rankedTags.slice(0, 12).map(([t, n]) => `${t} (${n})`).join(', ')}${rankedTags.length > 12 ? `, and ${rankedTags.length - 12} more` : ''}`);
+    lines.push(`  distinct authors: ${rankedAuthors.length}`);
+    lines.push(`    ${rankedAuthors.slice(0, 12).map(([a, n]) => `${a} (${n})`).join(', ')}${rankedAuthors.length > 12 ? `, and ${rankedAuthors.length - 12} more` : ''}`);
+    lines.push('  every figure above is tallied from the rants on this one page, not from a stored summary.');
+    return lines.join('\n');
+}

package/dist/license.js

@@ -0,0 +1,78 @@
+// Premium tools on this server need a license key bought from MCP Marketplace.
+// Buyers put the key in their MCP client config as MCP_LICENSE_KEY. Every tool
+// that is not listed in PREMIUM keeps working without a key.
+const SLUG = "devrant-mcp";
+// Tools that need a key. Everything else is free.
+const PREMIUM = new Set([
+    "rant_details",
+]);
+const BUY_URL = `https://mcp-marketplace.io/server/io-github-mrfentmen-${SLUG}`;
+// The license check calls the marketplace's verify endpoint directly instead of
+// using @mcp_marketplace/license. That SDK sends no `apikey` header, so every
+// check it makes is rejected by Supabase before it reaches the function. The
+// publishable key below is public by design - it ships in mcp-marketplace.io's
+// own JavaScript and only ever reaches their licence check.
+const DEFAULT_VERIFY_URL = "https://virupvwhtkpkjsiskckg.supabase.co/functions/v1/verify-key";
+const PUBLISHABLE_KEY = "sb_publishable_BuqlW96Ke8C_zzJG-LQv1Q_YHi_r_4h";
+const OK_CACHE_MS = 60 * 60 * 1000;
+const BAD_CACHE_MS = 60 * 1000;
+const seen = new Map();
+const REASONS = {
+    missing_key: "no key is set",
+    invalid_format: "that key is not a valid MCP Marketplace key",
+    not_found: "that key was not found",
+    revoked: "that key has been revoked",
+    rotated: "that key was rotated, use your new one",
+    expired: "that key has expired, renew it",
+    rate_limited: "there were too many checks just now, try again shortly",
+    network_error: "the license server could not be reached",
+};
+function blocked(tool, reason) {
+    const why = REASONS[reason] ?? `the license server answered "${reason}"`;
+    return `"${tool}" needs a license key, but ${why}. ` +
+        `Set MCP_LICENSE_KEY in your MCP client config. Get a key: ${BUY_URL}`;
+}
+async function verify(key) {
+    const res = await fetch(process.env.MCP_LICENSE_VERIFY_URL || DEFAULT_VERIFY_URL, {
+        method: "POST",
+        headers: {
+            apikey: PUBLISHABLE_KEY,
+            Authorization: `Bearer ${PUBLISHABLE_KEY}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ key, slug: SLUG }),
+        // an unusable key answers 400 with a JSON body, so read the body either way
+        signal: AbortSignal.timeout(15000),
+    });
+    const data = (await res.json());
+    if (typeof data?.valid !== "boolean")
+        return { valid: false, reason: "unexpected_response" };
+    return data;
+}
+/**
+ * Returns null when the caller may run the tool, or a short message telling
+ * them how to get a key.
+ *
+ * A good key is remembered for an hour, so a busy session does not hit the
+ * license server on every call and keeps working through a brief outage.
+ */
+export async function premiumRequired(tool) {
+    if (!PREMIUM.has(tool))
+        return null;
+    const key = process.env.MCP_LICENSE_KEY;
+    if (!key)
+        return blocked(tool, "missing_key");
+    const hit = seen.get(key);
+    if (hit && Date.now() - hit.at < (hit.valid ? OK_CACHE_MS : BAD_CACHE_MS)) {
+        return hit.valid ? null : blocked(tool, hit.reason ?? "invalid");
+    }
+    let result;
+    try {
+        result = await verify(key);
+    }
+    catch {
+        result = { valid: false, reason: "network_error" };
+    }
+    seen.set(key, { ...result, at: Date.now() });
+    return result.valid ? null : blocked(tool, result.reason ?? "invalid");
+}

package/dist/server.js

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { rants } from "./api.js";
+import { rants, rantDetails, rantDigest } from "./api.js";
+import { premiumRequired } from "./license.js";
 const text = (value) => ({ content: [{ type: "text", text: value }] });
 const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
 const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
@@ -20,5 +21,36 @@ export function createServer() {
             return textError(error(e));
         }
     });
+    server.registerTool("rant_details", {
+        title: "Rant details",
+        description: "One devRant rant opened in full: the author and their score, the real score, the tags, the links embedded in the text, whether it is marked special or edited, and the whole comment thread ranked by score with the ten best shown. The rants tool prints one truncated line per rant and never opens one.",
+        inputSchema: z.object({ rant_id: z.number().describe("Rant id, like 194632."), app: z.number().describe("devRant app id, 3 is the public one.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: rant_details ----
+        const paywallMessage = await premiumRequired("rant_details");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await rantDetails(args));
+        }
+        catch (e) {
+            return textError(error(e));
+        }
+    });
+    server.registerTool("rant_digest", {
+        title: "Rant digest",
+        description: "The totals for one page of devRant rants rather than a list of them: the score and comment distribution with highest, median and lowest, how many rants carry no comments at all, how many are special or edited or have an image, the post time span, the tag tally and the most active authors. The rants tool prints rows, never totals.",
+        inputSchema: z.object({ app: z.number().describe("devRant app id, 3 is the public one.").optional(), sort: z.string().describe("algo, new, hot or top.").optional(), limit: z.number().describe("How many rants to fetch, 1 to 50.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            return text(await rantDigest(args));
+        }
+        catch (e) {
+            return textError(error(e));
+        }
+    });
     return server;
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.1",
+  "version": "1.0.2",
   "type": "module",
   "repository": {
     "type": "git",