naftiko: 1.0.0-alpha2
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-06'
binds: []
capability:
  consumes:
  - type: http
    namespace: cranlogs
    baseUri: https://cranlogs.r-pkg.org
    description: METACRAN CranLogs public API — no authentication required
    resources:
    - name: download-totals
      path: /downloads/total
      description: Total download counts for R packages
      operations:
      - name: get-package-download-totals
        method: GET
        description: Get total download counts for packages over a period
        inputParameters:
        - name: period
          in: path
          type: string
          required: true
          description: 'Period: last-day, last-week, last-month, grand-total, or date range'
        - name: packages
          in: path
          type: string
          required: true
          description: Package name or comma-separated list
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: download-daily
      path: /downloads/daily
      description: Daily download counts for R packages
      operations:
      - name: get-package-download-daily
        method: GET
        description: Get daily download breakdown for packages over a period
        inputParameters:
        - name: period
          in: path
          type: string
          required: true
          description: Period or date range
        - name: packages
          in: path
          type: string
          required: true
          description: Package name or comma-separated list
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: top-packages
      path: /top
      description: Most-downloaded CRAN packages
      operations:
      - name: get-top-packages
        method: GET
        description: Get the most-downloaded CRAN packages for a period
        inputParameters:
        - name: period
          in: path
          type: string
          required: true
          description: 'Period: last-day, last-week, last-month'
        - name: count
          in: path
          type: integer
          required: true
          description: Number of top packages (max 100)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: crandb
    baseUri: https://crandb.r-pkg.org
    description: METACRAN CranDB public API — no authentication required
    resources:
    - name: packages
      path: /
      description: CRAN package metadata
      operations:
      - name: get-package
        method: GET
        description: Get metadata for the latest version of a CRAN package
        inputParameters:
        - name: package
          in: path
          type: string
          required: true
          description: CRAN package name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-package-version
        method: GET
        description: Get metadata for a specific version of a CRAN package
        inputParameters:
        - name: package
          in: path
          type: string
          required: true
          description: CRAN package name
        - name: version
          in: path
          type: string
          required: true
          description: Version string or 'all'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: all-packages
      path: /-/pkgs
      description: All CRAN package names and versions
      operations:
      - name: list-all-packages
        method: GET
        description: List all CRAN packages with latest versions
        inputParameters: []
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: rversions
    baseUri: https://rversions.r-pkg.org
    description: R Versions public API — no authentication required
    resources:
    - name: current-release
      path: /r-release
      description: Current stable R release
      operations:
      - name: get-r-release
        method: GET
        description: Get the current stable R release version and date
        inputParameters: []
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: previous-release
      path: /r-oldrel
      description: Previous (old-rel) R release
      operations:
      - name: get-r-oldrel
        method: GET
        description: Get the previous stable R release for backward compatibility testing
        inputParameters: []
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: all-versions
      path: /r-versions
      description: All historical R releases
      operations:
      - name: list-r-versions
        method: GET
        description: List all historical R release versions with dates and nicknames
        inputParameters: []
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  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: $.