Google People API (Contacts)

naftiko: 1.0.0-alpha2
info:
  label: Google People API (Contacts)
  description: The Google People API provides access to information about profiles and contacts. It allows you to list, create,
    update, delete, and search contacts, as well as manage contact groups. It replaces the legacy Google Contacts API.
  tags:
  - Google
  - Contacts
  - API
  created: '2026-05-06'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: google-contacts
    baseUri: https://people.googleapis.com/v1
    description: Google People API (Contacts) HTTP API.
    authentication:
      type: bearer
      token: '{{GOOGLE_CONTACTS_TOKEN}}'
    resources:
    - name: people-resourcename
      path: /people/{resourceName}
      operations:
      - name: getperson
        method: GET
        description: Get a person
        inputParameters:
        - name: resourceName
          in: path
          type: string
          required: true
          description: The resource name of the person to provide information about.
        - name: personFields
          in: query
          type: string
          description: A field mask to restrict which fields on the person are returned.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: people-resourcename-connections
      path: /people/{resourceName}/connections
      operations:
      - name: listconnections
        method: GET
        description: List contacts
        inputParameters:
        - name: resourceName
          in: path
          type: string
          required: true
        - name: personFields
          in: query
          type: string
        - name: pageSize
          in: query
          type: integer
        - name: pageToken
          in: query
          type: string
        - name: sortOrder
          in: query
          type: string
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: people-createcontact
      path: /people:createContact
      operations:
      - name: createcontact
        method: POST
        description: Create a contact
        inputParameters:
        - name: personFields
          in: query
          type: string
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: people-resourcename-updatecontact
      path: /people/{resourceName}:updateContact
      operations:
      - name: updatecontact
        method: PATCH
        description: Update a contact
        inputParameters:
        - name: resourceName
          in: path
          type: string
          required: true
        - name: updatePersonFields
          in: query
          type: string
        - name: personFields
          in: query
          type: string
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: people-resourcename-deletecontact
      path: /people/{resourceName}:deleteContact
      operations:
      - name: deletecontact
        method: DELETE
        description: Delete a contact
        inputParameters:
        - name: resourceName
          in: path
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: people-searchcontacts
      path: /people:searchContacts
      operations:
      - name: searchcontacts
        method: GET
        description: Search contacts
        inputParameters:
        - name: query
          in: query
          type: string
        - name: readMask
          in: query
          type: string
        - name: pageSize
          in: query
          type: integer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: contactgroups
      path: /contactGroups
      operations:
      - name: listcontactgroups
        method: GET
        description: List contact groups
        inputParameters:
        - name: pageSize
          in: query
          type: integer
        - name: pageToken
          in: query
          type: string
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: createcontactgroup
        method: POST
        description: Create a contact group
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: contactgroups-resourcename
      path: /contactGroups/{resourceName}
      operations:
      - name: getcontactgroup
        method: GET
        description: Get a contact group
        inputParameters:
        - name: resourceName
          in: path
          type: string
          required: true
        - name: maxMembers
          in: query
          type: integer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: updatecontactgroup
        method: PUT
        description: Update a contact group
        inputParameters:
        - name: resourceName
          in: path
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: deletecontactgroup
        method: DELETE
        description: Delete a contact group
        inputParameters:
        - name: resourceName
          in: path
          type: string
          required: true
        - name: deleteContacts
          in: query
          type: boolean
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: google-contacts-rest
    description: REST adapter for Google People API (Contacts).
    resources:
    - path: /people/{resourceName}
      name: getperson
      operations:
      - method: GET
        name: getperson
        description: Get a person
        call: google-contacts.getperson
        with:
          resourceName: rest.resourceName
        outputParameters:
        - type: object
          mapping: $.
    - path: /people/{resourceName}/connections
      name: listconnections
      operations:
      - method: GET
        name: listconnections
        description: List contacts
        call: google-contacts.listconnections
        with:
          resourceName: rest.resourceName
        outputParameters:
        - type: object
          mapping: $.
    - path: /people:createContact
      name: createcontact
      operations:
      - method: POST
        name: createcontact
        description: Create a contact
        call: google-contacts.createcontact
        outputParameters:
        - type: object
          mapping: $.
    - path: /people/{resourceName}:updateContact
      name: updatecontact
      operations:
      - method: PATCH
        name: updatecontact
        description: Update a contact
        call: google-contacts.updatecontact
        with:
          resourceName: rest.resourceName
        outputParameters:
        - type: object
          mapping: $.
    - path: /people/{resourceName}:deleteContact
      name: deletecontact
      operations:
      - method: DELETE
        name: deletecontact
        description: Delete a contact
        call: google-contacts.deletecontact
        with:
          resourceName: rest.resourceName
        outputParameters:
        - type: object
          mapping: $.
    - path: /people:searchContacts
      name: searchcontacts
      operations:
      - method: GET
        name: searchcontacts
        description: Search contacts
        call: google-contacts.searchcontacts
        outputParameters:
        - type: object
          mapping: $.
    - path: /contactGroups
      name: listcontactgroups
      operations:
      - method: GET
        name: listcontactgroups
        description: List contact groups
        call: google-contacts.listcontactgroups
        outputParameters:
        - type: object
          mapping: $.
    - path: /contactGroups
      name: createcontactgroup
      operations:
      - method: POST
        name: createcontactgroup
        description: Create a contact group
        call: google-contacts.createcontactgroup
        outputParameters:
        - type: object
          mapping: $.
    - path: /contactGroups/{resourceName}
      name: getcontactgroup
      operations:
      - method: GET
        name: getcontactgroup
        description: Get a contact group
        call: google-contacts.getcontactgroup
        with:
          resourceName: rest.resourceName
        outputParameters:
        - type: object
          mapping: $.
    - path: /contactGroups/{resourceName}
      name: updatecontactgroup
      operations:
      - method: PUT
        name: updatecontactgroup
        description: Update a contact group
        call: google-contacts.updatecontactgroup
        with:
          resourceName: rest.resourceName
        outputParameters:
        - type: object
          mapping: $.
    - path: /contactGroups/{resourceName}
      name: deletecontactgroup
      operations:
      - method: DELETE
        name: deletecontactgroup
        description: Delete a contact group
        call: google-contacts.deletecontactgroup
        with:
          resourceName: rest.resourceName
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: google-contacts-mcp
    transport: http
    description: MCP adapter for Google People API (Contacts) for AI agent use.
    tools:
    - name: getperson
      description: Get a person
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: google-contacts.getperson
      with:
        resourceName: tools.resourceName
        personFields: tools.personFields
      inputParameters:
      - name: resourceName
        type: string
        description: The resource name of the person to provide information about.
        required: true
      - name: personFields
        type: string
        description: A field mask to restrict which fields on the person are returned.
      outputParameters:
      - type: object
        mapping: $.
    - name: listconnections
      description: List contacts
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: google-contacts.listconnections
      with:
        resourceName: tools.resourceName
        personFields: tools.personFields
        pageSize: tools.pageSize
        pageToken: tools.pageToken
        sortOrder: tools.sortOrder
      inputParameters:
      - name: resourceName
        type: string
        description: resourceName
        required: true
      - name: personFields
        type: string
        description: personFields
      - name: pageSize
        type: integer
        description: pageSize
      - name: pageToken
        type: string
        description: pageToken
      - name: sortOrder
        type: string
        description: sortOrder
      outputParameters:
      - type: object
        mapping: $.
    - name: createcontact
      description: Create a contact
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: google-contacts.createcontact
      with:
        personFields: tools.personFields
      inputParameters:
      - name: personFields
        type: string
        description: personFields
      outputParameters:
      - type: object
        mapping: $.
    - name: updatecontact
      description: Update a contact
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: google-contacts.updatecontact
      with:
        resourceName: tools.resourceName
        updatePersonFields: tools.updatePersonFields
        personFields: tools.personFields
      inputParameters:
      - name: resourceName
        type: string
        description: resourceName
        required: true
      - name: updatePersonFields
        type: string
        description: updatePersonFields
      - name: personFields
        type: string
        description: personFields
      outputParameters:
      - type: object
        mapping: $.
    - name: deletecontact
      description: Delete a contact
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: google-contacts.deletecontact
      with:
        resourceName: tools.resourceName
      inputParameters:
      - name: resourceName
        type: string
        description: resourceName
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: searchcontacts
      description: Search contacts
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: google-contacts.searchcontacts
      with:
        query: tools.query
        readMask: tools.readMask
        pageSize: tools.pageSize
      inputParameters:
      - name: query
        type: string
        description: query
      - name: readMask
        type: string
        description: readMask
      - name: pageSize
        type: integer
        description: pageSize
      outputParameters:
      - type: object
        mapping: $.
    - name: listcontactgroups
      description: List contact groups
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: google-contacts.listcontactgroups
      with:
        pageSize: tools.pageSize
        pageToken: tools.pageToken
      inputParameters:
      - name: pageSize
        type: integer
        description: pageSize
      - name: pageToken
        type: string
        description: pageToken
      outputParameters:
      - type: object
        mapping: $.
    - name: createcontactgroup
      description: Create a contact group
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: google-contacts.createcontactgroup
      outputParameters:
      - type: object
        mapping: $.
    - name: getcontactgroup
      description: Get a contact group
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: google-contacts.getcontactgroup
      with:
        resourceName: tools.resourceName
        maxMembers: tools.maxMembers
      inputParameters:
      - name: resourceName
        type: string
        description: resourceName
        required: true
      - name: maxMembers
        type: integer
        description: maxMembers
      outputParameters:
      - type: object
        mapping: $.
    - name: updatecontactgroup
      description: Update a contact group
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: google-contacts.updatecontactgroup
      with:
        resourceName: tools.resourceName
      inputParameters:
      - name: resourceName
        type: string
        description: resourceName
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: deletecontactgroup
      description: Delete a contact group
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: google-contacts.deletecontactgroup
      with:
        resourceName: tools.resourceName
        deleteContacts: tools.deleteContacts
      inputParameters:
      - name: resourceName
        type: string
        description: resourceName
        required: true
      - name: deleteContacts
        type: boolean
        description: deleteContacts
      outputParameters:
      - type: object
        mapping: $.
binds:
- namespace: env
  keys:
    GOOGLE_CONTACTS_TOKEN: GOOGLE_CONTACTS_TOKEN