@aaronsb/google-workspace-mcp 2.0.0-alpha.4

package/build/factory/manifest.yaml

@@ -0,0 +1,852 @@
+# Service manifest — declarative registry for the tool factory (ADR-300).
+# Each entry produces one MCP tool via the generator.
+# gws 0.13.3 — 6 services, 51 operations
+#
+# Note: People (contacts) and Meet are supported by gws but excluded here
+# because gws auth login doesn't offer their required OAuth scopes.
+# See https://github.com/googleworkspace/cli/issues/556
+# Re-add when gws supports contacts.readonly and meetings.space.created scopes.
+
+services:
+  gmail:
+    tool_name: manage_email
+    description: "Search, read, send, forward, or manage emails in a Google Workspace account. Supports Gmail search syntax."
+    requires_email: true
+    gws_service: gmail
+    operations:
+
+      # --- Core message operations ---
+
+      search:
+        type: list
+        description: "find emails by query"
+        resource: users.messages.list
+        params:
+          query:
+            type: string
+            description: 'Gmail search query (e.g. "from:alice subject:meeting has:attachment")'
+            maps_to: q
+          maxResults:
+            type: number
+            description: "Max results (default: 10, max: 50)"
+            default: 10
+            max: 50
+        defaults:
+          userId: me
+        hydration:
+          resource: users.messages.get
+          format: metadata
+          headers: [From, Subject, Date]
+
+      read:
+        type: detail
+        description: "get full email by ID"
+        resource: users.messages.get
+        params:
+          messageId:
+            type: string
+            description: "Email message ID"
+            required: true
+            maps_to: id
+        defaults:
+          userId: me
+
+      send:
+        type: action
+        description: "compose and send a new email"
+        helper: "+send"
+        params:
+          to:
+            type: string
+            description: "Recipient email(s), comma-separated"
+            required: true
+          subject:
+            type: string
+            description: "Email subject line"
+            required: true
+          body:
+            type: string
+            description: "Email body text"
+            required: true
+          cc:
+            type: string
+            description: "CC email(s), comma-separated"
+          bcc:
+            type: string
+            description: "BCC email(s), comma-separated"
+        cli_args:
+          to: "--to"
+          subject: "--subject"
+          body: "--body"
+          cc: "--cc"
+          bcc: "--bcc"
+
+      reply:
+        type: action
+        description: "reply to a message (thread-aware)"
+        helper: "+reply"
+        params:
+          messageId:
+            type: string
+            description: "Message ID to reply to"
+            required: true
+          body:
+            type: string
+            description: "Reply body text"
+            required: true
+        cli_args:
+          messageId: "--message-id"
+          body: "--body"
+
+      replyAll:
+        type: action
+        description: "reply-all to a message (thread-aware, includes all recipients)"
+        helper: "+reply-all"
+        params:
+          messageId:
+            type: string
+            description: "Message ID to reply to"
+            required: true
+          body:
+            type: string
+            description: "Reply body text"
+            required: true
+          cc:
+            type: string
+            description: "Additional CC email(s), comma-separated"
+        cli_args:
+          messageId: "--message-id"
+          body: "--body"
+          cc: "--cc"
+
+      forward:
+        type: action
+        description: "forward a message to new recipients"
+        helper: "+forward"
+        params:
+          messageId:
+            type: string
+            description: "Message ID to forward"
+            required: true
+          to:
+            type: string
+            description: "Recipient email(s), comma-separated"
+            required: true
+          body:
+            type: string
+            description: "Optional note to prepend above forwarded message"
+        cli_args:
+          messageId: "--message-id"
+          to: "--to"
+          body: "--body"
+
+      # --- Inbox management ---
+
+      triage:
+        type: list
+        description: "unread inbox summary (sender, subject, date)"
+        helper: "+triage"
+
+      trash:
+        type: action
+        description: "move a message to trash"
+        resource: users.messages.trash
+        params:
+          messageId:
+            type: string
+            description: "Message ID to trash"
+            required: true
+            maps_to: id
+        defaults:
+          userId: me
+
+      untrash:
+        type: action
+        description: "restore a message from trash"
+        resource: users.messages.untrash
+        params:
+          messageId:
+            type: string
+            description: "Message ID to restore"
+            required: true
+            maps_to: id
+        defaults:
+          userId: me
+
+      getAttachment:
+        type: detail
+        description: "download an email attachment to workspace directory (use read first to see attachment list)"
+        resource: users.messages.attachments.get
+        params:
+          messageId:
+            type: string
+            description: "Message ID containing the attachment"
+            required: true
+          filename:
+            type: string
+            description: "Filename to save as (from the read response, e.g. 'invoice_template.md')"
+            required: true
+        defaults:
+          userId: me
+
+      modify:
+        type: action
+        description: "add or remove labels on a message (e.g. archive, mark read/unread)"
+        resource: users.messages.modify
+        params:
+          messageId:
+            type: string
+            description: "Message ID to modify"
+            required: true
+            maps_to: id
+          addLabelIds:
+            type: string
+            description: "Comma-separated label IDs to add (e.g. STARRED, IMPORTANT, Label_123)"
+          removeLabelIds:
+            type: string
+            description: "Comma-separated label IDs to remove (e.g. UNREAD, INBOX to archive)"
+        defaults:
+          userId: me
+
+      # --- Labels ---
+
+      labels:
+        type: list
+        description: "list all labels in the mailbox"
+        resource: users.labels.list
+        defaults:
+          userId: me
+
+      # --- Threads ---
+
+      threads:
+        type: list
+        description: "list email threads by query"
+        resource: users.threads.list
+        params:
+          query:
+            type: string
+            description: "Gmail search query to filter threads"
+            maps_to: q
+          maxResults:
+            type: number
+            description: "Max threads to return (default: 10, max: 50)"
+            default: 10
+            max: 50
+        defaults:
+          userId: me
+
+      getThread:
+        type: detail
+        description: "get all messages in a thread"
+        resource: users.threads.get
+        params:
+          threadId:
+            type: string
+            description: "Thread ID to retrieve"
+            required: true
+            maps_to: id
+        defaults:
+          userId: me
+          format: metadata
+          metadataHeaders: "From,Subject,Date,To"
+
+  calendar:
+    tool_name: manage_calendar
+    description: "List events, view agenda, check availability, or manage calendar events."
+    requires_email: true
+    gws_service: calendar
+    operations:
+
+      # --- Event viewing ---
+
+      list:
+        type: list
+        description: "upcoming events on primary calendar"
+        resource: events.list
+        params:
+          timeMin:
+            type: string
+            description: "Start of range (ISO 8601) — defaults to today"
+          timeMax:
+            type: string
+            description: "End of range (ISO 8601)"
+          maxResults:
+            type: number
+            description: "Max events (default: 10, max: 50)"
+            default: 10
+            max: 50
+          query:
+            type: string
+            description: "Free-text search terms to filter events"
+            maps_to: q
+        defaults:
+          calendarId: primary
+          singleEvents: true
+          orderBy: startTime
+
+      agenda:
+        type: list
+        description: "today's schedule at a glance (all calendars)"
+        helper: "+agenda"
+
+      get:
+        type: detail
+        description: "full event details by ID"
+        resource: events.get
+        params:
+          eventId:
+            type: string
+            description: "Event ID"
+            required: true
+        defaults:
+          calendarId: primary
+
+      # --- Event management ---
+
+      create:
+        type: action
+        description: "create a new calendar event"
+        helper: "+insert"
+        params:
+          summary:
+            type: string
+            description: "Event title"
+            required: true
+          start:
+            type: string
+            description: "Start time (ISO 8601)"
+            required: true
+          end:
+            type: string
+            description: "End time (ISO 8601)"
+            required: true
+          description:
+            type: string
+            description: "Event description or notes"
+          location:
+            type: string
+            description: "Event location"
+          attendees:
+            type: string
+            description: "Comma-separated attendee emails"
+        cli_args:
+          summary: "--summary"
+          start: "--start"
+          end: "--end"
+          description: "--description"
+          location: "--location"
+          attendees: "--attendees"
+
+      quickAdd:
+        type: action
+        description: "create event from natural language (e.g. 'Lunch with Alice tomorrow at noon')"
+        resource: events.quickAdd
+        params:
+          text:
+            type: string
+            description: "Natural language event description"
+            required: true
+        defaults:
+          calendarId: primary
+
+      update:
+        type: action
+        description: "update an existing event (patch semantics — only changed fields needed)"
+        resource: events.patch
+        params:
+          eventId:
+            type: string
+            description: "Event ID to update"
+            required: true
+          summary:
+            type: string
+            description: "Updated event title"
+          start:
+            type: string
+            description: "Updated start time (ISO 8601)"
+          end:
+            type: string
+            description: "Updated end time (ISO 8601)"
+          description:
+            type: string
+            description: "Updated description"
+          location:
+            type: string
+            description: "Updated location"
+        defaults:
+          calendarId: primary
+
+      delete:
+        type: action
+        description: "delete an event"
+        resource: events.delete
+        params:
+          eventId:
+            type: string
+            description: "Event ID to delete"
+            required: true
+        defaults:
+          calendarId: primary
+
+      # --- Calendar management ---
+
+      calendars:
+        type: list
+        description: "list all calendars the user has access to"
+        resource: calendarList.list
+
+      freebusy:
+        type: detail
+        description: "check availability (free/busy) for a time range"
+        resource: freebusy.query
+        params:
+          timeMin:
+            type: string
+            description: "Start of range (ISO 8601)"
+            required: true
+          timeMax:
+            type: string
+            description: "End of range (ISO 8601)"
+            required: true
+
+  drive:
+    tool_name: manage_drive
+    description: "Search, upload, download, share, or manage files in Google Drive."
+    requires_email: true
+    gws_service: drive
+    operations:
+
+      # --- File discovery ---
+
+      search:
+        type: list
+        description: "find files by query"
+        resource: files.list
+        params:
+          query:
+            type: string
+            description: "Drive search query (e.g. \"name contains 'budget'\" or \"mimeType='application/pdf'\")"
+            maps_to: q
+          maxResults:
+            type: number
+            description: "Max results (default: 10, max: 50)"
+            default: 10
+            max: 50
+            maps_to: pageSize
+        defaults:
+          fields: "files(id, name, mimeType, modifiedTime, size, webViewLink)"
+
+      get:
+        type: detail
+        description: "get file metadata"
+        resource: files.get
+        params:
+          fileId:
+            type: string
+            description: "File ID"
+            required: true
+        defaults:
+          fields: "id, name, mimeType, modifiedTime, size, webViewLink, owners, shared, parents"
+
+      # --- File operations ---
+
+      upload:
+        type: action
+        description: "upload a local file to Drive"
+        helper: "+upload"
+        params:
+          filePath:
+            type: string
+            description: "Local file path to upload"
+            required: true
+          name:
+            type: string
+            description: "File name in Drive (defaults to local name)"
+          parentFolderId:
+            type: string
+            description: "Destination folder ID"
+        cli_args:
+          name: "--name"
+          parentFolderId: "--parent"
+
+      download:
+        type: detail
+        description: "download file content to local path"
+        resource: files.get
+        params:
+          fileId:
+            type: string
+            description: "File ID to download"
+            required: true
+          outputPath:
+            type: string
+            description: "Local path to save the file"
+        defaults:
+          alt: media
+
+      copy:
+        type: action
+        description: "create a copy of a file"
+        resource: files.copy
+        params:
+          fileId:
+            type: string
+            description: "File ID to copy"
+            required: true
+          name:
+            type: string
+            description: "Name for the copy"
+
+      delete:
+        type: action
+        description: "permanently delete a file (cannot be undone)"
+        resource: files.delete
+        params:
+          fileId:
+            type: string
+            description: "File ID to delete"
+            required: true
+
+      export:
+        type: action
+        description: "export a Google Workspace document (Docs, Sheets, Slides) to a file format"
+        resource: files.export
+        params:
+          fileId:
+            type: string
+            description: "File ID to export"
+            required: true
+          mimeType:
+            type: string
+            description: "Target format (e.g. application/pdf, text/csv, text/plain, application/vnd.openxmlformats-officedocument.wordprocessingml.document)"
+            required: true
+          outputPath:
+            type: string
+            description: "Local path to save exported file"
+
+      # --- Sharing ---
+
+      listPermissions:
+        type: list
+        description: "list sharing permissions on a file"
+        resource: permissions.list
+        params:
+          fileId:
+            type: string
+            description: "File ID"
+            required: true
+
+      share:
+        type: action
+        description: "share a file with a user or group"
+        resource: permissions.create
+        params:
+          fileId:
+            type: string
+            description: "File ID to share"
+            required: true
+          shareEmail:
+            type: string
+            description: "Email address to share with"
+            required: true
+          role:
+            type: string
+            description: "Permission level"
+            enum: [reader, commenter, writer, organizer]
+            default: reader
+
+      unshare:
+        type: action
+        description: "remove sharing permission from a file"
+        resource: permissions.delete
+        params:
+          fileId:
+            type: string
+            description: "File ID"
+            required: true
+          permissionId:
+            type: string
+            description: "Permission ID to remove (from listPermissions)"
+            required: true
+
+  # ========================================================================
+  # Sheets
+  # ========================================================================
+
+  sheets:
+    tool_name: manage_sheets
+    description: "Read, write, and manage Google Sheets spreadsheets."
+    requires_email: true
+    gws_service: sheets
+    operations:
+
+      get:
+        type: detail
+        description: "get spreadsheet metadata and sheet names"
+        resource: spreadsheets.get
+        params:
+          spreadsheetId:
+            type: string
+            description: "Spreadsheet ID"
+            required: true
+
+      create:
+        type: action
+        description: "create a new empty spreadsheet"
+        resource: spreadsheets.create
+
+      read:
+        type: detail
+        description: "read cell values from a range"
+        helper: "+read"
+        params:
+          spreadsheetId:
+            type: string
+            description: "Spreadsheet ID"
+            required: true
+          range:
+            type: string
+            description: "Range to read (e.g. 'Sheet1!A1:D10' or just 'Sheet1')"
+            required: true
+        cli_args:
+          spreadsheetId: "--spreadsheet"
+          range: "--range"
+
+      append:
+        type: action
+        description: "append rows to a spreadsheet"
+        helper: "+append"
+        params:
+          spreadsheetId:
+            type: string
+            description: "Spreadsheet ID"
+            required: true
+          values:
+            type: string
+            description: "Comma-separated values for a single row (e.g. 'Alice,100,true')"
+          jsonValues:
+            type: string
+            description: "JSON array of rows for bulk insert (e.g. '[[\"a\",\"b\"],[\"c\",\"d\"]]')"
+        cli_args:
+          spreadsheetId: "--spreadsheet"
+          values: "--values"
+          jsonValues: "--json-values"
+
+      getValues:
+        type: detail
+        description: "get values from a specific range (raw API)"
+        resource: spreadsheets.values.get
+        params:
+          spreadsheetId:
+            type: string
+            description: "Spreadsheet ID"
+            required: true
+          range:
+            type: string
+            description: "A1 notation range (e.g. 'Sheet1!A1:B10')"
+            required: true
+
+      updateValues:
+        type: action
+        description: "write values to a specific range"
+        resource: spreadsheets.values.update
+        params:
+          spreadsheetId:
+            type: string
+            description: "Spreadsheet ID"
+            required: true
+          range:
+            type: string
+            description: "A1 notation range to write to"
+            required: true
+
+  # ========================================================================
+  # Docs
+  # ========================================================================
+
+  docs:
+    tool_name: manage_docs
+    description: "Read and write Google Docs documents."
+    requires_email: true
+    gws_service: docs
+    operations:
+
+      get:
+        type: detail
+        description: "get document content and metadata"
+        resource: documents.get
+        params:
+          documentId:
+            type: string
+            description: "Document ID"
+            required: true
+
+      create:
+        type: action
+        description: "create a new blank document"
+        resource: documents.create
+
+      write:
+        type: action
+        description: "append text to the end of a document"
+        helper: "+write"
+        params:
+          documentId:
+            type: string
+            description: "Document ID"
+            required: true
+          text:
+            type: string
+            description: "Text to append (plain text)"
+            required: true
+        cli_args:
+          documentId: "--document"
+          text: "--text"
+
+  # ========================================================================
+  # Tasks
+  # ========================================================================
+
+  tasks:
+    tool_name: manage_tasks
+    description: "Manage task lists and tasks in Google Tasks."
+    requires_email: true
+    gws_service: tasks
+    operations:
+
+      # --- Task lists ---
+
+      listTaskLists:
+        type: list
+        description: "list all task lists"
+        resource: tasklists.list
+
+      getTaskList:
+        type: detail
+        description: "get a task list by ID"
+        resource: tasklists.get
+        params:
+          taskListId:
+            type: string
+            description: "Task list ID"
+            required: true
+            maps_to: tasklist
+
+      createTaskList:
+        type: action
+        description: "create a new task list"
+        resource: tasklists.insert
+
+      deleteTaskList:
+        type: action
+        description: "delete a task list and all its tasks"
+        resource: tasklists.delete
+        params:
+          taskListId:
+            type: string
+            description: "Task list ID to delete"
+            required: true
+            maps_to: tasklist
+
+      # --- Tasks ---
+
+      list:
+        type: list
+        description: "list tasks in a task list"
+        resource: tasks.list
+        params:
+          taskListId:
+            type: string
+            description: "Task list ID (use listTaskLists to find)"
+            required: true
+            maps_to: tasklist
+          showCompleted:
+            type: boolean
+            description: "Include completed tasks (default: true)"
+          maxResults:
+            type: number
+            description: "Max tasks to return (default: 20, max: 100)"
+            default: 20
+            max: 100
+
+      get:
+        type: detail
+        description: "get a specific task"
+        resource: tasks.get
+        params:
+          taskListId:
+            type: string
+            description: "Task list ID"
+            required: true
+            maps_to: tasklist
+          taskId:
+            type: string
+            description: "Task ID"
+            required: true
+            maps_to: task
+
+      create:
+        type: action
+        description: "create a new task"
+        resource: tasks.insert
+        params:
+          taskListId:
+            type: string
+            description: "Task list ID"
+            required: true
+            maps_to: tasklist
+
+      update:
+        type: action
+        description: "update a task (patch semantics)"
+        resource: tasks.patch
+        params:
+          taskListId:
+            type: string
+            description: "Task list ID"
+            required: true
+            maps_to: tasklist
+          taskId:
+            type: string
+            description: "Task ID"
+            required: true
+            maps_to: task
+
+      complete:
+        type: action
+        description: "mark a task as completed"
+        resource: tasks.patch
+        params:
+          taskListId:
+            type: string
+            description: "Task list ID"
+            required: true
+            maps_to: tasklist
+          taskId:
+            type: string
+            description: "Task ID"
+            required: true
+            maps_to: task
+        defaults:
+          status: completed
+
+      delete:
+        type: action
+        description: "delete a task"
+        resource: tasks.delete
+        params:
+          taskListId:
+            type: string
+            description: "Task list ID"
+            required: true
+            maps_to: tasklist
+          taskId:
+            type: string
+            description: "Task ID to delete"
+            required: true
+            maps_to: task
+
+  # People (contacts) and Meet are excluded pending gws auth scope support.
+  # See https://github.com/googleworkspace/cli/issues/556
+  # Manifest entries ready at git tag pre-contacts-meet-removal if needed.