Radio Browser — Interactions

naftiko: 1.0.0-alpha2
info:
  label: Radio Browser — Interactions
  description: 'Radio Browser Interactions capability exposing click counting, voting, and station submission flows.
    These are throttled per IP by the upstream Radio Browser servers (1 click per 24h per station per IP, 1 vote per 10 minutes
    per station per IP).'
  tags:
  - Radio Browser
  - Interactions
  - Music
  created: '2026-05-28'
  modified: '2026-05-28'
binds:
- namespace: env
  keys:
    RADIO_BROWSER_USER_AGENT: RADIO_BROWSER_USER_AGENT
capability:
  consumes:
  - type: http
    namespace: radio-browser-interactions
    baseUri: https://de1.api.radio-browser.info
    description: HTTP capability for click, vote, and station submission events.
    headers:
      User-Agent: '{{env.RADIO_BROWSER_USER_AGENT}}'
    resources:
    - name: url-stationuuid
      path: /json/url/{stationuuid}
      operations:
      - name: clickStation
        method: GET
        description: Click Station
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: stationuuid
          in: path
          type: string
          required: true
    - name: vote-stationuuid
      path: /json/vote/{stationuuid}
      operations:
      - name: voteStation
        method: GET
        description: Vote For Station
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: stationuuid
          in: path
          type: string
          required: true
    - name: add
      path: /json/add
      operations:
      - name: addStation
        method: POST
        description: Submit Station
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: form
          type: string
          required: true
        - name: url
          in: form
          type: string
          required: true
        - name: homepage
          in: form
          type: string
        - name: favicon
          in: form
          type: string
        - name: country
          in: form
          type: string
        - name: countrycode
          in: form
          type: string
        - name: state
          in: form
          type: string
        - name: language
          in: form
          type: string
        - name: tags
          in: form
          type: string
    authentication:
      type: none
  exposes:
  - type: mcp
    namespace: radio-browser-interactions-mcp
    port: 9090
    transport: http
    description: MCP adapter exposing Radio Browser interaction endpoints. Write tools surface idempotency-friendly hints.
    tools:
    - name: click-station
      description: Click Station
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: radio-browser-interactions.clickStation
      with:
        stationuuid: tools.stationuuid
      outputParameters:
      - type: object
        mapping: $.
    - name: vote-station
      description: Vote For Station
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: radio-browser-interactions.voteStation
      with:
        stationuuid: tools.stationuuid
      outputParameters:
      - type: object
        mapping: $.
    - name: submit-station
      description: Submit Station
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: radio-browser-interactions.addStation
      with:
        name: tools.name
        url: tools.url
        homepage: tools.homepage
        favicon: tools.favicon
        country: tools.country
        countrycode: tools.countrycode
        state: tools.state
        language: tools.language
        tags: tools.tags
      outputParameters:
      - type: object
        mapping: $.