Lichess API — Opening Explorer

naftiko: 1.0.0-alpha2
info:
  label: Lichess API — Opening Explorer
  description: 'Lichess API — Opening Explorer. 4 operations. Lead operation: Masters database. Self-contained Naftiko capability covering one Lichess business surface.'
  tags:
  - Lichess
  - Opening Explorer
  created: '2026-05-25'
  modified: '2026-05-25'
binds:
- namespace: env
  keys:
    LICHESS_API_TOKEN: LICHESS_API_TOKEN
capability:
  consumes:
  - type: http
    namespace: opening-explorer
    baseUri: https://lichess.org
    description: Lichess Opening Explorer business capability. Self-contained, no shared references.
    resources:
    - name: masters
      path: /masters
      operations:
      - name: openingexplorermaster
        method: GET
        description: 'Masters database'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: fen
          in: query
          type: string
          required: false
        - name: play
          in: query
          type: string
          required: false
        - name: since
          in: query
          type: string
          required: false
        - name: until
          in: query
          type: string
          required: false
        - name: moves
          in: query
          type: string
          required: false
        - name: topGames
          in: query
          type: string
          required: false
    - name: lichess
      path: /lichess
      operations:
      - name: openingexplorerlichess
        method: GET
        description: 'Lichess games'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: variant
          in: query
          type: string
          required: false
        - name: fen
          in: query
          type: string
          required: false
        - name: play
          in: query
          type: string
          required: false
        - name: speeds
          in: query
          type: string
          required: false
        - name: ratings
          in: query
          type: string
          required: false
        - name: since
          in: query
          type: string
          required: false
        - name: until
          in: query
          type: string
          required: false
        - name: moves
          in: query
          type: string
          required: false
        - name: topGames
          in: query
          type: string
          required: false
        - name: recentGames
          in: query
          type: string
          required: false
        - name: history
          in: query
          type: string
          required: false
    - name: player
      path: /player
      operations:
      - name: openingexplorerplayer
        method: GET
        description: 'Player games'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: player
          in: query
          type: string
          required: false
        - name: color
          in: query
          type: string
          required: false
        - name: variant
          in: query
          type: string
          required: false
        - name: fen
          in: query
          type: string
          required: false
        - name: play
          in: query
          type: string
          required: false
        - name: speeds
          in: query
          type: string
          required: false
        - name: modes
          in: query
          type: string
          required: false
        - name: since
          in: query
          type: string
          required: false
        - name: until
          in: query
          type: string
          required: false
        - name: moves
          in: query
          type: string
          required: false
        - name: recentGames
          in: query
          type: string
          required: false
    - name: masters-pgn-gameid
      path: /masters/pgn/{gameId}
      operations:
      - name: openingexplorermastergame
        method: GET
        description: 'OTB master game'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: gameId
          in: path
          type: string
          required: true
    authentication:
      type: bearer
      value: '{{env.LICHESS_API_TOKEN}}'
      placement: header
  exposes:
  - type: rest
    namespace: opening-explorer-rest
    port: 8080
    description: REST adapter for Lichess Opening Explorer. One Spectral-compliant resource per consumed operation.
    resources:
    - path: /v1/masters
      name: masters
      description: REST surface for masters.
      operations:
      - method: GET
        name: openingexplorermaster
        description: 'Masters database'
        call: opening-explorer.openingexplorermaster
        with:
          fen: rest.query.fen
          play: rest.query.play
          since: rest.query.since
          until: rest.query.until
          moves: rest.query.moves
          topGames: rest.query.topGames
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/lichess
      name: lichess
      description: REST surface for lichess.
      operations:
      - method: GET
        name: openingexplorerlichess
        description: 'Lichess games'
        call: opening-explorer.openingexplorerlichess
        with:
          variant: rest.query.variant
          fen: rest.query.fen
          play: rest.query.play
          speeds: rest.query.speeds
          ratings: rest.query.ratings
          since: rest.query.since
          until: rest.query.until
          moves: rest.query.moves
          topGames: rest.query.topGames
          recentGames: rest.query.recentGames
          history: rest.query.history
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/player
      name: player
      description: REST surface for player.
      operations:
      - method: GET
        name: openingexplorerplayer
        description: 'Player games'
        call: opening-explorer.openingexplorerplayer
        with:
          player: rest.query.player
          color: rest.query.color
          variant: rest.query.variant
          fen: rest.query.fen
          play: rest.query.play
          speeds: rest.query.speeds
          modes: rest.query.modes
          since: rest.query.since
          until: rest.query.until
          moves: rest.query.moves
          recentGames: rest.query.recentGames
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/masters/pgn/{gameId}
      name: masters-pgn-gameid
      description: REST surface for masters-pgn-gameid.
      operations:
      - method: GET
        name: openingexplorermastergame
        description: 'OTB master game'
        call: opening-explorer.openingexplorermastergame
        with:
          gameId: rest.path.gameId
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: opening-explorer-mcp
    port: 9090
    transport: http
    description: MCP adapter for Lichess Opening Explorer. One tool per consumed operation.
    tools:
    - name: lichess-openingexplorermaster
      description: 'Masters database'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: opening-explorer.openingexplorermaster
      with:
        fen: tools.fen
        play: tools.play
        since: tools.since
        until: tools.until
        moves: tools.moves
        topGames: tools.topGames
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-openingexplorerlichess
      description: 'Lichess games'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: opening-explorer.openingexplorerlichess
      with:
        variant: tools.variant
        fen: tools.fen
        play: tools.play
        speeds: tools.speeds
        ratings: tools.ratings
        since: tools.since
        until: tools.until
        moves: tools.moves
        topGames: tools.topGames
        recentGames: tools.recentGames
        history: tools.history
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-openingexplorerplayer
      description: 'Player games'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: opening-explorer.openingexplorerplayer
      with:
        player: tools.player
        color: tools.color
        variant: tools.variant
        fen: tools.fen
        play: tools.play
        speeds: tools.speeds
        modes: tools.modes
        since: tools.since
        until: tools.until
        moves: tools.moves
        recentGames: tools.recentGames
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-openingexplorermastergame
      description: 'OTB master game'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: opening-explorer.openingexplorermastergame
      with:
        gameId: tools.gameId
      outputParameters:
      - type: object
        mapping: $.