Lichess API — Games

naftiko: 1.0.0-alpha2
info:
  label: Lichess API — Games
  description: 'Lichess API — Games. 13 operations. Lead operation: Export one game. Self-contained Naftiko capability covering one Lichess business surface.'
  tags:
  - Lichess
  - Games
  created: '2026-05-25'
  modified: '2026-05-25'
binds:
- namespace: env
  keys:
    LICHESS_API_TOKEN: LICHESS_API_TOKEN
capability:
  consumes:
  - type: http
    namespace: games
    baseUri: https://lichess.org
    description: Lichess Games business capability. Self-contained, no shared references.
    resources:
    - name: game-export-gameid
      path: /game/export/{gameId}
      operations:
      - name: gamepgn
        method: GET
        description: 'Export one game'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: gameId
          in: path
          type: string
          required: true
        - name: moves
          in: query
          type: string
          required: false
        - name: pgnInJson
          in: query
          type: string
          required: false
        - name: tags
          in: query
          type: string
          required: false
        - name: clocks
          in: query
          type: string
          required: false
        - name: evals
          in: query
          type: string
          required: false
        - name: accuracy
          in: query
          type: string
          required: false
        - name: opening
          in: query
          type: string
          required: false
        - name: division
          in: query
          type: string
          required: false
        - name: literate
          in: query
          type: string
          required: false
        - name: withBookmarked
          in: query
          type: string
          required: false
    - name: game-gameid-chat
      path: /game/{gameId}/chat
      operations:
      - name: gamechatget
        method: GET
        description: 'Fetch the spectator game chat'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: user-username-current-game
      path: /api/user/{username}/current-game
      operations:
      - name: apiusercurrentgame
        method: GET
        description: 'Export ongoing game of a user'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: username
          in: path
          type: string
          required: true
        - name: moves
          in: query
          type: string
          required: false
        - name: pgnInJson
          in: query
          type: string
          required: false
        - name: tags
          in: query
          type: string
          required: false
        - name: clocks
          in: query
          type: string
          required: false
        - name: evals
          in: query
          type: string
          required: false
        - name: accuracy
          in: query
          type: string
          required: false
        - name: opening
          in: query
          type: string
          required: false
        - name: division
          in: query
          type: string
          required: false
        - name: literate
          in: query
          type: string
          required: false
    - name: games-user-username
      path: /api/games/user/{username}
      operations:
      - name: apigamesuser
        method: GET
        description: 'Export games of a user'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: username
          in: path
          type: string
          required: true
        - name: since
          in: query
          type: string
          required: false
        - name: until
          in: query
          type: string
          required: false
        - name: max
          in: query
          type: string
          required: false
        - name: vs
          in: query
          type: string
          required: false
        - name: rated
          in: query
          type: string
          required: false
        - name: perfType
          in: query
          type: string
          required: false
        - name: color
          in: query
          type: string
          required: false
        - name: analysed
          in: query
          type: string
          required: false
        - name: moves
          in: query
          type: string
          required: false
        - name: pgnInJson
          in: query
          type: string
          required: false
        - name: tags
          in: query
          type: string
          required: false
        - name: clocks
          in: query
          type: string
          required: false
        - name: evals
          in: query
          type: string
          required: false
        - name: accuracy
          in: query
          type: string
          required: false
        - name: opening
          in: query
          type: string
          required: false
        - name: division
          in: query
          type: string
          required: false
        - name: ongoing
          in: query
          type: string
          required: false
        - name: finished
          in: query
          type: string
          required: false
        - name: literate
          in: query
          type: string
          required: false
        - name: lastFen
          in: query
          type: string
          required: false
        - name: withBookmarked
          in: query
          type: string
          required: false
        - name: sort
          in: query
          type: string
          required: false
    - name: games-export-ids
      path: /api/games/export/_ids
      operations:
      - name: gamesexportids
        method: POST
        description: 'Export games by IDs'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: moves
          in: query
          type: string
          required: false
        - name: pgnInJson
          in: query
          type: string
          required: false
        - name: tags
          in: query
          type: string
          required: false
        - name: clocks
          in: query
          type: string
          required: false
        - name: evals
          in: query
          type: string
          required: false
        - name: accuracy
          in: query
          type: string
          required: false
        - name: opening
          in: query
          type: string
          required: false
        - name: division
          in: query
          type: string
          required: false
        - name: literate
          in: query
          type: string
          required: false
        - name: body
          in: body
          type: object
          required: false
    - name: stream-games-by-users
      path: /api/stream/games-by-users
      operations:
      - name: gamesbyusers
        method: POST
        description: 'Stream games of users'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: withCurrentGames
          in: query
          type: string
          required: false
        - name: body
          in: body
          type: object
          required: false
    - name: stream-games-streamid
      path: /api/stream/games/{streamId}
      operations:
      - name: gamesbyids
        method: POST
        description: 'Stream games by IDs'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: streamId
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          required: false
    - name: stream-games-streamid-add
      path: /api/stream/games/{streamId}/add
      operations:
      - name: gamesbyidsadd
        method: POST
        description: 'Add game IDs to stream'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: streamId
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          required: false
    - name: account-playing
      path: /api/account/playing
      operations:
      - name: apiaccountplaying
        method: GET
        description: 'Get my ongoing games'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: nb
          in: query
          type: string
          required: false
    - name: stream-game-id
      path: /api/stream/game/{id}
      operations:
      - name: streamgame
        method: GET
        description: 'Stream moves of a game'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          required: true
    - name: import
      path: /api/import
      operations:
      - name: gameimport
        method: POST
        description: 'Import one game'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          required: false
    - name: games-export-imports
      path: /api/games/export/imports
      operations:
      - name: apiimportedgamesuser
        method: GET
        description: 'Export your imported games'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: games-export-bookmarks
      path: /api/games/export/bookmarks
      operations:
      - name: apiexportbookmarks
        method: GET
        description: 'Export your bookmarked games'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: since
          in: query
          type: string
          required: false
        - name: until
          in: query
          type: string
          required: false
        - name: max
          in: query
          type: string
          required: false
        - name: moves
          in: query
          type: string
          required: false
        - name: pgnInJson
          in: query
          type: string
          required: false
        - name: tags
          in: query
          type: string
          required: false
        - name: clocks
          in: query
          type: string
          required: false
        - name: evals
          in: query
          type: string
          required: false
        - name: accuracy
          in: query
          type: string
          required: false
        - name: opening
          in: query
          type: string
          required: false
        - name: division
          in: query
          type: string
          required: false
        - name: literate
          in: query
          type: string
          required: false
        - name: lastFen
          in: query
          type: string
          required: false
        - name: sort
          in: query
          type: string
          required: false
    authentication:
      type: bearer
      value: '{{env.LICHESS_API_TOKEN}}'
      placement: header
  exposes:
  - type: rest
    namespace: games-rest
    port: 8080
    description: REST adapter for Lichess Games. One Spectral-compliant resource per consumed operation.
    resources:
    - path: /v1/game/export/{gameId}
      name: game-export-gameid
      description: REST surface for game-export-gameid.
      operations:
      - method: GET
        name: gamepgn
        description: 'Export one game'
        call: games.gamepgn
        with:
          gameId: rest.path.gameId
          moves: rest.query.moves
          pgnInJson: rest.query.pgnInJson
          tags: rest.query.tags
          clocks: rest.query.clocks
          evals: rest.query.evals
          accuracy: rest.query.accuracy
          opening: rest.query.opening
          division: rest.query.division
          literate: rest.query.literate
          withBookmarked: rest.query.withBookmarked
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/game/{gameId}/chat
      name: game-gameid-chat
      description: REST surface for game-gameid-chat.
      operations:
      - method: GET
        name: gamechatget
        description: 'Fetch the spectator game chat'
        call: games.gamechatget
        with:
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/user/{username}/current-game
      name: user-username-current-game
      description: REST surface for user-username-current-game.
      operations:
      - method: GET
        name: apiusercurrentgame
        description: 'Export ongoing game of a user'
        call: games.apiusercurrentgame
        with:
          username: rest.path.username
          moves: rest.query.moves
          pgnInJson: rest.query.pgnInJson
          tags: rest.query.tags
          clocks: rest.query.clocks
          evals: rest.query.evals
          accuracy: rest.query.accuracy
          opening: rest.query.opening
          division: rest.query.division
          literate: rest.query.literate
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/games/user/{username}
      name: games-user-username
      description: REST surface for games-user-username.
      operations:
      - method: GET
        name: apigamesuser
        description: 'Export games of a user'
        call: games.apigamesuser
        with:
          username: rest.path.username
          since: rest.query.since
          until: rest.query.until
          max: rest.query.max
          vs: rest.query.vs
          rated: rest.query.rated
          perfType: rest.query.perfType
          color: rest.query.color
          analysed: rest.query.analysed
          moves: rest.query.moves
          pgnInJson: rest.query.pgnInJson
          tags: rest.query.tags
          clocks: rest.query.clocks
          evals: rest.query.evals
          accuracy: rest.query.accuracy
          opening: rest.query.opening
          division: rest.query.division
          ongoing: rest.query.ongoing
          finished: rest.query.finished
          literate: rest.query.literate
          lastFen: rest.query.lastFen
          withBookmarked: rest.query.withBookmarked
          sort: rest.query.sort
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/games/export/_ids
      name: games-export-ids
      description: REST surface for games-export-ids.
      operations:
      - method: POST
        name: gamesexportids
        description: 'Export games by IDs'
        call: games.gamesexportids
        with:
          moves: rest.query.moves
          pgnInJson: rest.query.pgnInJson
          tags: rest.query.tags
          clocks: rest.query.clocks
          evals: rest.query.evals
          accuracy: rest.query.accuracy
          opening: rest.query.opening
          division: rest.query.division
          literate: rest.query.literate
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/stream/games-by-users
      name: stream-games-by-users
      description: REST surface for stream-games-by-users.
      operations:
      - method: POST
        name: gamesbyusers
        description: 'Stream games of users'
        call: games.gamesbyusers
        with:
          withCurrentGames: rest.query.withCurrentGames
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/stream/games/{streamId}
      name: stream-games-streamid
      description: REST surface for stream-games-streamid.
      operations:
      - method: POST
        name: gamesbyids
        description: 'Stream games by IDs'
        call: games.gamesbyids
        with:
          streamId: rest.path.streamId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/stream/games/{streamId}/add
      name: stream-games-streamid-add
      description: REST surface for stream-games-streamid-add.
      operations:
      - method: POST
        name: gamesbyidsadd
        description: 'Add game IDs to stream'
        call: games.gamesbyidsadd
        with:
          streamId: rest.path.streamId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/account/playing
      name: account-playing
      description: REST surface for account-playing.
      operations:
      - method: GET
        name: apiaccountplaying
        description: 'Get my ongoing games'
        call: games.apiaccountplaying
        with:
          nb: rest.query.nb
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/stream/game/{id}
      name: stream-game-id
      description: REST surface for stream-game-id.
      operations:
      - method: GET
        name: streamgame
        description: 'Stream moves of a game'
        call: games.streamgame
        with:
          id: rest.path.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/import
      name: import
      description: REST surface for import.
      operations:
      - method: POST
        name: gameimport
        description: 'Import one game'
        call: games.gameimport
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/games/export/imports
      name: games-export-imports
      description: REST surface for games-export-imports.
      operations:
      - method: GET
        name: apiimportedgamesuser
        description: 'Export your imported games'
        call: games.apiimportedgamesuser
        with:
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/games/export/bookmarks
      name: games-export-bookmarks
      description: REST surface for games-export-bookmarks.
      operations:
      - method: GET
        name: apiexportbookmarks
        description: 'Export your bookmarked games'
        call: games.apiexportbookmarks
        with:
          since: rest.query.since
          until: rest.query.until
          max: rest.query.max
          moves: rest.query.moves
          pgnInJson: rest.query.pgnInJson
          tags: rest.query.tags
          clocks: rest.query.clocks
          evals: rest.query.evals
          accuracy: rest.query.accuracy
          opening: rest.query.opening
          division: rest.query.division
          literate: rest.query.literate
          lastFen: rest.query.lastFen
          sort: rest.query.sort
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: games-mcp
    port: 9090
    transport: http
    description: MCP adapter for Lichess Games. One tool per consumed operation.
    tools:
    - name: lichess-gamepgn
      description: 'Export one game'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: games.gamepgn
      with:
        gameId: tools.gameId
        moves: tools.moves
        pgnInJson: tools.pgnInJson
        tags: tools.tags
        clocks: tools.clocks
        evals: tools.evals
        accuracy: tools.accuracy
        opening: tools.opening
        division: tools.division
        literate: tools.literate
        withBookmarked: tools.withBookmarked
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-gamechatget
      description: 'Fetch the spectator game chat'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: games.gamechatget
      with:
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-apiusercurrentgame
      description: 'Export ongoing game of a user'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: games.apiusercurrentgame
      with:
        username: tools.username
        moves: tools.moves
        pgnInJson: tools.pgnInJson
        tags: tools.tags
        clocks: tools.clocks
        evals: tools.evals
        accuracy: tools.accuracy
        opening: tools.opening
        division: tools.division
        literate: tools.literate
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-apigamesuser
      description: 'Export games of a user'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: games.apigamesuser
      with:
        username: tools.username
        since: tools.since
        until: tools.until
        max: tools.max
        vs: tools.vs
        rated: tools.rated
        perfType: tools.perfType
        color: tools.color
        analysed: tools.analysed
        moves: tools.moves
        pgnInJson: tools.pgnInJson
        tags: tools.tags
        clocks: tools.clocks
        evals: tools.evals
        accuracy: tools.accuracy
        opening: tools.opening
        division: tools.division
        ongoing: tools.ongoing
        finished: tools.finished
        literate: tools.literate
        lastFen: tools.lastFen
        withBookmarked: tools.withBookmarked
        sort: tools.sort
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-gamesexportids
      description: 'Export games by IDs'
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: games.gamesexportids
      with:
        moves: tools.moves
        pgnInJson: tools.pgnInJson
        tags: tools.tags
        clocks: tools.clocks
        evals: tools.evals
        accuracy: tools.accuracy
        opening: tools.opening
        division: tools.division
        literate: tools.literate
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-gamesbyusers
      description: 'Stream games of users'
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: games.gamesbyusers
      with:
        withCurrentGames: tools.withCurrentGames
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-gamesbyids
      description: 'Stream games by IDs'
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: games.gamesbyids
      with:
        streamId: tools.streamId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-gamesbyidsadd
      description: 'Add game IDs to stream'
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: games.gamesbyidsadd
      with:
        streamId: tools.streamId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-apiaccountplaying
      description: 'Get my ongoing games'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: games.apiaccountplaying
      with:
        nb: tools.nb
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-streamgame
      description: 'Stream moves of a game'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: games.streamgame
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-gameimport
      description: 'Import one game'
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: games.gameimport
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-apiimportedgamesuser
      description: 'Export your imported games'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: games.apiimportedgamesuser
      with:
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-apiexportbookmarks
      description: 'Export your bookmarked games'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: games.apiexportbookmarks
      with:
        since: tools.since
        until: tools.until
        max: tools.max
        moves: tools.moves
        pgnInJson: tools.pgnInJson
        tags: tools.tags
        clocks: tools.clocks
        evals: tools.evals
        accuracy: tools.accuracy
        opening: tools.opening
        division: tools.division
        literate: tools.literate
        lastFen: tools.lastFen
        sort: tools.sort
      outputParameters:
      - type: object
        mapping: $.