Entertainment Discovery

naftiko: 1.0.0-alpha2
info:
  label: Entertainment Discovery
  description: Workflow capability for discovering, searching, and researching movies, TV series, and people using The Movie
    Database. Supports entertainment recommendation apps, streaming service aggregators, media library tools, and AI assistants
    answering questions about films and television.
  tags:
  - Entertainment
  - Movies
  - People
  - Streaming
  - Television
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    TMDB_ACCESS_TOKEN: TMDB_ACCESS_TOKEN
capability:
  consumes:
  - type: http
    namespace: tmdb
    baseUri: https://api.themoviedb.org/3
    description: The Movie Database API v3 — movies, TV, people, and images.
    authentication:
      type: bearer
      token: '{{TMDB_ACCESS_TOKEN}}'
    resources:
    - name: search
      path: /search
      description: Search across movies, TV series, people, and all media.
      operations:
      - name: search-movies
        method: GET
        description: Search for movies by title.
        inputParameters:
        - name: query
          in: query
          type: string
          required: true
          description: Movie title search query.
        - name: language
          in: query
          type: string
          required: false
          description: ISO 639-1 language code.
        - name: page
          in: query
          type: integer
          required: false
          description: Page number.
        - name: year
          in: query
          type: integer
          required: false
          description: Filter by release year.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: search-tv
        method: GET
        description: Search for TV series by title.
        inputParameters:
        - name: query
          in: query
          type: string
          required: true
          description: TV series title search query.
        - name: language
          in: query
          type: string
          required: false
          description: ISO 639-1 language code.
        - name: page
          in: query
          type: integer
          required: false
          description: Page number.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: search-people
        method: GET
        description: Search for people (actors, directors, crew) by name.
        inputParameters:
        - name: query
          in: query
          type: string
          required: true
          description: Person name search query.
        - name: language
          in: query
          type: string
          required: false
          description: ISO 639-1 language code.
        - name: page
          in: query
          type: integer
          required: false
          description: Page number.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: search-multi
        method: GET
        description: Search across movies, TV series, and people simultaneously.
        inputParameters:
        - name: query
          in: query
          type: string
          required: true
          description: Search query.
        - name: language
          in: query
          type: string
          required: false
          description: ISO 639-1 language code.
        - name: page
          in: query
          type: integer
          required: false
          description: Page number.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: movies
      path: /movie
      description: Movie data, discovery, and trending.
      operations:
      - name: get-movie-details
        method: GET
        description: Get full details for a movie by ID.
        inputParameters:
        - name: movie_id
          in: path
          type: integer
          required: true
          description: TMDB movie ID.
        - name: language
          in: query
          type: string
          required: false
          description: ISO 639-1 language code.
        - name: append_to_response
          in: query
          type: string
          required: false
          description: Comma-separated list of sub-requests to append.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-movie-credits
        method: GET
        description: Get cast and crew credits for a movie.
        inputParameters:
        - name: movie_id
          in: path
          type: integer
          required: true
          description: TMDB movie ID.
        - name: language
          in: query
          type: string
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-movie-recommendations
        method: GET
        description: Get movie recommendations based on a movie.
        inputParameters:
        - name: movie_id
          in: path
          type: integer
          required: true
        - name: language
          in: query
          type: string
          required: false
        - name: page
          in: query
          type: integer
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-popular-movies
        method: GET
        description: Get a list of currently popular movies.
        inputParameters:
        - name: language
          in: query
          type: string
          required: false
        - name: page
          in: query
          type: integer
          required: false
        - name: region
          in: query
          type: string
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-top-rated-movies
        method: GET
        description: Get the top rated movies on TMDB.
        inputParameters:
        - name: language
          in: query
          type: string
          required: false
        - name: page
          in: query
          type: integer
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: tv
      path: /tv
      description: TV series data, episodes, and trending.
      operations:
      - name: get-tv-details
        method: GET
        description: Get full details for a TV series by ID.
        inputParameters:
        - name: series_id
          in: path
          type: integer
          required: true
          description: TMDB TV series ID.
        - name: language
          in: query
          type: string
          required: false
        - name: append_to_response
          in: query
          type: string
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-tv-credits
        method: GET
        description: Get cast and crew credits for a TV series.
        inputParameters:
        - name: series_id
          in: path
          type: integer
          required: true
        - name: language
          in: query
          type: string
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-popular-tv
        method: GET
        description: Get a list of currently popular TV series.
        inputParameters:
        - name: language
          in: query
          type: string
          required: false
        - name: page
          in: query
          type: integer
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: trending
      path: /trending
      description: Trending movies, TV, and people.
      operations:
      - name: get-trending
        method: GET
        description: Get trending movies, TV series, or people for a time window.
        inputParameters:
        - name: time_window
          in: path
          type: string
          required: true
          description: Time window — day or week.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: people
      path: /person
      description: Person profiles and credits.
      operations:
      - name: get-person-details
        method: GET
        description: Get full details for a person (actor, director, etc.).
        inputParameters:
        - name: person_id
          in: path
          type: integer
          required: true
          description: TMDB person ID.
        - name: language
          in: query
          type: string
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-person-credits
        method: GET
        description: Get combined movie and TV credits for a person.
        inputParameters:
        - name: person_id
          in: path
          type: integer
          required: true
        - name: language
          in: query
          type: string
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: discover
      path: /discover
      description: Discover movies and TV series by genre, rating, and other filters.
      operations:
      - name: discover-movies
        method: GET
        description: Discover movies using extensive filters.
        inputParameters:
        - name: language
          in: query
          type: string
          required: false
        - name: sort_by
          in: query
          type: string
          required: false
        - name: with_genres
          in: query
          type: string
          required: false
        - name: page
          in: query
          type: integer
          required: false
        - name: vote_average_gte
          in: query
          type: number
          required: false
        - name: year
          in: query
          type: integer
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: discover-tv
        method: GET
        description: Discover TV series using extensive filters.
        inputParameters:
        - name: language
          in: query
          type: string
          required: false
        - name: sort_by
          in: query
          type: string
          required: false
        - name: with_genres
          in: query
          type: string
          required: false
        - name: page
          in: query
          type: integer
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: entertainment-discovery-api
    description: Unified REST API for movie and TV discovery, search, and detailed information.
    resources:
    - path: /v1/search
      name: search
      description: Cross-media search across movies, TV, and people.
      operations:
      - method: GET
        name: search-multi
        description: Search movies, TV series, and people simultaneously.
        call: tmdb.search-multi
        with:
          query: rest.query
          language: rest.language
          page: rest.page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/movies/search
      name: movie-search
      description: Search for movies by title.
      operations:
      - method: GET
        name: search-movies
        description: Search movies by title with optional year filter.
        call: tmdb.search-movies
        with:
          query: rest.query
          language: rest.language
          year: rest.year
          page: rest.page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/movies/{movie_id}
      name: movie-detail
      description: Detailed movie information.
      operations:
      - method: GET
        name: get-movie-details
        description: Get complete movie details by TMDB ID.
        call: tmdb.get-movie-details
        with:
          movie_id: rest.movie_id
          language: rest.language
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/movies/{movie_id}/recommendations
      name: movie-recommendations
      description: Movie recommendations.
      operations:
      - method: GET
        name: get-movie-recommendations
        description: Get recommendations based on a movie.
        call: tmdb.get-movie-recommendations
        with:
          movie_id: rest.movie_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/movies/popular
      name: popular-movies
      description: Popular movies list.
      operations:
      - method: GET
        name: get-popular-movies
        description: Get currently popular movies.
        call: tmdb.get-popular-movies
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/movies/top-rated
      name: top-rated-movies
      description: Top-rated movies list.
      operations:
      - method: GET
        name: get-top-rated-movies
        description: Get top rated movies on TMDB.
        call: tmdb.get-top-rated-movies
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/tv/search
      name: tv-search
      description: Search for TV series.
      operations:
      - method: GET
        name: search-tv
        description: Search TV series by title.
        call: tmdb.search-tv
        with:
          query: rest.query
          language: rest.language
          page: rest.page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/tv/{series_id}
      name: tv-detail
      description: Detailed TV series information.
      operations:
      - method: GET
        name: get-tv-details
        description: Get complete TV series details by TMDB ID.
        call: tmdb.get-tv-details
        with:
          series_id: rest.series_id
          language: rest.language
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/trending/{time_window}
      name: trending
      description: Trending content for the day or week.
      operations:
      - method: GET
        name: get-trending
        description: Get trending movies, TV, and people.
        call: tmdb.get-trending
        with:
          time_window: rest.time_window
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/discover/movies
      name: discover-movies
      description: Discover movies by genre and other filters.
      operations:
      - method: GET
        name: discover-movies
        description: Discover movies using genre, rating, and release year filters.
        call: tmdb.discover-movies
        with:
          with_genres: rest.with_genres
          sort_by: rest.sort_by
          year: rest.year
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/people/{person_id}
      name: person-detail
      description: Person profile information.
      operations:
      - method: GET
        name: get-person-details
        description: Get profile for an actor or crew member.
        call: tmdb.get-person-details
        with:
          person_id: rest.person_id
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: entertainment-discovery-mcp
    transport: http
    description: MCP server for AI-assisted entertainment discovery, movie research, and content recommendations.
    tools:
    - name: search-all-media
      description: Search across movies, TV series, and people simultaneously with a single query.
      hints:
        readOnly: true
        openWorld: true
      call: tmdb.search-multi
      with:
        query: tools.query
        language: tools.language
      outputParameters:
      - type: object
        mapping: $.
    - name: search-movies
      description: Search for movies by title with optional year and language filters.
      hints:
        readOnly: true
        openWorld: true
      call: tmdb.search-movies
      with:
        query: tools.query
        year: tools.year
        language: tools.language
      outputParameters:
      - type: object
        mapping: $.
    - name: get-movie-details
      description: Get full movie details including genres, production companies, budget, revenue, and ratings.
      hints:
        readOnly: true
        openWorld: false
      call: tmdb.get-movie-details
      with:
        movie_id: tools.movie_id
        language: tools.language
      outputParameters:
      - type: object
        mapping: $.
    - name: get-movie-credits
      description: Get the cast and crew for a movie.
      hints:
        readOnly: true
        openWorld: false
      call: tmdb.get-movie-credits
      with:
        movie_id: tools.movie_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-movie-recommendations
      description: Get recommended movies based on a seed movie.
      hints:
        readOnly: true
        openWorld: false
      call: tmdb.get-movie-recommendations
      with:
        movie_id: tools.movie_id
      outputParameters:
      - type: object
        mapping: $.
    - name: search-tv-series
      description: Search for TV series by title.
      hints:
        readOnly: true
        openWorld: true
      call: tmdb.search-tv
      with:
        query: tools.query
        language: tools.language
      outputParameters:
      - type: object
        mapping: $.
    - name: get-tv-details
      description: Get full details for a TV series including seasons, networks, and episode counts.
      hints:
        readOnly: true
        openWorld: false
      call: tmdb.get-tv-details
      with:
        series_id: tools.series_id
        language: tools.language
      outputParameters:
      - type: object
        mapping: $.
    - name: get-tv-credits
      description: Get the cast and crew for a TV series.
      hints:
        readOnly: true
        openWorld: false
      call: tmdb.get-tv-credits
      with:
        series_id: tools.series_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-trending-content
      description: Get trending movies, TV series, or people for today or this week.
      hints:
        readOnly: true
        openWorld: true
      call: tmdb.get-trending
      with:
        time_window: tools.time_window
      outputParameters:
      - type: object
        mapping: $.
    - name: discover-movies-by-genre
      description: Discover movies filtered by genre, minimum rating, sort order, and release year.
      hints:
        readOnly: true
        openWorld: true
      call: tmdb.discover-movies
      with:
        with_genres: tools.with_genres
        sort_by: tools.sort_by
        vote_average_gte: tools.vote_average_gte
        year: tools.year
      outputParameters:
      - type: object
        mapping: $.
    - name: get-popular-movies
      description: Get a list of currently popular movies on TMDB.
      hints:
        readOnly: true
        openWorld: true
      call: tmdb.get-popular-movies
      with:
        language: tools.language
        page: tools.page
      outputParameters:
      - type: object
        mapping: $.
    - name: get-person-profile
      description: Get profile, biography, and filmography for an actor, director, or crew member.
      hints:
        readOnly: true
        openWorld: false
      call: tmdb.get-person-details
      with:
        person_id: tools.person_id
      outputParameters:
      - type: object
        mapping: $.