NYT Content Discovery

naftiko: "1.0.0-alpha1"

info:
  label: "NYT Content Discovery"
  description: "Workflow for discovering NYT content trends, popular articles, books, movies, and entertainment coverage. Combines the Most Popular API, Books API, and Movie Reviews API to support media analysts, editorial teams, and content recommendation systems."
  tags:
    - New York Times
    - Content
    - Trending
    - Books
    - Movies
    - Entertainment
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      NYT_API_KEY: NYT_API_KEY

capability:
  consumes:
    - import: nyt-most-popular
      location: ./shared/most-popular.yaml
    - import: nyt-books
      location: ./shared/books.yaml
    - import: nyt-movie-reviews
      location: ./shared/movie-reviews.yaml

  exposes:
    - type: rest
      port: 8081
      namespace: nyt-content-discovery-api
      description: "Unified REST API for discovering trending NYT content, book rankings, and movie reviews."
      resources:
        - path: /v1/most-emailed/{section}/{time-period}
          name: most-emailed
          description: "Most emailed NYT articles."
          operations:
            - method: GET
              name: get-most-emailed
              description: "Get most emailed articles by section and time period."
              call: "nyt-most-popular.get-most-emailed"
              with:
                section: "rest.section"
                time-period: "rest.time-period"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/most-shared/{section}/{time-period}
          name: most-shared
          description: "Most shared NYT articles."
          operations:
            - method: GET
              name: get-most-shared
              description: "Get most shared articles by section and time period."
              call: "nyt-most-popular.get-most-shared"
              with:
                section: "rest.section"
                time-period: "rest.time-period"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/most-viewed/{section}/{time-period}
          name: most-viewed
          description: "Most viewed NYT articles."
          operations:
            - method: GET
              name: get-most-viewed
              description: "Get most viewed articles by section and time period."
              call: "nyt-most-popular.get-most-viewed"
              with:
                section: "rest.section"
                time-period: "rest.time-period"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/best-sellers
          name: best-sellers
          description: "NYT Best Sellers lists."
          operations:
            - method: GET
              name: get-best-seller-list
              description: "Get current NYT Best Sellers list."
              call: "nyt-books.get-best-seller-list"
              with:
                list: "rest.list"
                bestsellers-date: "rest.bestsellers-date"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/book-reviews
          name: book-reviews
          description: "NYT book reviews."
          operations:
            - method: GET
              name: get-book-reviews
              description: "Get NYT book reviews by title, author, or ISBN."
              call: "nyt-books.get-book-reviews"
              with:
                isbn: "rest.isbn"
                title: "rest.title"
                author: "rest.author"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/movie-reviews
          name: movie-reviews
          description: "NYT movie reviews."
          operations:
            - method: GET
              name: get-movie-reviews
              description: "Get NYT movie reviews, optionally filtered to Critics' Picks."
              call: "nyt-movie-reviews.get-movie-reviews"
              with:
                type: "rest.type"
                offset: "rest.offset"
                order: "rest.order"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/movie-reviews/search
          name: movie-reviews-search
          description: "Search NYT movie reviews."
          operations:
            - method: GET
              name: search-movie-reviews
              description: "Search NYT movie reviews by keyword or reviewer."
              call: "nyt-movie-reviews.search-movie-reviews"
              with:
                query: "rest.query"
                reviewer: "rest.reviewer"
                critics-pick: "rest.critics-pick"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9091
      namespace: nyt-content-discovery-mcp
      transport: http
      description: "MCP server for AI-assisted content trend analysis and entertainment discovery."
      tools:
        - name: get-most-emailed
          description: "Get the most emailed NYT articles by section and time period (1 day, 7 days, 30 days)."
          hints:
            readOnly: true
            idempotent: true
          call: "nyt-most-popular.get-most-emailed"
          with:
            section: "tools.section"
            time-period: "tools.time-period"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-most-shared
          description: "Get the most socially shared NYT articles by section and time period."
          hints:
            readOnly: true
            idempotent: true
          call: "nyt-most-popular.get-most-shared"
          with:
            section: "tools.section"
            time-period: "tools.time-period"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-most-viewed
          description: "Get the most viewed NYT articles by section and time period."
          hints:
            readOnly: true
            idempotent: true
          call: "nyt-most-popular.get-most-viewed"
          with:
            section: "tools.section"
            time-period: "tools.time-period"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-best-seller-list
          description: "Get current NYT Best Sellers list for a specific category (e.g., hardcover-fiction)."
          hints:
            readOnly: true
            idempotent: true
          call: "nyt-books.get-best-seller-list"
          with:
            list: "tools.list"
            bestsellers-date: "tools.bestsellers-date"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-best-seller-history
          description: "Search the full history of NYT Best Sellers by author, title, or ISBN."
          hints:
            readOnly: true
            idempotent: true
          call: "nyt-books.get-best-seller-history"
          with:
            author: "tools.author"
            title: "tools.title"
            isbn: "tools.isbn"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-book-reviews
          description: "Get NYT book reviews by title, author, or ISBN."
          hints:
            readOnly: true
            idempotent: true
          call: "nyt-books.get-book-reviews"
          with:
            isbn: "tools.isbn"
            title: "tools.title"
            author: "tools.author"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-movie-reviews
          description: "Get NYT movie reviews with optional filter for Critics' Picks."
          hints:
            readOnly: true
            idempotent: true
          call: "nyt-movie-reviews.get-movie-reviews"
          with:
            type: "tools.type"
            order: "tools.order"
          outputParameters:
            - type: object
              mapping: "$."

        - name: search-movie-reviews
          description: "Search NYT movie reviews by keyword, reviewer name, or date range."
          hints:
            readOnly: true
            idempotent: true
          call: "nyt-movie-reviews.search-movie-reviews"
          with:
            query: "tools.query"
            reviewer: "tools.reviewer"
            critics-pick: "tools.critics-pick"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-movie-critics
          description: "Get NYT movie critic profiles and biographies."
          hints:
            readOnly: true
            idempotent: true
          call: "nyt-movie-reviews.get-movie-critics"
          with:
            reviewer: "tools.reviewer"
          outputParameters:
            - type: object
              mapping: "$."