Wordnik — Word List

naftiko: "1.0.0-alpha2"

info:
  label: "Wordnik — Word List"
  description: >-
    Word List — single-user-word-list management surface. 6 operations covering reading,
    updating, and deleting a word list by permalink, plus listing, adding, and removing
    words inside it. Lead operation: return a word list by permalink. Self-contained
    Naftiko capability covering one Wordnik business surface.
  tags:
    - Wordnik
    - Dictionary
    - Word List
  created: "2026-05-29"
  modified: "2026-05-29"

binds:
  - namespace: env
    keys:
      WORDNIK_API_KEY: WORDNIK_API_KEY
      WORDNIK_AUTH_TOKEN: WORDNIK_AUTH_TOKEN

capability:

  consumes:
    - type: http
      namespace: "wordnik-word-list"
      baseUri: "https://api.wordnik.com/v4"
      description: "Wordnik — Word List business capability. Self-contained, no shared references."
      authentication:
        type: apikey
        key: api_key
        value: "{{env.WORDNIK_API_KEY}}"
        placement: query
      resources:
        - name: "word-list"
          path: "/wordList.json/{permalink}"
          operations:
            - name: "getWordListByPermalink"
              method: GET
              description: "Return a word list by permalink."
              inputParameters:
                - { name: permalink, in: path, type: string, required: true, description: "Permalink of the word list." }
                - { name: auth_token, in: header, type: string, required: true, description: "Valid user auth token." }
              outputRawFormat: json
              outputParameters:
                - { name: result, type: object, value: "$." }
            - name: "updateWordList"
              method: PUT
              description: "Update a word list."
              inputParameters:
                - { name: permalink, in: path, type: string, required: true, description: "Permalink of the word list." }
                - { name: auth_token, in: header, type: string, required: true, description: "Valid user auth token." }
                - { name: body, in: body, type: object, required: true, description: "WordList payload." }
              outputRawFormat: json
              outputParameters:
                - { name: result, type: object, value: "$." }
            - name: "deleteWordList"
              method: DELETE
              description: "Delete a word list."
              inputParameters:
                - { name: permalink, in: path, type: string, required: true, description: "Permalink of the word list." }
                - { name: auth_token, in: header, type: string, required: true, description: "Valid user auth token." }
              outputRawFormat: json
              outputParameters:
                - { name: result, type: object, value: "$." }
            - name: "getWordListWords"
              method: GET
              description: "Return words in a word list."
              inputParameters:
                - { name: permalink, in: path, type: string, required: true, description: "Permalink of the word list." }
                - { name: auth_token, in: header, type: string, required: true, description: "Valid user auth token." }
                - { name: sortBy, in: query, type: string, required: false, description: "Attribute to sort by." }
                - { name: sortOrder, in: query, type: string, required: false, description: "Sort direction." }
                - { name: skip, in: query, type: integer, required: false, description: "Results to skip." }
                - { name: limit, in: query, type: integer, required: false, description: "Maximum number of results to return." }
              outputRawFormat: json
              outputParameters:
                - { name: result, type: object, value: "$." }
            - name: "addWordsToWordList"
              method: POST
              description: "Add words to a word list."
              inputParameters:
                - { name: permalink, in: path, type: string, required: true, description: "Permalink of the word list." }
                - { name: auth_token, in: header, type: string, required: true, description: "Valid user auth token." }
                - { name: body, in: body, type: array, required: true, description: "Array of StringValue payloads." }
              outputRawFormat: json
              outputParameters:
                - { name: result, type: object, value: "$." }
            - name: "deleteWordsFromWordList"
              method: POST
              description: "Delete words from a word list."
              inputParameters:
                - { name: permalink, in: path, type: string, required: true, description: "Permalink of the word list." }
                - { name: auth_token, in: header, type: string, required: true, description: "Valid user auth token." }
                - { name: body, in: body, type: array, required: true, description: "Array of StringValue payloads to remove." }
              outputRawFormat: json
              outputParameters:
                - { name: result, type: object, value: "$." }

  exposes:
    - type: rest
      namespace: "wordnik-word-list-rest"
      port: 8080
      description: "REST adapter for Wordnik — Word List. One Spectral-compliant resource per consumed operation, prefixed with /v1."
      resources:
        - path: "/v1/word-lists/{permalink}"
          name: "word-list"
          description: "REST surface for a single word list."
          operations:
            - method: GET
              name: "getWordListByPermalink"
              description: "Return a word list by permalink."
              call: "wordnik-word-list.getWordListByPermalink"
              with:
                permalink: "rest.permalink"
                auth_token: "rest.auth_token"
              outputParameters:
                - { type: object, mapping: "$." }
            - method: PUT
              name: "updateWordList"
              description: "Update a word list."
              call: "wordnik-word-list.updateWordList"
              with:
                permalink: "rest.permalink"
                auth_token: "rest.auth_token"
                body: "rest.body"
              outputParameters:
                - { type: object, mapping: "$." }
            - method: DELETE
              name: "deleteWordList"
              description: "Delete a word list."
              call: "wordnik-word-list.deleteWordList"
              with:
                permalink: "rest.permalink"
                auth_token: "rest.auth_token"
              outputParameters:
                - { type: object, mapping: "$." }
        - path: "/v1/word-lists/{permalink}/words"
          name: "word-list-words"
          description: "REST surface for words inside a list."
          operations:
            - method: GET
              name: "getWordListWords"
              description: "Return words in a word list."
              call: "wordnik-word-list.getWordListWords"
              with:
                permalink: "rest.permalink"
                auth_token: "rest.auth_token"
                sortBy: "rest.sortBy"
                sortOrder: "rest.sortOrder"
                skip: "rest.skip"
                limit: "rest.limit"
              outputParameters:
                - { type: object, mapping: "$." }
            - method: POST
              name: "addWordsToWordList"
              description: "Add words to a word list."
              call: "wordnik-word-list.addWordsToWordList"
              with:
                permalink: "rest.permalink"
                auth_token: "rest.auth_token"
                body: "rest.body"
              outputParameters:
                - { type: object, mapping: "$." }
        - path: "/v1/word-lists/{permalink}/delete-words"
          name: "word-list-delete-words"
          description: "REST surface for removing words from a list."
          operations:
            - method: POST
              name: "deleteWordsFromWordList"
              description: "Delete words from a word list."
              call: "wordnik-word-list.deleteWordsFromWordList"
              with:
                permalink: "rest.permalink"
                auth_token: "rest.auth_token"
                body: "rest.body"
              outputParameters:
                - { type: object, mapping: "$." }

    - type: mcp
      namespace: "wordnik-word-list-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for Wordnik — Word List. One tool per consumed operation, routed inline through this capability's consumes block."
      tools:
        - name: "get-word-list"
          description: "Return a word list by permalink."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "wordnik-word-list.getWordListByPermalink"
          with:
            permalink: "tools.permalink"
            auth_token: "tools.auth_token"
          outputParameters:
            - { type: object, mapping: "$." }
        - name: "update-word-list"
          description: "Update a word list."
          hints: { readOnly: false, destructive: false, idempotent: true }
          call: "wordnik-word-list.updateWordList"
          with:
            permalink: "tools.permalink"
            auth_token: "tools.auth_token"
            body: "tools.body"
          outputParameters:
            - { type: object, mapping: "$." }
        - name: "delete-word-list"
          description: "Delete a word list."
          hints: { readOnly: false, destructive: true, idempotent: true }
          call: "wordnik-word-list.deleteWordList"
          with:
            permalink: "tools.permalink"
            auth_token: "tools.auth_token"
          outputParameters:
            - { type: object, mapping: "$." }
        - name: "list-word-list-words"
          description: "Return words in a word list."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "wordnik-word-list.getWordListWords"
          with:
            permalink: "tools.permalink"
            auth_token: "tools.auth_token"
            sortBy: "tools.sortBy"
            sortOrder: "tools.sortOrder"
            skip: "tools.skip"
            limit: "tools.limit"
          outputParameters:
            - { type: object, mapping: "$." }
        - name: "add-words-to-word-list"
          description: "Add words to a word list."
          hints: { readOnly: false, destructive: false, idempotent: false }
          call: "wordnik-word-list.addWordsToWordList"
          with:
            permalink: "tools.permalink"
            auth_token: "tools.auth_token"
            body: "tools.body"
          outputParameters:
            - { type: object, mapping: "$." }
        - name: "delete-words-from-word-list"
          description: "Delete words from a word list."
          hints: { readOnly: false, destructive: true, idempotent: false }
          call: "wordnik-word-list.deleteWordsFromWordList"
          with:
            permalink: "tools.permalink"
            auth_token: "tools.auth_token"
            body: "tools.body"
          outputParameters:
            - { type: object, mapping: "$." }