node-csfd-api 5.0.0-next.0 → 5.0.0-next.1

package/bin/mcp-server.mjs

@@ -14,13 +14,25 @@ const server = new McpServer({
 * TOOL 1: Search
 * Description: Essential first step to get IDs for movies or creators.
 */
-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 }) => {
+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 { content: [{
-			type: "text",
-			text: JSON.stringify(results, null, 2)
-		}] };
+		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: [{
@@ -35,13 +47,25 @@ server.tool("search", "Searches for a movie, TV series, or person on CSFD.cz. Re
 * TOOL 2: Movie Details
 * Description: Returns detailed info about a specific movie/series.
 */
-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 }) => {
+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 { content: [{
-			type: "text",
-			text: JSON.stringify(movie, null, 2)
-		}] };
+		return {
+			structuredContent: movie,
+			content: [{
+				type: "text",
+				text: `Movie ${movie.title} (${movie.year}) with rating ${movie.rating} retrieved successfully.`
+			}]
+		};
 	} catch (error) {
 		return {
 			content: [{
@@ -56,13 +80,25 @@ server.tool("get_movie", "Retrieves detailed information about a specific movie
 * TOOL 3: Creator Details
 * Description: Returns detailed info about a person (actor, director).
 */
-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 }) => {
+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 { content: [{
-			type: "text",
-			text: JSON.stringify(creator, null, 2)
-		}] };
+		return {
+			structuredContent: creator,
+			content: [{
+				type: "text",
+				text: `Creator ${creator.name} retrieved successfully.`
+			}]
+		};
 	} catch (error) {
 		return {
 			content: [{
@@ -77,13 +113,22 @@ server.tool("get_creator", "Retrieves information about a specific creator (acto
 * TOOL 4: User Ratings
 * Description: Returns ratings from a specific CSFD user.
 */
-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. \"series\", \"tv-film\")"),
-	includesOnly: z.array(z.string()).optional().describe("Only include these film types (e.g. \"film\")")
+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, {
@@ -93,10 +138,13 @@ server.tool("get_user_ratings", "Retrieves movie ratings from a specific CSFD us
 			excludes,
 			includesOnly
 		});
-		return { content: [{
-			type: "text",
-			text: JSON.stringify(results, null, 2)
-		}] };
+		return {
+			structuredContent: { results },
+			content: [{
+				type: "text",
+				text: `Retrieved ${results.length} user ratings successfully.`
+			}]
+		};
 	} catch (error) {
 		return {
 			content: [{
@@ -111,13 +159,22 @@ server.tool("get_user_ratings", "Retrieves movie ratings from a specific CSFD us
 * TOOL 5: User Reviews
 * Description: Returns reviews written by a specific CSFD user.
 */
-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. \"series\", \"tv-film\")"),
-	includesOnly: z.array(z.string()).optional().describe("Only include these film types (e.g. \"film\")")
+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, {
@@ -127,10 +184,13 @@ server.tool("get_user_reviews", "Retrieves movie reviews written by a specific C
 			excludes,
 			includesOnly
 		});
-		return { content: [{
-			type: "text",
-			text: JSON.stringify(results, null, 2)
-		}] };
+		return {
+			structuredContent: { results },
+			content: [{
+				type: "text",
+				text: `Retrieved ${results.length} user reviews successfully.`
+			}]
+		};
 	} catch (error) {
 		return {
 			content: [{
@@ -145,22 +205,34 @@ server.tool("get_user_reviews", "Retrieves movie reviews written by a specific C
 * TOOL 6: Cinemas
 * Description: Returns cinema screenings for a given district and time period.
 */
-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")
+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 { content: [{
-			type: "text",
-			text: JSON.stringify(results, null, 2)
-		}] };
+		return {
+			structuredContent: { results },
+			content: [{
+				type: "text",
+				text: `Retrieved ${results.length} cinema screenings successfully.`
+			}]
+		};
 	} catch (error) {
 		return {
 			content: [{
@@ -171,10 +243,37 @@ server.tool("get_cinemas", "Retrieves cinema screenings for a given district in
 		};
 	}
 });
+/**
+* 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.`
+		}
+	}] };
+});
 async function main() {
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
-	console.error("CSFD MCP Server running on stdio...");
+	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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-csfd-api",
-  "version": "5.0.0-next.0",
+  "version": "5.0.0-next.1",
   "description": "ČSFD API in JavaScript. Amazing NPM library for scrapping csfd.cz :)",
   "author": "BART! <bart@bartweb.cz>",
   "publishConfig": {

package/package.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 //#region package.json
 var name = "node-csfd-api";
-var version = "5.0.0-next.0";
+var version = "5.0.0-next.1";
 var homepage = "https://github.com/bartholomej/node-csfd-api#readme";
 
 //#endregion