naftiko: 1.0.0-alpha2
info:
  label: Vitess Cluster Administration
  description: Workflow capability for administering Vitess database clusters via the VTAdmin API. Combines cluster topology
    inspection, tablet management, keyspace and schema administration, VReplication workflow monitoring, backup auditing,
    and VTGate management into a unified interface. Used by database administrators, site reliability engineers, and platform
    engineers managing large-scale MySQL deployments on Kubernetes.
  tags:
  - Backups
  - Cluster Management
  - Cloud Native
  - CNCF
  - Database
  - Distributed Systems
  - MySQL
  - Sharding
  - Vitess
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    VTADMIN_TOKEN: VTADMIN_TOKEN
    VTADMIN_HOST: VTADMIN_HOST
    VTADMIN_PORT: VTADMIN_PORT
capability:
  consumes:
  - type: http
    namespace: vitess-vtadmin
    baseUri: http://{{VTADMIN_HOST}}:{{VTADMIN_PORT}}/api
    description: Vitess VTAdmin REST API for cluster administration
    authentication:
      type: bearer
      token: '{{VTADMIN_TOKEN}}'
    resources:
    - name: clusters
      path: /clusters
      description: Vitess cluster listing
      operations:
      - name: get-clusters
        method: GET
        description: List all registered Vitess clusters
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: tablets
      path: /tablets
      description: VTTablet instance management
      operations:
      - name: get-tablets
        method: GET
        description: List all VTTablet instances
        inputParameters:
        - name: cluster_id
          in: query
          type: array
          required: false
          description: Filter by cluster IDs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: tablet
      path: /tablet/{tablet}
      description: Individual tablet operations
      operations:
      - name: get-tablet
        method: GET
        description: Get a specific tablet by alias
        inputParameters:
        - name: tablet
          in: path
          type: string
          required: true
          description: Tablet alias (cluster/cell-uid)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: keyspaces
      path: /keyspaces
      description: Keyspace listing
      operations:
      - name: get-keyspaces
        method: GET
        description: List all keyspaces
        inputParameters:
        - name: cluster_id
          in: query
          type: array
          required: false
          description: Filter by cluster IDs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: schemas
      path: /schemas
      description: Database schema listing
      operations:
      - name: get-schemas
        method: GET
        description: List all keyspace schemas
        inputParameters:
        - name: cluster_id
          in: query
          type: array
          required: false
          description: Filter by cluster IDs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: schema
      path: /schema/{cluster_id}/{keyspace}
      description: Per-keyspace schema
      operations:
      - name: get-schema
        method: GET
        description: Get schema for a specific keyspace
        inputParameters:
        - name: cluster_id
          in: path
          type: string
          required: true
          description: Cluster identifier
        - name: keyspace
          in: path
          type: string
          required: true
          description: Keyspace name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: workflows
      path: /workflows
      description: VReplication workflow listing
      operations:
      - name: get-workflows
        method: GET
        description: List all VReplication workflows
        inputParameters:
        - name: cluster_id
          in: query
          type: array
          required: false
          description: Filter by cluster IDs
        - name: active_only
          in: query
          type: boolean
          required: false
          description: Return only active workflows
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: backups
      path: /backups
      description: Tablet backup listing
      operations:
      - name: get-backups
        method: GET
        description: List all tablet backups
        inputParameters:
        - name: cluster_id
          in: query
          type: array
          required: false
          description: Filter by cluster IDs
        - name: keyspace
          in: query
          type: string
          required: false
          description: Filter by keyspace
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: cells
      path: /cells
      description: Cell listing
      operations:
      - name: get-cells
        method: GET
        description: List all cells (availability zones)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: gates
      path: /gates
      description: VTGate instance listing
      operations:
      - name: get-gates
        method: GET
        description: List all VTGate instances
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: topology
      path: /topology/{cluster_id}
      description: Cluster topology
      operations:
      - name: get-cluster-topology
        method: GET
        description: Get full cluster topology
        inputParameters:
        - name: cluster_id
          in: path
          type: string
          required: true
          description: Cluster identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: vitess-cluster-admin-api
    description: Unified REST API for Vitess cluster administration and observability.
    resources:
    - path: /v1/clusters
      name: clusters
      description: Registered Vitess clusters
      operations:
      - method: GET
        name: get-clusters
        description: List all registered Vitess clusters
        call: vitess-vtadmin.get-clusters
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/tablets
      name: tablets
      description: VTTablet instances
      operations:
      - method: GET
        name: get-tablets
        description: List all VTTablet instances with cluster and shard info
        call: vitess-vtadmin.get-tablets
        with:
          cluster_id: rest.cluster_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/tablets/{tablet}
      name: tablet
      description: Individual tablet details
      operations:
      - method: GET
        name: get-tablet
        description: Get details of a specific tablet by alias
        call: vitess-vtadmin.get-tablet
        with:
          tablet: rest.tablet
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/keyspaces
      name: keyspaces
      description: Vitess keyspaces (logical databases)
      operations:
      - method: GET
        name: get-keyspaces
        description: List all keyspaces across clusters
        call: vitess-vtadmin.get-keyspaces
        with:
          cluster_id: rest.cluster_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/schemas
      name: schemas
      description: Database schemas for all keyspaces
      operations:
      - method: GET
        name: get-schemas
        description: List all keyspace schemas
        call: vitess-vtadmin.get-schemas
        with:
          cluster_id: rest.cluster_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/schemas/{cluster_id}/{keyspace}
      name: schema
      description: Schema for a specific keyspace
      operations:
      - method: GET
        name: get-schema
        description: Get table definitions for a keyspace
        call: vitess-vtadmin.get-schema
        with:
          cluster_id: rest.cluster_id
          keyspace: rest.keyspace
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/workflows
      name: workflows
      description: VReplication workflows
      operations:
      - method: GET
        name: get-workflows
        description: List all VReplication workflows
        call: vitess-vtadmin.get-workflows
        with:
          cluster_id: rest.cluster_id
          active_only: rest.active_only
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/backups
      name: backups
      description: Tablet backup inventory
      operations:
      - method: GET
        name: get-backups
        description: List all tablet backups
        call: vitess-vtadmin.get-backups
        with:
          cluster_id: rest.cluster_id
          keyspace: rest.keyspace
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/cells
      name: cells
      description: Availability zones and data centers
      operations:
      - method: GET
        name: get-cells
        description: List all cells across clusters
        call: vitess-vtadmin.get-cells
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/gates
      name: gates
      description: VTGate proxy instances
      operations:
      - method: GET
        name: get-gates
        description: List all VTGate instances
        call: vitess-vtadmin.get-gates
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/topology/{cluster_id}
      name: topology
      description: Full cluster topology
      operations:
      - method: GET
        name: get-cluster-topology
        description: Get complete topology for a cluster
        call: vitess-vtadmin.get-cluster-topology
        with:
          cluster_id: rest.cluster_id
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: vitess-cluster-admin-mcp
    transport: http
    description: MCP server for AI-assisted Vitess cluster administration and troubleshooting.
    tools:
    - name: get-clusters
      description: List all registered Vitess clusters and their identifiers
      hints:
        readOnly: true
        idempotent: true
      call: vitess-vtadmin.get-clusters
      outputParameters:
      - type: object
        mapping: $.
    - name: get-tablets
      description: List all VTTablet instances with type (PRIMARY/REPLICA), shard, keyspace, and state
      hints:
        readOnly: true
        idempotent: true
      call: vitess-vtadmin.get-tablets
      with:
        cluster_id: tools.cluster_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-tablet
      description: Get detailed information about a specific tablet including health and replication status
      hints:
        readOnly: true
        idempotent: true
      call: vitess-vtadmin.get-tablet
      with:
        tablet: tools.tablet
      outputParameters:
      - type: object
        mapping: $.
    - name: get-keyspaces
      description: List all Vitess keyspaces (logical databases) and their sharding configuration
      hints:
        readOnly: true
        idempotent: true
      call: vitess-vtadmin.get-keyspaces
      with:
        cluster_id: tools.cluster_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-schemas
      description: List database schemas for all keyspaces across clusters
      hints:
        readOnly: true
        idempotent: true
      call: vitess-vtadmin.get-schemas
      with:
        cluster_id: tools.cluster_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-schema
      description: Get table definitions and index information for a specific keyspace
      hints:
        readOnly: true
        idempotent: true
      call: vitess-vtadmin.get-schema
      with:
        cluster_id: tools.cluster_id
        keyspace: tools.keyspace
      outputParameters:
      - type: object
        mapping: $.
    - name: get-workflows
      description: List VReplication workflows including MoveTables, Reshard, and Materialize operations
      hints:
        readOnly: true
        idempotent: true
      call: vitess-vtadmin.get-workflows
      with:
        cluster_id: tools.cluster_id
        active_only: tools.active_only
      outputParameters:
      - type: object
        mapping: $.
    - name: get-backups
      description: List all tablet backups to audit backup coverage and find latest backup per shard
      hints:
        readOnly: true
        idempotent: true
      call: vitess-vtadmin.get-backups
      with:
        cluster_id: tools.cluster_id
        keyspace: tools.keyspace
      outputParameters:
      - type: object
        mapping: $.
    - name: get-cells
      description: List all cells (availability zones and data center locations) across clusters
      hints:
        readOnly: true
        idempotent: true
      call: vitess-vtadmin.get-cells
      outputParameters:
      - type: object
        mapping: $.
    - name: get-gates
      description: List all VTGate proxy instances and their configured keyspaces
      hints:
        readOnly: true
        idempotent: true
      call: vitess-vtadmin.get-gates
      outputParameters:
      - type: object
        mapping: $.
    - name: get-cluster-topology
      description: Get the complete topology of a Vitess cluster including all keyspaces, shards, and tablets
      hints:
        readOnly: true
        idempotent: true
      call: vitess-vtadmin.get-cluster-topology
      with:
        cluster_id: tools.cluster_id
      outputParameters:
      - type: object
        mapping: $.