wikimedia-commons-mcp 1.0.0 → 1.0.2

package/README.md

@@ -21,3 +21,22 @@ node dist/index.js
 ## Source
 
 Public free APIs only. See `src/api.ts` for exact endpoints.
+
+<!-- paywall -->
+## Premium tools
+
+These tools need a licence key:
+
+* `file_categories`
+* `file_thumbnail`
+
+The tool bodies run on our gateway, not inside this package, so the key is what buys access. Buy one at https://buy.polar.sh/polar_cl_mrO7rS5LZxpqM7oAFFEA10i9121J240U40IIj4JRZO4 and set it in your MCP client config:
+
+```json
+"env": { "MCP_LICENSE_KEY": "polar_..." }
+```
+
+The gateway checks the key against Polar and gives every key 1,000 free premium
+calls a month before per-call billing starts. Every other tool on this server
+stays free.
+<!-- /paywall -->

package/dist/api.js

@@ -102,3 +102,31 @@ export const m0_file = m0.file;
 export const m0_search = m0.search;
 export const m0_CommonsError = m0.CommonsError;
 export const m1_random = m1.random;
+// ---- muxC tools:
+const COMMONS_BASE = "https://commons.wikimedia.org/w/api.php";
+const COMMONS_UA = "mrfentmen-wikimedia-commons-mcp/1.0 (https://github.com/mrfentmen)";
+class CommonsLookupError extends Error {
+}
+async function commonsGet(url) {
+    const res = await fetch(url, {
+        headers: { "User-Agent": COMMONS_UA, Accept: "application/json" },
+        signal: AbortSignal.timeout(30000),
+    });
+    if (!res.ok)
+        throw new CommonsLookupError(`Wikimedia Commons returned HTTP ${res.status}`);
+    return res.json();
+}
+/** Browse a Commons category and list the media files inside it. */
+export async function categoryFiles(args) {
+    const raw = (args.category ?? "").trim();
+    if (!raw)
+        throw new CommonsLookupError("Provide a category name, e.g. Featured pictures of animals");
+    const category = raw.startsWith("Category:") ? raw : `Category:${raw}`;
+    const limit = Math.max(1, Math.min(args.limit ?? 10, 50));
+    const d = await commonsGet(`${COMMONS_BASE}?action=query&list=categorymembers&cmtitle=${encodeURIComponent(category)}&cmtype=file|subcat&cmlimit=${limit}&format=json&origin=*`);
+    const rows = d?.query?.categorymembers ?? [];
+    if (!rows.length)
+        return `Commons category ${category} has no file or subcategory members.`;
+    return `Members of ${category} (${rows.length} shown):\n` +
+        rows.map((m, i) => `${i + 1}. ${m.title} (${m.ns === 14 ? "subcategory" : "file"})`).join("\n");
+}

package/dist/gateway.js

@@ -0,0 +1,85 @@
+/**
+ * Thin client for the premium gateway.
+ *
+ * The premium tools do not run in this package any more. Their bodies live on
+ * the gateway, which checks a Polar licence key before it does any work, so
+ * deleting anything here buys nothing: the answer only exists behind the gate.
+ *
+ * Set `MCP_LICENSE_KEY` to a Polar licence key. `MCP_GATEWAY_URL` overrides the
+ * endpoint, which is only useful for testing.
+ */
+const DEFAULT_GATEWAY_URL = 'https://mcp-gateway.contactae2000.workers.dev/mcp';
+const DEFAULT_TIMEOUT_MS = 25000;
+const USER_AGENT = 'mrfentmen-mcp/1.0';
+/** Raised when a premium call cannot be completed. `message` is safe to show. */
+export class GatewayError extends Error {
+    refused;
+    constructor(message, refused) {
+        super(message);
+        this.refused = refused;
+        this.name = 'GatewayError';
+    }
+}
+export async function premiumTool(tool, args) {
+    const key = (process.env.MCP_LICENSE_KEY ?? '').trim();
+    if (!key) {
+        throw new GatewayError(`"${tool}" is a premium tool and no licence key is set. Set MCP_LICENSE_KEY in your MCP client config.`, true);
+    }
+    const url = (process.env.MCP_GATEWAY_URL ?? DEFAULT_GATEWAY_URL).trim();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                accept: 'application/json',
+                'user-agent': USER_AGENT,
+                authorization: `Bearer ${key}`,
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'tools/call',
+                params: { name: tool, arguments: args },
+            }),
+            signal: controller.signal,
+        });
+    }
+    catch {
+        throw new GatewayError(`"${tool}" could not reach the licence gateway. Check your connection and try again.`, false);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        throw new GatewayError(`"${tool}" could not reach the licence gateway (HTTP ${response.status}).`, false);
+    }
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        throw new GatewayError(`"${tool}" got an unreadable answer from the licence gateway.`, false);
+    }
+    if (body.error) {
+        throw new GatewayError(`"${tool}" was refused by the licence gateway: ${body.error.message ?? 'unknown error'}`, false);
+    }
+    const result = body.result ?? {};
+    const text = (result.content ?? [])
+        .map((part) => part.text ?? '')
+        .join('\n')
+        .trim();
+    if (result.isError) {
+        // The gateway marks a licence refusal structurally, so a missing or rejected
+        // key is told apart from a tool that failed after the gate let it through.
+        if (result.structuredContent?.licenceRefusal) {
+            throw new GatewayError(text || `"${tool}" needs a valid licence key.`, true);
+        }
+        throw new GatewayError(text || `"${tool}" failed on the licence gateway.`, false);
+    }
+    if (!text)
+        throw new GatewayError(`"${tool}" returned no data.`, false);
+    return text;
+}

package/dist/server.js

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { m0_file, m0_search, m1_random } from './api.js';
+import { m0_file, m0_search, m1_random, categoryFiles } from "./api.js";
+import { premiumTool } from "./gateway.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 };
@@ -47,5 +48,50 @@ export function createServer() {
             return textError(error(e));
         }
     });
+    server.registerTool("file_categories", {
+        title: "File categories",
+        description: "The Wikimedia Commons categories a file sits in, which is how Commons media gets browsed.",
+        inputSchema: z.object({ title: z.string().describe("File title like File:Example.jpg."), limit: z.number().describe("Max categories.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: file_categories ----
+        // The body runs on the gateway, behind the licence gate.
+        // ---- paywall: end ----
+        try {
+            return text(await premiumTool("mcp_wikimedia_commons_file_categories", args));
+        }
+        catch (e) {
+            return textError(error(e));
+        }
+    });
+    server.registerTool("file_thumbnail", {
+        title: "File thumbnail",
+        description: "The thumbnail URL for a Commons file at a chosen pixel width, alongside the original's dimensions and MIME type.",
+        inputSchema: z.object({ title: z.string().describe("File title like File:Example.jpg."), width: z.number().describe("Thumbnail width in pixels, 20 to 2000.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: file_thumbnail ----
+        // The body runs on the gateway, behind the licence gate.
+        // ---- paywall: end ----
+        try {
+            return text(await premiumTool("mcp_wikimedia_commons_file_thumbnail", args));
+        }
+        catch (e) {
+            return textError(error(e));
+        }
+    });
+    server.registerTool("category_files", {
+        title: "Category files",
+        description: "List the media files and subcategories inside a Wikimedia Commons category.",
+        inputSchema: z.object({ category: z.string().describe("Category name, e.g. Featured pictures of animals."), limit: z.number().describe("Max members.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            return text(await categoryFiles(args));
+        }
+        catch (e) {
+            return textError(error(e));
+        }
+    });
     return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wikimedia-commons-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Wikimedia Commons file search.",
   "type": "module",
   "main": "dist/index.js",

package/src/api.ts

@@ -67,7 +67,6 @@ return { CommonsError, file, search };
 const m1 = (() => {
 const BASE = 'https://commons.wikimedia.org/w/api.php';
 
-
 async function random(args: m1_RandomArgs): Promise<string> {
   const limit = Math.max(1, Math.min(args.limit ?? 5, 15));
   const params = new URLSearchParams({
@@ -111,3 +110,34 @@ export const m0_file = m0.file;
 export const m0_search = m0.search;
 export const m0_CommonsError = m0.CommonsError;
 export const m1_random = m1.random;
+
+// ---- muxC tools:
+
+const COMMONS_BASE = "https://commons.wikimedia.org/w/api.php"
+const COMMONS_UA = "mrfentmen-wikimedia-commons-mcp/1.0 (https://github.com/mrfentmen)"
+
+class CommonsLookupError extends Error {}
+
+async function commonsGet(url: string): Promise<any> {
+  const res = await fetch(url, {
+    headers: { "User-Agent": COMMONS_UA, Accept: "application/json" },
+    signal: AbortSignal.timeout(30000),
+  })
+  if (!res.ok) throw new CommonsLookupError(`Wikimedia Commons returned HTTP ${res.status}`)
+  return res.json()
+}
+
+/** Browse a Commons category and list the media files inside it. */
+export async function categoryFiles(args: { category?: string; limit?: number }): Promise<string> {
+  const raw = (args.category ?? "").trim()
+  if (!raw) throw new CommonsLookupError("Provide a category name, e.g. Featured pictures of animals")
+  const category = raw.startsWith("Category:") ? raw : `Category:${raw}`
+  const limit = Math.max(1, Math.min(args.limit ?? 10, 50))
+  const d = await commonsGet(
+    `${COMMONS_BASE}?action=query&list=categorymembers&cmtitle=${encodeURIComponent(category)}&cmtype=file|subcat&cmlimit=${limit}&format=json&origin=*`,
+  )
+  const rows = d?.query?.categorymembers ?? []
+  if (!rows.length) return `Commons category ${category} has no file or subcategory members.`
+  return `Members of ${category} (${rows.length} shown):\n` +
+    rows.map((m: any, i: number) => `${i + 1}. ${m.title} (${m.ns === 14 ? "subcategory" : "file"})`).join("\n")
+}

package/src/gateway.ts

@@ -0,0 +1,106 @@
+/**
+ * Thin client for the premium gateway.
+ *
+ * The premium tools do not run in this package any more. Their bodies live on
+ * the gateway, which checks a Polar licence key before it does any work, so
+ * deleting anything here buys nothing: the answer only exists behind the gate.
+ *
+ * Set `MCP_LICENSE_KEY` to a Polar licence key. `MCP_GATEWAY_URL` overrides the
+ * endpoint, which is only useful for testing.
+ */
+
+const DEFAULT_GATEWAY_URL = 'https://mcp-gateway.contactae2000.workers.dev/mcp'
+const DEFAULT_TIMEOUT_MS = 25000
+const USER_AGENT = 'mrfentmen-mcp/1.0'
+
+/** Raised when a premium call cannot be completed. `message` is safe to show. */
+export class GatewayError extends Error {
+  constructor(message: string, readonly refused: boolean) {
+    super(message)
+    this.name = 'GatewayError'
+  }
+}
+
+interface ContentPart {
+  text?: string
+}
+
+interface CallResult {
+  content?: ContentPart[]
+  isError?: boolean
+  structuredContent?: { licenceRefusal?: boolean }
+}
+
+interface JsonRpcResponse {
+  result?: CallResult
+  error?: { message?: string }
+}
+
+export async function premiumTool(tool: string, args: Record<string, unknown>): Promise<string> {
+  const key = (process.env.MCP_LICENSE_KEY ?? '').trim()
+  if (!key) {
+    throw new GatewayError(
+      `"${tool}" is a premium tool and no licence key is set. Set MCP_LICENSE_KEY in your MCP client config.`,
+      true,
+    )
+  }
+
+  const url = (process.env.MCP_GATEWAY_URL ?? DEFAULT_GATEWAY_URL).trim()
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS)
+  let response: Response
+  try {
+    response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        accept: 'application/json',
+        'user-agent': USER_AGENT,
+        authorization: `Bearer ${key}`,
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/call',
+        params: { name: tool, arguments: args },
+      }),
+      signal: controller.signal,
+    })
+  } catch {
+    throw new GatewayError(`"${tool}" could not reach the licence gateway. Check your connection and try again.`, false)
+  } finally {
+    clearTimeout(timer)
+  }
+
+  if (!response.ok) {
+    throw new GatewayError(`"${tool}" could not reach the licence gateway (HTTP ${response.status}).`, false)
+  }
+
+  let body: JsonRpcResponse
+  try {
+    body = (await response.json()) as JsonRpcResponse
+  } catch {
+    throw new GatewayError(`"${tool}" got an unreadable answer from the licence gateway.`, false)
+  }
+
+  if (body.error) {
+    throw new GatewayError(`"${tool}" was refused by the licence gateway: ${body.error.message ?? 'unknown error'}`, false)
+  }
+
+  const result = body.result ?? {}
+  const text = (result.content ?? [])
+    .map((part) => part.text ?? '')
+    .join('\n')
+    .trim()
+
+  if (result.isError) {
+    // The gateway marks a licence refusal structurally, so a missing or rejected
+    // key is told apart from a tool that failed after the gate let it through.
+    if (result.structuredContent?.licenceRefusal) {
+      throw new GatewayError(text || `"${tool}" needs a valid licence key.`, true)
+    }
+    throw new GatewayError(text || `"${tool}" failed on the licence gateway.`, false)
+  }
+  if (!text) throw new GatewayError(`"${tool}" returned no data.`, false)
+  return text
+}

package/src/server.ts

@@ -1,7 +1,8 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { z } from 'zod'
-import { m0_file, m0_search, m1_random } from './api.js'
 
+import { m0_file, m0_search, m1_random, categoryFiles } from "./api.js"
+import { premiumTool } from "./gateway.js"
 const text = (value: string) => ({ content: [{ type: 'text' as const, text: value }] })
 const textError = (t: string) => ({ content: [{ type: "text" as const, text: t }], isError: true as const })
 const READ_ONLY = { readOnlyHint: true, openWorldHint: true } as const
@@ -46,5 +47,50 @@ server.registerTool(
     try { return text(await m1_random(args)) } catch (e) { return textError(error(e)) }
   }
   )
+  server.registerTool(
+    "file_categories",
+    {
+      title: "File categories",
+      description: "The Wikimedia Commons categories a file sits in, which is how Commons media gets browsed.",
+      inputSchema: z.object( { title: z.string().describe("File title like File:Example.jpg."), limit: z.number().describe("Max categories.").optional() }),
+      annotations: READ_ONLY,
+    },
+    async (args) => {
+    // ---- paywall: file_categories ----
+        // The body runs on the gateway, behind the licence gate.
+    // ---- paywall: end ----
+    try { return text(await premiumTool("mcp_wikimedia_commons_file_categories", args)) } catch (e) { return textError(error(e)) }
+  }
+  )
+
+  server.registerTool(
+    "file_thumbnail",
+    {
+      title: "File thumbnail",
+      description: "The thumbnail URL for a Commons file at a chosen pixel width, alongside the original's dimensions and MIME type.",
+      inputSchema: z.object( { title: z.string().describe("File title like File:Example.jpg."), width: z.number().describe("Thumbnail width in pixels, 20 to 2000.").optional() }),
+      annotations: READ_ONLY,
+    },
+    async (args) => {
+    // ---- paywall: file_thumbnail ----
+        // The body runs on the gateway, behind the licence gate.
+    // ---- paywall: end ----
+    try { return text(await premiumTool("mcp_wikimedia_commons_file_thumbnail", args)) } catch (e) { return textError(error(e)) }
+  }
+  )
+
+  server.registerTool(
+    "category_files",
+    {
+      title: "Category files",
+      description: "List the media files and subcategories inside a Wikimedia Commons category.",
+      inputSchema: z.object( { category: z.string().describe("Category name, e.g. Featured pictures of animals."), limit: z.number().describe("Max members.").optional() }),
+      annotations: READ_ONLY,
+    },
+    async (args) => {
+    try { return text(await categoryFiles(args)) } catch (e) { return textError(error(e)) }
+  }
+  )
+
   return server
 }