Spreadsheet Automation

naftiko: 1.0.0-alpha2
info:
  label: Spreadsheet Automation
  description: Workflow capability for spreadsheet data automation using Google Sheets API. Enables AI assistants and applications
    to read data from sheets, write and append new rows, batch update multiple ranges, clear data, and manage spreadsheet
    structure. Supports data pipeline, reporting, form collection, and content management workflows.
  tags:
  - Spreadsheets
  - Google Sheets
  - Data Automation
  - Reporting
  - Productivity
  created: '2026-05-02'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    GOOGLE_ACCESS_TOKEN: GOOGLE_ACCESS_TOKEN
capability:
  consumes:
  - type: http
    namespace: google-sheets
    baseUri: https://sheets.googleapis.com/v4
    description: Google Sheets API v4 for reading and writing spreadsheet data
    authentication:
      type: bearer
      token: '{{GOOGLE_ACCESS_TOKEN}}'
    resources:
    - name: spreadsheet
      path: /spreadsheets/{spreadsheetId}
      description: Spreadsheet resource
      operations:
      - name: get-spreadsheet
        method: GET
        description: Get spreadsheet metadata and structure
        inputParameters:
        - name: spreadsheetId
          in: path
          type: string
          required: true
        - name: includeGridData
          in: query
          type: boolean
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: values
      path: /spreadsheets/{spreadsheetId}/values/{range}
      description: Cell values by range
      operations:
      - name: get-values
        method: GET
        description: Read cell values from a range
        inputParameters:
        - name: spreadsheetId
          in: path
          type: string
          required: true
        - name: range
          in: path
          type: string
          required: true
        - name: majorDimension
          in: query
          type: string
          required: false
        - name: valueRenderOption
          in: query
          type: string
          required: false
        outputRawFormat: json
        outputParameters:
        - name: values
          type: array
          value: $.values
        - name: range
          type: string
          value: $.range
      - name: update-values
        method: PUT
        description: Write cell values to a range
        inputParameters:
        - name: spreadsheetId
          in: path
          type: string
          required: true
        - name: range
          in: path
          type: string
          required: true
        - name: valueInputOption
          in: query
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            range: '{{tools.range}}'
            values: '{{tools.values}}'
    - name: values-append
      path: /spreadsheets/{spreadsheetId}/values/{range}:append
      description: Append values to a spreadsheet
      operations:
      - name: append-values
        method: POST
        description: Append rows to the end of an existing table
        inputParameters:
        - name: spreadsheetId
          in: path
          type: string
          required: true
        - name: range
          in: path
          type: string
          required: true
        - name: valueInputOption
          in: query
          type: string
          required: true
        - name: insertDataOption
          in: query
          type: string
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            values: '{{tools.values}}'
    - name: values-batch-get
      path: /spreadsheets/{spreadsheetId}/values:batchGet
      description: Batch read multiple ranges
      operations:
      - name: batch-get-values
        method: GET
        description: Read multiple ranges in a single API call
        inputParameters:
        - name: spreadsheetId
          in: path
          type: string
          required: true
        - name: ranges
          in: query
          type: array
          required: true
        - name: majorDimension
          in: query
          type: string
          required: false
        outputRawFormat: json
        outputParameters:
        - name: valueRanges
          type: array
          value: $.valueRanges
    - name: values-batch-update
      path: /spreadsheets/{spreadsheetId}/values:batchUpdate
      description: Batch write multiple ranges
      operations:
      - name: batch-update-values
        method: POST
        description: Write to multiple ranges in a single API call
        inputParameters:
        - name: spreadsheetId
          in: path
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            valueInputOption: '{{tools.valueInputOption}}'
            data: '{{tools.data}}'
  exposes:
  - type: rest
    port: 8080
    namespace: spreadsheet-automation-api
    description: Unified REST API for spreadsheet data automation workflows.
    resources:
    - path: /v1/spreadsheets/{spreadsheetId}
      name: spreadsheet
      description: Spreadsheet metadata and structure
      operations:
      - method: GET
        name: get-spreadsheet
        description: Get spreadsheet metadata including sheet names and structure
        call: google-sheets.get-spreadsheet
        with:
          spreadsheetId: rest.spreadsheetId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/spreadsheets/{spreadsheetId}/values/{range}
      name: values
      description: Read and write cell values
      operations:
      - method: GET
        name: get-values
        description: Read values from a cell range
        call: google-sheets.get-values
        with:
          spreadsheetId: rest.spreadsheetId
          range: rest.range
          majorDimension: rest.majorDimension
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: update-values
        description: Write values to a cell range
        call: google-sheets.update-values
        with:
          spreadsheetId: rest.spreadsheetId
          range: rest.range
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/spreadsheets/{spreadsheetId}/values/{range}/append
      name: values-append
      description: Append rows to a spreadsheet
      operations:
      - method: POST
        name: append-values
        description: Append new rows to the end of a table
        call: google-sheets.append-values
        with:
          spreadsheetId: rest.spreadsheetId
          range: rest.range
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/spreadsheets/{spreadsheetId}/values/batch
      name: batch-values
      description: Batch read/write operations
      operations:
      - method: GET
        name: batch-get-values
        description: Read multiple ranges in one request
        call: google-sheets.batch-get-values
        with:
          spreadsheetId: rest.spreadsheetId
          ranges: rest.ranges
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: batch-update-values
        description: Write to multiple ranges in one request
        call: google-sheets.batch-update-values
        with:
          spreadsheetId: rest.spreadsheetId
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: spreadsheet-automation-mcp
    transport: http
    description: MCP server for AI-assisted spreadsheet reading, writing, and data management.
    tools:
    - name: get-spreadsheet-info
      description: Get information about a Google Spreadsheet including its title, sheets, and structure.
      hints:
        readOnly: true
        openWorld: false
      call: google-sheets.get-spreadsheet
      with:
        spreadsheetId: tools.spreadsheetId
      outputParameters:
      - type: object
        mapping: $.
    - name: read-spreadsheet-range
      description: Read cell values from a Google Sheets range using A1 notation (e.g., 'Sheet1!A1:D10'). Returns a 2D array
        of values.
      hints:
        readOnly: true
        openWorld: false
      call: google-sheets.get-values
      with:
        spreadsheetId: tools.spreadsheetId
        range: tools.range
        majorDimension: tools.majorDimension
        valueRenderOption: tools.valueRenderOption
      outputParameters:
      - type: object
        mapping: $.
    - name: write-spreadsheet-range
      description: Write cell values to a Google Sheets range. Use valueInputOption='USER_ENTERED' to parse values like a
        user would (including formulas), or 'RAW' for literal string values.
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: google-sheets.update-values
      with:
        spreadsheetId: tools.spreadsheetId
        range: tools.range
      outputParameters:
      - type: object
        mapping: $.
    - name: append-to-spreadsheet
      description: Append new rows to a Google Sheet. Finds the last row of the existing table and inserts after it. Perfect
        for adding new form submissions, log entries, or data records.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: google-sheets.append-values
      with:
        spreadsheetId: tools.spreadsheetId
        range: tools.range
      outputParameters:
      - type: object
        mapping: $.
    - name: batch-read-spreadsheet
      description: Read multiple ranges from a Google Sheet in a single API call. More efficient than multiple individual
        reads.
      hints:
        readOnly: true
        openWorld: false
      call: google-sheets.batch-get-values
      with:
        spreadsheetId: tools.spreadsheetId
        ranges: tools.ranges
      outputParameters:
      - type: object
        mapping: $.
    - name: batch-write-spreadsheet
      description: Write to multiple ranges in a Google Sheet in a single API call. Efficient for updating several disjoint
        regions at once.
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: google-sheets.batch-update-values
      with:
        spreadsheetId: tools.spreadsheetId
      outputParameters:
      - type: object
        mapping: $.