node-csfd-api 4.1.6 → 4.2.0-next.0

package/mcp-server.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import packageJson from "./package.json" with { type: "json" };
+import { csfd } from "./index.mjs";
+const server = new McpServer({
+  name: packageJson.name,
+  version: packageJson.version
+});
+server.tool(
+  "search",
+  "Searches for a movie, TV series, or person on CSFD.cz. Returns a list of results with IDs. Use this tool FIRST to find the ID needed for other tools.",
+  {
+    query: z.string().describe("Search query (movie title, series, or actor name)")
+  },
+  async ({ query }) => {
+    try {
+      const results = await csfd.search(query);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(results, null, 2)
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `Error during search: ${error}` }],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "get_movie",
+  "Retrieves detailed information about a specific movie or series, including rating, plot, genres, and actors. Requires a numeric CSFD ID.",
+  {
+    id: z.number().describe("CSFD Movie ID (found using the 'search' tool)")
+  },
+  async ({ id }) => {
+    try {
+      const movie = await csfd.movie(id);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(movie, null, 2)
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `Error retrieving movie details: ${error}` }],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "get_creator",
+  "Retrieves information about a specific creator (actor, director, etc.), including their biography and filmography. Requires a numeric CSFD ID.",
+  {
+    id: z.number().describe("CSFD Creator ID (found using the 'search' tool)")
+  },
+  async ({ id }) => {
+    try {
+      const creator = await csfd.creator(id);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(creator, null, 2)
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `Error retrieving creator details: ${error}` }],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "get_user_ratings",
+  "Retrieves movie ratings from a specific CSFD user. Returns a list of movies with their user rating (0-5 stars). Supports pagination and filtering by film type.",
+  {
+    user: z.union([z.string(), z.number()]).describe("CSFD User ID (numeric) or username"),
+    page: z.number().optional().describe("Page number to fetch (default: 1)"),
+    allPages: z.boolean().optional().describe("Fetch all pages at once (use wisely, may be slow)"),
+    allPagesDelay: z.number().optional().describe("Delay in ms between page requests when using allPages"),
+    excludes: z.array(z.string()).optional().describe('Film types to exclude (e.g. "seri\xE1l", "TV film")'),
+    includesOnly: z.array(z.string()).optional().describe('Only include these film types (e.g. "film")')
+  },
+  async ({ user, page, allPages, allPagesDelay, excludes, includesOnly }) => {
+    try {
+      const results = await csfd.userRatings(user, {
+        page,
+        allPages,
+        allPagesDelay,
+        excludes,
+        includesOnly
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(results, null, 2)
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `Error retrieving user ratings: ${error}` }],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "get_user_reviews",
+  "Retrieves movie reviews written by a specific CSFD user. Returns a list of movies with their review text and rating. Supports pagination and filtering by film type.",
+  {
+    user: z.union([z.string(), z.number()]).describe("CSFD User ID (numeric) or username"),
+    page: z.number().optional().describe("Page number to fetch (default: 1)"),
+    allPages: z.boolean().optional().describe("Fetch all pages at once (use wisely, may be slow)"),
+    allPagesDelay: z.number().optional().describe("Delay in ms between page requests when using allPages"),
+    excludes: z.array(z.string()).optional().describe('Film types to exclude (e.g. "seri\xE1l", "TV film")'),
+    includesOnly: z.array(z.string()).optional().describe('Only include these film types (e.g. "film")')
+  },
+  async ({ user, page, allPages, allPagesDelay, excludes, includesOnly }) => {
+    try {
+      const results = await csfd.userReviews(user, {
+        page,
+        allPages,
+        allPagesDelay,
+        excludes,
+        includesOnly
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(results, null, 2)
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `Error retrieving user reviews: ${error}` }],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "get_cinemas",
+  "Retrieves cinema screenings for a given district in Czech Republic. Returns a list of cinemas with their current screenings, showtimes, and movie details.",
+  {
+    district: z.union([z.number(), z.string()]).describe("District ID (numeric) or name"),
+    period: z.enum(["today", "tomorrow", "weekend", "week", "month"]).describe("Time period for screenings")
+  },
+  async ({ district, period }) => {
+    try {
+      const results = await csfd.cinema(district, period);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(results, null, 2)
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `Error retrieving cinema data: ${error}` }],
+        isError: true
+      };
+    }
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("CSFD MCP Server running on stdio...");
+}
+main().catch((error) => {
+  console.error("Fatal error in MCP server:", error);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-csfd-api",
-  "version": "4.1.6",
+  "version": "4.2.0-next.0",
   "description": "ČSFD API in JavaScript. Amazing NPM library for scrapping csfd.cz :)",
   "author": "BART! <bart@bartweb.cz>",
   "publishConfig": {
@@ -8,8 +8,12 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "cross-fetch": "^4.1.0",
-    "node-html-parser": "^7.0.2"
+    "node-html-parser": "^7.0.2",
+    "express": "^5.2.1",
+    "dotenv": "^17.2.4",
+    "zod": "^4.3.6"
   },
   "repository": {
     "url": "git+https://github.com/bartholomej/node-csfd-api.git",
@@ -41,9 +45,14 @@
   "types": "./index.d.ts",
   "exports": {
     ".": {
-      "require": "./index.js",
-      "import": "./index.mjs"
+      "import": "./index.mjs",
+      "require": "./index.js"
     },
     "./package.json": "./package.json"
-  }
-}
+  },
+  "bin": {
+    "csfd-mcp": "mcp-server.js",
+    "csfd-server": "server.js"
+  },
+  "sideEffects": false
+}

package/server.js

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import express from "express";
+import packageJson from "./package.json" with { type: "json" };
+import { csfd } from "./index.mjs";
+const LOG_COLORS = {
+  info: "\x1B[36m",
+  // cyan
+  warn: "\x1B[33m",
+  // yellow
+  error: "\x1B[31m",
+  // red
+  success: "\x1B[32m",
+  // green
+  reset: "\x1B[0m"
+};
+const LOG_SYMBOLS = {
+  info: "\u2139\uFE0F",
+  warn: "\u26A0\uFE0F",
+  error: "\u274C",
+  success: "\u2705"
+};
+const LOG_PADDED_SEVERITY = {
+  info: "INFO   ",
+  warn: "WARN   ",
+  error: "ERROR  ",
+  success: "SUCCESS"
+};
+var Errors = /* @__PURE__ */ ((Errors2) => {
+  Errors2["API_KEY_MISSING"] = "API_KEY_MISSING";
+  Errors2["API_KEY_INVALID"] = "API_KEY_INVALID";
+  Errors2["ID_MISSING"] = "ID_MISSING";
+  Errors2["MOVIE_FETCH_FAILED"] = "MOVIE_FETCH_FAILED";
+  Errors2["CREATOR_FETCH_FAILED"] = "CREATOR_FETCH_FAILED";
+  Errors2["SEARCH_FETCH_FAILED"] = "SEARCH_FETCH_FAILED";
+  Errors2["USER_RATINGS_FETCH_FAILED"] = "USER_RATINGS_FETCH_FAILED";
+  Errors2["USER_REVIEWS_FETCH_FAILED"] = "USER_REVIEWS_FETCH_FAILED";
+  Errors2["CINEMAS_FETCH_FAILED"] = "CINEMAS_FETCH_FAILED";
+  Errors2["PAGE_NOT_FOUND"] = "PAGE_NOT_FOUND";
+  Errors2["TOO_MANY_REQUESTS"] = "TOO_MANY_REQUESTS";
+  return Errors2;
+})(Errors || {});
+function logMessage(severity, log, req) {
+  const time = (/* @__PURE__ */ new Date()).toISOString();
+  const reqInfo = req ? `${req.method}: ${req.originalUrl}` : "";
+  const reqIp = req ? req.headers["x-forwarded-for"] || req.socket.remoteAddress || req.ip || req.ips : "";
+  const msg = `${LOG_COLORS[severity]}[${LOG_PADDED_SEVERITY[severity]}]${LOG_COLORS.reset} ${time} | IP: ${reqIp} ${LOG_SYMBOLS[severity]} ${log.error ? log.error + ":" : ""} ${log.message} \u{1F517} ${reqInfo}`;
+  const logSuccessEnabled = process.env.VERBOSE === "true";
+  if (severity === "success") {
+    if (logSuccessEnabled) {
+      console.log(msg);
+    }
+  } else if (severity === "error") {
+    console.error(msg);
+  } else if (severity === "warn") {
+    console.warn(msg);
+  } else {
+    console.log(msg);
+  }
+}
+var Endpoint = /* @__PURE__ */ ((Endpoint2) => {
+  Endpoint2["MOVIE"] = "/movie/:id";
+  Endpoint2["CREATOR"] = "/creator/:id";
+  Endpoint2["SEARCH"] = "/search/:query";
+  Endpoint2["USER_RATINGS"] = "/user-ratings/:id";
+  Endpoint2["USER_REVIEWS"] = "/user-reviews/:id";
+  Endpoint2["CINEMAS"] = "/cinemas";
+  return Endpoint2;
+})(Endpoint || {});
+const app = express();
+const port = process.env.PORT || 3e3;
+const API_KEY_NAME = process.env.API_KEY_NAME || "x-api-key";
+const API_KEY = process.env.API_KEY;
+const RAW_LANGUAGE = process.env.LANGUAGE;
+const isSupportedLanguage = (value) => value === "cs" || value === "en" || value === "sk";
+const BASE_LANGUAGE = isSupportedLanguage(RAW_LANGUAGE) ? RAW_LANGUAGE : void 0;
+const API_KEYS_LIST = API_KEY ? API_KEY.split(/[,;\s]+/).map((k) => k.trim()).filter(Boolean) : [];
+if (BASE_LANGUAGE) {
+  csfd.setOptions({ language: BASE_LANGUAGE });
+}
+app.use((req, res, next) => {
+  if (API_KEY) {
+    const apiKey = req.get(API_KEY_NAME)?.trim();
+    if (!apiKey) {
+      const log = {
+        error: "API_KEY_MISSING" /* API_KEY_MISSING */,
+        message: `Missing API key in request header: ${API_KEY_NAME}`
+      };
+      logMessage("error", log, req);
+      res.status(401).json(log);
+      return;
+    }
+    if (!API_KEYS_LIST.includes(apiKey)) {
+      const log = {
+        error: "API_KEY_INVALID" /* API_KEY_INVALID */,
+        message: `Invalid API key in request header: ${API_KEY_NAME}`
+      };
+      logMessage("error", log, req);
+      res.status(401).json(log);
+      return;
+    }
+  }
+  next();
+});
+app.get("/", (_, res) => {
+  logMessage("info", { error: null, message: "/" });
+  res.json({
+    name: packageJson.name,
+    version: packageJson.version,
+    docs: packageJson.homepage,
+    links: Object.values(Endpoint)
+  });
+});
+app.get(["/movie/", "/creator/", "/search/", "/user-ratings/", "/user-reviews/"], (req, res) => {
+  const log = {
+    error: "ID_MISSING" /* ID_MISSING */,
+    message: `ID is missing. Provide ID like this: ${req.url}${req.url.endsWith("/") ? "" : "/"}1234`
+  };
+  logMessage("warn", log, req);
+  res.status(404).json(log);
+});
+app.get("/movie/:id" /* MOVIE */, async (req, res) => {
+  const rawLanguage = req.query.language;
+  const language = isSupportedLanguage(rawLanguage) ? rawLanguage : void 0;
+  try {
+    const movie = await csfd.movie(+req.params.id, { language });
+    res.json(movie);
+    logMessage(
+      "success",
+      {
+        error: null,
+        message: `${"/movie/:id" /* MOVIE */}: ${req.params.id}${language ? ` [${language}]` : ""}`
+      },
+      req
+    );
+  } catch (error) {
+    const log = {
+      error: "MOVIE_FETCH_FAILED" /* MOVIE_FETCH_FAILED */,
+      message: "Failed to fetch movie data: " + error
+    };
+    logMessage("error", log, req);
+    res.status(500).json(log);
+  }
+});
+app.get("/creator/:id" /* CREATOR */, async (req, res) => {
+  const rawLanguage = req.query.language;
+  const language = isSupportedLanguage(rawLanguage) ? rawLanguage : void 0;
+  try {
+    const result = await csfd.creator(+req.params.id, { language });
+    res.json(result);
+    logMessage(
+      "success",
+      {
+        error: null,
+        message: `${"/creator/:id" /* CREATOR */}: ${req.params.id}${language ? ` [${language}]` : ""}`
+      },
+      req
+    );
+  } catch (error) {
+    const log = {
+      error: "CREATOR_FETCH_FAILED" /* CREATOR_FETCH_FAILED */,
+      message: "Failed to fetch creator data: " + error
+    };
+    logMessage("error", log, req);
+    res.status(500).json(log);
+  }
+});
+app.get("/search/:query" /* SEARCH */, async (req, res) => {
+  const rawLanguage = req.query.language;
+  const language = isSupportedLanguage(rawLanguage) ? rawLanguage : void 0;
+  try {
+    const result = await csfd.search(req.params.query, { language });
+    res.json(result);
+    logMessage(
+      "success",
+      {
+        error: null,
+        message: `${"/search/:query" /* SEARCH */}: ${req.params.query}${language ? ` [${language}]` : ""}`
+      },
+      req
+    );
+  } catch (error) {
+    const log = {
+      error: "SEARCH_FETCH_FAILED" /* SEARCH_FETCH_FAILED */,
+      message: "Failed to fetch search data: " + error
+    };
+    logMessage("error", log, req);
+    res.status(500).json(log);
+  }
+});
+app.get("/user-ratings/:id" /* USER_RATINGS */, async (req, res) => {
+  const { allPages, allPagesDelay, excludes, includesOnly, page } = req.query;
+  const rawLanguage = req.query.language;
+  const language = isSupportedLanguage(rawLanguage) ? rawLanguage : void 0;
+  try {
+    const result = await csfd.userRatings(
+      req.params.id,
+      {
+        allPages: allPages === "true",
+        allPagesDelay: allPagesDelay ? +allPagesDelay : void 0,
+        excludes: excludes ? excludes.split(",") : void 0,
+        includesOnly: includesOnly ? includesOnly.split(",") : void 0,
+        page: page ? +page : void 0
+      },
+      {
+        language
+      }
+    );
+    res.json(result);
+    logMessage(
+      "success",
+      {
+        error: null,
+        message: `${"/user-ratings/:id" /* USER_RATINGS */}: ${req.params.id}${language ? ` [${language}]` : ""}`
+      },
+      req
+    );
+  } catch (error) {
+    const log = {
+      error: "USER_RATINGS_FETCH_FAILED" /* USER_RATINGS_FETCH_FAILED */,
+      message: "Failed to fetch user-ratings data: " + error
+    };
+    logMessage("error", log, req);
+    res.status(500).json(log);
+  }
+});
+app.get("/user-reviews/:id" /* USER_REVIEWS */, async (req, res) => {
+  const { allPages, allPagesDelay, excludes, includesOnly, page } = req.query;
+  const rawLanguage = req.query.language;
+  const language = isSupportedLanguage(rawLanguage) ? rawLanguage : void 0;
+  try {
+    const result = await csfd.userReviews(
+      req.params.id,
+      {
+        allPages: allPages === "true",
+        allPagesDelay: allPagesDelay ? +allPagesDelay : void 0,
+        excludes: excludes ? excludes.split(",") : void 0,
+        includesOnly: includesOnly ? includesOnly.split(",") : void 0,
+        page: page ? +page : void 0
+      },
+      {
+        language
+      }
+    );
+    res.json(result);
+    logMessage(
+      "success",
+      {
+        error: null,
+        message: `${"/user-reviews/:id" /* USER_REVIEWS */}: ${req.params.id}${language ? ` [${language}]` : ""}`
+      },
+      req
+    );
+  } catch (error) {
+    const log = {
+      error: "USER_REVIEWS_FETCH_FAILED" /* USER_REVIEWS_FETCH_FAILED */,
+      message: "Failed to fetch user-reviews data: " + error
+    };
+    logMessage("error", log, req);
+    res.status(500).json(log);
+  }
+});
+app.get("/cinemas" /* CINEMAS */, async (req, res) => {
+  const rawLanguage = req.query.language;
+  const language = isSupportedLanguage(rawLanguage) ? rawLanguage : void 0;
+  try {
+    const result = await csfd.cinema(1, "today", { language });
+    logMessage(
+      "success",
+      { error: null, message: `${"/cinemas" /* CINEMAS */}${language ? ` [${language}]` : ""}` },
+      req
+    );
+    res.json(result);
+  } catch (error) {
+    const log = {
+      error: "CINEMAS_FETCH_FAILED" /* CINEMAS_FETCH_FAILED */,
+      message: "Failed to fetch cinemas data: " + error
+    };
+    logMessage("error", log, req);
+    res.status(500).json(log);
+  }
+});
+app.use((req, res) => {
+  const log = {
+    error: "PAGE_NOT_FOUND" /* PAGE_NOT_FOUND */,
+    message: "The requested endpoint could not be found."
+  };
+  logMessage("warn", log, req);
+  res.status(404).json(log);
+});
+app.listen(port, () => {
+  console.log(`
+                  _                  __    _               _
+                 | |                / _|  | |             (_)
+  _ __   ___   __| | ___    ___ ___| |_ __| |   __ _ _ __  _
+ | '_ \\ / _ \\ / _\` |/ _ \\  / __/ __|  _/ _\` |  / _\` | '_ \\| |
+ | | | | (_) | (_| |  __/ | (__\\__ \\ || (_| | | (_| | |_) | |
+ |_| |_|\\___/ \\__,_|\\___|  \\___|___/_| \\__,_|  \\__,_| .__/|_|
+                                                    | |
+                                                    |_|
+`);
+  console.log(`node-csfd-api@${packageJson.version}
+`);
+  console.log(`Docs: ${packageJson.homepage}`);
+  console.log(`Endpoints: ${Object.values(Endpoint).join(", ")}
+`);
+  console.log(`API is running on: http://localhost:${port}`);
+  if (BASE_LANGUAGE) {
+    console.log(`Base language configured: ${BASE_LANGUAGE}
+`);
+  }
+  if (API_KEYS_LIST.length === 0) {
+    console.log(
+      "\x1B[31m%s\x1B[0m",
+      "\u26A0\uFE0F Server is OPEN!\n- Your server will be open to the world and potentially everyone can use it without any restriction.\n- To enable some basic protection, set API_KEY environment variable (single value or comma-separated list) and provide the same value in request header: " + API_KEY_NAME
+    );
+  } else {
+    console.log(
+      "\x1B[32m%s\x1B[0m",
+      `\u2714\uFE0F Server is protected (somehow).
+- ${API_KEYS_LIST.length} API key(s) are configured and will be checked for each request header: ${API_KEY_NAME}`
+    );
+  }
+});