Storyblok Content Management

naftiko: "1.0.0-alpha1"

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-02"

binds:
  - namespace: env
    keys:
      STORYBLOK_CDN_TOKEN: STORYBLOK_CDN_TOKEN
      STORYBLOK_MANAGEMENT_TOKEN: STORYBLOK_MANAGEMENT_TOKEN

capability:
  consumes:
    - import: storyblok-cdn
      location: ./shared/content-delivery.yaml
    - import: storyblok-mapi
      location: ./shared/management.yaml

  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: "$."