finalspace-mcp 1.0.0 → 1.0.1

package/README.md

@@ -19,3 +19,22 @@ node dist/index.js
 ```
 
 Data comes from the public Final Space API.
+
+<!-- paywall -->
+## Premium tools
+
+These tools need a license key:
+
+* `roster_census`
+* `alias_index`
+
+Buy a key at https://mcp-marketplace.io/server/io-github-mrfentmen-finalspace-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

@@ -35,3 +35,158 @@ 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(', ');
+}
+/** A census of the whole cast: who is alive, what they are, where they are from and what they can do. */
+export async function rosterCensus(args) {
+    const rows = await roster();
+    const limit = bound(args.limit, 1, 20, 8);
+    const statuses = new Map();
+    const species = new Map();
+    const genders = new Map();
+    const origins = new Map();
+    const hair = new Map();
+    const abilities = new Map();
+    let withAbilities = 0;
+    let withAliases = 0;
+    let aliasTotal = 0;
+    for (const c of rows) {
+        statuses.set(field(c, 'status'), (statuses.get(field(c, 'status')) ?? 0) + 1);
+        species.set(field(c, 'species'), (species.get(field(c, 'species')) ?? 0) + 1);
+        genders.set(field(c, 'gender'), (genders.get(field(c, 'gender')) ?? 0) + 1);
+        origins.set(field(c, 'origin'), (origins.get(field(c, 'origin')) ?? 0) + 1);
+        hair.set(field(c, 'hair'), (hair.get(field(c, 'hair')) ?? 0) + 1);
+        const list = c.abilities ?? [];
+        if (list.length)
+            withAbilities += 1;
+        for (const a of list)
+            abilities.set(a, (abilities.get(a) ?? 0) + 1);
+        const alias = c.alias ?? [];
+        if (alias.length)
+            withAliases += 1;
+        aliasTotal += alias.length;
+    }
+    const alive = (statuses.get('Alive') ?? 0);
+    return [
+        `Final Space cast census over ${rows.length} character(s)`,
+        `Status: ${tally(statuses, limit)}`,
+        `Alive: ${alive} of ${rows.length} (${((alive / rows.length) * 100).toFixed(1)}%), with ${rows.length - alive} not recorded as alive`,
+        `Species: ${rows.length} distinct values, leading them ${tally(species, limit)}`,
+        `Gender: ${rows.length} distinct values as the API records them, leading them ${tally(genders, limit)}`,
+        `Origin: ${origins.size} distinct origins, leading them ${tally(origins, limit)}`,
+        `Hair: ${tally(hair, limit)}`,
+        `Characters with at least one ability: ${withAbilities} of ${rows.length}`,
+        `Distinct abilities across the cast: ${abilities.size}, from ${[...abilities.values()].reduce((a, b) => a + b, 0)} mentions, most common ${tally(abilities, 8)}`,
+        `Aliases: ${aliasTotal} across ${withAliases} character(s), so ${(aliasTotal / Math.max(1, withAliases)).toFixed(1)} per character that has any`,
+    ].join('\n');
+}
+/** Resolve a code name or alias back to the character who carries it, which the name and id tools cannot do. */
+export async function aliasIndex(args) {
+    const rows = await roster();
+    const query = (args.query ?? '').trim().toLowerCase();
+    const limit = bound(args.limit, 1, 40, 20);
+    const entries = [];
+    for (const c of rows) {
+        for (const alias of c.alias ?? [])
+            entries.push({ alias, name: field(c, 'name'), id: Number(c.id ?? 0) });
+    }
+    const hits = query ? entries.filter((e) => e.alias.toLowerCase().includes(query) || e.name.toLowerCase().includes(query)) : entries;
+    const most = new Map();
+    for (const c of rows)
+        most.set(field(c, 'name'), (c.alias ?? []).length);
+    const busiest = [...most.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5);
+    if (!hits.length) {
+        return `No alias or character name in the ${entries.length} recorded aliases contains "${query}".`;
+    }
+    return [
+        query ? `Alias matches for "${query}" across the ${entries.length} aliases the API records:` : `Every alias the API records: ${entries.length}`,
+        `Aliases are matched loosely, so a code name in the show can often be resolved to a character id here.`,
+        ...hits.slice(0, limit).map((e, i) => `${i + 1}. "${e.alias}" -> ${e.name} (character id ${e.id || 'not reported'})`),
+        hits.length > limit ? `... and ${hits.length - limit} more match(es).` : '',
+        `Characters with the most aliases: ${busiest.map(([k, n]) => `${k} (${n})`).join(', ')}`,
+    ].filter(Boolean).join('\n');
+}
+/** 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/license.js

@@ -0,0 +1,79 @@
+// 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 = "finalspace-mcp";
+// Tools that need a key. Everything else is free.
+const PREMIUM = new Set([
+    "roster_census",
+    "alias_index",
+]);
+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,7 +1,8 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { character } from "./api.js";
-import { characters } from "./api.js";
+import { characters, rosterCensus, aliasIndex, originMap } 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 };
@@ -34,5 +35,54 @@ export function createServer() {
             return textError(error(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) => {
+        // ---- paywall: roster_census ----
+        const paywallMessage = await premiumRequired("roster_census");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await rosterCensus(args));
+        }
+        catch (e) {
+            return textError(error(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) => {
+        // ---- paywall: alias_index ----
+        const paywallMessage = await premiumRequired("alias_index");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await aliasIndex(args));
+        }
+        catch (e) {
+            return textError(error(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(error(e));
+        }
+    });
     return server;
 }

package/package.json

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