node-csfd-api 4.2.0-next.1 → 4.3.0-next.0

package/README.md

@@ -6,11 +6,11 @@
 
 <div align="center">
 
-# CSFD API 🎬 2026
+# CSFD API 🎬 + CSFD Export + MCP Server 🤖
 
-#### Modern TypeScript NPM library for scraping **Czech Movie Database (csfd.cz)** _(unofficial)_
+#### Modern TypeScript NPM library for scraping **CSFD.CZ**. Scraper, API, Export and MCP Server in one package. _(unofficial)_
 
-[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [API Reference](#-api-reference) • [Examples](#-usage-examples) • [Docker](#-docker-support)
+[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [API Reference](#-api-reference) • [Examples](#-usage-examples) • [MCP Server](#-mcp-server-model-context-protocol) • [Docker](#-docker-support)
 
 </div>
 
@@ -22,14 +22,16 @@
 - 🧪 **Well-tested** - ~100% code coverage
 - 🚀 **Universal** - Works in Node.js, browsers, and serverless environments
 - 🐳 **Docker ready** - Pre-built Docker images available
+- 🤖 **MCP Server** - Use CSFD data directly within LLMs like Claude Desktop
 - 🔄 **Modern API** - Promise-based with async/await support
-- 📦 **One dependency** - Lightweight and efficient
+- 📦 **Few dependencies** - Lightweight and efficient
 
 ### Supported Platforms
 
 - Node.js (ESM & CommonJS)
 - Browsers (with CORS considerations)
 - Docker containers
+- MCP Server (Claude Desktop, etc.)
 - Serverless (Firebase Functions, AWS Lambda, CloudFlare Workers, etc.)
 - Chrome Extensions
 - React Native (Yes, with Expo too!)
@@ -75,6 +77,7 @@ console.log(reviews);
 - [Creators](#creators)
 - [User Ratings](#user-ratings)
 - [User Reviews](#user-reviews)
+- [MCP Server](#-mcp-server-model-context-protocol)
 - [Docker Support](#-docker-support)
 - [Development](#-development)
 
@@ -517,6 +520,75 @@ const filtered = await csfd.userReviews(195357, {
 
 Same options as [UserRatingsOptions](#userrationsoptions).
 
+## 💻 CLI Tools
+
+This library comes with a powerful CLI that exposes several tools.
+
+### 1. Export Ratings (CSV, JSON & Letterboxd)
+
+> Backup your personal user ratings to CSV (default), JSON, or Letterboxd format. Use this tool just to keep a local copy of your data.
+
+```bash
+# Export to CSV (default) -> saves as <userId>-ratings.csv
+npx node-csfd-api export ratings 912
+
+# Export to JSON -> saves as <userId>-ratings.json
+npx node-csfd-api export ratings 912 --json
+
+# Export to Letterboxd CSV -> saves as <userId>-for-letterboxd.csv
+npx node-csfd-api export ratings 912 --letterboxd
+```
+
+### 2. REST API Server
+
+Run a standalone REST API server.
+
+```bash
+npx node-csfd-api server
+# Server listening on port 3000
+```
+
+### 3. MCP Server
+
+Run the Model Context Protocol server for AI agents.
+
+```bash
+npx node-csfd-api mcp
+```
+
+## 🤖 MCP Server (Model Context Protocol)
+
+This library includes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server. This allows you to use ČSFD data directly within LLMs like **Claude Desktop**.
+
+### Features
+
+- **Search**: Search for movies, TV series, and users.
+- **Details**: Get comprehensive details about movies, creators, and users.
+- **Reviews**: Read user reviews and ratings.
+
+### Usage with Claude Desktop
+
+Add the following configuration to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "csfd": {
+      "command": "npx",
+      "args": ["-y", "node-csfd-api", "mcp"]
+    }
+  }
+}
+```
+
+### Supported Tools
+
+- `search`: Search query (returns movies, series, users)
+- `movie_details`: Get movie details by ID
+- `creator_details`: Get creator details by ID
+- `user_ratings`: Get user ratings
+- `user_reviews`: Get user reviews
+
 ## 🐳 Docker Support
 
 Run the CSFD API as a standalone REST service using Docker.

package/bin/export-ratings.mjs

@@ -0,0 +1,61 @@
+import { writeFile } from "node:fs/promises";
+import { csfd } from "./../index.mjs";
+async function runRatingsExport(userId, options) {
+  try {
+    if (options.format === "letterboxd") {
+      csfd.setOptions({ language: "en" });
+    }
+    console.log(`Fetching ratings for user ${userId} (${options.format.toUpperCase()})...`);
+    const ratings = await csfd.userRatings(userId, options.userRatingsOptions);
+    console.log(`Fetched ${ratings.length} ratings.`);
+    let content = "";
+    let fileName = "";
+    const escapeCsvField = (value) => {
+      const needsQuotes = /[",\n\r]/.test(value);
+      const escaped = value.replaceAll('"', '""');
+      return needsQuotes ? `"${escaped}"` : escaped;
+    };
+    if (options.format === "letterboxd") {
+      content = [
+        "Title,Year,Rating,WatchedDate",
+        ...ratings.map((r) => {
+          const title = escapeCsvField(r.title ?? "");
+          const year = r.year ?? "";
+          const rating = r.userRating ?? "";
+          const watchedDate = escapeCsvField(r.userDate ?? "");
+          return `${title},${year},${rating},${watchedDate}`;
+        })
+      ].join("\n");
+      fileName = `${userId}-for-letterboxd.csv`;
+    } else if (options.format === "json") {
+      content = JSON.stringify(ratings, null, 2);
+      fileName = `${userId}-ratings.json`;
+    } else {
+      const headers = ["id", "title", "year", "rating", "date", "type", "url", "colorRating"];
+      content = [
+        headers.join(","),
+        ...ratings.map((r) => {
+          return [
+            r.id,
+            escapeCsvField(r.title ?? ""),
+            r.year ?? "",
+            r.userRating ?? "",
+            escapeCsvField(r.userDate ?? ""),
+            escapeCsvField(r.type ?? ""),
+            escapeCsvField(r.url ?? ""),
+            escapeCsvField(r.colorRating ?? "")
+          ].join(",");
+        })
+      ].join("\n");
+      fileName = `${userId}-ratings.csv`;
+    }
+    await writeFile(fileName, content);
+    console.log("Saved in file:", `./${fileName}`);
+  } catch (error) {
+    console.error("Error exporting ratings:", error);
+    throw error;
+  }
+}
+export {
+  runRatingsExport
+};

package/{mcp-server.mjs → bin/mcp-server.mjs}

@@ -2,8 +2,8 @@
 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";
+import packageJson from "./../package.json" with { type: "json" };
+import { csfd } from "./../index.mjs";
 const server = new McpServer({
   name: packageJson.name,
   version: packageJson.version

package/{server.mjs → bin/server.mjs}

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import "dotenv/config";
 import express from "express";
-import packageJson from "./package.json" with { type: "json" };
-import { csfd } from "./index.mjs";
+import packageJson from "./../package.json" with { type: "json" };
+import { csfd } from "./../index.mjs";
 const LOG_COLORS = {
   info: "\x1B[36m",
   // cyan

package/cli.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  switch (command) {
+    case "server":
+    case "api":
+      try {
+        await import(path.join(__dirname, "bin/server.mjs"));
+      } catch (error) {
+        console.error("Failed to start server:", error);
+        process.exit(1);
+      }
+      break;
+    case "mcp":
+      try {
+        await import(path.join(__dirname, "bin/mcp-server.mjs"));
+      } catch (error) {
+        console.error("Failed to start MCP server:", error);
+        process.exit(1);
+      }
+      break;
+    case "export":
+      if (args[1] === "ratings") {
+        const userIdRaw = args[2];
+        const userId = Number(userIdRaw);
+        if (!userIdRaw || isNaN(userId)) {
+          console.error("Error: Please provide a valid numeric User ID.");
+          console.log("Usage: npx node-csfd-api export ratings <userId> [options]");
+          process.exit(1);
+        }
+        const isLetterboxd = args.includes("--letterboxd");
+        const isJson = args.includes("--json");
+        const isCsv = args.includes("--csv");
+        let format = "csv";
+        if (isLetterboxd) {
+          format = "letterboxd";
+        } else if (isJson) {
+          format = "json";
+        } else if (isCsv) {
+          format = "csv";
+        }
+        try {
+          const modulePath = path.join(__dirname, "bin/export-ratings.mjs");
+          const { runRatingsExport } = await import(modulePath);
+          await runRatingsExport(userId, {
+            format,
+            userRatingsOptions: {
+              // Default behavior for Letterboxd (films only) if not overridden
+              includesOnly: isLetterboxd ? ["film"] : void 0,
+              allPages: true,
+              allPagesDelay: 1e3
+            }
+          });
+        } catch (error) {
+          console.error("Failed to run export:", error);
+          process.exit(1);
+        }
+      } else if (args[1] === "letterboxd") {
+        console.warn(
+          'Deprecation Warning: "export letterboxd" is deprecated. Please use "export ratings <id> --letterboxd" instead.'
+        );
+        console.log("Usage: npx node-csfd-api export ratings <userId> --letterboxd");
+        process.exit(1);
+      } else {
+        console.error(`Unknown export target: ${args[1]}`);
+        printUsage();
+        process.exit(1);
+      }
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+    default:
+      printUsage();
+      break;
+  }
+}
+function printUsage() {
+  console.log(`
+Usage: npx node-csfd-api <command> [options]
+
+Commands:
+  server, api                Start the REST API server
+  mcp                        Start the MCP (Model Context Protocol) server for AI agents
+  export ratings <userId>    Export user ratings to CSV (default), JSON, or Letterboxd format
+    Options:
+      --csv                  Export to CSV format (default)
+      --json                 Export to JSON format
+      --letterboxd           Export to Letterboxd-compatible CSV format
+  help                       Show this help message
+`);
+}
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-csfd-api",
-  "version": "4.2.0-next.1",
+  "version": "4.3.0-next.0",
   "description": "ČSFD API in JavaScript. Amazing NPM library for scrapping csfd.cz :)",
   "author": "BART! <bart@bartweb.cz>",
   "publishConfig": {
@@ -10,9 +10,9 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "cross-fetch": "^4.1.0",
-    "node-html-parser": "^7.0.2",
+    "dotenv": "^17.3.1",
     "express": "^5.2.1",
-    "dotenv": "^17.2.4",
+    "node-html-parser": "^7.0.2",
     "zod": "^4.3.6"
   },
   "repository": {
@@ -51,8 +51,7 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "csfd-mcp": "mcp-server.mjs",
-    "csfd-server": "server.mjs"
+    "node-csfd-api": "cli.mjs"
   },
   "sideEffects": false
 }