wikimedia-commons-mcp 1.0.0

package/README.md

@@ -0,0 +1,23 @@
+# wikimedia-commons-mcp
+
+Wikimedia Commons file search.
+
+A merged MCP server that consolidates duplicate single-purpose servers in this monorepo into one focused server.
+
+## Tools
+
+- `search` — Search Commons files by text.
+- `file` — Details for one Commons file.
+- `random` — Random image files from Commons.
+
+## Run
+
+```bash
+npm install
+npm run build
+node dist/index.js
+```
+
+## Source
+
+Public free APIs only. See `src/api.ts` for exact endpoints.

package/dist/api.js

@@ -0,0 +1,104 @@
+const m0 = (() => {
+    const BASE = "https://commons.wikimedia.org/w/api.php";
+    const UA = "mrfentmen-wikimedia-commons-mcp/1.0 (https://github.com/mrfentmen)";
+    class CommonsError extends Error {
+    }
+    async function get(url) {
+        const res = await fetch(url, {
+            headers: { "User-Agent": UA, Accept: "application/json" },
+            signal: AbortSignal.timeout(30000),
+        });
+        if (!res.ok)
+            throw new CommonsError(`Wikimedia Commons returned HTTP ${res.status}`);
+        return (await res.json());
+    }
+    function pagesFrom(d) {
+        const pages = d?.query?.pages ?? {};
+        return Object.values(pages);
+    }
+    async function search(args) {
+        const q = (args.query ?? "").trim();
+        if (!q)
+            throw new CommonsError("Provide a search query");
+        const limit = Math.min(args.limit ?? 8, 20);
+        const d = await get(`${BASE}?action=query&generator=search&gsrnamespace=6&gsrsearch=${encodeURIComponent(q)}&gsrlimit=${limit}&prop=imageinfo&iiprop=url|size|mime&format=json&origin=*`);
+        const pages = pagesFrom(d);
+        if (!pages.length)
+            return `No Commons files found for \"${q}\"`;
+        return `Commons files for \"${q}\":\n` + pages.map((p, i) => {
+            const info = p?.imageinfo?.[0] ?? {};
+            const size = info?.width && info?.height ? `${info.width}x${info.height}` : "";
+            const bytes = info?.size != null ? `${(info.size / 1024).toFixed(0)} KB` : "";
+            return `${i + 1}. ${p?.title ?? "n/a"}\n   ${info?.url ?? ""} ${size ? `| ${size}` : ""} ${bytes ? `| ${bytes}` : ""}`;
+        }).join("\n");
+    }
+    async function file(args) {
+        const title = (args.title ?? "").trim();
+        if (!title)
+            throw new CommonsError("Provide a file title like File:Example.jpg");
+        const d = await get(`${BASE}?action=query&titles=${encodeURIComponent(title)}&prop=imageinfo&iiprop=url|size|mime|extmetadata&format=json&origin=*`);
+        const p = pagesFrom(d)[0];
+        const info = p?.imageinfo?.[0];
+        if (!info)
+            throw new CommonsError(`File not found: ${title}`);
+        const meta = info?.extmetadata ?? {};
+        const artist = (meta?.Artist?.value ?? "").replace(/<[^>]+>/g, "").slice(0, 120);
+        const license = (meta?.LicenseShortName?.value ?? "").replace(/<[^>]+>/g, "");
+        const lines = [
+            `Title: ${p?.title ?? title}`,
+            `URL: ${info?.url ?? ""}`,
+            `Size: ${info?.width ?? "?"}x${info?.height ?? "?"} | ${info?.mime ?? ""} | ${info?.size != null ? `${(info.size / 1024 / 1024).toFixed(1)} MB` : ""}`,
+        ];
+        if (artist)
+            lines.push(`Artist: ${artist}`);
+        if (license)
+            lines.push(`License: ${license}`);
+        return lines.join("\n");
+    }
+    return { CommonsError, file, search };
+})();
+const m1 = (() => {
+    const BASE = 'https://commons.wikimedia.org/w/api.php';
+    async function random(args) {
+        const limit = Math.max(1, Math.min(args.limit ?? 5, 15));
+        const params = new URLSearchParams({
+            action: 'query',
+            format: 'json',
+            generator: 'random',
+            grnnamespace: '6',
+            grnlimit: String(limit),
+            prop: 'imageinfo',
+            iiprop: 'url|size|extmetadata',
+        });
+        const res = await fetch(`${BASE}?${params.toString()}`, {
+            headers: { 'User-Agent': 'mrfentmen-wikimedia-feed-mcp/1.0', Accept: 'application/json' },
+            signal: AbortSignal.timeout(25000),
+        });
+        if (!res.ok)
+            throw new Error(`Wikimedia Commons returned ${res.status}`);
+        const data = (await res.json());
+        const pages = data.query?.pages ?? {};
+        const items = Object.values(pages).map((p) => {
+            const rec = p;
+            const info = Array.isArray(rec.imageinfo) ? rec.imageinfo[0] : {};
+            const meta = info.extmetadata ?? {};
+            const title = meta.ImageDescription?.value ?? rec.title ?? '';
+            const artist = meta.Artist?.value ?? '';
+            const clean = String(title).replace(/<[^>]*>/g, '').trim();
+            const by = String(artist).replace(/<[^>]*>/g, '').trim();
+            return `${clean}${by ? ` by ${by}` : ''}${info.descriptionurl ? `\n   ${info.descriptionurl}` : ''}`;
+        });
+        if (!items.length)
+            return 'No random images returned.';
+        return `Random Wikimedia Commons images (${items.length} shown):\n` + items.map((s, i) => `${i + 1}. ${s}`).join('\n');
+    }
+    return { random };
+})();
+export const CommonsError = m0.CommonsError;
+export const file = m0.file;
+export const random = m1.random;
+export const search = m0.search;
+export const m0_file = m0.file;
+export const m0_search = m0.search;
+export const m0_CommonsError = m0.CommonsError;
+export const m1_random = m1.random;

package/dist/index.js

@@ -0,0 +1,4 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+const main = async () => { const server = createServer(); await server.connect(new StdioServerTransport()); };
+main().catch((error) => { console.error("Fatal error:", error); process.exit(1); });

package/dist/server.js

@@ -0,0 +1,51 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { m0_file, m0_search, m1_random } 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 };
+const error = (e) => `Error: ${e instanceof Error ? e.message : String(e)}`;
+const errorMessage = error;
+export function createServer() {
+    const server = new McpServer({ name: 'wikimedia-commons-mcp', version: '1.0.0' });
+    server.registerTool("search", {
+        title: "Search",
+        description: "Search Commons files by text.",
+        inputSchema: z.object({ query: z.string().describe("Search terms."), limit: z.number().describe("Max results.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            return text(await m0_search(args));
+        }
+        catch (e) {
+            return textError(error(e));
+        }
+    });
+    server.registerTool("file", {
+        title: "File",
+        description: "Details for one Commons file.",
+        inputSchema: z.object({ title: z.string().describe("File title.") }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            return text(await m0_file(args));
+        }
+        catch (e) {
+            return textError(error(e));
+        }
+    });
+    server.registerTool("random", {
+        title: "Random",
+        description: "Random image files from Commons.",
+        inputSchema: z.object({ limit: z.number().describe("Max results.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            return text(await m1_random(args));
+        }
+        catch (e) {
+            return textError(error(e));
+        }
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "wikimedia-commons-mcp",
+  "version": "1.0.0",
+  "description": "Wikimedia Commons file search.",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.0.0"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "mcpName": "io.github.mrfentmen/wikimedia-commons-mcp"
+}

package/server.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.mrfentmen/wikimedia-commons-mcp",
+  "description": "Wikimedia Commons file search.",
+  "repository": {
+    "url": "https://github.com/mrfentmen/awesome-mcps",
+    "source": "github"
+  },
+  "version": "1.0.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "wikimedia-commons-mcp",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

package/src/api.ts

@@ -0,0 +1,113 @@
+
+export interface m1_RandomArgs {
+  limit?: number;
+}
+
+const m0 = (() => {
+const BASE = "https://commons.wikimedia.org/w/api.php"
+const UA = "mrfentmen-wikimedia-commons-mcp/1.0 (https://github.com/mrfentmen)"
+class CommonsError extends Error {}
+
+async function get<T>(url: string): Promise<T> {
+  const res = await fetch(url, {
+    headers: { "User-Agent": UA, Accept: "application/json" },
+    signal: AbortSignal.timeout(30000),
+  })
+  if (!res.ok) throw new CommonsError(`Wikimedia Commons returned HTTP ${res.status}`)
+  return (await res.json()) as T
+}
+
+function pagesFrom(d: any): any[] {
+  const pages = d?.query?.pages ?? {}
+  return Object.values(pages) as any[]
+}
+
+async function search(args: { query?: string; limit?: number }): Promise<string> {
+  const q = (args.query ?? "").trim()
+  if (!q) throw new CommonsError("Provide a search query")
+  const limit = Math.min(args.limit ?? 8, 20)
+  const d = await get<any>(
+    `${BASE}?action=query&generator=search&gsrnamespace=6&gsrsearch=${encodeURIComponent(q)}&gsrlimit=${limit}&prop=imageinfo&iiprop=url|size|mime&format=json&origin=*`
+  )
+  const pages = pagesFrom(d)
+  if (!pages.length) return `No Commons files found for \"${q}\"`
+  return `Commons files for \"${q}\":\n` + pages.map((p: any, i: number) => {
+    const info = p?.imageinfo?.[0] ?? {}
+    const size = info?.width && info?.height ? `${info.width}x${info.height}` : ""
+    const bytes = info?.size != null ? `${(info.size / 1024).toFixed(0)} KB` : ""
+    return `${i + 1}. ${p?.title ?? "n/a"}\n   ${info?.url ?? ""} ${size ? `| ${size}` : ""} ${bytes ? `| ${bytes}` : ""}`
+  }).join("\n")
+}
+
+async function file(args: { title?: string }): Promise<string> {
+  const title = (args.title ?? "").trim()
+  if (!title) throw new CommonsError("Provide a file title like File:Example.jpg")
+  const d = await get<any>(
+    `${BASE}?action=query&titles=${encodeURIComponent(title)}&prop=imageinfo&iiprop=url|size|mime|extmetadata&format=json&origin=*`
+  )
+  const p = pagesFrom(d)[0]
+  const info = p?.imageinfo?.[0]
+  if (!info) throw new CommonsError(`File not found: ${title}`)
+  const meta = info?.extmetadata ?? {}
+  const artist = (meta?.Artist?.value ?? "").replace(/<[^>]+>/g, "").slice(0, 120)
+  const license = (meta?.LicenseShortName?.value ?? "").replace(/<[^>]+>/g, "")
+  const lines = [
+    `Title: ${p?.title ?? title}`,
+    `URL: ${info?.url ?? ""}`,
+    `Size: ${info?.width ?? "?"}x${info?.height ?? "?"} | ${info?.mime ?? ""} | ${info?.size != null ? `${(info.size / 1024 / 1024).toFixed(1)} MB` : ""}`,
+  ]
+  if (artist) lines.push(`Artist: ${artist}`)
+  if (license) lines.push(`License: ${license}`)
+  return lines.join("\n")
+}
+
+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({
+    action: 'query',
+    format: 'json',
+    generator: 'random',
+    grnnamespace: '6',
+    grnlimit: String(limit),
+    prop: 'imageinfo',
+    iiprop: 'url|size|extmetadata',
+  });
+  const res = await fetch(`${BASE}?${params.toString()}`, {
+    headers: { 'User-Agent': 'mrfentmen-wikimedia-feed-mcp/1.0', Accept: 'application/json' },
+    signal: AbortSignal.timeout(25000),
+  });
+  if (!res.ok) throw new Error(`Wikimedia Commons returned ${res.status}`);
+  const data = (await res.json()) as { query?: { pages?: Record<string, unknown> } };
+  const pages = data.query?.pages ?? {};
+  const items = Object.values(pages).map((p) => {
+    const rec = p as Record<string, unknown>;
+    const info = Array.isArray(rec.imageinfo) ? (rec.imageinfo[0] as Record<string, unknown>) : {};
+    const meta = (info.extmetadata as Record<string, unknown>) ?? {};
+    const title = (meta.ImageDescription as Record<string, unknown>)?.value ?? rec.title ?? '';
+    const artist = (meta.Artist as Record<string, unknown>)?.value ?? '';
+    const clean = String(title).replace(/<[^>]*>/g, '').trim();
+    const by = String(artist).replace(/<[^>]*>/g, '').trim();
+    return `${clean}${by ? ` by ${by}` : ''}${info.descriptionurl ? `\n   ${info.descriptionurl}` : ''}`;
+  });
+  if (!items.length) return 'No random images returned.';
+  return `Random Wikimedia Commons images (${items.length} shown):\n` + items.map((s, i) => `${i + 1}. ${s}`).join('\n');
+}
+
+return { random };
+})();
+
+export const CommonsError = m0.CommonsError;
+export const file = m0.file;
+export const random = m1.random;
+export const search = m0.search;
+export const m0_file = m0.file;
+export const m0_search = m0.search;
+export const m0_CommonsError = m0.CommonsError;
+export const m1_random = m1.random;

package/src/index.ts

@@ -0,0 +1,4 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import { createServer } from "./server.js"
+const main = async () => { const server = createServer(); await server.connect(new StdioServerTransport()) }
+main().catch((error) => { console.error("Fatal error:", error); process.exit(1) })

package/src/server.ts

@@ -0,0 +1,50 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import { m0_file, m0_search, m1_random } from './api.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
+const error = (e: unknown) => `Error: ${e instanceof Error ? e.message : String(e)}`
+const errorMessage = error
+
+export function createServer(): McpServer {
+  const server = new McpServer({ name: 'wikimedia-commons-mcp', version: '1.0.0' })
+server.registerTool(
+    "search",
+    {
+      title: "Search",
+      description: "Search Commons files by text.",
+      inputSchema: z.object( { query: z.string().describe("Search terms."), limit: z.number().describe("Max results.").optional() }),
+      annotations: READ_ONLY,
+    },
+    async (args) => {
+    try { return text(await m0_search(args)) } catch (e) { return textError(error(e)) }
+  }
+  )
+server.registerTool(
+    "file",
+    {
+      title: "File",
+      description: "Details for one Commons file.",
+      inputSchema: z.object( { title: z.string().describe("File title.") }),
+      annotations: READ_ONLY,
+    },
+    async (args) => {
+    try { return text(await m0_file(args)) } catch (e) { return textError(error(e)) }
+  }
+  )
+server.registerTool(
+    "random",
+    {
+      title: "Random",
+      description: "Random image files from Commons.",
+      inputSchema: z.object( { limit: z.number().describe("Max results.").optional() }),
+      annotations: READ_ONLY,
+    },
+    async (args) => {
+    try { return text(await m1_random(args)) } catch (e) { return textError(error(e)) }
+  }
+  )
+  return server
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "src/**/*"
+  ]
+}