@aaronsb/google-workspace-mcp 4.2.0 → 4.3.0

package/build/factory/manifest/contacts.yaml

@@ -0,0 +1,247 @@
+tool_name: manage_contacts
+description: "Search, read, create, update and delete Google Contacts: your saved contacts, the addresses you have corresponded with but never saved, and your organization's directory."
+requires_email: true
+google_service: people
+
+# The People API asks the caller to name every field it wants back, on every call, via
+# `personFields` or `readMask`. Omit the mask and the call is REJECTED outright — this is
+# not a shape that degrades to a sensible default.
+#
+# Those masks live in `defaults` rather than `params` so they never enter the generated
+# schema. An agent asking "who is Dana" should not first have to know that a birthday is
+# spelled `birthdays` and lives behind a different parameter name depending on which of
+# the seven operations it picked. The masks also differ per operation because Google
+# restricts them per operation, which is exactly the routing this tool exists to absorb.
+#
+# `sources` is left out of the schema for a sharper reason: its legal values are NOT the
+# same across operations. The contact operations take READ_SOURCE_TYPE_*, the directory
+# operations take DIRECTORY_SOURCE_TYPE_*, and generateSchema keeps only the FIRST
+# declaration of a param name — so a single advertised `sources` enum would be wrong for
+# whichever half lost the race.
+operations:
+
+  # --- Your own contacts ---
+
+  list:
+    type: list
+    description: "list your saved contacts"
+    resource: people.connections.list
+    params:
+      maxResults:
+        type: number
+        description: "Max people to return (default 25). Capped per operation: 30 for `search` and `searchOther`, 100 for everything else."
+        default: 25
+        max: 100
+        maps_to: pageSize
+      pageToken:
+        type: string
+        description: "Continue from where a previous page stopped — pass the token that response printed"
+      sortOrder:
+        type: string
+        description: "Order for `list` — by first name, by last name, or most recently changed first"
+        enum: [firstName, lastName, lastModified]
+    defaults:
+      # connections.list reads one person's connections, and the person is always the
+      # authenticated account. `people/me` is Google's alias for it, so the agent never
+      # has to know its own resource name.
+      resourceName: people/me
+      personFields: names,emailAddresses,phoneNumbers,organizations,metadata
+      sortOrder: firstName
+
+  search:
+    type: list
+    description: "search your saved contacts by name, email, nickname or phone"
+    resource: people.searchContacts
+    params:
+      query:
+        type: string
+        description: "Text to match against names, email addresses, nicknames and phone numbers. Matching is by PREFIX: `ann` finds Anna, `nna` finds nobody."
+        required: true
+      maxResults:
+        type: number
+        description: "Max people to return (default 25). Capped per operation: 30 for `search` and `searchOther`, 100 for everything else."
+        default: 25
+        max: 30
+        maps_to: pageSize
+    defaults:
+      readMask: names,emailAddresses,phoneNumbers,organizations,metadata
+
+  get:
+    type: detail
+    description: "get one person in full — addresses, birthday, notes, relations"
+    resource: people.get
+    params:
+      contactId:
+        type: string
+        description: "Person id as `list` or `search` printed it (e.g. `people/c1234567890`). A bare id without the `people/` prefix is accepted."
+        required: true
+        maps_to: resourceName
+    defaults:
+      personFields: names,nicknames,emailAddresses,phoneNumbers,addresses,organizations,birthdays,biographies,urls,relations,memberships,photos,metadata
+
+  # The Person body is built by the patch, not declared here. Every field the People API
+  # wants is a parallel array of objects — `names: [{givenName, familyName}]` — and any
+  # param this manifest declares that Google does not recognise as a query parameter goes
+  # into the request body VERBATIM. Declared flat, `name: "Ada Lovelace"` would be sent as
+  # a top-level `name` field, which Google ignores, producing a contact with no name and
+  # no error. So these are declared for the SCHEMA and converted before the call.
+  create:
+    type: action
+    description: "create a new contact"
+    resource: people.createContact
+    params:
+      name:
+        type: string
+        description: "Full name, e.g. `Ada Lovelace`. Split into given and family name on the way in; a single word becomes the given name."
+      contactEmail:
+        type: string
+        description: "The contact's email address. (`email` is the account making the call, not the person being saved.) On `update` this REPLACES every address the contact has — pass an empty string to clear them."
+      phone:
+        type: string
+        description: "Phone number, in whatever form you have it — Google normalizes it. On `update` this REPLACES every number the contact has — pass an empty string to clear them."
+      company:
+        type: string
+        description: "Organization name"
+      jobTitle:
+        type: string
+        description: "Job title within the organization"
+      notes:
+        type: string
+        description: "Free-text note stored on the contact"
+    defaults:
+      # Echoes back EVERY field this operation can write. Live, the shorter read mask
+      # confirmed a create without the note it had just stored — a confirmation that
+      # drops a field the caller supplied is indistinguishable from one that dropped it
+      # on the way in.
+      personFields: names,emailAddresses,phoneNumbers,organizations,biographies,metadata
+
+  # updatePersonFields is not sent from here — the patch derives it from which fields the
+  # caller actually supplied. A fixed list would name fields nobody touched, and naming a
+  # field in updatePersonFields with no value in the body CLEARS it. Declared statically,
+  # this operation would wipe a contact's phone number every time someone corrected a
+  # job title.
+  update:
+    type: action
+    description: "change an existing contact (only the fields you pass; pass an empty string to clear one)"
+    resource: people.updateContact
+    params:
+      contactId:
+        type: string
+        description: "Person id as `list` or `search` printed it (e.g. `people/c1234567890`). A bare id without the `people/` prefix is accepted."
+        required: true
+        maps_to: resourceName
+      name:
+        type: string
+        description: "Full name, e.g. `Ada Lovelace`. Split into given and family name on the way in; a single word becomes the given name."
+      contactEmail:
+        type: string
+        description: "The contact's email address. (`email` is the account making the call, not the person being saved.) On `update` this REPLACES every address the contact has — pass an empty string to clear them."
+      phone:
+        type: string
+        description: "Phone number, in whatever form you have it — Google normalizes it. On `update` this REPLACES every number the contact has — pass an empty string to clear them."
+      company:
+        type: string
+        description: "Organization name"
+      jobTitle:
+        type: string
+        description: "Job title within the organization"
+      notes:
+        type: string
+        description: "Free-text note stored on the contact"
+    defaults:
+      personFields: names,emailAddresses,phoneNumbers,organizations,biographies,metadata
+
+  delete:
+    type: action
+    description: "delete a contact"
+    resource: people.deleteContact
+    params:
+      contactId:
+        type: string
+        description: "Person id as `list` or `search` printed it (e.g. `people/c1234567890`). A bare id without the `people/` prefix is accepted."
+        required: true
+        maps_to: resourceName
+
+  # --- Other contacts: addresses seen in mail, never saved ---
+
+  listOther:
+    type: list
+    description: "list 'other contacts' — addresses you have corresponded with but never saved"
+    resource: otherContacts.list
+    params:
+      maxResults:
+        type: number
+        description: "Max people to return (default 25). Capped per operation: 30 for `search` and `searchOther`, 100 for everything else."
+        default: 25
+        max: 100
+        maps_to: pageSize
+      pageToken:
+        type: string
+        description: "Continue from where a previous page stopped — pass the token that response printed"
+    defaults:
+      # otherContacts accepts a narrower mask than the contact operations do; asking it
+      # for organizations is an error, not an empty field.
+      readMask: names,emailAddresses,phoneNumbers,metadata
+
+  searchOther:
+    type: list
+    description: "search 'other contacts' by name or email"
+    resource: otherContacts.search
+    params:
+      query:
+        type: string
+        description: "Text to match against names, email addresses, nicknames and phone numbers. Matching is by PREFIX: `ann` finds Anna, `nna` finds nobody."
+        required: true
+      maxResults:
+        type: number
+        description: "Max people to return (default 25). Capped per operation: 30 for `search` and `searchOther`, 100 for everything else."
+        default: 25
+        max: 30
+        maps_to: pageSize
+    defaults:
+      readMask: names,emailAddresses,phoneNumbers,metadata
+
+  # --- The organization directory (Google Workspace accounts only) ---
+
+  listDirectory:
+    type: list
+    description: "list people in your organization's directory (Workspace accounts only)"
+    resource: people.listDirectoryPeople
+    params:
+      maxResults:
+        type: number
+        description: "Max people to return (default 25). Capped per operation: 30 for `search` and `searchOther`, 100 for everything else."
+        default: 25
+        max: 100
+        maps_to: pageSize
+      pageToken:
+        type: string
+        description: "Continue from where a previous page stopped — pass the token that response printed"
+    defaults:
+      readMask: names,emailAddresses,phoneNumbers,organizations,metadata
+      # `sources` is REQUIRED here — the directory operations reject a call that does not
+      # say which directory to read. Both value sets are wanted: DOMAIN_PROFILE is the
+      # people with accounts, DOMAIN_CONTACT the shared contacts an admin published.
+      sources: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE,DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT
+
+  searchDirectory:
+    type: list
+    description: "search your organization's directory by name or email (Workspace accounts only)"
+    resource: people.searchDirectoryPeople
+    params:
+      query:
+        type: string
+        description: "Text to match against names, email addresses, nicknames and phone numbers. Matching is by PREFIX: `ann` finds Anna, `nna` finds nobody."
+        required: true
+      maxResults:
+        type: number
+        description: "Max people to return (default 25). Capped per operation: 30 for `search` and `searchOther`, 100 for everything else."
+        default: 25
+        max: 100
+        maps_to: pageSize
+      pageToken:
+        type: string
+        description: "Continue from where a previous page stopped — pass the token that response printed"
+    defaults:
+      readMask: names,emailAddresses,phoneNumbers,organizations,metadata
+      sources: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE,DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT

package/build/factory/manifest/drive.yaml

@@ -51,10 +51,10 @@ operations:
         required: true
       name:
         type: string
-        description: "File name in Drive (defaults to local name)"
+        description: "File name in Drive. On `upload`, defaults to the local file's name. On `copy`, the name for the copy — without it Drive names it 'Copy of <original>'. On `update`, the new name (a rename)."
       parentFolderId:
         type: string
-        description: "Destination folder ID"
+        description: "Destination folder ID. On `copy`, defaults to the source file's folder."
 
   viewImage:
     type: detail
@@ -63,7 +63,7 @@ operations:
     params:
       fileId:
         type: string
-        description: "File ID of the image to view"
+        description: "File ID"
         required: true
     defaults:
       supportsAllDrives: true
@@ -75,7 +75,7 @@ operations:
     params:
       fileId:
         type: string
-        description: "File ID to download"
+        description: "File ID"
         required: true
       outputPath:
         type: string
@@ -91,14 +91,14 @@ operations:
     params:
       fileId:
         type: string
-        description: "File ID to copy"
+        description: "File ID"
         required: true
       name:
         type: string
-        description: "Name for the copy (without it, Drive names it 'Copy of <original>')"
+        description: "File name in Drive. On `upload`, defaults to the local file's name. On `copy`, the name for the copy — without it Drive names it 'Copy of <original>'. On `update`, the new name (a rename)."
       parentFolderId:
         type: string
-        description: "Folder ID to place the copy in (defaults to the source's folder)"
+        description: "Destination folder ID. On `copy`, defaults to the source file's folder."
     defaults:
       supportsAllDrives: true
 
@@ -109,11 +109,11 @@ operations:
     params:
       fileId:
         type: string
-        description: "File ID to update"
+        description: "File ID"
         required: true
       name:
         type: string
-        description: "New file name (rename)"
+        description: "File name in Drive. On `upload`, defaults to the local file's name. On `copy`, the name for the copy — without it Drive names it 'Copy of <original>'. On `update`, the new name (a rename)."
       addParents:
         type: string
         description: "Comma-separated folder ID(s) to add as parents (move into a folder)"
@@ -130,7 +130,7 @@ operations:
     params:
       fileId:
         type: string
-        description: "File ID to delete"
+        description: "File ID"
         required: true
     defaults:
       supportsAllDrives: true
@@ -142,7 +142,7 @@ operations:
     params:
       fileId:
         type: string
-        description: "File ID to export"
+        description: "File ID"
         required: true
       mimeType:
         type: string
@@ -150,7 +150,7 @@ operations:
         required: true
       outputPath:
         type: string
-        description: "Local path to save exported file"
+        description: "Local path to save the file"
     defaults:
       supportsAllDrives: true
 
@@ -175,7 +175,7 @@ operations:
     params:
       fileId:
         type: string
-        description: "File ID to share"
+        description: "File ID"
         required: true
       shareEmail:
         type: string
@@ -258,7 +258,7 @@ operations:
         required: true
       content:
         type: string
-        description: "Comment text"
+        description: "Comment text. On `replyToComment`, the reply text."
         required: true
       quotedText:
         type: string
@@ -299,11 +299,11 @@ operations:
         required: true
       commentId:
         type: string
-        description: "Comment ID to reply to"
+        description: "Comment ID"
         required: true
       content:
         type: string
-        description: "Reply text"
+        description: "Comment text. On `replyToComment`, the reply text."
         required: true
     defaults:
       fields: "id, content, htmlContent, author(displayName), createdTime"

package/build/factory/manifest/gmail.yaml

@@ -60,14 +60,14 @@ operations:
         required: true
       body:
         type: string
-        description: "Email body text"
+        description: "Email body text. On `forward`, an optional note prepended ABOVE the forwarded message."
         required: true
       from:
         type: string
         description: "Sender email or RFC 2822 mailbox for a verified Gmail Send As alias"
       cc:
         type: string
-        description: "CC email(s), comma-separated"
+        description: "CC email(s), comma-separated. On `replyAll` these are ADDITIONAL — they do not replace the recipients already on the thread."
       bcc:
         type: string
         description: "BCC email(s), comma-separated"
@@ -87,11 +87,11 @@ operations:
     params:
       messageId:
         type: string
-        description: "Message ID to reply to"
+        description: "Email message ID"
         required: true
       body:
         type: string
-        description: "Reply body text"
+        description: "Email body text. On `forward`, an optional note prepended ABOVE the forwarded message."
         required: true
       attachments:
         type: string
@@ -109,15 +109,15 @@ operations:
     params:
       messageId:
         type: string
-        description: "Message ID to reply to"
+        description: "Email message ID"
         required: true
       body:
         type: string
-        description: "Reply body text"
+        description: "Email body text. On `forward`, an optional note prepended ABOVE the forwarded message."
         required: true
       cc:
         type: string
-        description: "Additional CC email(s), comma-separated"
+        description: "CC email(s), comma-separated. On `replyAll` these are ADDITIONAL — they do not replace the recipients already on the thread."
       attachments:
         type: string
         description: "Workspace filenames to attach, comma-separated (files must exist in workspace via manage_workspace). Creates draft when present."
@@ -134,7 +134,7 @@ operations:
     params:
       messageId:
         type: string
-        description: "Message ID to forward"
+        description: "Email message ID"
         required: true
       to:
         type: string
@@ -142,7 +142,7 @@ operations:
         required: true
       body:
         type: string
-        description: "Optional note to prepend above forwarded message"
+        description: "Email body text. On `forward`, an optional note prepended ABOVE the forwarded message."
 
   # --- Inbox management ---
 
@@ -165,7 +165,7 @@ operations:
     params:
       messageId:
         type: string
-        description: "Message ID to trash"
+        description: "Email message ID"
         required: true
         maps_to: id
     defaults:
@@ -178,7 +178,7 @@ operations:
     params:
       messageId:
         type: string
-        description: "Message ID to restore"
+        description: "Email message ID"
         required: true
         maps_to: id
     defaults:
@@ -191,11 +191,11 @@ operations:
     params:
       messageId:
         type: string
-        description: "Message ID containing the attachment"
+        description: "Email message ID"
         required: true
       filename:
         type: string
-        description: "Filename to save as (from the read response, e.g. 'invoice_template.md')"
+        description: "Attachment filename, exactly as it appears in the `read` response (e.g. 'invoice_template.md')"
         required: true
     defaults:
       userId: me
@@ -207,11 +207,11 @@ operations:
     params:
       messageId:
         type: string
-        description: "Message ID containing the attachment"
+        description: "Email message ID"
         required: true
       filename:
         type: string
-        description: "Image filename from the read response"
+        description: "Attachment filename, exactly as it appears in the `read` response (e.g. 'invoice_template.md')"
         required: true
     defaults:
       userId: me
@@ -223,7 +223,7 @@ operations:
     params:
       messageId:
         type: string
-        description: "Message ID to modify"
+        description: "Email message ID"
         required: true
         maps_to: id
       addLabelIds:
@@ -253,11 +253,11 @@ operations:
     params:
       query:
         type: string
-        description: "Gmail search query to filter threads"
+        description: "Gmail search query (e.g. \"from:alice subject:meeting has:attachment\")"
         maps_to: q
       maxResults:
         type: number
-        description: "Max threads to return (default: 10, max: 50)"
+        description: "Max results (default: 10, max: 50)"
         default: 10
         max: 50
     defaults:

package/build/factory/manifest/meet.yaml

@@ -13,10 +13,10 @@ operations:
     params:
       filter:
         type: string
-        description: "EBNF filter (e.g. 'space.meeting_code = \"abc-mnop-xyz\"' or 'start_time>=\"2026-01-01T00:00:00Z\"')"
+        description: "EBNF filter. On `listConferences`, e.g. 'space.meeting_code = \"abc-mnop-xyz\"' or 'start_time>=\"2026-01-01T00:00:00Z\"'. On `listParticipants`, e.g. 'latest_end_time IS NULL' for active participants."
       maxResults:
         type: number
-        description: "Max conferences to return (default: 25, max: 100)"
+        description: "Max results per page, as default/ceiling. Differs by operation: `listConferences` 25/100, `listParticipants` 100/250, `listTranscriptEntries` 100/100. (Google's own default for transcript entries is 10; this tool raises it.)"
         default: 25
         max: 100
         maps_to: pageSize
@@ -28,7 +28,7 @@ operations:
     params:
       conferenceId:
         type: string
-        description: "Conference record ID (from listConferences)"
+        description: "Conference record ID (from `listConferences`)"
         required: true
         maps_to: name
 
@@ -41,15 +41,15 @@ operations:
     params:
       conferenceId:
         type: string
-        description: "Conference record ID"
+        description: "Conference record ID (from `listConferences`)"
         required: true
         maps_to: parent
       filter:
         type: string
-        description: "Filter (e.g. 'latest_end_time IS NULL' for active participants)"
+        description: "EBNF filter. On `listConferences`, e.g. 'space.meeting_code = \"abc-mnop-xyz\"' or 'start_time>=\"2026-01-01T00:00:00Z\"'. On `listParticipants`, e.g. 'latest_end_time IS NULL' for active participants."
       maxResults:
         type: number
-        description: "Max participants (default: 100, max: 250)"
+        description: "Max results per page, as default/ceiling. Differs by operation: `listConferences` 25/100, `listParticipants` 100/250, `listTranscriptEntries` 100/100. (Google's own default for transcript entries is 10; this tool raises it.)"
         default: 100
         max: 250
         maps_to: pageSize
@@ -63,7 +63,7 @@ operations:
     params:
       conferenceId:
         type: string
-        description: "Conference record ID"
+        description: "Conference record ID (from `listConferences`)"
         required: true
         maps_to: parent
 
@@ -74,7 +74,7 @@ operations:
     params:
       transcriptName:
         type: string
-        description: "Transcript resource name (from listTranscripts)"
+        description: "Transcript resource name (from `listTranscripts`, e.g. conferenceRecords/.../transcripts/...)"
         required: true
         maps_to: name
 
@@ -85,12 +85,12 @@ operations:
     params:
       transcriptName:
         type: string
-        description: "Transcript resource name (e.g. conferenceRecords/.../transcripts/...)"
+        description: "Transcript resource name (from `listTranscripts`, e.g. conferenceRecords/.../transcripts/...)"
         required: true
         maps_to: parent
       maxResults:
         type: number
-        description: "Max entries per page (default: 10, max: 100)"
+        description: "Max results per page, as default/ceiling. Differs by operation: `listConferences` 25/100, `listParticipants` 100/250, `listTranscriptEntries` 100/100. (Google's own default for transcript entries is 10; this tool raises it.)"
         default: 100
         max: 100
         maps_to: pageSize
@@ -104,7 +104,7 @@ operations:
     params:
       conferenceId:
         type: string
-        description: "Conference record ID"
+        description: "Conference record ID (from `listConferences`)"
         required: true
         maps_to: parent
 
@@ -128,7 +128,7 @@ operations:
     params:
       conferenceId:
         type: string
-        description: "Conference record ID (from listConferences)"
+        description: "Conference record ID (from `listConferences`)"
         required: true
       pageToken:
         type: string
@@ -143,7 +143,7 @@ operations:
     params:
       conferenceId:
         type: string
-        description: "Conference record ID"
+        description: "Conference record ID (from `listConferences`)"
         required: true
         maps_to: parent
 
@@ -157,3 +157,81 @@ operations:
         description: "Smart note resource name (from listSmartNotes)"
         required: true
         maps_to: name
+
+  # --- Meeting spaces ---
+  #
+  # A space is a standalone meeting link, not attached to a calendar event. For a link on
+  # an event, use `manage_calendar` with `meet: true` — that goes through Calendar and
+  # keeps the two together.
+  #
+  # `createSpace` is the first manage_meet operation that WRITES. Everything above reads
+  # conference records, which `meetings.space.readonly` covers on its own; creating a
+  # space needs `meetings.space.created`, which a read-only account does not hold
+  # (ADR-202). Both handlers are custom: spaces.create declares no parameters at all, so
+  # everything travels in the body, and the response nests the joinable URL.
+
+  createSpace:
+    type: action
+    description: "create a standalone Google Meet link (not attached to a calendar event)"
+    resource: spaces.create
+    params:
+      accessType:
+        type: string
+        enum: ["OPEN", "TRUSTED", "RESTRICTED"]
+        description: "Who can join without knocking. OPEN: anyone with the link. TRUSTED (default): people in your organization, plus invited guests. RESTRICTED: invited guests only."
+      moderation:
+        type: boolean
+        description: "Turn on host controls — the host admits guests and manages who can present or chat."
+
+  activeConferences:
+    type: list
+    description: "list conferences happening RIGHT NOW across your meetings"
+    resource: conferenceRecords.list
+    params:
+      maxResults:
+        type: number
+        description: "Max results per page, as default/ceiling. Differs by operation: `listConferences` 25/100, `listParticipants` 100/250, `listTranscriptEntries` 100/100. (Google's own default for transcript entries is 10; this tool raises it.)"
+        default: 25
+        max: 100
+
+  getSpace:
+    type: detail
+    description: "look up a meeting space by its meeting code or resource name"
+    resource: spaces.get
+    params:
+      space:
+        type: string
+        description: "Meeting code (the abc-mnop-xyz part of a Meet link) or a full spaces/... resource name"
+        required: true
+        maps_to: name
+
+  updateSpace:
+    type: action
+    description: "change who can join a meeting space, or turn host controls on or off"
+    resource: spaces.patch
+    params:
+      space:
+        type: string
+        description: "Meeting code (the abc-mnop-xyz part of a Meet link) or a full spaces/... resource name"
+        required: true
+        maps_to: name
+      accessType:
+        type: string
+        enum: ["OPEN", "TRUSTED", "RESTRICTED"]
+        description: "Who can join without knocking. OPEN: anyone with the link. TRUSTED (default): people in your organization, plus invited guests. RESTRICTED: invited guests only."
+      moderation:
+        type: boolean
+        description: "Turn on host controls — the host admits guests and manages who can present or chat."
+
+  # Ends the meeting for EVERYONE currently in it. There is no undo and no warning to
+  # participants; the call returns an empty body whether or not anyone was in the room.
+  endActiveConference:
+    type: action
+    description: "end the call happening in a space right now, disconnecting everyone in it"
+    resource: spaces.endActiveConference
+    params:
+      space:
+        type: string
+        description: "Meeting code (the abc-mnop-xyz part of a Meet link) or a full spaces/... resource name"
+        required: true
+        maps_to: name