node-csfd-api 4.3.4 → 5.0.0-next-2

package/README.md

@@ -223,7 +223,7 @@ console.log(results.users); // Array of users
     title: 'Black Bart',
     year: '1975',
     url: 'https://www.csfd.cz/film/19653-black-bart/',
-    type: 'TV film',
+    type: 'tv-film',
     colorRating: 'bad',
     poster: 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7',
     origins: ['USA'],
@@ -247,7 +247,7 @@ tvSeries: [
     title: 'Království',
     year: 1994,
     url: 'https://www.csfd.cz/film/71924-kralovstvi/',
-    type: 'seriál',
+    type: 'series',
     colorRating: 'good',
     poster: 'https://image.pmgstatic.com/cache/resized/w60h85/files/images/film/posters/166/708/166708064_2da697.jpg',
     origins: ['Dánsko'],
@@ -398,7 +398,7 @@ const onlyMovies = await csfd.userRatings('912-bart', {
 });
 
 const excludeEpisodes = await csfd.userRatings('912-bart', {
-  exclude: ['epizoda', 'série']
+  exclude: ['episode', 'season']
 });
 ```
 
@@ -434,13 +434,13 @@ const excludeEpisodes = await csfd.userRatings('912-bart', {
 
 #### UserRatingsOptions
 
-| Option          | Type              | Default | Description                                                      |
-| --------------- | ----------------- | ------- | ---------------------------------------------------------------- |
-| `includesOnly`  | `CSFDFilmTypes[]` | `null`  | Include only specific content types (e.g., `['film', 'seriál']`) |
-| `exclude`       | `CSFDFilmTypes[]` | `null`  | Exclude specific content types (e.g., `['epizoda']`)             |
-| `allPages`      | `boolean`         | `false` | Fetch all pages of ratings                                       |
-| `allPagesDelay` | `number`          | `0`     | Delay between page requests in milliseconds                      |
-| `page`          | `number`          | `1`     | Fetch specific page number                                       |
+| Option          | Type              | Default | Description                                                          |
+| --------------- | ----------------- | ------- | -------------------------------------------------------------------- |
+| `includesOnly`  | `CSFDFilmTypes[]` | `null`  | Include only specific content types (e.g., `['film', 'series']`) |
+| `exclude`       | `CSFDFilmTypes[]` | `null`  | Exclude specific content types (e.g., `['episode']`)                 |
+| `allPages`      | `boolean`         | `false` | Fetch all pages of ratings                                           |
+| `allPagesDelay` | `number`          | `0`     | Delay between page requests in milliseconds                          |
+| `page`          | `number`          | `1`     | Fetch specific page number                                           |
 
 > 📝 **Note**: `includesOnly` and `exclude` are mutually exclusive. If both are provided, `includesOnly` takes precedence.
 >
@@ -476,7 +476,7 @@ const allReviews = await csfd.userReviews(195357, {
 // Filter by content type
 const filtered = await csfd.userReviews(195357, {
   includesOnly: ['film'],
-  exclude: ['epizoda']
+  exclude: ['episode']
 });
 ```
 

package/bin/export-ratings.mjs

@@ -1,61 +1,65 @@
+#!/usr/bin/env node
+import { csfd } from "../index.mjs";
 import { writeFile } from "node:fs/promises";
-import { csfd } from "./../index.mjs";
+
+//#region src/tools/export-ratings.ts
+/**
+* Runs the ratings export process for a given user.
+* @param userId - The CSFD user ID.
+* @param options - Export options (format, filters, language).
+*/
 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;
-  }
+	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) => {
+				return `${escapeCsvField(r.title ?? "")},${r.year ?? ""},${r.userRating ?? ""},${escapeCsvField(r.userDate ?? "")}`;
+			})].join("\n");
+			fileName = `${userId}-for-letterboxd.csv`;
+		} else if (options.format === "json") {
+			content = JSON.stringify(ratings, null, 2);
+			fileName = `${userId}-ratings.json`;
+		} else {
+			content = [[
+				"id",
+				"title",
+				"year",
+				"rating",
+				"date",
+				"type",
+				"url",
+				"colorRating"
+			].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
-};
+
+//#endregion
+export { runRatingsExport };

package/bin/mcp-server.mjs

@@ -1,192 +1,284 @@
 #!/usr/bin/env node
+import { csfd } from "../index.mjs";
+import { name, version } from "../package.mjs";
 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";
+
+//#region src/mcp-server/index.ts
 const server = new McpServer({
-  name: packageJson.name,
-  version: packageJson.version
+	name,
+	version
+});
+/**
+* TOOL 1: Search
+* Description: Essential first step to get IDs for movies or creators.
+*/
+server.registerTool("search", {
+	title: "Search",
+	description: "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.",
+	inputSchema: { query: z.string().describe("Search query (movie title, series, or actor, director, etc. name)") },
+	annotations: {
+		readOnlyHint: true,
+		idempotentHint: true,
+		openWorldHint: false
+	}
+}, async ({ query }) => {
+	try {
+		const results = await csfd.search(query);
+		return {
+			structuredContent: results,
+			content: [{
+				type: "text",
+				text: `Found ${results.movies.length} movies, ${results.tvSeries.length} TV series, and ${results.users.length} users.`
+			}]
+		};
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: `Error during search: ${error}`
+			}],
+			isError: true
+		};
+	}
+});
+/**
+* TOOL 2: Movie Details
+* Description: Returns detailed info about a specific movie/series.
+*/
+server.registerTool("get_movie", {
+	title: "Get Movie",
+	description: "Retrieves detailed information about a specific movie or series, including rating, plot, genres, and actors. Requires a numeric CSFD ID.",
+	inputSchema: { id: z.number().describe("CSFD Movie ID (found using the 'search' tool)") },
+	annotations: {
+		readOnlyHint: true,
+		idempotentHint: true,
+		openWorldHint: false
+	}
+}, async ({ id }) => {
+	try {
+		const movie = await csfd.movie(id);
+		return {
+			structuredContent: movie,
+			content: [{
+				type: "text",
+				text: `Movie ${movie.title} (${movie.year}) with rating ${movie.rating} retrieved successfully.`
+			}]
+		};
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: `Error retrieving movie details: ${error}`
+			}],
+			isError: true
+		};
+	}
+});
+/**
+* TOOL 3: Creator Details
+* Description: Returns detailed info about a person (actor, director).
+*/
+server.registerTool("get_creator", {
+	title: "Get Creator",
+	description: "Retrieves information about a specific creator (actor, director, etc.), including their biography and filmography. Requires a numeric CSFD ID.",
+	inputSchema: { id: z.number().describe("CSFD Creator ID") },
+	annotations: {
+		readOnlyHint: true,
+		idempotentHint: true,
+		openWorldHint: false
+	}
+}, async ({ id }) => {
+	try {
+		const creator = await csfd.creator(id);
+		return {
+			structuredContent: creator,
+			content: [{
+				type: "text",
+				text: `Creator ${creator.name} retrieved successfully.`
+			}]
+		};
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: `Error retrieving creator details: ${error}`
+			}],
+			isError: true
+		};
+	}
+});
+/**
+* TOOL 4: User Ratings
+* Description: Returns ratings from a specific CSFD user.
+*/
+server.registerTool("get_user_ratings", {
+	title: "Get User Ratings",
+	description: "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.",
+	inputSchema: {
+		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. \"series\", \"tv-film\")"),
+		includesOnly: z.array(z.string()).optional().describe("Only include these film types (e.g. \"film\")")
+	},
+	annotations: {
+		readOnlyHint: true,
+		idempotentHint: true,
+		openWorldHint: false
+	}
+}, async ({ user, page, allPages, allPagesDelay, excludes, includesOnly }) => {
+	try {
+		const results = await csfd.userRatings(user, {
+			page,
+			allPages,
+			allPagesDelay,
+			excludes,
+			includesOnly
+		});
+		return {
+			structuredContent: { results },
+			content: [{
+				type: "text",
+				text: `Retrieved ${results.length} user ratings successfully.`
+			}]
+		};
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: `Error retrieving user ratings: ${error}`
+			}],
+			isError: true
+		};
+	}
+});
+/**
+* TOOL 5: User Reviews
+* Description: Returns reviews written by a specific CSFD user.
+*/
+server.registerTool("get_user_reviews", {
+	title: "Get User Reviews",
+	description: "Retrieves movie reviews written by a specific CSFD user. Returns a list of movies with their review text and rating.",
+	inputSchema: {
+		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. \"series\", \"tv-film\")"),
+		includesOnly: z.array(z.string()).optional().describe("Only include these film types (e.g. \"film\")")
+	},
+	annotations: {
+		readOnlyHint: true,
+		idempotentHint: true,
+		openWorldHint: false
+	}
+}, async ({ user, page, allPages, allPagesDelay, excludes, includesOnly }) => {
+	try {
+		const results = await csfd.userReviews(user, {
+			page,
+			allPages,
+			allPagesDelay,
+			excludes,
+			includesOnly
+		});
+		return {
+			structuredContent: { results },
+			content: [{
+				type: "text",
+				text: `Retrieved ${results.length} user reviews successfully.`
+			}]
+		};
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: `Error retrieving user reviews: ${error}`
+			}],
+			isError: true
+		};
+	}
+});
+/**
+* TOOL 6: Cinemas
+* Description: Returns cinema screenings for a given district and time period.
+*/
+server.registerTool("get_cinemas", {
+	title: "Get Cinemas",
+	description: "Retrieves cinema screenings for a given district in Czech Republic. Returns a list of cinemas with their current screenings, showtimes, and movie names and ids.",
+	inputSchema: {
+		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")
+	},
+	annotations: {
+		readOnlyHint: true,
+		idempotentHint: true,
+		openWorldHint: false
+	}
+}, async ({ district, period }) => {
+	try {
+		const results = await csfd.cinema(district, period);
+		return {
+			structuredContent: { results },
+			content: [{
+				type: "text",
+				text: `Retrieved ${results.length} cinema screenings successfully.`
+			}]
+		};
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: `Error retrieving cinema data: ${error}`
+			}],
+			isError: true
+		};
+	}
+});
+/**
+* PROMPT: Actor's Top Rated Works
+* Example: "Find movies starring Mads Mikkelsen and give me the top 5 sorted by rating."
+*/
+server.registerPrompt("actor-top-rated", {
+	title: "Actor Top Rated",
+	description: "Finds and ranks the best movies of a specific actor or creator.",
+	argsSchema: { actorName: z.string().describe("Name of the actor or director") }
+}, async ({ actorName }) => {
+	return { messages: [{
+		role: "user",
+		content: {
+			type: "text",
+			text: `First, search for the person "${actorName}" to get their ID. Then, retrieve their full profile to see their filmography. From the results, identify the top 5 highest-rated movies they acted in. Finally, provide a bulleted list with the movie titles, years, and their CSFD ratings.`
+		}
+	}] };
 });
-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...");
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	console.error(`--- CSFD MCP Server (v${version}) ---`);
+	console.error("Status: Running via Stdio");
+	console.error("\nTo use this server in Claude Desktop, add this to your config:");
+	console.error(JSON.stringify({ "node-csfd-api": {
+		command: "npx",
+		args: [
+			"-y",
+			"node-csfd-api",
+			"mcp"
+		]
+	} }, null, 2));
 }
 main().catch((error) => {
-  console.error("Fatal error in MCP server:", error);
-  process.exit(1);
+	console.error("Fatal error in MCP server:", error);
+	process.exit(1);
 });
+
+//#endregion
+export {  };