naftiko: 1.0.0-alpha2
info:
  label: Lichess API — Challenges
  description: 'Lichess API — Challenges. 11 operations. Lead operation: List your challenges. Self-contained Naftiko capability covering one Lichess business surface.'
  tags:
  - Lichess
  - Challenges
  created: '2026-05-25'
  modified: '2026-05-25'
binds:
- namespace: env
  keys:
    LICHESS_API_TOKEN: LICHESS_API_TOKEN
capability:
  consumes:
  - type: http
    namespace: challenges
    baseUri: https://lichess.org
    description: Lichess Challenges business capability. Self-contained, no shared references.
    resources:
    - name: challenge
      path: /api/challenge
      operations:
      - name: challengelist
        method: GET
        description: 'List your challenges'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: challenge-username
      path: /api/challenge/{username}
      operations:
      - name: challengecreate
        method: POST
        description: 'Create a challenge'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: username
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          required: false
    - name: challenge-challengeid-show
      path: /api/challenge/{challengeId}/show
      operations:
      - name: challengeshow
        method: GET
        description: 'Show one challenge'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: challengeId
          in: path
          type: string
          required: true
    - name: challenge-challengeid-accept
      path: /api/challenge/{challengeId}/accept
      operations:
      - name: challengeaccept
        method: POST
        description: 'Accept a challenge'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: challengeId
          in: path
          type: string
          required: true
        - name: color
          in: query
          type: string
          required: false
    - name: challenge-challengeid-decline
      path: /api/challenge/{challengeId}/decline
      operations:
      - name: challengedecline
        method: POST
        description: 'Decline a challenge'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: challengeId
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          required: false
    - name: challenge-challengeid-cancel
      path: /api/challenge/{challengeId}/cancel
      operations:
      - name: challengecancel
        method: POST
        description: 'Cancel a challenge'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: challengeId
          in: path
          type: string
          required: true
        - name: opponentToken
          in: query
          type: string
          required: false
    - name: challenge-ai
      path: /api/challenge/ai
      operations:
      - name: challengeai
        method: POST
        description: 'Challenge the AI'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          required: false
    - name: challenge-open
      path: /api/challenge/open
      operations:
      - name: challengeopen
        method: POST
        description: 'Open-ended challenge'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          required: false
    - name: challenge-gameid-start-clocks
      path: /api/challenge/{gameId}/start-clocks
      operations:
      - name: challengestartclocks
        method: POST
        description: 'Start clocks of a game'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: gameId
          in: path
          type: string
          required: true
        - name: token1
          in: query
          type: string
          required: false
        - name: token2
          in: query
          type: string
          required: false
    - name: round-gameid-add-time-seconds
      path: /api/round/{gameId}/add-time/{seconds}
      operations:
      - name: roundaddtime
        method: POST
        description: 'Add time to the opponent clock'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: gameId
          in: path
          type: string
          required: true
        - name: seconds
          in: path
          type: string
          required: true
    - name: token-admin-challenge
      path: /api/token/admin-challenge
      operations:
      - name: adminchallengetokens
        method: POST
        description: 'Admin challenge tokens'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          required: false
    authentication:
      type: bearer
      value: '{{env.LICHESS_API_TOKEN}}'
      placement: header
  exposes:
  - type: rest
    namespace: challenges-rest
    port: 8080
    description: REST adapter for Lichess Challenges. One Spectral-compliant resource per consumed operation.
    resources:
    - path: /v1/api/challenge
      name: challenge
      description: REST surface for challenge.
      operations:
      - method: GET
        name: challengelist
        description: 'List your challenges'
        call: challenges.challengelist
        with:
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/challenge/{username}
      name: challenge-username
      description: REST surface for challenge-username.
      operations:
      - method: POST
        name: challengecreate
        description: 'Create a challenge'
        call: challenges.challengecreate
        with:
          username: rest.path.username
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/challenge/{challengeId}/show
      name: challenge-challengeid-show
      description: REST surface for challenge-challengeid-show.
      operations:
      - method: GET
        name: challengeshow
        description: 'Show one challenge'
        call: challenges.challengeshow
        with:
          challengeId: rest.path.challengeId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/challenge/{challengeId}/accept
      name: challenge-challengeid-accept
      description: REST surface for challenge-challengeid-accept.
      operations:
      - method: POST
        name: challengeaccept
        description: 'Accept a challenge'
        call: challenges.challengeaccept
        with:
          challengeId: rest.path.challengeId
          color: rest.query.color
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/challenge/{challengeId}/decline
      name: challenge-challengeid-decline
      description: REST surface for challenge-challengeid-decline.
      operations:
      - method: POST
        name: challengedecline
        description: 'Decline a challenge'
        call: challenges.challengedecline
        with:
          challengeId: rest.path.challengeId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/challenge/{challengeId}/cancel
      name: challenge-challengeid-cancel
      description: REST surface for challenge-challengeid-cancel.
      operations:
      - method: POST
        name: challengecancel
        description: 'Cancel a challenge'
        call: challenges.challengecancel
        with:
          challengeId: rest.path.challengeId
          opponentToken: rest.query.opponentToken
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/challenge/ai
      name: challenge-ai
      description: REST surface for challenge-ai.
      operations:
      - method: POST
        name: challengeai
        description: 'Challenge the AI'
        call: challenges.challengeai
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/challenge/open
      name: challenge-open
      description: REST surface for challenge-open.
      operations:
      - method: POST
        name: challengeopen
        description: 'Open-ended challenge'
        call: challenges.challengeopen
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/challenge/{gameId}/start-clocks
      name: challenge-gameid-start-clocks
      description: REST surface for challenge-gameid-start-clocks.
      operations:
      - method: POST
        name: challengestartclocks
        description: 'Start clocks of a game'
        call: challenges.challengestartclocks
        with:
          gameId: rest.path.gameId
          token1: rest.query.token1
          token2: rest.query.token2
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/round/{gameId}/add-time/{seconds}
      name: round-gameid-add-time-seconds
      description: REST surface for round-gameid-add-time-seconds.
      operations:
      - method: POST
        name: roundaddtime
        description: 'Add time to the opponent clock'
        call: challenges.roundaddtime
        with:
          gameId: rest.path.gameId
          seconds: rest.path.seconds
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/token/admin-challenge
      name: token-admin-challenge
      description: REST surface for token-admin-challenge.
      operations:
      - method: POST
        name: adminchallengetokens
        description: 'Admin challenge tokens'
        call: challenges.adminchallengetokens
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: challenges-mcp
    port: 9090
    transport: http
    description: MCP adapter for Lichess Challenges. One tool per consumed operation.
    tools:
    - name: lichess-challengelist
      description: 'List your challenges'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: challenges.challengelist
      with:
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-challengecreate
      description: 'Create a challenge'
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: challenges.challengecreate
      with:
        username: tools.username
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-challengeshow
      description: 'Show one challenge'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: challenges.challengeshow
      with:
        challengeId: tools.challengeId
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-challengeaccept
      description: 'Accept a challenge'
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: challenges.challengeaccept
      with:
        challengeId: tools.challengeId
        color: tools.color
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-challengedecline
      description: 'Decline a challenge'
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: challenges.challengedecline
      with:
        challengeId: tools.challengeId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-challengecancel
      description: 'Cancel a challenge'
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: challenges.challengecancel
      with:
        challengeId: tools.challengeId
        opponentToken: tools.opponentToken
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-challengeai
      description: 'Challenge the AI'
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: challenges.challengeai
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-challengeopen
      description: 'Open-ended challenge'
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: challenges.challengeopen
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-challengestartclocks
      description: 'Start clocks of a game'
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: challenges.challengestartclocks
      with:
        gameId: tools.gameId
        token1: tools.token1
        token2: tools.token2
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-roundaddtime
      description: 'Add time to the opponent clock'
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: challenges.roundaddtime
      with:
        gameId: tools.gameId
        seconds: tools.seconds
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-adminchallengetokens
      description: 'Admin challenge tokens'
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: challenges.adminchallengetokens
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.