gmcp 0.5.0

data/lib/gmcp/gmail/tools.rb

@@ -0,0 +1,364 @@
+require 'mcp'
+
+module GMCP
+  module Gmail
+    module Tools
+      def self.register(server)
+        register_read(server)
+        register_write(server)
+        register_bulk(server)
+        register_attachments(server)
+        register_unsubscribe(server)
+      end
+
+      def self.register_read(server)
+        ToolHelpers.account_tool(
+          server,
+          name: 'gmail_search',
+          capability: 'gmail.read',
+          description: 'Search Gmail messages using a query string (same syntax as Gmail search box). ' \
+                       'Returns one line per message: id, date, from, subject. ' \
+                       'Returns a page_token when more results exist; pass it back to get the next page.',
+          properties: {
+            query:       { type: 'string', description: 'Gmail search query, e.g. "from:alice subject:report"' },
+            max_results: { type: 'integer', description: 'Max messages per page (default 20, Gmail caps at 500)' },
+            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|
+          Tools.search(query: query, max_results: max_results, page_token: page_token)
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'gmail_get_message',
+          capability: 'gmail.read',
+          description: 'Get a Gmail message by ID, with decoded headers and body text',
+          properties: {
+            message_id: { type: 'string' }
+          },
+          required: ['message_id']
+        ) do |message_id:|
+          ToolHelpers.json_response(Message.find(message_id).to_summary)
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'gmail_list_labels',
+          capability: 'gmail.read',
+          description: 'List all Gmail labels',
+          properties: {}
+        ) do
+          ToolHelpers.list_response(Label.all, empty_message: 'No labels found.') { |l| "#{l.id}: #{l.name}" }
+        end
+      end
+
+      def self.register_write(server)
+        ToolHelpers.account_tool(
+          server,
+          name: 'gmail_trash_message',
+          capability: 'gmail.trash',
+          description: 'Move a Gmail message to trash',
+          properties: {
+            message_id: { type: 'string' }
+          },
+          required: ['message_id']
+        ) do |message_id:|
+          Message.find(message_id).trash!
+          ToolHelpers.text_response("Message #{message_id} moved to trash.")
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'gmail_archive_message',
+          capability: 'gmail.modify_labels',
+          description: 'Archive a Gmail message (remove from INBOX)',
+          properties: {
+            message_id: { type: 'string' }
+          },
+          required: ['message_id']
+        ) do |message_id:|
+          Message.find(message_id).archive!
+          ToolHelpers.text_response("Message #{message_id} archived.")
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'gmail_label_message',
+          capability: 'gmail.modify_labels',
+          description: 'Add and/or remove labels on a Gmail message',
+          properties: {
+            message_id:       { type: 'string' },
+            add_label_ids:    { type: 'array', items: { type: 'string' }, description: 'Label IDs to add' },
+            remove_label_ids: { type: 'array', items: { type: 'string' }, description: 'Label IDs to remove' }
+          },
+          required: ['message_id']
+        ) do |message_id:, add_label_ids: [], remove_label_ids: []|
+          Message.find(message_id).modify!(addLabelIds: add_label_ids, removeLabelIds: remove_label_ids)
+          ToolHelpers.text_response("Labels updated on #{message_id}.")
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'gmail_send',
+          capability: 'gmail.send',
+          description: 'Send a new email',
+          properties: {
+            to:      { type: 'string', description: 'Recipient email address' },
+            subject: { type: 'string' },
+            body:    { type: 'string', description: 'Plain-text message body' }
+          },
+          required: ['to', 'subject', 'body']
+        ) do |to:, subject:, body:|
+          Message.send_message(to: to, subject: subject, body: body)
+          ToolHelpers.text_response("Message sent to #{to}.")
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'gmail_create_draft',
+          capability: 'gmail.send',
+          description: 'Create a Gmail draft',
+          properties: {
+            to:      { type: 'string' },
+            subject: { type: 'string' },
+            body:    { type: 'string' }
+          },
+          required: ['to', 'subject', 'body']
+        ) do |to:, subject:, body:|
+          Draft.create_draft(to: to, subject: subject, body: body)
+          ToolHelpers.text_response('Draft created.')
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'gmail_reply',
+          capability: 'gmail.send',
+          description: 'Reply to a Gmail message',
+          properties: {
+            message_id: { type: 'string' },
+            body:       { type: 'string', description: 'Reply body (plain text)' }
+          },
+          required: ['message_id', 'body']
+        ) do |message_id:, body:|
+          Message.metadata(message_id, headers: Message::REPLY_HEADERS).reply!(body: body)
+          ToolHelpers.text_response('Reply sent.')
+        end
+      end
+
+      # ── bulk operations ─────────────────────────────────────────────────
+      #
+      # One request for up to 1000 messages. Without these, acting on a
+      # triage result means one round trip per message.
+      def self.register_bulk(server)
+        ToolHelpers.account_tool(
+          server,
+          name: 'gmail_batch_archive',
+          capability: 'gmail.modify_labels',
+          description: 'Archive many messages at once (removes INBOX). Up to 1000 ids per call. Reversible.',
+          properties: {
+            message_ids: { type: 'array', items: { type: 'string' }, description: 'Message IDs to archive' }
+          },
+          required: ['message_ids']
+        ) do |message_ids:|
+          Tools.batching(message_ids) do |ids|
+            Message.batch_archive(ids: ids)
+            "Archived #{ids.length} message(s)."
+          end
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'gmail_batch_trash',
+          capability: 'gmail.trash',
+          description: 'Move many messages to trash at once. Up to 1000 ids per call. ' \
+                       'Recoverable for 30 days, after which Gmail deletes them permanently.',
+          properties: {
+            message_ids: { type: 'array', items: { type: 'string' }, description: 'Message IDs to trash' }
+          },
+          required: ['message_ids']
+        ) do |message_ids:|
+          Tools.batching(message_ids) do |ids|
+            Message.batch_trash(ids: ids)
+            "Moved #{ids.length} message(s) to trash. Recoverable for 30 days."
+          end
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'gmail_batch_modify',
+          capability: 'gmail.modify_labels',
+          description: 'Add and/or remove labels on many messages at once. Up to 1000 ids per call.',
+          properties: {
+            message_ids:      { type: 'array', items: { type: 'string' } },
+            add_label_ids:    { type: 'array', items: { type: 'string' }, description: 'Label IDs to add' },
+            remove_label_ids: { type: 'array', items: { type: 'string' }, description: 'Label IDs to remove' }
+          },
+          required: ['message_ids']
+        ) do |message_ids:, add_label_ids: [], remove_label_ids: []|
+          if add_label_ids.empty? && remove_label_ids.empty?
+            next ToolHelpers.error_response('Nothing to do: no labels to add or remove.')
+          end
+          Tools.batching(message_ids) do |ids|
+            Message.batch_modify(ids: ids, add_label_ids: add_label_ids, remove_label_ids: remove_label_ids)
+            "Updated labels on #{ids.length} message(s)."
+          end
+        end
+      end
+
+      # ── attachments ─────────────────────────────────────────────────────
+      def self.register_attachments(server)
+        ToolHelpers.account_tool(
+          server,
+          name: 'gmail_list_attachments',
+          capability: 'gmail.read',
+          description: 'List the attachments on a message: part_id (needed to download it), filename, type and size.',
+          properties: {
+            message_id: { type: 'string' }
+          },
+          required: ['message_id']
+        ) do |message_id:|
+          found = Message.attachments(message_id)
+          ToolHelpers.list_response(found, empty_message: 'No attachments on this message.') do |a|
+            "part_id #{a[:part_id]}  #{a[:filename]}  (#{a[:mime_type]}, #{a[:size]} bytes)"
+          end
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'gmail_download_attachment',
+          capability: 'gmail.download',
+          description: 'Download an attachment to a local directory. Get the part_id from gmail_list_attachments.',
+          properties: {
+            message_id:    { type: 'string' },
+            part_id:       { type: 'string', description: 'From gmail_list_attachments. Names the file after the attachment.' },
+            attachment_id: { type: 'string', description: 'Raw Gmail attachment id, instead of part_id. ' \
+                                                         'Carries no filename, so pass filename too.' },
+            dest_dir:      { type: 'string', description: 'Existing directory to write into. Required — there is no default.' },
+            filename:      { type: 'string', description: 'Override the filename. Defaults to the name on the attachment.' }
+          },
+          required: %w[message_id dest_dir]
+        ) do |message_id:, dest_dir:, part_id: nil, attachment_id: nil, filename: nil|
+          Tools.download_attachment_to(
+            message_id: message_id, part_id: part_id, attachment_id: attachment_id,
+            dest_dir: dest_dir, filename: filename
+          )
+        end
+      end
+
+      # ── unsubscribe ─────────────────────────────────────────────────────
+      def self.register_unsubscribe(server)
+        ToolHelpers.account_tool(
+          server,
+          name: 'gmail_unsubscribe_info',
+          capability: 'gmail.read',
+          description: 'Show the List-Unsubscribe options a message offers, and whether one-click (RFC 8058) is supported.',
+          properties: {
+            message_id: { type: 'string' }
+          },
+          required: ['message_id']
+        ) do |message_id:|
+          details = Unsubscribe.info(message_id)
+          next ToolHelpers.text_response('This message offers no List-Unsubscribe header.') if details.nil?
+
+          ToolHelpers.text_response([
+            "one-click (RFC 8058): #{details[:one_click] ? 'yes' : 'no'}",
+            "https:  #{details[:https] || '(none)'}",
+            "http:   #{details[:http] || '(none)'}",
+            "mailto: #{details[:mailto] || '(none)'}"
+          ].join("\n"))
+        end
+
+        ToolHelpers.account_tool(
+          server,
+          name: 'gmail_unsubscribe',
+          capability: 'gmail.unsubscribe',
+          description: 'Unsubscribe from a sender via RFC 8058 one-click, using the URL in the message\'s own ' \
+                       'List-Unsubscribe header. https only. Note this confirms to the sender that the address is live.',
+          properties: {
+            message_id: { type: 'string', description: 'A message from the sender you want to stop hearing from' }
+          },
+          required: ['message_id']
+        ) do |message_id:|
+          code = Unsubscribe.one_click!(message_id)
+          ToolHelpers.text_response("Unsubscribe request accepted (HTTP #{code}).")
+        # Expected outcomes, not faults: say what happened in the user's terms
+        # instead of guarded's class name and a backtrace on stderr.
+        rescue Unsubscribe::NotSupported => e
+          ToolHelpers.error_response("Cannot one-click unsubscribe: #{e.message}")
+        rescue Unsubscribe::Failed => e
+          ToolHelpers.error_response("Unsubscribe failed: #{e.message}")
+        end
+      end
+
+      class << self
+        # One line per message — id, date, sender, subject — so a caller can
+        # triage a page without a follow-up fetch per result.
+        def search(query:, max_results: 20, page_token: nil)
+          page     = Message.search_page(query, max_results: max_results, page_token: page_token)
+          messages = Message.metadata_for(page[:messages].map(&:id), headers: Message::SEARCH_HEADERS)
+
+          lines = messages.map do |m|
+            [m.id, m.header('Date'), m.header('From'), m.header('Subject')].compact.join('  ')
+          end
+          body = lines.empty? ? 'No messages found.' : lines.join("\n")
+          if page[:next_page_token]
+            body += "\n\nMore results available. next page_token: #{page[:next_page_token]}"
+          end
+          body += "\n(Gmail estimates ~#{page[:estimate]} total matches; the estimate is approximate.)" if page[:estimate]
+          ToolHelpers.text_response(body)
+        end
+
+        # Shared shape for the batch tools: clean the id set and refuse an
+        # empty one before any request. Gmail's own limit is enforced, not
+        # truncated, by Message.batch_modify.
+        def batching(ids)
+          ids = Array(ids).map { |i| i.to_s.strip }.reject(&:empty?).uniq
+          return ToolHelpers.error_response('No message ids given.') if ids.empty?
+
+          ToolHelpers.text_response(yield(ids))
+        end
+
+        # part_id is the normal route: one listing yields both the filename and
+        # a current attachmentId. A bare attachment_id cannot be named from a
+        # listing, because Gmail reissues the id on every fetch.
+        def download_attachment_to(message_id:, dest_dir:, part_id: nil, attachment_id: nil, filename: nil)
+          dir = ::File.expand_path(dest_dir)
+          return ToolHelpers.error_response("Not a directory: #{dir}") unless ::File.directory?(dir)
+          if blank?(part_id) && blank?(attachment_id)
+            return ToolHelpers.error_response('Pass part_id (from gmail_list_attachments) or attachment_id.')
+          end
+
+          if blank?(part_id)
+            fallback = "#{message_id}-#{attachment_id[0, 12]}.bin"
+          else
+            found         = Message.attachment(message_id, part_id: part_id)
+            attachment_id = found[:attachment_id]
+            fallback      = found[:filename]
+          end
+
+          name = ::File.basename((blank?(filename) ? fallback : filename).to_s)
+          return ToolHelpers.error_response('Refusing to write: unusable filename.') if name.empty? || name == '.' || name == '..'
+
+          path = ::File.expand_path(::File.join(dir, name))
+          # basename should make this unreachable; belt and braces against a
+          # filename that escapes the destination.
+          unless path.start_with?(dir + ::File::SEPARATOR)
+            return ToolHelpers.error_response('Refusing to write outside the destination directory.')
+          end
+          return ToolHelpers.error_response("Refusing to overwrite existing file: #{path}") if ::File.exist?(path)
+
+          bytes = Message.download_attachment(message_id: message_id, attachment_id: attachment_id)
+          ::File.binwrite(path, bytes)
+          ToolHelpers.text_response("Wrote #{bytes.bytesize} bytes to #{path}")
+        end
+
+        private
+
+        def blank?(value)
+          value.nil? || value.to_s.strip.empty?
+        end
+      end
+    end
+  end
+end

data/lib/gmcp/gmail/unsubscribe.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+
+module GMCP
+  module Gmail
+    # RFC 8058 one-click unsubscribe.
+    #
+    # This is the one place GMCP talks to a host that is not Google, so the
+    # rules are deliberately narrow:
+    #
+    #   * The target URL is read from the message's own List-Unsubscribe header.
+    #     A caller cannot pass a URL in — otherwise this would be a general
+    #     purpose "POST anywhere" tool wearing a Gmail costume.
+    #   * https only. A mailto: entry is reported but never acted on, and a
+    #     plaintext http:// entry is refused rather than downgraded silently.
+    #   * One-click is only attempted when the sender advertises it via
+    #     List-Unsubscribe-Post, which is what RFC 8058 requires. Without that
+    #     header the link is a web page needing a human, not an endpoint.
+    #
+    # Note that unsubscribing confirms to the sender that the address is live.
+    # That is fine for a legitimate business and a bad idea for a spammer; the
+    # judgement of which is which is the caller's, not this module's.
+    module Unsubscribe
+      ONE_CLICK_BODY = 'List-Unsubscribe=One-Click'
+      USER_AGENT     = 'GMCP'
+      OPEN_TIMEOUT   = 10
+      READ_TIMEOUT   = 20
+      HEADERS        = %w[List-Unsubscribe List-Unsubscribe-Post].freeze
+
+      class NotSupported < StandardError; end
+      class Failed       < StandardError; end
+
+      # Returns { https:, mailto:, one_click:, raw: } — or nil if the message
+      # carries no List-Unsubscribe header at all.
+      def self.info(message_id)
+        message = Message.metadata(message_id, headers: HEADERS)
+        raw = message.header('List-Unsubscribe')
+        return nil if raw.nil? || raw.to_s.strip.empty?
+
+        uris = raw.to_s.scan(/<([^>]+)>/).flatten
+        uris = raw.to_s.split(',').map(&:strip) if uris.empty?
+
+        {
+          https:     uris.find { |u| u.start_with?('https://') },
+          http:      uris.find { |u| u.start_with?('http://') },
+          mailto:    uris.find { |u| u.start_with?('mailto:') },
+          one_click: message.header('List-Unsubscribe-Post').to_s.downcase.include?('one-click'),
+          raw:       raw
+        }
+      end
+
+      # Performs the unsubscribe. Returns the final HTTP status.
+      def self.one_click!(message_id)
+        details = info(message_id)
+        raise NotSupported, 'message has no List-Unsubscribe header' if details.nil?
+        unless details[:one_click]
+          raise NotSupported,
+                'sender does not advertise List-Unsubscribe-Post; the link needs a human'
+        end
+        if details[:https].nil?
+          raise NotSupported,
+                details[:http] ? 'only a plaintext http:// unsubscribe URL is offered; refusing to use it'
+                               : 'no https unsubscribe URL offered (mailto only)'
+        end
+
+        post(details[:https])
+      end
+
+      def self.post(url, redirects_left: 3)
+        uri = URI.parse(url)
+        raise NotSupported, "refusing non-https unsubscribe URL: #{uri.scheme}" unless uri.is_a?(URI::HTTPS)
+
+        req = Net::HTTP::Post.new(uri)
+        req['Content-Type'] = 'application/x-www-form-urlencoded'
+        req['User-Agent']   = USER_AGENT
+        req.body            = ONE_CLICK_BODY
+
+        resp = Net::HTTP.start(uri.host, uri.port,
+                               use_ssl: true,
+                               open_timeout: OPEN_TIMEOUT,
+                               read_timeout: READ_TIMEOUT) { |h| h.request(req) }
+
+        if resp.is_a?(Net::HTTPRedirection) && resp['location'] && redirects_left.positive?
+          return post(URI.join(url, resp['location']).to_s, redirects_left: redirects_left - 1)
+        end
+
+        raise Failed, "unsubscribe endpoint returned HTTP #{resp.code}" unless resp.is_a?(Net::HTTPSuccess)
+
+        resp.code
+      end
+      private_class_method :post
+    end
+  end
+end

data/lib/gmcp/server.rb

@@ -0,0 +1,90 @@
+require 'mcp'
+
+# mcp validates schemas with json-schema, which warns on every start unless
+# told to use the stdlib JSON it already has.
+require 'json-schema'
+JSON::Validator.use_multi_json = false
+
+module GMCP
+  module Server
+    SERVER_NAME    = 'gmcp'
+    SERVER_VERSION = GMCP::VERSION
+
+    def self.run!(accounts:)
+      @registry = AccountRegistry.new(accounts: accounts)
+      @registry.load_authorized_accounts!
+      MCP::Server::Transports::StdioTransport.new(build_server).open
+    end
+
+    def self.reinitialize!(account:)
+      registry.reinitialize!(account: account)
+    end
+
+    # Runs the block with `account` bound for the duration, restoring whatever
+    # was bound before. The binding is fiber-local, so two concurrent tool calls
+    # for different accounts cannot see each other's APIs.
+    def self.with_account(account, &block)
+      error, result = registry.scoped(account, &block)
+      error ? ToolHelpers.error_response(error) : result
+    end
+
+    # The account a tool call names, or the default one; refuses an account
+    # outside GMCP_ACCOUNTS. For tools that do not bind Google APIs (Voice).
+    def self.configured_account(account)
+      account ||= registry.default_account
+      return account if account && registry.accounts.include?(account)
+
+      raise ArgumentError, registry.authorization_message(account)
+    end
+
+    def self.build_server
+      server = MCP::Server.new(name: SERVER_NAME, version: SERVER_VERSION)
+      register_auth_tool(server)
+      Gmail::Tools.register(server)
+      Calendar::Tools.register(server)
+      Drive::Tools.register(server)
+      Voice::Tools.register(server)
+      server
+    end
+
+    def self.register_auth_tool(server)
+      ToolHelpers.define_tool(
+        server,
+        name: 'gmcp_authorize',
+        capability: 'gmcp.authorize',
+        description: 'Connect GMCP to a Google account. Opens a browser window for OAuth and captures the callback automatically.',
+        properties: {
+          account: {
+            type: 'string',
+            description: "Google account to authorize (configured: #{registry.account_description})"
+          }
+        }
+      ) do |account: nil|
+        account ||= registry.default_account
+
+        next ToolHelpers.error_response(registry.authorization_message(account)) unless registry.accounts.include?(account)
+
+        unless ::File.exist?(Auth.credentials_path)
+          next ToolHelpers.error_response(
+            "credentials.json not found at #{Auth.credentials_path}.\n\n" \
+            "1. Go to https://console.cloud.google.com/ → APIs & Services → Credentials\n" \
+            "2. Create an OAuth 2.0 Client ID (Desktop app)\n" \
+            "3. Download the JSON and save it to #{Auth.credentials_path}"
+          )
+        end
+
+        url = Auth.authorize_interactive!(account: account, on_success: ->(acct) { Server.reinitialize!(account: acct) })
+        ToolHelpers.text_response(
+          "A browser window has opened for #{account}. Complete sign-in there — tools will become available automatically once you authorize.\n\n" \
+          "If the browser did not open, use this URL manually:\n#{url}"
+        )
+      end
+    end
+
+    def self.registry
+      @registry ||= AccountRegistry.new(accounts: [])
+    end
+
+    private_class_method :build_server, :register_auth_tool, :registry
+  end
+end

data/lib/gmcp/tool_helpers.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'mcp'
+require 'json'
+
+module GMCP
+  module ToolHelpers
+    ACCOUNT_PARAM = {
+      account: {
+        type: 'string',
+        description: 'Google account to use (optional if only one is configured)'
+      }
+    }.freeze
+
+    def self.text_response(text)
+      MCP::Tool::Response.new([{ type: 'text', text: text }])
+    end
+
+    # Marked isError, so the client knows the call failed rather than having to
+    # guess from the wording.
+    def self.error_response(text)
+      MCP::Tool::Response.new([{ type: 'text', text: text }], error: true)
+    end
+
+    # Him models do not include ActiveModel::Serializers::JSON, so `to_json` on
+    # one resolves to Object#to_json and yields the inspect string —
+    # "#<GMCP::Gmail::Message:0x...>". That is valid JSON and completely empty
+    # of the record, so a caller cannot tell it from success. Serialize by
+    # attributes instead, recursing so a collection of models does not hit the
+    # same wall one level down.
+    def self.json_response(object)
+      text_response(JSON.pretty_generate(serializable(object)))
+    end
+
+    def self.serializable(object)
+      case object
+      when Array then object.map { |item| serializable(item) }
+      when Hash  then object.to_h { |key, value| [key, serializable(value)] }
+      else
+        object.respond_to?(:attributes) ? serializable(object.attributes) : object
+      end
+    end
+
+    # Registers a tool, unless `capability:` names a capability this process was
+    # not granted — in which case the tool is never defined and therefore never
+    # appears in tools/list. See GMCP::Capabilities.
+    #
+    # Returns the tool on registration, nil when gated out.
+    #
+    # Every failure becomes an isError response here, once, instead of each
+    # tool rescuing its own way or letting the exception escape as a JSON-RPC
+    # internal error that hides the cause.
+    def self.define_tool(server, name:, description:, properties:, required: nil, capability: nil, &block)
+      declarations[name] = capability
+      return nil unless Capabilities.enabled?(capability)
+
+      schema = { properties: properties }
+      schema[:required] = required if required
+      # Declared with **args, so MCP passes server_context; the tool blocks do
+      # not take it. MCP installs this as the tool's own `call`, so self is the
+      # tool there: name the module explicitly.
+      handler = lambda do |**args|
+        args.delete(:server_context)
+        ToolHelpers.guarded { block.call(**args) }
+      end
+      server.define_tool(name: name, description: description, input_schema: schema, &handler)
+    end
+
+    # A tool that acts on a Google account: adds the `account` parameter and
+    # runs the block with that account bound.
+    def self.account_tool(server, properties:, **options, &block)
+      define_tool(server, properties: properties.merge(ACCOUNT_PARAM), **options) do |account: nil, **args|
+        GMCP::Server.with_account(account) { block.call(**args) }
+      end
+    end
+
+    def self.guarded
+      yield
+    rescue ApiError, Auth::AuthRequired, ApiBinding::NotBound, ArgumentError => e
+      error_response(e.message)
+    rescue Signet::AuthorizationError => e
+      error_response("Google rejected the stored token (#{e.message.lines.first&.strip}). Call gmcp_authorize to reconnect.")
+    rescue StandardError => e
+      warn "GMCP tool error: #{e.class}: #{e.message}\n#{e.backtrace&.first(5)&.join("\n")}"
+      error_response("#{e.class}: #{e.message}")
+    end
+
+    def self.list_response(items, empty_message:, &formatter)
+      lines = items.map(&formatter).join("\n")
+      text_response(lines.empty? ? empty_message : lines)
+    end
+
+    # Every (tool name => capability) pair this process has attempted to
+    # register, granted or not. Populated as a side effect of define_tool, so it
+    # cannot drift from what the tools actually declare — which is what makes
+    # the manifest consistency spec exact rather than a regex over source.
+    def self.declarations
+      @declarations ||= {}
+    end
+
+    def self.reset_declarations!
+      @declarations = {}
+    end
+  end
+end

data/lib/gmcp/version.rb

@@ -0,0 +1,3 @@
+module GMCP
+  VERSION = '0.5.0'
+end