civitai-mcp 1.0.0 → 1.0.2

package/README.md

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

@@ -47,3 +47,156 @@ export async function model(args) {
         s('createdAt') ? `Created: ${String(s('createdAt')).slice(0, 10)}` : '',
     ].filter(Boolean).join('\n') || `No data for model ${id}.`;
 }
+// ---- muxE tools:
+// The two existing tools read the model list and the model record, both of which
+// stop at the model. The new ones go one level deeper to a single released
+// version and its files and generation settings, and sideways to everything one
+// creator has published, which the models route cannot filter for on its own.
+const API_ROOT = 'https://civitai.com/api/v1';
+const CIV_UA = 'mrfentmen-civitai-mcp/1.0';
+async function civGet(url, notFound) {
+    const res = await fetch(url, {
+        headers: { 'User-Agent': CIV_UA, Accept: 'application/json' },
+        signal: AbortSignal.timeout(25000),
+    });
+    const raw = await res.text();
+    let parsed = null;
+    try {
+        parsed = raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        // the body was not JSON, so only the status is available as a reason
+        parsed = null;
+    }
+    if (!res.ok) {
+        if (notFound && res.status === 404)
+            throw new Error(notFound);
+        const why = typeof parsed?.message === 'string' ? parsed.message : typeof parsed?.error === 'string' ? parsed.error : `Civitai returned ${res.status}`;
+        throw new Error(why);
+    }
+    if (!parsed)
+        throw new Error('Civitai returned a body that is not JSON.');
+    if (typeof parsed.error === 'string')
+        throw new Error(`Civitai said: ${parsed.error}`);
+    return parsed;
+}
+const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? value.toLocaleString('en-US') : 'not reported');
+/** identifiers are never grouped, only counts are */
+const idOf = (value) => (typeof value === 'number' && Number.isFinite(value) ? String(value) : 'not reported');
+const metaText = (meta, key) => {
+    const v = meta?.[key];
+    if (v === undefined || v === null || v === '')
+        return 'not reported';
+    return String(v).slice(0, 160);
+};
+export async function modelVersion(args) {
+    const id = Math.floor(Number(args?.version_id));
+    if (!Number.isInteger(id) || id <= 0)
+        throw new Error('Provide the model version ID as a whole number, for example 290640.');
+    const v = await civGet(`${API_ROOT}/model-versions/${id}`, 'Civitai does not know that model version id.');
+    if (!v || typeof v !== 'object' || typeof v.id !== 'number' || typeof v.name !== 'string') {
+        throw new Error('Civitai returned no version record for that id.');
+    }
+    const stats = v.stats ?? {};
+    const files = Array.isArray(v.files) ? v.files : [];
+    const images = Array.isArray(v.images) ? v.images : [];
+    const lines = [
+        `${v.model?.name ?? 'model not reported'} - version ${v.name}`,
+        `  version id: ${idOf(v.id)}, model id: ${idOf(v.modelId)}`,
+        `  type: ${v.model?.type ?? 'not reported'}`,
+        `  status: ${v.status ?? 'not reported'}`,
+        `  published: ${v.publishedAt ? String(v.publishedAt).slice(0, 10) : 'not reported'}`,
+        `  created: ${v.createdAt ? String(v.createdAt).slice(0, 10) : 'not reported'}`,
+        `  last updated: ${v.updatedAt ? String(v.updatedAt).slice(0, 10) : 'not reported'}`,
+        `  base model: ${v.baseModel ?? 'not reported'} (${v.baseModelType ?? 'type not reported'})`,
+        `  downloads: ${num(stats.downloadCount)}, thumbs up: ${num(stats.thumbsUpCount)}, comments: ${num(stats.commentCount)}, ratings: ${num(stats.ratingCount)}`,
+        `  usage: ${v.usageControl ?? 'not reported'}, upload type: ${v.uploadType ?? 'not reported'}`,
+    ];
+    const words = Array.isArray(v.trainedWords) ? v.trainedWords : [];
+    if (words.length) {
+        lines.push(`  trigger words: ${words.length}`);
+        for (const w of words.slice(0, 12))
+            lines.push(`    ${String(w).slice(0, 80)}`);
+        if (words.length > 12)
+            lines.push(`    and ${words.length - 12} more`);
+    }
+    else {
+        lines.push('  trigger words: none listed.');
+    }
+    lines.push(`  files: ${files.length}`);
+    for (const f of files.slice(0, 12)) {
+        const sizeKb = typeof f.sizeKB === 'number' && Number.isFinite(f.sizeKB) ? `${(f.sizeKB / 1024).toFixed(1)} MB` : 'size not reported';
+        lines.push(`    ${f.name ?? 'name not reported'} [${f.type ?? 'type not reported'}] ${sizeKb}`);
+        const sha = f.hashes?.SHA256;
+        lines.push(`      sha256: ${sha ?? 'not reported'}`);
+        lines.push(`      virus scan: ${f.virusScanResult ?? 'not reported'}, pickle scan: ${f.pickleScanResult ?? 'not reported'}`);
+    }
+    if (files.length > 12)
+        lines.push(`    and ${files.length - 12} more file(s)`);
+    if (v.downloadUrl)
+        lines.push(`  download endpoint: ${v.downloadUrl}`);
+    const described = images.filter((im) => im.hasMeta && im.meta);
+    lines.push(`  example images: ${images.length}, of which ${described.length} carry the generation settings that produced them`);
+    for (const im of described.slice(0, 5)) {
+        const m = im.meta ?? {};
+        const size = typeof im.width === 'number' && typeof im.height === 'number' ? `${im.width}x${im.height}` : 'size not reported';
+        lines.push(`    ${im.url ?? 'image url not reported'}`);
+        lines.push(`      ${size}, seed ${metaText(m, 'seed')}, sampler ${metaText(m, 'sampler')}, scheduler ${metaText(m, 'scheduler')}, steps ${metaText(m, 'steps')}, cfg ${metaText(m, 'cfgScale')}`);
+        lines.push(`      prompt: ${metaText(m, 'prompt')}`);
+        const neg = m.negativePrompt;
+        if (neg !== undefined && neg !== null && neg !== '')
+            lines.push(`      negative prompt: ${String(neg).slice(0, 120)}`);
+    }
+    if (described.length > 5)
+        lines.push(`    and ${described.length - 5} more described image(s)`);
+    if (!described.length)
+        lines.push('  none of the example images publish their generation settings.');
+    return lines.join('\n');
+}
+export async function creatorModels(args) {
+    const username = (args?.username ?? '').trim();
+    if (!username)
+        throw new Error('Provide a Civitai username.');
+    if (!/^[\w.-]{1,64}$/.test(username)) {
+        throw new Error('A Civitai username may only hold letters, digits, dots, dashes and underscores.');
+    }
+    const limit = Math.max(1, Math.min(Number(args?.limit ?? 10) || 10, 30));
+    const url = `${API_ROOT}/models?username=${encodeURIComponent(username)}&limit=${limit}`;
+    const d = await civGet(url, `Civitai has no creator called "${username}".`);
+    const rows = Array.isArray(d.items) ? d.items : [];
+    if (!rows.length)
+        return `Civitai lists no public model for the creator "${username}".`;
+    const totalItems = typeof d.metadata?.totalItems === 'number' ? d.metadata.totalItems : null;
+    const lines = [
+        `Public models by ${username} on Civitai (${rows.length} shown${totalItems !== null ? `, the API reports ${totalItems.toLocaleString('en-US')} in total` : ''}):`,
+    ];
+    let downloads = 0;
+    let counted = 0;
+    rows.forEach((r, i) => {
+        const s = (k) => (r[k] != null ? String(r[k]) : '');
+        const stats = (r.stats && typeof r.stats === 'object' ? r.stats : {});
+        const dl = typeof stats.downloadCount === 'number' ? stats.downloadCount : null;
+        const tu = typeof stats.thumbsUpCount === 'number' ? stats.thumbsUpCount : null;
+        if (dl !== null) {
+            downloads += dl;
+            counted += 1;
+        }
+        const tags = Array.isArray(r.tags) ? r.tags.map((t) => (t && typeof t === 'object' ? String(t.name ?? '') : String(t))).filter(Boolean) : [];
+        const bases = Array.isArray(r.baseModels) ? r.baseModels.map((b) => String(b)).filter(Boolean) : [];
+        const versions = Array.isArray(r.modelVersions) ? r.modelVersions.length : null;
+        lines.push(`${i + 1}. ${s('name') || 'name not reported'} [${s('type') || 'type not reported'}]`);
+        lines.push(`   id ${s('id') || 'not reported'}, downloads ${dl !== null ? dl.toLocaleString('en-US') : 'not reported'}, thumbs up ${tu !== null ? tu.toLocaleString('en-US') : 'not reported'}${versions !== null ? `, ${versions} version(s)` : ''}`);
+        lines.push(`   created ${s('createdAt') ? String(s('createdAt')).slice(0, 10) : 'not reported'}, mode ${s('mode') || 'not reported'}${r.nsfw === true ? ', marked NSFW' : ''}`);
+        if (bases.length)
+            lines.push(`   base models: ${bases.slice(0, 6).join(', ')}`);
+        if (tags.length)
+            lines.push(`   tags: ${tags.slice(0, 10).join(', ')}${tags.length > 10 ? `, and ${tags.length - 10} more` : ''}`);
+        const desc = s('description').replace(/<[^>]*>/g, '').trim();
+        if (desc)
+            lines.push(`   ${desc.slice(0, 160)}`);
+    });
+    if (counted) {
+        lines.push(`  downloads across the ${counted} model(s) above: ${downloads.toLocaleString('en-US')}`);
+    }
+    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 = "civitai-mcp";
+// Tools that need a key. Everything else is free.
+const PREMIUM = new Set([
+    "model_version",
+]);
+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 { model } from "./api.js";
-import { models } from "./api.js";
+import { models, modelVersion, creatorModels } 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,36 @@ export function createServer() {
             return textError(error(e));
         }
     });
+    server.registerTool("model_version", {
+        title: "Model version",
+        description: "One released model version in full: its base model, trigger words, stats, every downloadable file with its size, sha256 and virus and pickle scan results, and the generation settings behind the example images, seed by seed. The model tool only reports the parent model's name, description and totals.",
+        inputSchema: z.object({ version_id: z.number().describe("Model version ID, like 290640. The models tool's rows carry these under versions.") }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: model_version ----
+        const paywallMessage = await premiumRequired("model_version");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await modelVersion(args));
+        }
+        catch (e) {
+            return textError(error(e));
+        }
+    });
+    server.registerTool("creator_models", {
+        title: "Creator models",
+        description: "Everything one Civitai creator has published: each model with its type, downloads, thumbs up, version count, base models and tags, plus the total downloads across the models shown. The models tool searches by text only and cannot filter to a creator.",
+        inputSchema: z.object({ username: z.string().describe("Civitai username, like JustMaier."), limit: z.number().describe("Max models, 1 to 30.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            return text(await creatorModels(args));
+        }
+        catch (e) {
+            return textError(error(e));
+        }
+    });
     return server;
 }

package/package.json

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

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/mrfentmen/civitai-mcp",
     "source": "github"
   },
-  "version": "1.0.0",
+  "version": "1.0.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "civitai-mcp",
-      "version": "1.0.0",
+      "version": "1.0.1",
       "transport": {
         "type": "stdio"
       }