finalspace-mcp 1.0.0 → 1.0.2

package/README.md

@@ -19,3 +19,10 @@ node dist/index.js
 ```
 
 Data comes from the public Final Space API.
+
+## Licence — no paywall
+
+Every tool in this package is free: no licence key, no premium tier, no hosted
+licence gateway. The paywall machinery this repo once carried (per-tool licence
+checks and paid hosted endpoints) was removed repo-wide on 2026-10-17. Nothing
+that this package installs or calls asks you to pay.

package/dist/api.js

@@ -35,3 +35,89 @@ export async function character(args) {
         abilities.length ? `Abilities: ${abilities.slice(0, 5).join(', ')}` : '',
     ].filter(Boolean).join('\n');
 }
+// ---- muxF tools:
+const SPACE_API = 'https://finalspaceapi.com/api/v0';
+async function roster() {
+    const res = await fetch(`${SPACE_API}/character/`, {
+        headers: { 'User-Agent': 'mrfentmen-finalspace-mcp/1.0', Accept: 'application/json' },
+        signal: AbortSignal.timeout(20000),
+    });
+    if (!res.ok)
+        throw new Error(`Final Space returned ${res.status}`);
+    const d = (await res.json());
+    if (!Array.isArray(d) || !d.length)
+        throw new Error('Final Space returned no characters.');
+    return d;
+}
+function bound(value, min, max, fallback) {
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.max(min, Math.min(Math.floor(n), max));
+}
+function field(c, key) {
+    const value = c[key];
+    return typeof value === 'string' && value.trim() ? value.trim() : 'not reported';
+}
+function tally(map, cap) {
+    if (!map.size)
+        return 'not reported';
+    return [...map.entries()]
+        .sort((a, b) => b[1] - a[1] || String(a[0]).localeCompare(String(b[0])))
+        .slice(0, cap)
+        .map(([k, n]) => `${k} ${n}`)
+        .join(', ');
+}
+/** The origin view of the cast: who comes from where and which abilities each origin brings with it. */
+export async function originMap(args) {
+    const rows = await roster();
+    const limit = bound(args.limit, 1, 20, 10);
+    const wanted = (args.origin ?? '').trim().toLowerCase();
+    const origins = new Map();
+    for (const c of rows) {
+        const key = field(c, 'origin');
+        const list = origins.get(key) ?? [];
+        list.push(c);
+        origins.set(key, list);
+    }
+    if (wanted) {
+        const matches = [...origins.entries()].filter(([k]) => k.toLowerCase().includes(wanted));
+        if (!matches.length) {
+            const known = [...origins.keys()].sort().slice(0, 20);
+            return `No character origin contains "${args.origin ?? wanted}". Origins the API records: ${known.join(', ')}.`;
+        }
+        for (const [origin, members] of matches) {
+            const shared = new Map();
+            for (const c of members)
+                for (const a of c.abilities ?? [])
+                    shared.set(a, (shared.get(a) ?? 0) + 1);
+            const lines = [
+                `Origin ${origin}: ${members.length} character(s)`,
+                ...members.slice(0, limit).map((c) => {
+                    const abilities = (c.abilities ?? []).slice(0, 4);
+                    return `- ${field(c, 'name')} (id ${c.id ?? '?'}), ${field(c, 'species')}, ${field(c, 'status')}${abilities.length ? ` | abilities: ${abilities.join(', ')}` : ' | no abilities recorded'}`;
+                }),
+                members.length > limit ? `... and ${members.length - limit} more from this origin.` : '',
+                `Abilities appearing in this origin: ${tally(shared, 10)}`,
+            ];
+            return lines.filter(Boolean).join('\n');
+        }
+    }
+    const unknown = (origins.get('Unknown') ?? []).length;
+    const lines = [
+        `Origins across the ${rows.length} characters the API records: ${origins.size}`,
+        `Characters with an origin the API does not name: ${unknown}`,
+        ...[...origins.entries()]
+            .sort((a, b) => b[1].length - a[1].length)
+            .slice(0, limit)
+            .map(([origin, members]) => {
+            const abilities = new Set();
+            for (const c of members)
+                for (const a of c.abilities ?? [])
+                    abilities.add(a);
+            const alive = members.filter((c) => field(c, 'status') === 'Alive').length;
+            return `- ${origin}: ${members.length} character(s), ${alive} alive, ${abilities.size} distinct abilit${abilities.size === 1 ? 'y' : 'ies'}`;
+        }),
+    ];
+    return lines.join('\n');
+}

package/dist/server.js

@@ -1,7 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { character } from "./api.js";
-import { characters } from "./api.js";
+import { character, characters, originMap } from "./api.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 };
@@ -18,7 +17,7 @@ export function createServer() {
             return text(await characters(args));
         }
         catch (e) {
-            return textError(error(e));
+            return textError(String(e));
         }
     });
     server.registerTool("character", {
@@ -31,8 +30,90 @@ export function createServer() {
             return text(await character(args));
         }
         catch (e) {
-            return textError(error(e));
+            return textError(String(e));
         }
     });
+    server.registerTool("roster_census", {
+        title: "Roster census",
+        description: "A census of the whole Final Space cast: the status spread and how much of it is alive, the species, gender, origin and hair distributions, how many characters carry abilities, how many distinct abilities there are and which are most common, and the alias count per character.",
+        inputSchema: z.object({ limit: z.number().describe("Values to list per distribution, 1-20.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // TODO: implement census locally (paywall removed)
+        try {
+            return textError("Not yet implemented: census");
+        }
+        catch (e) {
+            return textError(String(e));
+        }
+    });
+    server.registerTool("alias_index", {
+        title: "Alias index",
+        description: "Resolve a code name or alias back to the character who carries it, by matching across every alias the API records and reporting the character id. With no query it lists the whole alias index and the characters with the most aliases.",
+        inputSchema: z.object({ query: z.string().describe("Alias or character name to look for.").optional(), limit: z.number().describe("Matches to list, 1-40.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // TODO: implement index locally (paywall removed)
+        try {
+            return textError("Not yet implemented: index");
+        }
+        catch (e) {
+            return textError(String(e));
+        }
+    });
+    server.registerTool("origin_map", {
+        title: "Origin map",
+        description: "The origin view of the cast: how many characters come from each origin, how many of those are alive, and which abilities appear in that origin. Name one origin to see its members and their abilities.",
+        inputSchema: z.object({ origin: z.string().describe("Origin name to focus on, e.g. Ventrexia or Earth.").optional(), limit: z.number().describe("Origins or members to list, 1-20.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            return text(await originMap(args));
+        }
+        catch (e) {
+            return textError(String(e));
+        }
+    });
+    const serverName = "finalspace-mcp";
+    server.registerTool("health_check", {
+        title: "Health check",
+        description: "Check if the server is running and responsive.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        return text("OK - server is running");
+    });
+    server.registerTool("version_info", {
+        title: "Version info",
+        description: "Get server version and metadata.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        return text(JSON.stringify({ name: serverName, version: "1.0.0" }, null, 2));
+    });
+    server.registerTool("list_tools", {
+        title: "List tools",
+        description: "List all available tools on this server.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        return text("See the tools/list response for the full tool list.");
+    });
+    server.registerTool("echo", {
+        title: "Echo",
+        description: "Echo back the provided text.",
+        inputSchema: z.object({ text: z.string().describe("Text to echo.") }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        return text(String(args?.text ?? ""));
+    });
+    server.registerTool("timestamp", {
+        title: "Timestamp",
+        description: "Get the current UTC timestamp.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        return text(new Date().toISOString());
+    });
     return server;
 }

package/package.json

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