demozoo-mcp 1.0.0

package/README.md

@@ -0,0 +1,23 @@
+# Demozoo MCP
+
+Keyless MCP server for Demozoo, the demoscene database: search 390k+ demos, intros, graphics and music, get download links, credits, groups and sceners.
+
+## Quick start
+
+```bash
+npm install
+npm run build
+node dist/index.js
+```
+
+The server uses stdio, so it can be connected to Claude Desktop, Cursor, VS Code, MCP Inspector, or another compatible MCP client.
+
+## Tools at a glance
+
+- `search_productions`: Search demos, intros, graphics, music by text query.
+- `get_production`: Full detail for one production (credits, download links, platforms).
+- `get_releaser`: Group or scener profile (nicks, memberships, members).
+
+## Limits and privacy
+
+This project is intentionally narrow. It should be treated as a practical helper, not a complete certification or security audit. Check the implementation and the returned data before using it with sensitive material. No credentials are required.

package/dist/api.d.ts

@@ -0,0 +1,34 @@
+export declare class DemozooError extends Error {
+}
+export interface ProductionSummary {
+    id: number;
+    title: string;
+    authors: string[];
+    release_date?: string;
+    supertype?: string;
+    platforms: string[];
+    types: string[];
+    demozoo_url?: string;
+}
+export interface ProductionDetails extends ProductionSummary {
+    credits: string[];
+    download_links: string[];
+}
+export interface Releaser {
+    id: number;
+    name: string;
+    is_group: boolean;
+    nicks: string[];
+    member_of: string[];
+    members: string[];
+    demozoo_url?: string;
+}
+type Raw = Record<string, any>;
+export declare function toSummary(p: Raw): ProductionSummary;
+export declare function searchProductions(query: string, limit?: number): Promise<ProductionSummary[]>;
+export declare function getProduction(id: string): Promise<ProductionDetails | null>;
+export declare function getReleaser(id: string): Promise<Releaser | null>;
+export declare function formatSummary(p: ProductionSummary, index?: number): string;
+export declare function formatProduction(p: ProductionDetails): string;
+export declare function formatReleaser(r: Releaser): string;
+export {};

package/dist/api.js

@@ -0,0 +1,97 @@
+/**
+ * Demozoo API v1 client, keyless.
+ * Docs: https://demozoo.org/api/v1/ (browse the root URL for the endpoint list)
+ */
+const BASE = "https://demozoo.org/api/v1";
+export class DemozooError extends Error {
+}
+async function getJson(path) {
+    const res = await fetch(`${BASE}${path}`, {
+        headers: { "User-Agent": "demozoo-mcp/1.0" },
+        signal: AbortSignal.timeout(15000),
+    });
+    if (!res.ok)
+        throw new DemozooError(`Demozoo error ${res.status}`);
+    return (await res.json());
+}
+const names = (arr) => Array.isArray(arr) ? arr.map((x) => String(x?.name ?? x)) : [];
+export function toSummary(p) {
+    return {
+        id: p.id,
+        title: String(p.title ?? "(untitled)"),
+        authors: Array.isArray(p.author_nicks) ? p.author_nicks.map((n) => n.name) : [],
+        release_date: p.release_date,
+        supertype: p.supertype,
+        platforms: names(p.platforms),
+        types: names(p.types),
+        demozoo_url: p.demozoo_url,
+    };
+}
+export async function searchProductions(query, limit = 5) {
+    const data = await getJson(`/productions/?query=${encodeURIComponent(query)}`);
+    return data.results.slice(0, limit).map(toSummary);
+}
+export async function getProduction(id) {
+    if (!/^\d+$/.test(id.trim()))
+        throw new DemozooError(`Production id must be numeric, got "${id}".`);
+    const p = await getJson(`/productions/${id.trim()}/`);
+    if (!p || p.id === undefined)
+        return null;
+    const s = toSummary(p);
+    return {
+        ...s,
+        credits: Array.isArray(p.credits)
+            ? p.credits.map((c) => `${c?.nick?.name ?? "?"} — ${c?.category ?? "?"}`).slice(0, 12)
+            : [],
+        download_links: Array.isArray(p.download_links)
+            ? p.download_links.map((d) => String(d.url)).slice(0, 8)
+            : [],
+    };
+}
+export async function getReleaser(id) {
+    if (!/^\d+$/.test(id.trim()))
+        throw new DemozooError(`Releaser id must be numeric, got "${id}".`);
+    const r = await getJson(`/releasers/${id.trim()}/`);
+    if (!r || r.id === undefined)
+        return null;
+    return {
+        id: r.id,
+        name: String(r.name ?? "?"),
+        is_group: Boolean(r.is_group),
+        nicks: Array.isArray(r.nicks) ? r.nicks.map((n) => String(n.name)) : [],
+        member_of: Array.isArray(r.member_of) ? r.member_of.map((m) => String(m?.group?.name ?? "?")) : [],
+        members: Array.isArray(r.members) ? r.members.map((m) => String(m?.nick?.name ?? "?")).slice(0, 15) : [],
+        demozoo_url: r.demozoo_url,
+    };
+}
+export function formatSummary(p, index) {
+    const prefix = index !== undefined ? `${index + 1}. ` : "";
+    const by = p.authors.length ? ` by ${p.authors.slice(0, 3).join(", ")}` : "";
+    const meta = [p.release_date, p.platforms.slice(0, 3).join("/"), p.types.slice(0, 2).join(", ")]
+        .filter(Boolean)
+        .join(" · ");
+    return `${prefix}[${p.id}] ${p.title}${by}${meta ? ` (${meta})` : ""}`;
+}
+export function formatProduction(p) {
+    const lines = [
+        `[${p.id}] ${p.title}`,
+        p.authors.length ? `By: ${p.authors.join(", ")}` : "",
+        p.release_date ? `Released: ${p.release_date}` : "",
+        p.platforms.length ? `Platforms: ${p.platforms.join(", ")}` : "",
+        p.types.length ? `Type: ${p.types.join(", ")}` : "",
+        p.credits.length ? `Credits:\n- ${p.credits.join("\n- ")}` : "",
+        p.download_links.length ? `Downloads:\n- ${p.download_links.join("\n- ")}` : "",
+        p.demozoo_url ? `More: ${p.demozoo_url}` : "",
+    ].filter(Boolean);
+    return lines.join("\n");
+}
+export function formatReleaser(r) {
+    const lines = [
+        `[${r.id}] ${r.name} (${r.is_group ? "group" : "scener"})`,
+        r.nicks.length > 1 ? `Nicks: ${r.nicks.join(", ")}` : "",
+        r.member_of.length ? `Member of: ${r.member_of.join(", ")}` : "",
+        r.members.length ? `Members: ${r.members.join(", ")}` : "",
+        r.demozoo_url ? `More: ${r.demozoo_url}` : "",
+    ].filter(Boolean);
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

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

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,75 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { DemozooError, formatProduction, formatReleaser, formatSummary, getProduction, getReleaser, searchProductions, } from "./api.js";
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
+const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
+export function createServer() {
+    const server = new McpServer({
+        name: "demozoo-mcp",
+        version: "1.0.0",
+    });
+    server.registerTool("search_productions", {
+        title: "Search demoscene productions",
+        description: "Search Demozoo for demoscene productions: demos, intros, graphics, music. Finds titles across 390k+ entries.",
+        inputSchema: z.object({
+            query: z.string().describe("Search text, e.g. 'second reality', 'farbrausch', 'amiga cracktro'"),
+            limit: z.number().int().min(1).max(20).default(5),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ query, limit }) => {
+        try {
+            const results = await searchProductions(query, limit);
+            if (results.length === 0)
+                return text(`No Demozoo productions match "${query}".`);
+            return text(`Demozoo results for "${query}":\n\n${results.map((p, i) => formatSummary(p, i)).join("\n")}`);
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("get_production", {
+        title: "Get production details",
+        description: "Get a Demozoo production by id: authors, release date, platforms, credits, and download links.",
+        inputSchema: z.object({
+            id: z.string().describe("Numeric Demozoo production id, e.g. '1' (use search_productions to find it)"),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ id }) => {
+        try {
+            const p = await getProduction(id);
+            if (!p)
+                return text(`No Demozoo production with id ${id}.`);
+            return text(formatProduction(p));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("get_releaser", {
+        title: "Get group or scener profile",
+        description: "Get a Demozoo group or scener profile by id: nicks, group memberships, members.",
+        inputSchema: z.object({
+            id: z.string().describe("Numeric Demozoo releaser id, e.g. '16685' (shown in production credits)"),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ id }) => {
+        try {
+            const r = await getReleaser(id);
+            if (!r)
+                return text(`No Demozoo group/scener with id ${id}.`);
+            return text(formatReleaser(r));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    return server;
+}
+function errorMessage(e) {
+    if (e instanceof DemozooError)
+        return `Error: ${e.message}`;
+    if (e instanceof Error)
+        return `Error: ${e.message}`;
+    return `Error: ${String(e)}`;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "demozoo-mcp",
+  "version": "1.0.0",
+  "description": "Keyless MCP server for Demozoo, the demoscene database: search 390k+ demos, intros, graphics and music, get download links, credits, groups and sceners.",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/demozoo-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrfentmen/awesome-mcps.git"
+  },
+  "bin": {
+    "demozoo-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "rm -rf dist && tsc -p tsconfig.json && node dist/index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "demozoo",
+    "demoscene",
+    "api"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}