NYT Article Research

naftiko: "1.0.0-alpha1"

info:
  label: "NYT Article Research"
  description: "Unified workflow for researching and discovering NYT content. Combines article search, archive access, top stories, and the newswire to support journalists, researchers, and developers building news applications. Enables keyword-based article discovery, historical archive access, and real-time content monitoring."
  tags:
    - New York Times
    - Research
    - Articles
    - Journalism
    - News Discovery
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      NYT_API_KEY: NYT_API_KEY

capability:
  consumes:
    - import: nyt-article-search
      location: ./shared/article-search.yaml
    - import: nyt-archive
      location: ./shared/archive.yaml
    - import: nyt-top-stories
      location: ./shared/top-stories.yaml
    - import: nyt-newswire
      location: ./shared/times-newswire.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: nyt-article-research-api
      description: "Unified REST API for researching and discovering NYT articles."
      resources:
        - path: /v1/articles
          name: article-search
          description: "Search NYT articles by keyword, date range, and facets."
          operations:
            - method: GET
              name: search-articles
              description: "Search NYT articles using keywords, filters, and facets."
              call: "nyt-article-search.search-articles"
              with:
                q: "rest.q"
                fq: "rest.fq"
                begin_date: "rest.begin_date"
                end_date: "rest.end_date"
                sort: "rest.sort"
                page: "rest.page"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/archive/{year}/{month}
          name: archive
          description: "NYT article archive by year and month."
          operations:
            - method: GET
              name: get-articles-by-month
              description: "Get all NYT articles for a specific year and month."
              call: "nyt-archive.get-articles-by-month"
              with:
                year: "rest.year"
                month: "rest.month"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/top-stories/{section}
          name: top-stories
          description: "Top stories from a specific NYT section."
          operations:
            - method: GET
              name: get-top-stories-by-section
              description: "Get top stories from the specified NYT section."
              call: "nyt-top-stories.get-top-stories-by-section"
              with:
                section: "rest.section"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/newswire/{source}/{section}
          name: newswire
          description: "Real-time NYT article stream."
          operations:
            - method: GET
              name: get-newswire-content
              description: "Get recently published NYT articles in real-time."
              call: "nyt-newswire.get-newswire-content"
              with:
                source: "rest.source"
                section: "rest.section"
                limit: "rest.limit"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: nyt-article-research-mcp
      transport: http
      description: "MCP server for AI-assisted NYT article research and content discovery."
      tools:
        - name: search-articles
          description: "Search NYT articles from 1851 to today using keywords, date ranges, and section filters."
          hints:
            readOnly: true
            idempotent: true
          call: "nyt-article-search.search-articles"
          with:
            q: "tools.q"
            fq: "tools.fq"
            begin_date: "tools.begin_date"
            end_date: "tools.end_date"
            sort: "tools.sort"
            page: "tools.page"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-articles-by-month
          description: "Retrieve all NYT articles published in a specific year and month, going back to 1851."
          hints:
            readOnly: true
            idempotent: true
          call: "nyt-archive.get-articles-by-month"
          with:
            year: "tools.year"
            month: "tools.month"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-top-stories-by-section
          description: "Get articles currently featured on a specific NYT section front page."
          hints:
            readOnly: true
            idempotent: true
          call: "nyt-top-stories.get-top-stories-by-section"
          with:
            section: "tools.section"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-newswire-content
          description: "Monitor the NYT newswire for recently published articles by section in real-time."
          hints:
            readOnly: true
            idempotent: true
          call: "nyt-newswire.get-newswire-content"
          with:
            source: "tools.source"
            section: "tools.section"
            limit: "tools.limit"
          outputParameters:
            - type: object
              mapping: "$."