{"id":16225770,"url":"https://github.com/bartholomej/node-csfd-api","last_synced_at":"2026-04-01T20:25:47.341Z","repository":{"id":38418943,"uuid":"309122697","full_name":"bartholomej/node-csfd-api","owner":"bartholomej","description":"ČSFD API in JavaScript. Amazing NPM library for scrapping csfd.cz. Now with MCP server","archived":false,"fork":false,"pushed_at":"2026-03-02T17:34:07.000Z","size":6097,"stargazers_count":42,"open_issues_count":7,"forks_count":10,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-03-02T18:57:11.822Z","etag":null,"topics":["csfd","csfd-api","film","hollywood","imdb","javascript","movie","nodejs","ratings","scraper","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bartholomej.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["bartholomej"],"patreon":null,"open_collective":null,"ko_fi":"bartholomej","buy_me_a_coffee":"bartholomej","thanks_dev":"u/gh/bartholomej","tidelift":null,"custom":["https://www.paypal.me/bartholomej"]}},"created_at":"2020-11-01T15:12:03.000Z","updated_at":"2026-03-02T17:34:10.000Z","dependencies_parsed_at":"2023-10-05T02:45:27.240Z","dependency_job_id":"8d544f2c-6dae-4dd9-bce0-f2dd6327e4ba","html_url":"https://github.com/bartholomej/node-csfd-api","commit_stats":{"total_commits":261,"total_committers":2,"mean_commits":130.5,"dds":"0.019157088122605415","last_synced_commit":"7fdabbdc59f80f1090f9d63b68d9c678346cfb03"},"previous_names":[],"tags_count":133,"template":false,"template_full_name":null,"purl":"pkg:github/bartholomej/node-csfd-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bartholomej%2Fnode-csfd-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bartholomej%2Fnode-csfd-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bartholomej%2Fnode-csfd-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bartholomej%2Fnode-csfd-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bartholomej","download_url":"https://codeload.github.com/bartholomej/node-csfd-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bartholomej%2Fnode-csfd-api/sbom","scorecard":{"id":226308,"data":{"date":"2025-08-11","repo":{"name":"github.com/bartholomej/node-csfd-api","commit":"c507c25f96afe1548f98a3548edf887cf9832315"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.8,"checks":[{"name":"Code-Review","score":0,"reason":"Found 0/28 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":10,"reason":"17 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/main.yml:1","Warn: no topLevel permission defined: .github/workflows/publish.yml:1","Warn: no topLevel permission defined: .github/workflows/test.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"License","score":0,"reason":"license file not detected","details":["Warn: project does not have a license file"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/main.yml:10: update your workflow using https://app.stepsecurity.io/secureworkflow/bartholomej/node-csfd-api/main.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/main.yml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/bartholomej/node-csfd-api/main.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/main.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/bartholomej/node-csfd-api/main.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/main.yml:36: update your workflow using https://app.stepsecurity.io/secureworkflow/bartholomej/node-csfd-api/main.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/bartholomej/node-csfd-api/publish.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/bartholomej/node-csfd-api/publish.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/bartholomej/node-csfd-api/publish.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/publish.yml:40: update your workflow using https://app.stepsecurity.io/secureworkflow/bartholomej/node-csfd-api/publish.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/bartholomej/node-csfd-api/test.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/bartholomej/node-csfd-api/test.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/bartholomej/node-csfd-api/test.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/test.yml:38: update your workflow using https://app.stepsecurity.io/secureworkflow/bartholomej/node-csfd-api/test.yml/master?enable=pin","Warn: containerImage not pinned by hash: Dockerfile:1: pin your Docker image by updating node:24-alpine to node:24-alpine@sha256:e8e882c692a08878d55ec8ff6c5a4a71b3edca25eda0af4406e2a160d8a93cf2","Info:   0 out of   9 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   3 third-party GitHubAction dependencies pinned","Info:   0 out of   1 containerImage dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Packaging","score":10,"reason":"packaging workflow detected","details":["Info: Project packages its releases by way of GitHub Actions.: .github/workflows/publish.yml:9"],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 5 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-17T03:53:34.996Z","repository_id":38418943,"created_at":"2025-08-17T03:53:34.996Z","updated_at":"2025-08-17T03:53:34.996Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30104221,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T01:06:53.091Z","status":"ssl_error","status_checked_at":"2026-03-05T01:02:35.679Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csfd","csfd-api","film","hollywood","imdb","javascript","movie","nodejs","ratings","scraper","typescript"],"created_at":"2024-10-10T12:46:20.607Z","updated_at":"2026-04-01T20:25:47.318Z","avatar_url":"https://github.com/bartholomej.png","language":"TypeScript","funding_links":["https://github.com/sponsors/bartholomej","https://ko-fi.com/bartholomej","https://buymeacoffee.com/bartholomej","https://thanks.dev/u/gh/bartholomej","https://www.paypal.me/bartholomej"],"categories":[],"sub_categories":[],"readme":"[![npm version](https://badge.fury.io/js/node-csfd-api.svg)](https://badge.fury.io/js/node-csfd-api)\n[![License](https://img.shields.io/npm/l/node-csfd-api.svg)](https://www.npmjs.com/node-csfd-api)\n[![Build \u0026 Publish](https://github.com/bartholomej/node-csfd-api/workflows/Publish/badge.svg)](https://github.com/bartholomej/node-csfd-api/actions)\n[![Coverage](https://codecov.io/gh/bartholomej/node-csfd-api/branch/master/graph/badge.svg?token=YQH9UoVrGP)](https://codecov.io/gh/bartholomej/node-csfd-api)\n[![npm downloads](https://img.shields.io/npm/dm/node-csfd-api.svg)](https://www.npmjs.com/node-csfd-api)\n\n\u003cdiv align=\"center\"\u003e\n\n# CSFD API 🎬 + CSFD Export 💾 + CSFD MCP 🤖\n\n#### Modern TypeScript NPM library for scraping **CSFD.CZ**. Scraper, API Rest Server, Exporter and MCP Server in one package. _(unofficial)_\n\n[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)\n\n\u003c/div\u003e\n\n---\n\n## ✨ Features\n\n- 🎯 **Type-safe** - Full TypeScript support with type definitions\n- 🧪 **Well-tested** - ~100% code coverage\n- 🚀 **Universal** - Works in Node.js, browsers, and serverless environments\n- 🐳 **Docker ready** - Pre-built Docker images available\n- 🍺 **Homebrew support** - Easy globally installed CLI via Homebrew tap\n- 🤖 **MCP Server** - Use CSFD data directly within LLMs like Claude Desktop\n- 🔄 **Modern API** - Promise-based with async/await support\n- 📦 **Few dependencies** - Lightweight and efficient\n\n### Supported Platforms\n\n- Node.js (ESM \u0026 CommonJS)\n- Browsers (with CORS considerations)\n- Docker containers\n- macOS/Linux CLI (via Homebrew)\n- MCP Server (Claude Desktop, etc.)\n- Serverless (Firebase Functions, AWS Lambda, CloudFlare Workers, etc.)\n- Chrome Extensions\n- React Native (Yes, with Expo too!)\n\n## 📦 Installation\n\n```bash\nnpm install node-csfd-api\n# yarn add node-csfd-api\n# pnpm add node-csfd-api\n```\n\n## 🚀 Quick Start\n\n```typescript\nimport { csfd } from 'node-csfd-api';\n\n// Fetch movie details\nconst movie = await csfd.movie(535121);\nconsole.log(movie.title); // \"Na špatné straně\"\n\n// Search for content\nconst results = await csfd.search('Tarantino');\nconsole.log(results.movies, results.tvSeries, results.users);\n\n// Get creator info\nconst creator = await csfd.creator(2120);\nconsole.log(creator.name); // \"Quentin Tarantino\"\n\n// Get user ratings\nconst ratings = await csfd.userRatings('912');\nconsole.log(ratings);\n\n// Get user reviews\nconst reviews = await csfd.userReviews('195357-verbal');\nconsole.log(reviews);\n```\n\n## 📖 Table of Contents\n\n- [Movie Details](#movie)\n- [Search](#search)\n- [Creators](#creators)\n- [User Ratings](#user-ratings)\n- [User Reviews](#user-reviews)\n- [MCP Server](#-mcp-server-model-context-protocol)\n- [Docker Support](#-docker-support)\n- [Development](#-development)\n\n## 📚 API Reference\n\n### Movie\n\n\u003e Retrieve comprehensive information about a movie or TV series by its ČSFD ID.\n\n**Method:** `csfd.movie(id: number): Promise\u003cMovie\u003e`\n\n```typescript\nimport { csfd } from 'node-csfd-api';\n\n// Using async/await\nconst movie = await csfd.movie(535121);\n\n// Alternatively, using promises\ncsfd.movie(535121).then((movie) =\u003e console.log(movie));\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003e🔎 Click here to see full result example\u003c/summary\u003e\n\n```javascript\n{\n  id: 535121,\n  title: 'Na špatné straně',\n  year: '2018',\n  descriptions: [\n    'Otupělý policejní veterán Ridgeman (Mel Gibson)...',\n    'Brett je policajt tesne ...'\n  ],\n  genres: [ 'Krimi', 'Drama', 'Thriller' ],\n  type: 'film',\n  url: 'https://www.csfd.cz/film/535121',\n  origins: [ 'USA', 'Kanada' ],\n  colorRating: 'good',\n  rating: 73,\n  ratingCount: 6654,\n  photo: '//image.pmgstatic.com/cache/resized/w1326/files/images/film/photos/162/980/162980090_bbffbb.jpg',\n  trivia: ['Když Henry (Tory Kittles) se svým mladším bratrem...', 'Ve filmu se střídají...'],\n  titlesOther: [\n    { country: 'USA', title: 'Dragged Across Concrete' },\n    { country: 'Kanada', title: 'Dragged Across Concrete' },\n    { country: 'Slovensko', title: 'Na zlej strane' },\n    { country: 'Austrálie', title: 'Dragged Across Concrete' },\n    { country: 'Velká Británie', title: 'Dragged Across Concrete' }\n  ],\n  poster: 'https://image.pmgstatic.com/cache/resized/w1080/files/images/film/posters/163/579/163579352_bf8737.jpg',\n  creators: {\n    directors: [\n    {\n      id: 87470,\n      name: 'S. Craig Zahler',\n      url: 'https://www.csfd.cz/tvurce/87470-s-craig-zahler/'\n      }\n    ],\n    actors: [\n      {\n        id: 1,\n        name: 'Mel Gibson',\n        url: 'https://www.csfd.cz/tvurce/1-mel-gibson/'\n      }\n    ],\n    basedOn: [],\n    writers: [\n      {\n        id: 87470,\n        name: 'S. Craig Zahler',\n        url: 'https://www.csfd.cz/tvurce/87470-s-craig-zahler/'\n      }\n    ],\n    music: [\n      {\n        id: 203209,\n        name: 'Jeff Herriott',\n        url: 'https://www.csfd.cz/tvurce/203209-jeff-herriott/'\n      }\n    ],\n    producers: [\n      {\n        id: 320006,\n        name: 'Sefton Fincham',\n        url: 'https://www.csfd.cz/tvurce/320006-sefton-fincham/'\n      }\n    ]\n  },\n  vod: [\n    {\n      title: 'Voyo',\n      url: 'https://voyo.nova.cz/filmy/4604-na-spatne-strane'\n    },\n    {\n      title: 'DVD',\n      url: 'https://filmy.heureka.cz/na-spatne-strane-dvd/#utm_source=csfd.cz\u0026utm_medium=cooperation\u0026utm_campaign=csfd_movies_feed'\n    }\n  ],\n  tags: ['město', 'sledování'],\n  premieres: [\n   {\n      country: 'Česko',\n      format: 'Na Blu-ray',\n      date: '07.08.2019',\n      company: 'Magic Box'\n    },\n    {\n      country: 'USA',\n      format: 'V kinech',\n      date: '22.03.2019',\n      company: 'Lionsgate US'\n    }\n  ]\n}\n```\n\n\u003c/details\u003e\n\n### Search\n\n\u003e Search for movies, TV series, and users across the ČSFD database.\n\n**Method:** `csfd.search(query: string): Promise\u003cSearchResults\u003e`\n\n```typescript\nimport { csfd } from 'node-csfd-api';\n\nconst results = await csfd.search('bart');\n\n// Access different result types\nconsole.log(results.movies); // Array of movies\nconsole.log(results.tvSeries); // Array of TV series\nconsole.log(results.users); // Array of users\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003e🔎 Click here to see full result example\u003c/summary\u003e\n\n```javascript\n[\n  {\n    id: 19653,\n    title: 'Black Bart',\n    year: '1975',\n    url: 'https://www.csfd.cz/film/19653-black-bart/',\n    type: 'tv-film',\n    colorRating: 'bad',\n    poster: 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7',\n    origins: ['USA'],\n    creators: {\n      directors: [{\n        id: 87470,\n        name: 'S. Craig Zahler',\n        url: 'https://www.csfd.cz/tvurce/87470-s-craig-zahler/'\n      }],\n      actors: [{\n        id: 1,\n        name: 'Mel Gibson',\n        url: 'https://www.csfd.cz/tvurce/1-mel-gibson/'\n      }]\n    }\n  }\n],\ntvSeries: [\n  {\n    id: 71924,\n    title: 'Království',\n    year: 1994,\n    url: 'https://www.csfd.cz/film/71924-kralovstvi/',\n    type: 'series',\n    colorRating: 'good',\n    poster: 'https://image.pmgstatic.com/cache/resized/w60h85/files/images/film/posters/166/708/166708064_2da697.jpg',\n    origins: ['Dánsko'],\n    creators: []\n  }\n],\nusers: [\n  {\n    id: 912,\n    user: 'BART!',\n    userRealName: 'Lukáš Barták',\n    avatar: 'https://image.pmgstatic.com/cache/resized/w45h60/files/images/user/avatars/000/281/281554_1c0fef.jpg',\n    url: 'https://www.csfd.cz/uzivatel/912-bart/'\n  }\n]\n```\n\n\u003c/details\u003e\n\n### Creators\n\n\u003e Get detailed information about a creator including their biography and filmography.\n\n**Method:** `csfd.creator(id: number): Promise\u003cCreator\u003e`\n\n```typescript\nimport { csfd } from 'node-csfd-api';\n\nconst creator = await csfd.creator(2120); // Quentin Tarantino\n\nconsole.log(creator.name); // Name\nconsole.log(creator.bio); // Biography\nconsole.log(creator.films); // Filmography\nconsole.log(creator.birthday); // Birth date\n// ... many more properties, see example\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003e🔎 Click here to see full result example\u003c/summary\u003e\n\n```javascript\n{\n  id: 2120,\n  name: 'Quentin Tarantino',\n  birthday: '27.03.1963',\n  birthplace: 'Knoxville, Tennessee, USA',\n  photo: 'https://image.pmgstatic.com/cache/resized/w100h132crop/files/images/creator/photos/164/515/164515525_b98f8a.jpg',\n  age: 58,\n  bio: 'Quentin Tarantino se narodil 27. března roku 1963 v americkém Knoxville teprve šestnáctileté Connie Tarantinové. Své jméno Quentin dostal podle matčiny oblíbené televizní postavy Quinta ze seriálu \"Gunsmoke\". Quentinův otec byl jistý Tony Tarantino, který rodinu opustil když byl Quentin ještě malinký. Jeho dětství a dospívání ovlivnily nejen filmy, ale pop kultura obecně. Televizní seriály, komiksy, populární hudba, to vše jako mladý hltal ve velkém a stále neměl…',\n  films: [\n    {\n      id: 527699,\n      title: 'Tenkrát v Hollywoodu',\n      year: 2019,\n      colorRating: 'good'\n    },\n    {\n      id: 362228,\n      title: 'Osm hrozných',\n      year: 2015,\n      colorRating: 'good'\n    },\n    {\n      id: 294824,\n      title: 'Nespoutaný Django',\n      year: 2012,\n      colorRating: 'good'\n    },\n    {\n      id: 117077,\n      title: 'Hanebný pancharti',\n      year: 2009,\n      colorRating: 'good'\n    },\n    {\n      id: 229384,\n      title: 'Grindhouse: Auto zabiják',\n      year: 2007,\n      colorRating: 'average'\n    },\n    {\n      id: 178904,\n      title: 'Sin City - město hříchu',\n      year: 2005,\n      colorRating: 'good'\n    },\n    {\n      id: 136304,\n      title: 'Kill Bill 2',\n      year: 2004,\n      colorRating: 'good'\n    },\n    { id: 43483, title: 'Kill Bill', year: 2003, colorRating: 'good' },\n    {\n      id: 8850,\n      title: 'Jackie Brown',\n      year: 1997,\n      colorRating: 'good'\n    },\n    {\n      id: 7743,\n      title: 'Čtyři pokoje',\n      year: 1995,\n      colorRating: 'good'\n    },\n    {\n      id: 8852,\n      title: 'Pulp Fiction: Historky z podsvětí',\n      year: 1994,\n      colorRating: 'good'\n    }\n  ]\n}\n```\n\n\u003c/details\u003e\n\n### User Ratings\n\n\u003e Retrieve user ratings from their ČSFD profile.\n\n**Method:** `csfd.userRatings(username: string, options?: UserRatingsOptions): Promise\u003cRating[]\u003e`\n\n#### Basic Usage\n\n```typescript\nimport { csfd } from 'node-csfd-api';\n\n// Get last page of ratings (~50 items)\nconst ratings = await csfd.userRatings('912-bart');\n```\n\n#### Advanced Options\n\n```typescript\n// Get specific page\nconst page2 = await csfd.userRatings('912-bart', { page: 2 });\n\n// Get all ratings (use with caution - rate limiting applies)\nconst allRatings = await csfd.userRatings('912-bart', {\n  allPages: true,\n  allPagesDelay: 2000 // 2 second delay between requests\n});\n\n// Filter by content type\nconst onlyMovies = await csfd.userRatings('912-bart', {\n  includesOnly: ['film']\n});\n\nconst excludeEpisodes = await csfd.userRatings('912-bart', {\n  exclude: ['episode', 'season']\n});\n```\n\n\u003e ⚠️ **Rate Limiting Warning**: When fetching all pages, use appropriate delays to avoid detection. Consider implementing exponential backoff for large datasets.\n\n\u003cdetails\u003e\n  \u003csummary\u003e🔎 Click here to see full result example\u003c/summary\u003e\n\n```javascript\n[\n  {\n    title: 'David Attenborough: Život na naší planetě',\n    year: 2020,\n    type: 'film',\n    url: 'https://www.csfd.cz/film/812944-david-attenborough-zivot-na-nasi-planete/',\n    colorRating: 'good',\n    userDate: '01.11.2020',\n    userRating: 5\n  },\n  {\n    title: 'Coronation',\n    year: 2020,\n    type: 'film',\n    url: 'https://www.csfd.cz/film/912552-coronation/',\n    colorRating: 'good',\n    userDate: '28.10.2020',\n    userRating: 4\n  }\n];\n```\n\n\u003c/details\u003e\n\n#### UserRatingsOptions\n\n| Option          | Type                                    | Default     | Description                                                      |\n| --------------- | --------------------------------------- | ----------- | ---------------------------------------------------------------- |\n| `includesOnly`  | `CSFDFilmTypes[]`                       | `null`      | Include only specific content types (e.g., `['film', 'series']`) |\n| `exclude`       | `CSFDFilmTypes[]`                       | `null`      | Exclude specific content types (e.g., `['episode']`)             |\n| `allPages`      | `boolean`                               | `false`     | Fetch all pages of ratings                                       |\n| `allPagesDelay` | `number`                                | `0`         | Delay between page requests in milliseconds                      |\n| `page`          | `number`                                | `1`         | Fetch specific page number                                       |\n| `onProgress`    | `(page: number, total: number) =\u003e void` | `undefined` | Called on each page fetch — use for progress bars or logging     |\n\n\u003e 📝 **Note**: `includesOnly` and `exclude` are mutually exclusive. If both are provided, `includesOnly` takes precedence.\n\u003e\n\u003e 🔗 See [CSFDFilmTypes definition](https://github.com/bartholomej/node-csfd-api/blob/master/src/dto/global.ts)\n\n### User Reviews\n\n\u003e Retrieve detailed user reviews from their ČSFD profile.\n\n**Method:** `csfd.userReviews(userId: number | string, options?: UserReviewsOptions): Promise\u003cReview[]\u003e`\n\n#### Basic Usage\n\n```typescript\nimport { csfd } from 'node-csfd-api';\n\n// Get latest reviews\nconst reviews = await csfd.userReviews(195357);\n```\n\n#### Advanced Options\n\n```typescript\n// Get specific page\nconst page2 = await csfd.userReviews(195357, { page: 2 });\n\n// Get all reviews with rate limiting\nconst allReviews = await csfd.userReviews(195357, {\n  allPages: true,\n  allPagesDelay: 2000\n});\n\n// Filter by content type\nconst filtered = await csfd.userReviews(195357, {\n  includesOnly: ['film'],\n  exclude: ['episode']\n});\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003e🔎 Click here to see full result example\u003c/summary\u003e\n\n```javascript\n[\n  {\n    id: 1391448,\n    title: 'Co s Péťou?',\n    year: 2025,\n    type: 'film',\n    url: 'https://www.csfd.cz/film/1391448-co-s-petou/prehled/',\n    colorRating: 'good',\n    userDate: '27.11.2025',\n    userRating: 4,\n    text: 'Co s Péťou? Inu, co by? Každý normální Sparťan by to okamžitě mrdnul z útesu...',\n    poster:\n      'https://image.pmgstatic.com/cache/resized/w240h339/files/images/film/posters/170/492/170492173_1l3djd.jpg'\n  },\n  {\n    id: 1530416,\n    title: 'Kouzlo derby',\n    year: 2025,\n    type: 'film',\n    url: 'https://www.csfd.cz/film/1530416-kouzlo-derby/prehled/',\n    colorRating: 'average',\n    userDate: '26.11.2025',\n    userRating: 1,\n    text: 'Typické kolečkoidní sebevykradačské pásmo klišovitých...',\n    poster:\n      'https://image.pmgstatic.com/cache/resized/w240h339/files/images/film/posters/170/230/170230377_cimu90.jpg'\n  }\n];\n```\n\n\u003c/details\u003e\n\n#### UserReviewsOptions\n\nSame options as [UserRatingsOptions](#userrationsoptions).\n\n## 💻 CLI Tools\n\nThis library ships with a CLI exposing several tools. Choose the installation method that fits your workflow.\n\n### Installation\n\n**Option A: npx** _(no installation required)_\n\n\u003e Runs directly via Node.js\n\n```bash\nnpx node-csfd-api \u003ccommand\u003e\n```\n\n**Option B: Homebrew** _(macOS)_\n\n```bash\nbrew install bartholomej/tap/csfd\n```\n\n**Option C: Install script** _(macOS \u0026 Linux)_\n\n\u003e Installs the latest stable release as a standalone binary to `~/.local/bin/csfd`.\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/bartholomej/node-csfd-api/master/install.sh | bash\n## Install specific version\n# curl -fsSL https://raw.githubusercontent.com/bartholomej/node-csfd-api/master/install.sh | CSFD_VERSION=5.5.0 bash\n```\n\n**Option D: Windows** _(manual download)_\n\nDownload `csfd-windows-x64.zip` from the [latest release](https://github.com/bartholomej/node-csfd-api/releases/latest), extract `csfd.exe`, and add it to your `PATH`.\n\n\u003e ⚠️ Windows may show a SmartScreen warning (\"Windows protected your PC\") because the binary is not code-signed. To proceed: click **More info** → **Run anyway**. Alternatively, right-click the `.exe` → Properties → check **Unblock**.\n\n---\n\n### CLI Examples\n\n\u003e 💡 The examples below use `csfd` (Options B, C \u0026 D). If you use npx, replace it with `npx node-csfd-api` — e.g. `npx node-csfd-api export ratings 912`.\n\n#### 1. Search\n\n```bash\ncsfd search tarantino\n# npx node-csfd-api search tarantino\ncsfd search \"blade runner\" --json   # raw JSON output\n# npx node-csfd-api search \"blade runner\" --json\n```\n\n#### 2. Movie Details\n\n```bash\ncsfd movie 535121             # by ID\n# npx node-csfd-api movie 535121\ncsfd movie \"blade runner\"     # by title — searches and shows the top result\n# npx node-csfd-api movie \"blade runner\"\ncsfd movie 535121 --json      # raw JSON output, pipe-friendly\n# npx node-csfd-api movie 535121 --json\n```\n\n#### 3. Export Ratings (CSV, JSON \u0026 Letterboxd)\n\n\u003e Backup your personal user ratings. _Use this tool just to keep a local copy of your data._\n\n```bash\ncsfd export ratings 912            # CSV (default) -\u003e \u003cuserId\u003e-ratings.csv\n# npx node-csfd-api export ratings 912\ncsfd export ratings 912 --json     # JSON -\u003e \u003cuserId\u003e-ratings.json\n# npx node-csfd-api export ratings 912 --json\ncsfd export ratings 912 --letterboxd  # Letterboxd CSV -\u003e \u003cuserId\u003e-for-letterboxd.csv\n# npx node-csfd-api export ratings 912 --letterboxd\n```\n\n#### 3. Export Reviews (CSV \u0026 JSON)\n\n```bash\ncsfd export reviews 912            # CSV (default) -\u003e \u003cuserId\u003e-reviews.csv\n# npx node-csfd-api export reviews 912\ncsfd export reviews 912 --json     # JSON -\u003e \u003cuserId\u003e-reviews.json\n# npx node-csfd-api export reviews 912 --json\n```\n\n#### 4. REST API Server\n\n```bash\ncsfd server\n# npx node-csfd-api server\n```\n\n#### 5. MCP Server for AI Agents\n\n```bash\ncsfd mcp\n# npx node-csfd-api mcp\n```\n\n## 🤖 MCP Server (Model Context Protocol)\n\nThis 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**.\n\n### Features\n\n- **Search**: Search for movies, TV series, and users.\n- **Details**: Get comprehensive details about movies, creators, and users.\n- **Reviews**: Read user reviews and ratings.\n\n### Usage with Claude Desktop\n\nAdd the following configuration to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"csfd\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"node-csfd-api\", \"mcp\"]\n    }\n  }\n}\n```\n\n### Supported Tools\n\n- `search`: Search query (returns movies, series, users)\n- `movie_details`: Get movie details by ID\n- `creator_details`: Get creator details by ID\n- `user_ratings`: Get user ratings\n- `user_reviews`: Get user reviews\n\n## 🐳 Docker Support\n\nRun the CSFD API as a standalone REST service using Docker.\n\n### Using Pre-built Image\n\n```bash\n# Pull the latest image\ndocker pull bartholomej/node-csfd-api\n\n# Run the container\ndocker run -p 3000:3000 bartholomej/node-csfd-api\n```\n\n### Building Your Own Image\n\n```bash\n# Build the image\ndocker build -t node-csfd-api .\n\n# Run the container\ndocker run -p 3000:3000 node-csfd-api\n```\n\n### REST API Endpoints\n\nOnce running, access the API at `http://localhost:3000`:\n\n| Endpoint                  | Description       | Example                  |\n| ------------------------- | ----------------- | ------------------------ |\n| `/movie/:id`              | Get movie details | `/movie/535121`          |\n| `/search/:query`          | Search content    | `/search/tarantino`      |\n| `/creator/:id`            | Get creator info  | `/creator/2120`          |\n| `/user-ratings/:username` | Get user ratings  | `/user-ratings/912-bart` |\n| `/user-reviews/:userId`   | Get user reviews  | `/user-reviews/195357`   |\n\n**Docker Hub:** [bartholomej/node-csfd-api](https://hub.docker.com/r/bartholomej/node-csfd-api)\n\n## 🌟 Real-World Usage\n\nThis library powers several production applications:\n\n### Browser Extensions\n\n- **[Netflix ČSFD Extension](https://chrome.google.com/webstore/detail/netflix-csfd/eomgekccbddnlpmehgdjmlphndjgnlni)** - Shows ČSFD ratings on Netflix ([source](https://github.com/bartholomej/netflix-csfd-ext))\n- **[Dafilms Extension](https://chrome.google.com/webstore/detail/dafilms/hgcgneddmgflnbmhkjnefiobjgobbmdm)** - ČSFD integration for Dafilms ([source](https://github.com/bartholomej/dafilms-ext))\n- **[Kviff.tv Extension](https://chrome.google.com/webstore/detail/kvifftv-%20-csfd/ihpngekoejodiligajlppbeedofhnmfm)** - ČSFD ratings for Kviff.tv ([source](https://github.com/bartholomej/kviff-ext))\n\n### Web Applications\n\n- **[bartweb.cz](https://bartweb.cz)** - Personal website using Firebase Functions for \"Last Seen\" movie tracking\n\n### Mobile Applications\n\n- **[KinoKlub](https://play.google.com/store/apps/details?id=com.aquasoup)** - React Native app for AeroFilms cinema chain (Android \u0026 iOS)\n\n## 🔮 Roadmap\n\n### Completed Features ✅\n\n- **Movies \u0026 TV Series**\n  - Basic info (title, year, rating, poster, duration)\n  - Detailed metadata (genres, origins, VOD platforms)\n  - Cast \u0026 crew (directors, actors, writers, composers, producers, etc.)\n  - Related content (similar movies, trivia)\n  - Alternative titles, premieres, tags\n- **Search**\n  - Movies, TV series, Creators and users\n- **Creators**\n  - Biography and filmography\n- **User Data**\n  - Ratings with pagination and filtering\n  - Reviews with pagination and filtering\n\n### Planned Features 🚧\n\n- [x] Search: Creator search functionality\n- [ ] Movie: reviews from movie detail page\n- [ ] Movie: Original soundtracks (OST) information\n- [ ] Server: Caching layer for improved performance\n- [ ] Server: Rate limiting helpers\n\n## 🛠️ Development\n\n### Prerequisites\n\n- Node.js 18+\n- yarn/npm/pnpm/...\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/bartholomej/node-csfd-api.git\ncd node-csfd-api\n\n# Install dependencies\nyarn install\n\n# Run tests\nyarn test\n\n# Run tests with coverage\nyarn test:coverage\n\n# Start development mode\nyarn start\n\n# Run the demo\nyarn demo\n```\n\n### Project Structure\n\n```text\nsrc/\n├── dto/              # Data transfer objects \u0026 types\n├── fetchers/         # HTTP request handlers\n├── helpers/          # Parsing \u0026 data transformation\n├── services/         # Main API service classes\n└── index.ts          # Public API exports\n```\n\n### Testing\n\nThe project maintains ~100% code coverage. Tests are located in the `tests/` directory.\n\n```bash\n# Run all tests\nyarn test\n\n# Run tests in watch mode\nyarn test:watch\n\n# Generate coverage report\nyarn test:coverage\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n### How to Contribute\n\n1. **Fork the repository**\n2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)\n3. **Make your changes**\n4. **Add tests** for new functionality\n5. **Ensure tests pass** (`yarn test`)\n6. **Commit your changes** (`git commit -m 'Add amazing feature'`)\n7. **Push to the branch** (`git push origin feature/amazing-feature`)\n8. **Open a Pull Request**\n\n### Guidelines\n\n- Write clear, concise commit messages\n- Add tests for new features\n- Update documentation as needed\n- Follow the existing code style\n- Ensure all tests pass before submitting PR\n\n### Reporting Issues\n\nFound a bug? Have a feature request? Please [open an issue](https://github.com/bartholomej/node-csfd-api/issues) with:\n\n- Clear description of the problem\n- Steps to reproduce (for bugs)\n- Expected vs actual behavior\n- Environment details (Node version, OS, etc.)\n\n## ⭐️ Support\n\nIf you find this project useful and you are brave enough consider [making a donation](https://github.com/sponsors/bartholomej) for some 🍺 or 🍵 ;)\n\n- Giving it a ⭐️ on [GitHub](https://github.com/bartholomej/node-csfd-api)\n- Sharing it with others who might benefit\n- [Sponsoring the project](https://github.com/sponsors/bartholomej) to support ongoing development\n\nYour support helps maintain and improve this library! 🙏\n\n## 🔒 Privacy \u0026 Security\n\n**This library does not collect, store, or transmit any user data.**\n\nAll requests are made directly from your application to ČSFD.cz. No intermediary servers are involved, and no data is logged or stored by this library.\n\nI physically can't. I have nowhere to store it. I don't even have a server database to store it. So even if Justin Bieber asked nicely to see your data, I wouldn't have anything to show him.\n\n### Important Notes\n\n- This is a **scraping library** - use it responsibly and respect ❤️ ČSFD's terms of service\n- Implement appropriate rate limiting in production\n- Consider caching responses to minimize server load\n- Be aware of CORS restrictions when using in browsers\n\n## 📝 License\n\nMIT © 2020 - 2026 [Lukas Bartak](http://bartweb.cz)\n\nSee [LICENSE](LICENSE) for full details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Built with ❤️ by [Lukas Bartak](https://bartweb.cz)**\n\nPowered by nature 🗻, wind 💨, tea 🍵 and beer 🍺\n\n[⭐ Star on GitHub](https://github.com/bartholomej/node-csfd-api) • [📦 NPM Package](https://www.npmjs.com/node-csfd-api) • [🐳 Docker Hub](https://hub.docker.com/r/bartholomej/node-csfd-api)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbartholomej%2Fnode-csfd-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbartholomej%2Fnode-csfd-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbartholomej%2Fnode-csfd-api/lists"}