Sanity Content Management

naftiko: "1.0.0-alpha1"

info:
  label: "Sanity Content Management"
  description: >-
    Unified capability combining Sanity's Content API and Projects API for
    full content lifecycle management. Used by developers, content engineers,
    and editorial teams to query, create, update, and manage content in
    Sanity Content Lake, as well as manage projects, datasets, and webhooks.
  tags:
    - Content Management
    - Headless CMS
    - GROQ
    - Project Administration
    - Sanity
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      SANITY_API_TOKEN: SANITY_API_TOKEN
      SANITY_PROJECT_ID: SANITY_PROJECT_ID

capability:
  consumes:
    - import: sanity-content
      location: ./shared/sanity-content.yaml
    - import: sanity-projects
      location: ./shared/sanity-projects.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: sanity-content-management-api
      description: "Unified REST API for Sanity content and project management."
      resources:
        - path: /v1/content/query
          name: content-query
          description: "Query Content Lake documents using GROQ"
          operations:
            - method: POST
              name: query-documents
              description: "Execute a GROQ query against a dataset"
              call: "sanity-content.query-documents-post"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/content/mutate
          name: content-mutate
          description: "Write operations on Content Lake documents"
          operations:
            - method: POST
              name: mutate-documents
              description: "Apply create, update, patch, or delete mutations"
              call: "sanity-content.mutate-documents"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/projects
          name: projects
          description: "Sanity project management"
          operations:
            - method: GET
              name: list-projects
              description: "List all accessible Sanity projects"
              call: "sanity-projects.list-projects"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/projects/{projectId}/datasets
          name: datasets
          description: "Dataset management for a project"
          operations:
            - method: GET
              name: list-datasets
              description: "List datasets in a project"
              call: "sanity-projects.list-datasets"
              with:
                projectId: "rest.projectId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/projects/{projectId}/tokens
          name: tokens
          description: "API token management"
          operations:
            - method: GET
              name: list-tokens
              description: "List API tokens for a project"
              call: "sanity-projects.list-tokens"
              with:
                projectId: "rest.projectId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/projects/{projectId}/webhooks
          name: webhooks
          description: "Webhook configuration for content events"
          operations:
            - method: GET
              name: list-webhooks
              description: "List webhooks for a project"
              call: "sanity-projects.list-webhooks"
              with:
                projectId: "rest.projectId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-webhook
              description: "Create a new webhook"
              call: "sanity-projects.create-webhook"
              with:
                projectId: "rest.projectId"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: sanity-content-management-mcp
      transport: http
      description: "MCP server for AI-assisted Sanity content management and querying."
      tools:
        - name: query-content
          description: "Query Sanity Content Lake documents using GROQ syntax"
          hints:
            readOnly: true
            openWorld: false
          call: "sanity-content.query-documents-post"
          with:
            query: "tools.query"
          outputParameters:
            - type: object
              mapping: "$."

        - name: create-document
          description: "Create a new document in Sanity Content Lake"
          hints:
            readOnly: false
            destructive: false
          call: "sanity-content.mutate-documents"
          outputParameters:
            - type: object
              mapping: "$."

        - name: update-document
          description: "Update an existing document in Sanity Content Lake"
          hints:
            readOnly: false
            idempotent: false
          call: "sanity-content.mutate-documents"
          outputParameters:
            - type: object
              mapping: "$."

        - name: delete-document
          description: "Delete a document from Sanity Content Lake"
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "sanity-content.mutate-documents"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-projects
          description: "List all Sanity projects accessible with the current token"
          hints:
            readOnly: true
            openWorld: false
          call: "sanity-projects.list-projects"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-datasets
          description: "List datasets in a Sanity project"
          hints:
            readOnly: true
            openWorld: false
          call: "sanity-projects.list-datasets"
          with:
            projectId: "tools.projectId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: create-webhook
          description: "Configure a webhook to receive Sanity content change notifications"
          hints:
            readOnly: false
          call: "sanity-projects.create-webhook"
          outputParameters:
            - type: object
              mapping: "$."