Tinybird Real-Time Analytics

naftiko: "1.0.0-alpha1"

info:
  label: "Tinybird Real-Time Analytics"
  description: >-
    Workflow capability for real-time data analytics using Tinybird. Combines data
    ingestion, SQL transformation pipelines, and instant API publishing to support
    analytics engineers, data platform teams, and application developers building
    high-concurrency analytics APIs.
  tags:
    - Analytics
    - Real-Time
    - Data Platform
    - Streaming
    - SQL
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      TINYBIRD_TOKEN: TINYBIRD_TOKEN

capability:
  consumes:
    - import: tinybird
      location: ./shared/tinybird.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: tinybird-analytics-api
      description: "Unified REST API for Tinybird real-time analytics workflows."
      resources:
        - path: /v1/data-sources
          name: data-sources
          description: "Manage analytics data sources"
          operations:
            - method: GET
              name: list-data-sources
              description: "List all data sources available for analytics"
              call: "tinybird.list-data-sources"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-data-source
              description: "Create a new data source for analytics ingestion"
              call: "tinybird.create-data-source"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/data-sources/{name}
          name: data-source
          description: "Individual data source management"
          operations:
            - method: GET
              name: get-data-source
              description: "Get statistics and schema for a data source"
              call: "tinybird.get-data-source"
              with:
                name: "rest.name"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: delete-data-source
              description: "Drop a data source"
              call: "tinybird.delete-data-source"
              with:
                name: "rest.name"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/events
          name: events
          description: "Stream events into analytics data sources"
          operations:
            - method: POST
              name: ingest-events
              description: "Ingest NDJSON events for real-time analytics"
              call: "tinybird.ingest-events"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pipes
          name: pipes
          description: "SQL transformation pipelines"
          operations:
            - method: GET
              name: list-pipes
              description: "List all data transformation pipes"
              call: "tinybird.list-pipes"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-pipe
              description: "Create a new SQL transformation pipe"
              call: "tinybird.create-pipe"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pipes/{name}
          name: pipe
          description: "Individual pipe management"
          operations:
            - method: GET
              name: get-pipe
              description: "Get pipe details and transformation nodes"
              call: "tinybird.get-pipe"
              with:
                name: "rest.name"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: delete-pipe
              description: "Delete a transformation pipe"
              call: "tinybird.delete-pipe"
              with:
                name: "rest.name"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/query
          name: query
          description: "Ad-hoc SQL analytics queries"
          operations:
            - method: GET
              name: execute-sql-query
              description: "Execute a SQL query for analytics exploration"
              call: "tinybird.execute-sql-query"
              with:
                q: "rest.q"
                format: "rest.format"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/tokens
          name: tokens
          description: "Authentication token management"
          operations:
            - method: GET
              name: list-tokens
              description: "List all API tokens"
              call: "tinybird.list-tokens"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-token
              description: "Create a new scoped API token"
              call: "tinybird.create-token"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/jobs
          name: jobs
          description: "Background job monitoring"
          operations:
            - method: GET
              name: list-jobs
              description: "Monitor background jobs and import status"
              call: "tinybird.list-jobs"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: tinybird-analytics-mcp
      transport: http
      description: "MCP server for AI-assisted real-time analytics with Tinybird."
      tools:
        - name: list-data-sources
          description: "List all Tinybird data sources in the workspace for analytics exploration"
          hints:
            readOnly: true
            openWorld: true
          call: "tinybird.list-data-sources"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-data-source
          description: "Get schema and row statistics for a specific Tinybird data source"
          hints:
            readOnly: true
            openWorld: false
          call: "tinybird.get-data-source"
          with:
            name: "tools.name"
          outputParameters:
            - type: object
              mapping: "$."
        - name: ingest-events
          description: "Stream NDJSON events into a Tinybird data source for real-time ingestion"
          hints:
            readOnly: false
            destructive: false
          call: "tinybird.ingest-events"
          with:
            name: "tools.name"
            events_payload: "tools.events_payload"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-pipes
          description: "List all SQL transformation pipes and published API endpoints in Tinybird"
          hints:
            readOnly: true
            openWorld: true
          call: "tinybird.list-pipes"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-pipe
          description: "Inspect the SQL nodes and configuration of a Tinybird transformation pipe"
          hints:
            readOnly: true
            openWorld: false
          call: "tinybird.get-pipe"
          with:
            name: "tools.name"
          outputParameters:
            - type: object
              mapping: "$."
        - name: execute-sql-query
          description: "Run an ad-hoc SQL query against Tinybird data sources for analytics exploration"
          hints:
            readOnly: true
            openWorld: true
          call: "tinybird.execute-sql-query"
          with:
            q: "tools.q"
            format: "tools.format"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-tokens
          description: "List all Tinybird authentication tokens with their scopes"
          hints:
            readOnly: true
            openWorld: true
          call: "tinybird.list-tokens"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-token
          description: "Create a new Tinybird API token with specific scope permissions"
          hints:
            readOnly: false
            destructive: false
          call: "tinybird.create-token"
          with:
            token_name: "tools.token_name"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-jobs
          description: "Monitor Tinybird background jobs including imports and schema changes"
          hints:
            readOnly: true
            openWorld: true
          call: "tinybird.list-jobs"
          with:
            status: "tools.status"
          outputParameters:
            - type: object
              mapping: "$."
        - name: delete-data-source
          description: "Drop a Tinybird data source and all its stored data permanently"
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "tinybird.delete-data-source"
          with:
            name: "tools.name"
          outputParameters:
            - type: object
              mapping: "$."