@mrfentmen/catfact-mcp 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# Cat Fact
 
-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.
+Cat facts and breed data from catfact.ninja - a random fact, fact browsing by page, and the cat breed list, keyless.
+
+Keyless — no signup, no API key, no environment variables.
+
+## Install
+
+```bash
+npx -y @mrfentmen/catfact-mcp
+```
+
+Or add it to your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "catfact-mcp": { "command": "npx", "args": ["-y", "@mrfentmen/catfact-mcp"] }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `random_cat_fact` | One random cat fact. |
+| `cat_breeds` | The cat breed list with country of origin, coat and pattern. |
+| `list_facts` | Browse the cat fact database page by page. |
+
+## Data source
+
+catfact.ninja, a keyless cat fact and breed API.

package/dist/api.d.ts

@@ -0,0 +1,14 @@
+export declare class SourceError extends Error {
+}
+export declare function getJson(path: string, accept?: string, timeoutMs?: number): Promise<any>;
+export declare function clampLimit(n: number | undefined, fallback: number, max: number): number;
+export declare function clean(s: unknown): string;
+export declare function randomCatFact(): Promise<string>;
+export declare function catBreeds(a: {
+    limit?: number;
+    page?: number;
+}): Promise<string>;
+export declare function listFacts(a: {
+    limit?: number;
+    page?: number;
+}): Promise<string>;

package/dist/api.js

@@ -0,0 +1,91 @@
+/**
+ * Cat Fact — keyless public API client.
+ */
+const BASE = "https://catfact.ninja";
+const SOURCE = "Cat Fact";
+export class SourceError extends Error {
+}
+async function request(path, accept = "application/json", timeoutMs = 25000) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const res = await fetch(path.startsWith("http") ? path : BASE + path, {
+            signal: ctrl.signal,
+            headers: { "user-agent": "catfact-mcp", accept },
+        });
+        if (!res.ok)
+            throw new SourceError(`${SOURCE} responded ${res.status}`);
+        return res;
+    }
+    catch (e) {
+        if (e instanceof SourceError)
+            throw e;
+        if (e.name === "AbortError")
+            throw new SourceError(`${SOURCE} request timed out`);
+        throw new SourceError(`${SOURCE} request failed: ${e.message}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function getJson(path, accept = "application/json", timeoutMs = 25000) {
+    const res = await request(path, accept, timeoutMs);
+    const body = await res.text();
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        throw new SourceError(`${SOURCE} returned malformed JSON`);
+    }
+}
+export function clampLimit(n, fallback, max) {
+    const v = n ?? fallback;
+    if (!Number.isInteger(v) || v < 1 || v > max)
+        throw new SourceError(`limit must be between 1 and ${max}`);
+    return v;
+}
+export function clean(s) {
+    return String(s ?? "").replace(/\s+/g, " ").trim();
+}
+export async function randomCatFact() {
+    const body = await getJson("/fact", "application/json", 25000);
+    const fact = clean(body?.fact);
+    if (!fact)
+        throw new SourceError("catfact.ninja returned no fact");
+    return `${fact}\n\n(${fact.length} characters)`;
+}
+export async function catBreeds(a) {
+    const limit = clampLimit(a.limit, 10, 50);
+    const page = Math.floor(a.page ?? 1);
+    if (!Number.isInteger(page) || page < 1 || page > 50)
+        throw new SourceError("page must be between 1 and 50");
+    const body = await getJson(`/breeds?limit=${limit}&page=${page}`, "application/json", 25000);
+    const rows = Array.isArray(body?.data) ? body.data : [];
+    if (!rows.length)
+        throw new SourceError("catfact.ninja returned no breeds");
+    const start = (Number(body?.current_page ?? page) - 1) * limit;
+    return [
+        `${body?.total ?? rows.length} breed(s) on record (page ${body?.current_page ?? page} of ${body?.last_page ?? "?"}), showing ${rows.length}:`,
+        "",
+        ...rows.map((r, i) => {
+            const bits = [clean(r?.country), clean(r?.coat) ? `coat ${clean(r.coat)}` : "", clean(r?.pattern)].filter(Boolean);
+            return `${String(start + i + 1).padStart(3)}. ${clean(r?.breed).padEnd(24)} ${bits.join(" · ")}`;
+        }),
+    ].join("\n");
+}
+export async function listFacts(a) {
+    const limit = clampLimit(a.limit, 10, 50);
+    const page = Math.floor(a.page ?? 1);
+    if (!Number.isInteger(page) || page < 1 || page > 50)
+        throw new SourceError("page must be between 1 and 50");
+    const body = await getJson(`/facts?limit=${limit}&page=${page}`, "application/json", 25000);
+    const rows = Array.isArray(body?.data) ? body.data : [];
+    if (!rows.length)
+        throw new SourceError("catfact.ninja returned no facts");
+    const start = (Number(body?.current_page ?? page) - 1) * limit;
+    return [
+        `${body?.total ?? rows.length} fact(s) on record (page ${body?.current_page ?? page} of ${body?.last_page ?? "?"}), showing ${rows.length}:`,
+        "",
+        ...rows.map((r, i) => `${String(start + i + 1).padStart(4)}. ${clean(r?.fact)}`),
+    ].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("catfact-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,43 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { catBreeds, listFacts, randomCatFact, SourceError } from "./api.js";
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+function errorMessage(e) {
+    if (e instanceof SourceError || e instanceof Error)
+        return `Error: ${e.message}`;
+    return `Error: ${String(e)}`;
+}
+export function createServer() {
+    const server = new McpServer({ name: "catfact-mcp", version: "1.0.0" });
+    server.tool("random_cat_fact", "One random cat fact.", {
+    // no arguments
+    }, async (a) => {
+        try {
+            return text(await randomCatFact());
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: errorMessage(e) }], isError: true };
+        }
+    });
+    server.tool("cat_breeds", "The cat breed list with country of origin, coat and pattern.", {
+        limit: z.number().int().min(1).max(50).optional().describe('Breeds per page, default 10'), page: z.number().int().min(1).max(50).optional().describe('Page number, default 1')
+    }, async (a) => {
+        try {
+            return text(await catBreeds(a));
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: errorMessage(e) }], isError: true };
+        }
+    });
+    server.tool("list_facts", "Browse the cat fact database page by page.", {
+        limit: z.number().int().min(1).max(50).optional().describe('Facts per page, default 10'), page: z.number().int().min(1).max(50).optional().describe('Page number, default 1')
+    }, async (a) => {
+        try {
+            return text(await listFacts(a));
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: errorMessage(e) }], isError: true };
+        }
+    });
+    return server;
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@mrfentmen/catfact-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Cat facts and breed data from catfact.ninja - a random fact, fact browsing by page, and the cat breed list, keyless.",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/catfact-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrfentmen/awesome-servers.git"
+  },
+  "bin": {
+    "catfact-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "cats",
+    "facts",
+    "breeds",
+    "animals",
+    "fun",
+    "keyless"
+  ],
+  "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"
+  }
+}