Marvel Comics API

naftiko: 1.0.0-alpha2
info:
  label: Marvel Comics API
  description: The Marvel Comics API allows developers to access information about Marvel's extensive catalog of characters,
    comics, creators, events, series, and stories. All requests must be authenticated using a public key, timestamp, and MD5
    hash of the timestamp + private key + public key, supplied as query parameters.
  tags:
  - Marvel
  - API
  created: '2026-05-06'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: marvel
    baseUri: https://gateway.marvel.com/v1/public
    description: Marvel Comics API HTTP API.
    authentication:
      type: apikey
      in: query
      name: apikey
      value: '{{MARVEL_TOKEN}}'
    resources:
    - name: characters
      path: /characters
      operations:
      - name: listcharacters
        method: GET
        description: List characters
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: characters-characterid
      path: /characters/{characterId}
      operations:
      - name: getcharacter
        method: GET
        description: Get character by ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: characters-characterid-comics
      path: /characters/{characterId}/comics
      operations:
      - name: listcharactercomics
        method: GET
        description: List comics for a character
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: comics
      path: /comics
      operations:
      - name: listcomics
        method: GET
        description: List comics
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: comics-comicid
      path: /comics/{comicId}
      operations:
      - name: getcomic
        method: GET
        description: Get comic by ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: creators
      path: /creators
      operations:
      - name: listcreators
        method: GET
        description: List creators
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: creators-creatorid
      path: /creators/{creatorId}
      operations:
      - name: getcreator
        method: GET
        description: Get creator by ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: events
      path: /events
      operations:
      - name: listevents
        method: GET
        description: List events
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: events-eventid
      path: /events/{eventId}
      operations:
      - name: getevent
        method: GET
        description: Get event by ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: series
      path: /series
      operations:
      - name: listseries
        method: GET
        description: List series
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: series-seriesid
      path: /series/{seriesId}
      operations:
      - name: getseries
        method: GET
        description: Get series by ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: stories
      path: /stories
      operations:
      - name: liststories
        method: GET
        description: List stories
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: stories-storyid
      path: /stories/{storyId}
      operations:
      - name: getstory
        method: GET
        description: Get story by ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: marvel-rest
    description: REST adapter for Marvel Comics API.
    resources:
    - path: /characters
      name: listcharacters
      operations:
      - method: GET
        name: listcharacters
        description: List characters
        call: marvel.listcharacters
        outputParameters:
        - type: object
          mapping: $.
    - path: /characters/{characterId}
      name: getcharacter
      operations:
      - method: GET
        name: getcharacter
        description: Get character by ID
        call: marvel.getcharacter
        outputParameters:
        - type: object
          mapping: $.
    - path: /characters/{characterId}/comics
      name: listcharactercomics
      operations:
      - method: GET
        name: listcharactercomics
        description: List comics for a character
        call: marvel.listcharactercomics
        outputParameters:
        - type: object
          mapping: $.
    - path: /comics
      name: listcomics
      operations:
      - method: GET
        name: listcomics
        description: List comics
        call: marvel.listcomics
        outputParameters:
        - type: object
          mapping: $.
    - path: /comics/{comicId}
      name: getcomic
      operations:
      - method: GET
        name: getcomic
        description: Get comic by ID
        call: marvel.getcomic
        outputParameters:
        - type: object
          mapping: $.
    - path: /creators
      name: listcreators
      operations:
      - method: GET
        name: listcreators
        description: List creators
        call: marvel.listcreators
        outputParameters:
        - type: object
          mapping: $.
    - path: /creators/{creatorId}
      name: getcreator
      operations:
      - method: GET
        name: getcreator
        description: Get creator by ID
        call: marvel.getcreator
        outputParameters:
        - type: object
          mapping: $.
    - path: /events
      name: listevents
      operations:
      - method: GET
        name: listevents
        description: List events
        call: marvel.listevents
        outputParameters:
        - type: object
          mapping: $.
    - path: /events/{eventId}
      name: getevent
      operations:
      - method: GET
        name: getevent
        description: Get event by ID
        call: marvel.getevent
        outputParameters:
        - type: object
          mapping: $.
    - path: /series
      name: listseries
      operations:
      - method: GET
        name: listseries
        description: List series
        call: marvel.listseries
        outputParameters:
        - type: object
          mapping: $.
    - path: /series/{seriesId}
      name: getseries
      operations:
      - method: GET
        name: getseries
        description: Get series by ID
        call: marvel.getseries
        outputParameters:
        - type: object
          mapping: $.
    - path: /stories
      name: liststories
      operations:
      - method: GET
        name: liststories
        description: List stories
        call: marvel.liststories
        outputParameters:
        - type: object
          mapping: $.
    - path: /stories/{storyId}
      name: getstory
      operations:
      - method: GET
        name: getstory
        description: Get story by ID
        call: marvel.getstory
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: marvel-mcp
    transport: http
    description: MCP adapter for Marvel Comics API for AI agent use.
    tools:
    - name: listcharacters
      description: List characters
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: marvel.listcharacters
      outputParameters:
      - type: object
        mapping: $.
    - name: getcharacter
      description: Get character by ID
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: marvel.getcharacter
      outputParameters:
      - type: object
        mapping: $.
    - name: listcharactercomics
      description: List comics for a character
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: marvel.listcharactercomics
      outputParameters:
      - type: object
        mapping: $.
    - name: listcomics
      description: List comics
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: marvel.listcomics
      outputParameters:
      - type: object
        mapping: $.
    - name: getcomic
      description: Get comic by ID
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: marvel.getcomic
      outputParameters:
      - type: object
        mapping: $.
    - name: listcreators
      description: List creators
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: marvel.listcreators
      outputParameters:
      - type: object
        mapping: $.
    - name: getcreator
      description: Get creator by ID
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: marvel.getcreator
      outputParameters:
      - type: object
        mapping: $.
    - name: listevents
      description: List events
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: marvel.listevents
      outputParameters:
      - type: object
        mapping: $.
    - name: getevent
      description: Get event by ID
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: marvel.getevent
      outputParameters:
      - type: object
        mapping: $.
    - name: listseries
      description: List series
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: marvel.listseries
      outputParameters:
      - type: object
        mapping: $.
    - name: getseries
      description: Get series by ID
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: marvel.getseries
      outputParameters:
      - type: object
        mapping: $.
    - name: liststories
      description: List stories
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: marvel.liststories
      outputParameters:
      - type: object
        mapping: $.
    - name: getstory
      description: Get story by ID
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: marvel.getstory
      outputParameters:
      - type: object
        mapping: $.
binds:
- namespace: env
  keys:
    MARVEL_TOKEN: MARVEL_TOKEN