naftiko: 1.0.0-alpha2
info:
  label: Storyblok Content Management
  description: Unified capability for managing and delivering Storyblok headless CMS content. Combines the Content Delivery
    API for fetching published content and the Management API for creating, editing, and publishing content programmatically.
    Supports content migration, editorial automation, CI/CD pipelines, and headless site generation workflows.
  tags:
  - Assets
  - CMS
  - Components
  - Content Delivery
  - Content Management
  - Headless CMS
  - Stories
  - Webhooks
  created: '2026-05-02'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    STORYBLOK_CDN_TOKEN: STORYBLOK_CDN_TOKEN
    STORYBLOK_MANAGEMENT_TOKEN: STORYBLOK_MANAGEMENT_TOKEN
capability:
  consumes:
  - type: http
    namespace: storyblok-cdn
    baseUri: https://api.storyblok.com/v2/cdn
    description: Storyblok Content Delivery API v2
    authentication:
      type: apikey
      key: token
      value: '{{STORYBLOK_CDN_TOKEN}}'
      placement: query
    resources:
    - name: stories
      path: /stories
      description: Published story content
      operations:
      - name: list-stories
        method: GET
        description: List published stories with filtering and pagination
        inputParameters:
        - name: version
          in: query
          type: string
          required: false
          description: 'Content version: published or draft'
        - name: starts_with
          in: query
          type: string
          required: false
          description: Filter stories by slug prefix
        - name: per_page
          in: query
          type: integer
          required: false
          description: Results per page (max 200)
        - name: page
          in: query
          type: integer
          required: false
          description: Page number for pagination
        - name: sort_by
          in: query
          type: string
          required: false
          description: Field to sort by
        - name: search_term
          in: query
          type: string
          required: false
          description: Full-text search query
        - name: filter_query
          in: query
          type: string
          required: false
          description: Filter stories by component field values
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-story-by-slug
        method: GET
        description: Retrieve a single story by its full slug
        inputParameters:
        - name: slug
          in: path
          type: string
          required: true
          description: Full slug of the story
        - name: version
          in: query
          type: string
          required: false
          description: 'Content version: published or draft'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-story-by-id
        method: GET
        description: Retrieve a single story by its numeric ID
        inputParameters:
        - name: id
          in: path
          type: integer
          required: true
          description: Numeric story ID
        - name: version
          in: query
          type: string
          required: false
          description: Content version
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: datasources
      path: /datasources
      description: Reusable key-value datasources
      operations:
      - name: list-datasources
        method: GET
        description: List datasources in the space
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: list-datasource-entries
        method: GET
        description: List entries from a datasource
        inputParameters:
        - name: datasource
          in: query
          type: string
          required: false
          description: Datasource slug to filter entries
        - name: dimension
          in: query
          type: string
          required: false
          description: Dimension (locale) for entries
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: links
      path: /links
      description: Story URL tree for navigation
      operations:
      - name: list-links
        method: GET
        description: List all story links for sitemap or navigation
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: tags
      path: /tags
      description: Story tags
      operations:
      - name: list-tags
        method: GET
        description: List all tags used in stories
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: storyblok-mapi
    baseUri: https://mapi.storyblok.com/v1
    description: Storyblok Management API
    authentication:
      type: bearer
      token: '{{STORYBLOK_MANAGEMENT_TOKEN}}'
    resources:
    - name: spaces
      path: /spaces/{space_id}
      description: Space configuration and metadata
      operations:
      - name: get-space
        method: GET
        description: Retrieve space details and configuration
        inputParameters:
        - name: space_id
          in: path
          type: integer
          required: true
          description: Numeric space identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: stories
      path: /spaces/{space_id}/stories
      description: Story CRUD operations
      operations:
      - name: list-management-stories
        method: GET
        description: List stories in a space with pagination
        inputParameters:
        - name: space_id
          in: path
          type: integer
          required: true
          description: Space identifier
        - name: per_page
          in: query
          type: integer
          required: false
          description: Results per page
        - name: page
          in: query
          type: integer
          required: false
          description: Page number
        - name: text_search
          in: query
          type: string
          required: false
          description: Search query
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: create-story
        method: POST
        description: Create a new story in the space
        inputParameters:
        - name: space_id
          in: path
          type: integer
          required: true
          description: Space identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            story: '{{tools.story}}'
      - name: get-story
        method: GET
        description: Retrieve a story by ID
        inputParameters:
        - name: space_id
          in: path
          type: integer
          required: true
          description: Space identifier
        - name: story_id
          in: path
          type: integer
          required: true
          description: Story identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: update-story
        method: PUT
        description: Update an existing story
        inputParameters:
        - name: space_id
          in: path
          type: integer
          required: true
          description: Space identifier
        - name: story_id
          in: path
          type: integer
          required: true
          description: Story identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            story: '{{tools.story}}'
      - name: delete-story
        method: DELETE
        description: Delete a story
        inputParameters:
        - name: space_id
          in: path
          type: integer
          required: true
          description: Space identifier
        - name: story_id
          in: path
          type: integer
          required: true
          description: Story identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: publish-story
        method: GET
        description: Publish a story
        inputParameters:
        - name: space_id
          in: path
          type: integer
          required: true
          description: Space identifier
        - name: story_id
          in: path
          type: integer
          required: true
          description: Story identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: unpublish-story
        method: GET
        description: Unpublish a story
        inputParameters:
        - name: space_id
          in: path
          type: integer
          required: true
          description: Space identifier
        - name: story_id
          in: path
          type: integer
          required: true
          description: Story identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: components
      path: /spaces/{space_id}/components
      description: Component schema management
      operations:
      - name: list-components
        method: GET
        description: List component definitions in a space
        inputParameters:
        - name: space_id
          in: path
          type: integer
          required: true
          description: Space identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-component
        method: GET
        description: Retrieve a component definition by ID
        inputParameters:
        - name: space_id
          in: path
          type: integer
          required: true
          description: Space identifier
        - name: component_id
          in: path
          type: integer
          required: true
          description: Component identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: assets
      path: /spaces/{space_id}/assets
      description: Asset library management
      operations:
      - name: list-assets
        method: GET
        description: List assets in the space library
        inputParameters:
        - name: space_id
          in: path
          type: integer
          required: true
          description: Space identifier
        - name: per_page
          in: query
          type: integer
          required: false
          description: Results per page
        - name: page
          in: query
          type: integer
          required: false
          description: Page number
        - name: search
          in: query
          type: string
          required: false
          description: Search query
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: webhooks
      path: /spaces/{space_id}/webhook_endpoints
      description: Webhook endpoint management
      operations:
      - name: list-webhooks
        method: GET
        description: List webhook endpoints configured in the space
        inputParameters:
        - name: space_id
          in: path
          type: integer
          required: true
          description: Space identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: create-webhook
        method: POST
        description: Create a new webhook endpoint
        inputParameters:
        - name: space_id
          in: path
          type: integer
          required: true
          description: Space identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            webhook_endpoint: '{{tools.webhook_endpoint}}'
      - name: delete-webhook
        method: DELETE
        description: Delete a webhook endpoint
        inputParameters:
        - name: space_id
          in: path
          type: integer
          required: true
          description: Space identifier
        - name: webhook_id
          in: path
          type: integer
          required: true
          description: Webhook identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: storyblok-content-api
    description: Unified REST API for Storyblok content management and delivery.
    resources:
    - path: /v1/stories
      name: stories
      description: Content story operations
      operations:
      - method: GET
        name: list-stories
        description: List published stories (delivery)
        call: storyblok-cdn.list-stories
        with:
          version: rest.version
          starts_with: rest.starts_with
          per_page: rest.per_page
          page: rest.page
          search_term: rest.search_term
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/stories/{slug}
      name: story-by-slug
      operations:
      - method: GET
        name: get-story
        description: Get a story by full slug (delivery)
        call: storyblok-cdn.get-story-by-slug
        with:
          slug: rest.slug
          version: rest.version
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/manage/spaces/{space-id}/stories
      name: manage-stories
      description: Management story operations
      operations:
      - method: GET
        name: list-manage-stories
        description: List stories via management API
        call: storyblok-mapi.list-management-stories
        with:
          space_id: rest.space-id
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: create-story
        description: Create a new story
        call: storyblok-mapi.create-story
        with:
          space_id: rest.space-id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/manage/spaces/{space-id}/stories/{story-id}/publish
      name: publish-story
      operations:
      - method: POST
        name: publish-story
        description: Publish a story
        call: storyblok-mapi.publish-story
        with:
          space_id: rest.space-id
          story_id: rest.story-id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/manage/spaces/{space-id}/components
      name: components
      operations:
      - method: GET
        name: list-components
        description: List component schemas
        call: storyblok-mapi.list-components
        with:
          space_id: rest.space-id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/manage/spaces/{space-id}/assets
      name: assets
      operations:
      - method: GET
        name: list-assets
        description: List media assets
        call: storyblok-mapi.list-assets
        with:
          space_id: rest.space-id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/links
      name: links
      operations:
      - method: GET
        name: list-links
        description: Get story link tree for navigation
        call: storyblok-cdn.list-links
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/datasources
      name: datasources
      operations:
      - method: GET
        name: list-datasources
        description: List datasources
        call: storyblok-cdn.list-datasources
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: storyblok-content-mcp
    transport: http
    description: MCP server for AI-assisted Storyblok content management.
    tools:
    - name: cdn-list-stories
      description: List published stories from the Content Delivery API with filtering by slug prefix, full-text search, and
        pagination support.
      hints:
        readOnly: true
        openWorld: false
      call: storyblok-cdn.list-stories
      with:
        version: tools.version
        starts_with: tools.starts_with
        per_page: tools.per_page
        page: tools.page
        search_term: tools.search_term
      outputParameters:
      - type: object
        mapping: $.
    - name: cdn-get-story
      description: Retrieve a specific published story by its full URL slug
      hints:
        readOnly: true
        openWorld: false
      call: storyblok-cdn.get-story-by-slug
      with:
        slug: tools.slug
        version: tools.version
      outputParameters:
      - type: object
        mapping: $.
    - name: cdn-list-links
      description: Get the story URL tree for building navigation menus or sitemaps
      hints:
        readOnly: true
        openWorld: false
      call: storyblok-cdn.list-links
      outputParameters:
      - type: object
        mapping: $.
    - name: cdn-list-datasource-entries
      description: Fetch options, translations, or config data from a datasource
      hints:
        readOnly: true
        openWorld: false
      call: storyblok-cdn.list-datasource-entries
      with:
        datasource: tools.datasource
        dimension: tools.dimension
      outputParameters:
      - type: object
        mapping: $.
    - name: mapi-list-stories
      description: List all stories including drafts via management API
      hints:
        readOnly: true
        openWorld: false
      call: storyblok-mapi.list-management-stories
      with:
        space_id: tools.space_id
        per_page: tools.per_page
        page: tools.page
        text_search: tools.text_search
      outputParameters:
      - type: object
        mapping: $.
    - name: mapi-create-story
      description: Create a new story in a Storyblok space
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: storyblok-mapi.create-story
      with:
        space_id: tools.space_id
      outputParameters:
      - type: object
        mapping: $.
    - name: mapi-update-story
      description: Update the content or metadata of an existing story
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: storyblok-mapi.update-story
      with:
        space_id: tools.space_id
        story_id: tools.story_id
      outputParameters:
      - type: object
        mapping: $.
    - name: mapi-publish-story
      description: Publish a story to make it live on the Content Delivery API
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: storyblok-mapi.publish-story
      with:
        space_id: tools.space_id
        story_id: tools.story_id
      outputParameters:
      - type: object
        mapping: $.
    - name: mapi-delete-story
      description: Permanently delete a story from the space
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: storyblok-mapi.delete-story
      with:
        space_id: tools.space_id
        story_id: tools.story_id
      outputParameters:
      - type: object
        mapping: $.
    - name: mapi-list-components
      description: List component schemas to understand content structure
      hints:
        readOnly: true
        openWorld: false
      call: storyblok-mapi.list-components
      with:
        space_id: tools.space_id
      outputParameters:
      - type: object
        mapping: $.
    - name: mapi-list-assets
      description: List media assets in the space asset library
      hints:
        readOnly: true
        openWorld: false
      call: storyblok-mapi.list-assets
      with:
        space_id: tools.space_id
        search: tools.search
      outputParameters:
      - type: object
        mapping: $.
    - name: mapi-list-webhooks
      description: List webhook endpoints configured in the space
      hints:
        readOnly: true
        openWorld: false
      call: storyblok-mapi.list-webhooks
      with:
        space_id: tools.space_id
      outputParameters:
      - type: object
        mapping: $.