R Package Analytics

naftiko: "1.0.0-alpha1"

info:
  label: "R Package Analytics"
  description: "R package ecosystem analytics workflow combining METACRAN CranLogs download statistics, CranDB package metadata, and R version information. Used by R package maintainers, data scientists, CI/CD engineers, and ecosystem researchers to analyze package adoption, trends, R version compatibility, and ecosystem health."
  tags:
    - R
    - CRAN
    - Package Analytics
    - Downloads
    - Open Source
    - Statistics
    - Versions
  created: "2026-05-02"
  modified: "2026-05-02"

binds: []

capability:
  consumes:
    - import: cranlogs
      location: ./shared/metacran-cranlogs.yaml
    - import: crandb
      location: ./shared/metacran-crandb.yaml
    - import: rversions
      location: ./shared/rversions.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: r-package-analytics-api
      description: "Unified REST API for R package analytics combining metadata and download statistics."
      resources:
        - path: /v1/packages/{package}
          name: packages
          description: "R package metadata"
          operations:
            - method: GET
              name: get-package
              description: "Get CRAN package metadata"
              call: "crandb.get-package"
              with:
                package: "rest.package"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/downloads/total/{period}/{packages}
          name: download-totals
          description: "Package download totals"
          operations:
            - method: GET
              name: get-download-totals
              description: "Get total download counts for packages"
              call: "cranlogs.get-package-download-totals"
              with:
                period: "rest.period"
                packages: "rest.packages"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/downloads/daily/{period}/{packages}
          name: daily-downloads
          description: "Daily package download counts"
          operations:
            - method: GET
              name: get-daily-downloads
              description: "Get daily download counts for packages"
              call: "cranlogs.get-package-download-daily"
              with:
                period: "rest.period"
                packages: "rest.packages"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/top/{period}/{count}
          name: top-packages
          description: "Top downloaded packages"
          operations:
            - method: GET
              name: get-top-packages
              description: "Get most-downloaded CRAN packages"
              call: "cranlogs.get-top-packages"
              with:
                period: "rest.period"
                count: "rest.count"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/r/release
          name: r-release
          description: "Current R release version"
          operations:
            - method: GET
              name: get-r-release
              description: "Get current stable R release version and date"
              call: "rversions.get-r-release"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/r/versions
          name: r-versions
          description: "All R release versions"
          operations:
            - method: GET
              name: list-r-versions
              description: "List all historical R releases"
              call: "rversions.list-r-versions"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: r-package-analytics-mcp
      transport: http
      description: "MCP server for AI-assisted R package ecosystem analysis."
      tools:
        - name: get-cran-package-metadata
          description: "Get detailed metadata for a CRAN R package including description, version, author, maintainer, dependencies (Imports, Depends, Suggests), license, and URLs."
          hints:
            readOnly: true
            openWorld: false
          call: "crandb.get-package"
          with:
            package: "tools.package"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-package-download-totals
          description: "Get total CRAN download counts for R packages for a given period (last-day, last-week, last-month, grand-total, or custom date range like 2023-01-01:2023-12-31)."
          hints:
            readOnly: true
            openWorld: false
          call: "cranlogs.get-package-download-totals"
          with:
            period: "tools.period"
            packages: "tools.packages"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-package-daily-downloads
          description: "Get daily CRAN download breakdown for R packages over a period. Useful for trend analysis and identifying download spikes."
          hints:
            readOnly: true
            openWorld: false
          call: "cranlogs.get-package-download-daily"
          with:
            period: "tools.period"
            packages: "tools.packages"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-top-downloaded-packages
          description: "Get the most-downloaded R packages from CRAN for last-day, last-week, or last-month. Returns up to 100 packages ranked by download count."
          hints:
            readOnly: true
            openWorld: false
          call: "cranlogs.get-top-packages"
          with:
            period: "tools.period"
            count: "tools.count"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-all-cran-packages
          description: "List all R packages available on CRAN with their current version numbers."
          hints:
            readOnly: true
            openWorld: false
          call: "crandb.list-all-packages"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-current-r-version
          description: "Get the current stable R release version number and date. Use to verify CI/CD pipelines target the latest R."
          hints:
            readOnly: true
            openWorld: false
          call: "rversions.get-r-release"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-previous-r-version
          description: "Get the previous stable R release (oldrel) version for backward compatibility testing."
          hints:
            readOnly: true
            openWorld: false
          call: "rversions.get-r-oldrel"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-all-r-versions
          description: "List all historical R releases with version numbers, release dates, and nicknames."
          hints:
            readOnly: true
            openWorld: false
          call: "rversions.list-r-versions"
          outputParameters:
            - type: object
              mapping: "$."