gmcp 0.5.0

data/lib/gmcp/calendar/event.rb

@@ -0,0 +1,95 @@
+module GMCP
+  module Calendar
+    class Event
+      include Him::Model
+
+      collection_path 'calendars/primary/events'
+      primary_key :id
+
+      parse_root_in_json true
+      root_element :items
+
+      attributes :id, :summary, :description, :start, :end, :location,
+                 :attendees, :status, :organizer, :recurringEventId, :htmlLink
+
+      DATE_ONLY = /\A\d{4}-\d{2}-\d{2}\z/
+
+      # PATCH, not PUT: PUT replaces the whole event and Google rejects one
+      # without start and end. The attendee list is sent whole because Google
+      # replaces arrays rather than merging them.
+      def rsvp!(response, calendar_id: 'primary')
+        list = (attendees || []).map { |a| a.to_h.transform_keys(&:to_s) }
+        me = list.find { |a| a['self'] }
+        raise ArgumentError, "this account is not an attendee of event #{id}, so it cannot RSVP" unless me
+
+        me['responseStatus'] = response.to_s
+        self.class.patch_raw(Apis.path('calendars', calendar_id, 'events', id), { attendees: list })
+      end
+
+      # The start as Google reports it: dateTime for timed events, date for
+      # all-day ones. The raw hash is unreadable in a listing.
+      def starts_at
+        return nil unless start.is_a?(Hash)
+
+        start[:dateTime] || start['dateTime'] || start[:date] || start['date']
+      end
+
+      class << self
+        # A YYYY-MM-DD value is an all-day event; anything else is a dateTime.
+        # Google wants exactly one of date or dateTime.
+        def time_field(value, time_zone: nil)
+          return { date: value } if value.to_s.match?(DATE_ONLY)
+
+          { dateTime: value, timeZone: time_zone }.compact
+        end
+
+        def fetch(event_id, calendar_id: 'primary')
+          get_resource(Apis.path('calendars', calendar_id, 'events', event_id))
+        end
+
+        def list(**options)
+          list_page(**options)[:events]
+        end
+
+        # Returns { events:, next_page_token: }; next_page_token is nil on the
+        # last page. get_collection would drop the cursor.
+        def list_page(calendar_id: 'primary', time_min: nil, time_max: nil, max_results: 20, page_token: nil)
+          params = { maxResults: max_results, singleEvents: true, orderBy: 'startTime' }
+          params[:timeMin]   = time_min   if time_min
+          params[:timeMax]   = time_max   if time_max
+          params[:pageToken] = page_token if page_token && !page_token.to_s.empty?
+
+          get_raw(Apis.path('calendars', calendar_id, 'events'), params) do |parsed, _response|
+            data = parsed[:data] || {}
+            {
+              events:          (data[:items] || []).map { |e| new(e) },
+              next_page_token: data[:nextPageToken]
+            }
+          end
+        end
+
+        # sendUpdates is a query parameter, and him sends non-GET params as the
+        # body, so it rides on the path. Without it Google adds attendees
+        # silently and nobody is invited.
+        def create_event(calendar_id: 'primary', **attrs)
+          post_raw(with_updates(Apis.path('calendars', calendar_id, 'events'), attrs), attrs)
+        end
+
+        def update_event(event_id:, calendar_id: 'primary', **attrs)
+          patch_raw(with_updates(Apis.path('calendars', calendar_id, 'events', event_id), attrs), attrs)
+        end
+
+        def delete_event(event_id:, calendar_id: 'primary')
+          delete_raw(Apis.path('calendars', calendar_id, 'events', event_id), {})
+        end
+
+        private
+
+        def with_updates(base, attrs)
+          attendees = attrs[:attendees]
+          attendees.nil? || attendees.empty? ? base : "#{base}?sendUpdates=all"
+        end
+      end
+    end
+  end
+end

data/lib/gmcp/calendar/tools.rb

@@ -0,0 +1,150 @@
+require 'mcp'
+require 'time'
+
+module GMCP
+  module Calendar
+    module Tools
+      def self.register(server)
+        ToolHelpers.account_tool(
+          server,
+          name: 'calendar_list_calendars',
+          capability: 'calendar.read',
+          description: 'List all calendars on the account',
+          properties: {}
+        ) do
+          ToolHelpers.list_response(Calendar.all, empty_message: 'No calendars found.') do |c|
+            "#{c.id}: #{c.summary}#{c.primary ? ' [primary]' : ''}"
+          end
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'calendar_list_events',
+          capability: 'calendar.read',
+          description: 'List events from a calendar within an optional time range. ' \
+                       'Returns a page_token when more results exist; pass it back to get the next page.',
+          properties: {
+            calendar_id: { type: 'string', description: 'Calendar ID (default: primary)' },
+            time_min:    { type: 'string', description: 'RFC3339 start of range (default: now), e.g. 2025-01-01T00:00:00Z' },
+            time_max:    { type: 'string', description: 'RFC3339 end of range' },
+            max_results: { type: 'integer' },
+            page_token:  { type: 'string', description: 'Cursor from a previous call. Omit for the first page.' }
+          }
+        ) do |calendar_id: 'primary', time_min: nil, time_max: nil, max_results: 20, page_token: nil|
+          # Without a lower bound Google starts at the calendar's first event,
+          # which can be decades back; "list events" means upcoming ones.
+          time_min ||= Time.now.utc.iso8601
+          page = Event.list_page(calendar_id: calendar_id, time_min: time_min, time_max: time_max,
+                                 max_results: max_results, page_token: page_token)
+          lines = page[:events].map { |e| "#{e.id}: #{e.summary} (#{e.starts_at})" }
+          body  = lines.empty? ? 'No events found.' : lines.join("\n")
+          body += "\n\nMore results available. next page_token: #{page[:next_page_token]}" if page[:next_page_token]
+          ToolHelpers.text_response(body)
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'calendar_get_event',
+          capability: 'calendar.read',
+          description: 'Get a calendar event by ID',
+          properties: {
+            event_id:    { type: 'string' },
+            calendar_id: { type: 'string', description: 'Calendar ID (default: primary)' }
+          },
+          required: ['event_id']
+        ) do |event_id:, calendar_id: 'primary'|
+          ToolHelpers.json_response(Event.fetch(event_id, calendar_id: calendar_id))
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'calendar_create_event',
+          capability: 'calendar.write',
+          description: 'Create a calendar event. Pass YYYY-MM-DD dates for an all-day event (the end date is ' \
+                       'exclusive). Attendees are sent invitations.',
+          properties: {
+            summary:     { type: 'string' },
+            start_time:  { type: 'string', description: 'RFC3339 datetime, e.g. 2025-06-01T10:00:00-07:00, or YYYY-MM-DD for all-day' },
+            end_time:    { type: 'string', description: 'RFC3339 datetime, or YYYY-MM-DD (exclusive) for all-day' },
+            time_zone:   { type: 'string', description: 'IANA time zone for timed events, e.g. America/Denver' },
+            description: { type: 'string' },
+            location:    { type: 'string' },
+            attendees:   { type: 'array', items: { type: 'string' }, description: 'Email addresses; each is sent an invitation' },
+            calendar_id: { type: 'string' }
+          },
+          required: ['summary', 'start_time', 'end_time']
+        ) do |summary:, start_time:, end_time:, time_zone: nil, description: nil, location: nil, attendees: [], calendar_id: 'primary'|
+          attrs = {
+            summary:   summary,
+            start:     Event.time_field(start_time, time_zone: time_zone),
+            end:       Event.time_field(end_time, time_zone: time_zone),
+            attendees: attendees.map { |e| { email: e } }
+          }
+          attrs[:description] = description if description
+          attrs[:location]    = location    if location
+          Event.create_event(calendar_id: calendar_id, **attrs)
+          ToolHelpers.text_response("Event '#{summary}' created.")
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'calendar_update_event',
+          capability: 'calendar.write',
+          description: 'Update fields on an existing calendar event. Pass YYYY-MM-DD dates to make it all-day ' \
+                       '(the end date is exclusive).',
+          properties: {
+            event_id:    { type: 'string' },
+            summary:     { type: 'string' },
+            start_time:  { type: 'string', description: 'RFC3339 datetime, or YYYY-MM-DD for all-day' },
+            end_time:    { type: 'string', description: 'RFC3339 datetime, or YYYY-MM-DD (exclusive) for all-day' },
+            time_zone:   { type: 'string', description: 'IANA time zone for timed events, e.g. America/Denver' },
+            description: { type: 'string' },
+            location:    { type: 'string' },
+            calendar_id: { type: 'string' }
+          },
+          required: ['event_id']
+        ) do |event_id:, calendar_id: 'primary', summary: nil, start_time: nil, end_time: nil, time_zone: nil, description: nil, location: nil|
+          attrs = {}
+          attrs[:summary]     = summary                                            if summary
+          attrs[:start]       = Event.time_field(start_time, time_zone: time_zone) if start_time
+          attrs[:end]         = Event.time_field(end_time, time_zone: time_zone)   if end_time
+          attrs[:description] = description                                        if description
+          attrs[:location]    = location                                           if location
+          Event.update_event(event_id: event_id, calendar_id: calendar_id, **attrs)
+          ToolHelpers.text_response("Event #{event_id} updated.")
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'calendar_delete_event',
+          capability: 'calendar.delete',
+          description: 'Delete a calendar event',
+          properties: {
+            event_id:    { type: 'string' },
+            calendar_id: { type: 'string' }
+          },
+          required: ['event_id']
+        ) do |event_id:, calendar_id: 'primary'|
+          Event.delete_event(event_id: event_id, calendar_id: calendar_id)
+          ToolHelpers.text_response("Event #{event_id} deleted.")
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'calendar_rsvp',
+          capability: 'calendar.write',
+          description: 'RSVP to a calendar event (accepted, declined, tentative). The account must be an attendee.',
+          properties: {
+            event_id:    { type: 'string' },
+            response:    { type: 'string', enum: %w[accepted declined tentative] },
+            calendar_id: { type: 'string', description: 'Calendar ID (default: primary)' }
+          },
+          required: ['event_id', 'response']
+        ) do |event_id:, response:, calendar_id: 'primary'|
+          Event.fetch(event_id, calendar_id: calendar_id).rsvp!(response, calendar_id: calendar_id)
+          ToolHelpers.text_response("RSVP'd #{response} to event #{event_id}.")
+        end
+      end
+    end
+  end
+end

data/lib/gmcp/capabilities.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module GMCP
+  # Capability gating for tool registration.
+  #
+  # GMCP fits a grant-based permission model in which a grant is
+  # `(identity, connector_account, capabilities[])`. GMCP honors the two axes:
+  #
+  #   connector_account → GMCP_ACCOUNTS  (which mailboxes this process can reach)
+  #   capabilities      → GMCP_CAPABILITIES (which verbs this process exposes)
+  #
+  # Gating happens at REGISTRATION, not invocation: a tool whose capability was
+  # not granted is never defined on the MCP server, so it never appears in
+  # tools/list and cannot be called no matter what the client sends. That is
+  # deliberately stronger than a client-side --allowedTools flag, which depends
+  # on the launcher assembling it correctly and the client honoring it.
+  #
+  # ── nil vs empty string is load-bearing ────────────────────────────────────
+  #
+  #   GMCP_CAPABILITIES unset (nil) → every capability. For a human running
+  #                                   bin/gmcp directly with no grant system.
+  #   GMCP_CAPABILITIES=""          → NO capabilities. The explicit empty grant
+  #                                   set for an identity that was granted
+  #                                   nothing.
+  #
+  # A launcher must therefore ALWAYS set the variable explicitly, including when
+  # the grant set is empty. Omitting it conditionally ("no grants, so skip the
+  # env var") fails open and hands the agent everything.
+  module Capabilities
+    # Loaded from config/capabilities.yml — that file is the source of truth,
+    # and spec/gmcp/capability_manifest_spec.rb asserts it matches the tools
+    # actually registered in lib/.
+    MANIFEST_PATH = "config/capabilities.yml"
+
+    def self.manifest
+      @manifest ||= YAML.load_file(GMCP.root(MANIFEST_PATH)).freeze
+    end
+
+    # gmail / google_calendar / drive / voice are separate
+    # connectors. One GMCP process serves all of them, and they do NOT share
+    # account semantics — see ACCOUNT_SCOPING.
+    def self.connectors
+      @connectors ||= manifest.fetch("connectors").freeze
+    end
+
+    # Whether GMCP_ACCOUNTS constrains which principal a connector reaches.
+    #
+    #   enforced — it does; a grant's connector_account means what it says.
+    #   ignored  — it does not; the principal is resolved outside GMCP, and a
+    #              grant's connector_account is decorative for that connector.
+    ACCOUNT_SCOPING = %w[enforced ignored].freeze
+
+    # Where a connector's credential lives. Voice is `delegated`: Chrome holds
+    # its session.
+    CREDENTIAL_SOURCES = %w[local_file keychain delegated none].freeze
+
+    def self.declared
+      @declared ||= connectors.flat_map { |c| c.fetch("capabilities").map { |x| x.fetch("name") } }.freeze
+    end
+
+    # capability name => the connector hash that declares it
+    def self.connector_index
+      @connector_index ||= connectors.each_with_object({}) do |connector, index|
+        connector.fetch("capabilities").each { |cap| index[cap.fetch("name")] = connector }
+      end.freeze
+    end
+
+    def self.connector_for(capability)
+      connector_index[capability]
+    end
+
+    def self.account_scoping_for(capability)
+      connector_for(capability)&.fetch("account_scoping")
+    end
+
+    # Granted capabilities whose connector ignores GMCP_ACCOUNTS. These reach a
+    # principal this process cannot narrow, so bin/gmcp says so on startup
+    # rather than letting the account list imply a containment it does not have.
+    def self.unscoped_grants
+      granted.select { |cap| account_scoping_for(cap) == "ignored" }
+    end
+
+    ALL = declared
+
+    ENV_VAR = 'GMCP_CAPABILITIES'
+
+    class << self
+      def granted
+        @granted ||= parse(ENV.fetch(ENV_VAR, nil))
+      end
+
+      def enabled?(capability)
+        return true if capability.nil?
+
+        granted.include?(capability)
+      end
+
+      # Human-readable summary, used by bin/gmcp on startup so the operator can
+      # see what this process is actually able to do.
+      def summary
+        if unrestricted?
+          "all (#{ALL.length} capabilities; #{ENV_VAR} not set)"
+        elsif granted.empty?
+          "none (#{ENV_VAR} set but empty)"
+        else
+          granted.join(', ')
+        end
+      end
+
+      def unrestricted?
+        ENV.fetch(ENV_VAR, nil).nil?
+      end
+
+      # Test seam — capability state is read once and memoized.
+      def reset!
+        @granted = nil
+      end
+
+      private
+
+      def parse(raw)
+        return ALL.dup if raw.nil?
+
+        requested = raw.split(',').map(&:strip).reject(&:empty?)
+        unknown   = requested - ALL
+        warn "GMCP: ignoring unknown #{ENV_VAR} entries: #{unknown.join(', ')}" if unknown.any?
+        requested & ALL
+      end
+    end
+  end
+end

data/lib/gmcp/drive/file.rb

@@ -0,0 +1,145 @@
+module GMCP
+  module Drive
+    class File
+      include Him::Model
+
+      collection_path 'files'
+      primary_key :id
+
+      parse_root_in_json true
+      root_element :files
+
+      attributes :id, :name, :mimeType, :description, :parents, :size,
+                 :webViewLink, :webContentLink, :createdTime, :modifiedTime
+
+      # Large enough for any document worth reading into a conversation, small
+      # enough not to flood one.
+      MAX_BYTES = 1_048_576
+
+      # Google-native files have no bytes of their own; they must be exported.
+      EXPORTS = {
+        'application/vnd.google-apps.document'     => 'text/plain',
+        'application/vnd.google-apps.spreadsheet'  => 'text/csv',
+        'application/vnd.google-apps.presentation' => 'text/plain'
+      }.freeze
+
+      GOOGLE_APPS = 'application/vnd.google-apps.'
+
+      TEXT_TYPES = %w[
+        application/json application/xml application/javascript application/x-javascript
+        application/yaml application/x-yaml application/sql application/x-sh
+        application/csv application/x-httpd-php application/toml
+      ].freeze
+
+      LIST_FIELDS = 'nextPageToken,files(id,name,mimeType,size,modifiedTime,webViewLink)'
+
+      class << self
+        def search(query, **options)
+          search_page(query, **options)[:files]
+        end
+
+        # Returns { files:, next_page_token: }; next_page_token is nil on the
+        # last page. get_collection would drop the cursor, and `fields` must
+        # name nextPageToken or Google leaves it out.
+        #
+        # Without the all-drives flags, files on shared drives are invisible.
+        def search_page(query, max_results: 20, order_by: 'modifiedTime desc', page_token: nil)
+          params = {
+            q: query, pageSize: max_results, orderBy: order_by, fields: LIST_FIELDS,
+            supportsAllDrives: true, includeItemsFromAllDrives: true
+          }
+          params[:pageToken] = page_token if page_token && !page_token.to_s.empty?
+
+          get_raw('files', params) do |parsed, _response|
+            data = parsed[:data] || {}
+            {
+              files:           (data[:files] || []).map { |f| new(f) },
+              next_page_token: data[:nextPageToken]
+            }
+          end
+        end
+
+        def list_folder(folder_id, **options)
+          search("#{quote(folder_id)} in parents and trashed=false", **options)
+        end
+
+        def list_folder_page(folder_id, **options)
+          search_page("#{quote(folder_id)} in parents and trashed=false", **options)
+        end
+
+        # A value as a Drive query string literal. An unescaped quote in an id
+        # would end the literal and let the rest rewrite the query.
+        def quote(value)
+          "'#{value.to_s.gsub(/[\\']/) { |c| "\\#{c}" }}'"
+        end
+
+        # The file's content as text: Google-native files exported, text files
+        # downloaded. Raises ArgumentError for anything that is not text or is
+        # too large, since there is no useful way to hand either to a model.
+        def read_text(file_id)
+          meta = metadata(file_id)
+          mime = meta[:mimeType].to_s
+          name = meta[:name] || file_id
+
+          body =
+            if mime.start_with?(GOOGLE_APPS)
+              export = EXPORTS[mime]
+              raise ArgumentError, "#{name} is a #{mime}, which cannot be exported as text" unless export
+
+              raw_get(Apis.path('files', file_id, 'export'), mimeType: export)
+            else
+              raise ArgumentError, "#{name} is #{mime.empty? ? 'of unknown type' : mime}, not text" unless text?(mime)
+              raise ArgumentError, too_large(name, meta[:size].to_i) if meta[:size].to_i > MAX_BYTES
+
+              raw_get(Apis.path('files', file_id), alt: 'media', supportsAllDrives: true)
+            end
+
+          # Exports report no size up front.
+          raise ArgumentError, too_large(name, body.bytesize) if body.bytesize > MAX_BYTES
+
+          to_utf8(body)
+        end
+
+        def metadata(file_id)
+          get_raw(Apis.path('files', file_id), fields: 'id,name,mimeType,size', supportsAllDrives: true) do |parsed, _response|
+            parsed[:data] || {}
+          end
+        end
+
+        def text?(mime)
+          mime.start_with?('text/') || TEXT_TYPES.include?(mime) || mime.end_with?('+json', '+xml')
+        end
+
+        private
+
+        def too_large(name, bytes)
+          "#{name} is #{bytes} bytes; drive_read_file reads at most #{MAX_BYTES}"
+        end
+
+        # GET through the bound API's own middleware (bearer token, ApiError,
+        # adapter) minus him's JSON parser, which raises on a text body and
+        # turns a JSON file into a parsed hash. Built from the stack rather than
+        # a fresh Faraday connection so token refresh and error handling stay
+        # in one place.
+        def raw_get(request_path, params = {})
+          connection = her_api.connection
+          builder    = connection.builder
+          app = builder.handlers
+                       .reject { |handler| handler.klass <= Him::Middleware::ParseJSON }
+                       .reverse
+                       .inject(builder.adapter.build) { |inner, handler| handler.build(inner) }
+          request = connection.build_request(:get) { |req| req.url(request_path, params) }
+          app.call(builder.build_env(connection, request)).body.to_s
+        end
+
+        # Drive does not report a charset for most text files; UTF-8 is the
+        # overwhelming case, and invalid bytes are dropped rather than failing
+        # the whole read.
+        def to_utf8(body)
+          text = body.dup.force_encoding(Encoding::UTF_8)
+          text.valid_encoding? ? text : text.scrub('')
+        end
+      end
+    end
+  end
+end

data/lib/gmcp/drive/tools.rb

@@ -0,0 +1,64 @@
+require 'mcp'
+
+module GMCP
+  module Drive
+    module Tools
+      def self.register(server)
+        ToolHelpers.account_tool(
+          server,
+          name: 'drive_search',
+          capability: 'drive.read',
+          description: 'Search Google Drive files, including shared drives, using a Drive query string. ' \
+                       'Returns a page_token when more results exist; pass it back to get the next page.',
+          properties: {
+            query:       { type: 'string', description: "Drive query, e.g. \"name contains 'report' and mimeType='application/pdf'\"" },
+            max_results: { type: 'integer' },
+            page_token:  { type: 'string', description: 'Cursor from a previous call. Omit for the first page.' }
+          },
+          required: ['query']
+        ) do |query:, max_results: 20, page_token: nil|
+          page = File.search_page(query, max_results: max_results, page_token: page_token)
+          Tools.listing(page, 'No files found.')
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'drive_list_folder',
+          capability: 'drive.read',
+          description: 'List files in a Drive folder. ' \
+                       'Returns a page_token when more results exist; pass it back to get the next page.',
+          properties: {
+            folder_id:   { type: 'string', description: 'Drive folder ID or "root"' },
+            max_results: { type: 'integer' },
+            page_token:  { type: 'string', description: 'Cursor from a previous call. Omit for the first page.' }
+          },
+          required: ['folder_id']
+        ) do |folder_id:, max_results: 50, page_token: nil|
+          page = File.list_folder_page(folder_id, max_results: max_results, page_token: page_token)
+          Tools.listing(page, 'Folder is empty.')
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'drive_read_file',
+          capability: 'drive.read',
+          description: 'Read a Drive file as text. Google Docs and Slides export as plain text, Sheets as CSV ' \
+                       '(first sheet only). Other files must be text and at most 1 MB; binaries are refused.',
+          properties: {
+            file_id: { type: 'string' }
+          },
+          required: ['file_id']
+        ) do |file_id:|
+          ToolHelpers.text_response(File.read_text(file_id))
+        end
+      end
+
+      def self.listing(page, empty_message)
+        lines = page[:files].map { |f| "#{f.id}: #{f.name} (#{f.mimeType})" }
+        body  = lines.empty? ? empty_message : lines.join("\n")
+        body += "\n\nMore results available. next page_token: #{page[:next_page_token]}" if page[:next_page_token]
+        ToolHelpers.text_response(body)
+      end
+    end
+  end
+end

data/lib/gmcp/gmail/draft.rb

@@ -0,0 +1,21 @@
+module GMCP
+  module Gmail
+    class Draft
+      include Him::Model
+
+      collection_path 'drafts'
+      primary_key :id
+
+      parse_root_in_json true
+      root_element :drafts
+
+      attributes :id, :message
+
+      class << self
+        def create_draft(to:, subject:, body:)
+          post_raw('drafts', { message: { raw: Mime.build(to: to, subject: subject, body: body) } })
+        end
+      end
+    end
+  end
+end

data/lib/gmcp/gmail/label.rb

@@ -0,0 +1,16 @@
+module GMCP
+  module Gmail
+    class Label
+      include Him::Model
+
+      collection_path 'labels'
+      primary_key :id
+
+      parse_root_in_json true
+      root_element :labels
+
+      attributes :id, :name, :messageListVisibility, :labelListVisibility, :type,
+                 :messagesTotal, :messagesUnread, :threadsTotal, :threadsUnread
+    end
+  end
+end