earl-bot 0.1.0

data/lib/earl/mcp/heartbeat_handler.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+module Earl
+  module Mcp
+    # MCP handler exposing a manage_heartbeat tool to create, update, delete,
+    # and list heartbeat schedules. Writes changes to the heartbeats YAML file;
+    # the HeartbeatScheduler auto-reloads when it detects file changes.
+    # Conforms to the Server handler interface: tool_definitions, handles?, call.
+    class HeartbeatHandler
+      include HandlerBase
+
+      TOOL_NAMES = %w[manage_heartbeat].freeze
+      def self.config_path
+        @config_path ||= File.join(Earl.config_root, "heartbeats.yml")
+      end
+
+      VALID_ACTIONS = %w[list create update delete].freeze
+      MUTABLE_FIELDS = %w[description cron interval run_at channel_id working_dir
+                          prompt permission_mode persistent timeout enabled once].freeze
+
+      def initialize(default_channel_id: nil, config_path: self.class.config_path)
+        @default_channel_id = default_channel_id
+        @config_path = config_path
+      end
+
+      def tool_definitions
+        [manage_heartbeat_definition]
+      end
+
+      NAME_REQUIRED_ACTIONS = %w[create update delete].freeze
+
+      def call(name, arguments)
+        return unless handles?(name)
+
+        error = validate_action(arguments)
+        return error if error
+
+        send("handle_#{arguments["action"]}", arguments)
+      end
+
+      private
+
+      def validate_action(arguments)
+        action = arguments["action"]
+        return text_content("Error: action is required (list, create, update, delete)") unless action
+        unless VALID_ACTIONS.include?(action)
+          return text_content("Error: unknown action '#{action}'. Valid: #{VALID_ACTIONS.join(", ")}")
+        end
+
+        text_content("Error: name is required") if name_required_but_missing?(action, arguments)
+      end
+
+      def name_required_but_missing?(action, arguments)
+        return false unless NAME_REQUIRED_ACTIONS.include?(action)
+
+        hb_name = arguments["name"]
+        !hb_name || hb_name.empty?
+      end
+
+      # --- Action handlers ---
+
+      def handle_list(_arguments)
+        data = load_yaml
+        heartbeats = data["heartbeats"] || {}
+        return text_content("No heartbeats defined.") if heartbeats.empty?
+
+        lines = heartbeats.map { |name, config| format_heartbeat(name, config) }
+        text_content("**Heartbeats (#{heartbeats.size}):**\n\n#{lines.join("\n\n")}")
+      end
+
+      def handle_create(arguments)
+        name = arguments["name"]
+        data = load_yaml
+        heartbeats = (data["heartbeats"] ||= {})
+        return text_content("Error: heartbeat '#{name}' already exists") if heartbeats.key?(name)
+
+        heartbeats[name] = build_entry(arguments)
+        save_yaml(data)
+        text_content("Created heartbeat '#{name}'. Scheduler will pick it up within 30 seconds.")
+      end
+
+      def handle_update(arguments)
+        name = arguments["name"]
+        data = load_yaml
+        heartbeats = (data["heartbeats"] ||= {})
+        entry = heartbeats.fetch(name, nil)
+        return text_content("Error: heartbeat '#{name}' not found") unless entry
+
+        merge_entry(entry, arguments)
+        save_yaml(data)
+        text_content("Updated heartbeat '#{name}'. Scheduler will pick up changes within 30 seconds.")
+      end
+
+      def handle_delete(arguments)
+        name = arguments["name"]
+        data = load_yaml
+        heartbeats = (data["heartbeats"] ||= {})
+        removed = heartbeats.delete(name)
+        return text_content("Error: heartbeat '#{name}' not found") unless removed
+
+        save_yaml(data)
+        text_content("Deleted heartbeat '#{name}'. Scheduler will remove it within 30 seconds.")
+      end
+
+      # --- YAML I/O ---
+
+      # YAML file persistence for heartbeat definitions.
+      module YamlPersistence
+        private
+
+        def load_yaml
+          return { "heartbeats" => {} } unless File.exist?(@config_path)
+
+          data = YAML.safe_load_file(@config_path)
+          data.is_a?(Hash) ? data : { "heartbeats" => {} }
+        end
+
+        def save_yaml(data)
+          FileUtils.mkdir_p(File.dirname(@config_path))
+          # Use file lock to coordinate with HeartbeatScheduler#disable_heartbeat
+          File.open(@config_path, File::CREAT | File::WRONLY | File::TRUNC) do |file|
+            file.flock(File::LOCK_EX)
+            file.write(YAML.dump(data))
+          end
+        end
+      end
+
+      include YamlPersistence
+
+      # Entry building: constructs and merges heartbeat configuration hashes.
+      module EntryBuilder
+        OPTIONAL_STRING_KEYS = %w[working_dir prompt permission_mode timeout].freeze
+        SCHEDULE_KEYS = %w[cron interval run_at].freeze
+
+        private
+
+        def build_entry(arguments)
+          schedule = slice_present(arguments, SCHEDULE_KEYS)
+          schedule["run_at"] = Time.now.to_i if arguments["once"] && schedule.empty?
+
+          base = slice_present(arguments, %w[description once])
+          base.merge(
+            "schedule" => schedule,
+            "channel_id" => arguments["channel_id"] || @default_channel_id,
+            "enabled" => arguments.fetch("enabled", true)
+          ).merge(slice_present(arguments, OPTIONAL_STRING_KEYS))
+              .merge(slice_key(arguments, "persistent"))
+        end
+
+        def slice_present(hash, keys)
+          keys.each_with_object({}) do |key, result|
+            result[key] = hash[key] if hash.key?(key)
+          end
+        end
+
+        def slice_key(hash, key)
+          hash.key?(key) ? { key => hash[key] } : {}
+        end
+
+        def merge_entry(entry, arguments)
+          schedule = (entry["schedule"] ||= {})
+          MUTABLE_FIELDS.each do |field|
+            next unless arguments.key?(field)
+
+            value = arguments[field]
+            target = SCHEDULE_KEYS.include?(field) ? schedule : entry
+            target[field] = value
+          end
+        end
+
+        def build_schedule(arguments)
+          slice_present(arguments, SCHEDULE_KEYS)
+        end
+      end
+
+      include EntryBuilder
+
+      # --- Formatting ---
+
+      # Human-readable heartbeat list formatting.
+      module Formatting
+        private
+
+        def format_heartbeat(name, config)
+          schedule, enabled, once, description = extract_display_fields(config, name)
+          schedule_str = format_schedule(schedule)
+          enabled_str = enabled ? "enabled" : "disabled"
+          once_badge = once ? ", once" : ""
+          "- **#{name}** (#{enabled_str}#{once_badge}, #{schedule_str})\n  #{description}"
+        end
+
+        def extract_display_fields(config, name)
+          [
+            config["schedule"] || {},
+            config.fetch("enabled", true),
+            config.fetch("once", false),
+            config["description"] || name
+          ]
+        end
+
+        def format_schedule(schedule)
+          cron = schedule["cron"]
+          interval = schedule["interval"]
+          run_at = schedule["run_at"]
+
+          return "cron: `#{cron}`" if cron
+          return "interval: #{interval}s" if interval
+          return "run_at: #{Time.at(run_at).strftime("%Y-%m-%d %H:%M:%S")}" if run_at
+
+          "no schedule"
+        end
+      end
+
+      include Formatting
+
+      # --- MCP response helper ---
+
+      def text_content(text)
+        { content: [{ type: "text", text: text }] }
+      end
+
+      # Tool definition building: splits the large schema into composable property groups.
+      module ToolDefinitionBuilder
+        private
+
+        def manage_heartbeat_definition
+          {
+            name: "manage_heartbeat",
+            description: heartbeat_tool_description,
+            inputSchema: heartbeat_input_schema
+          }
+        end
+
+        def heartbeat_tool_description
+          "Manage Earl's heartbeat schedules. " \
+            "Create, update, delete, or list tasks that run on cron, interval, or one-shot (run_at) schedules."
+        end
+
+        def heartbeat_input_schema
+          {
+            type: "object",
+            properties: heartbeat_properties,
+            required: %w[action]
+          }
+        end
+
+        def heartbeat_properties
+          {}.merge(action_properties)
+            .merge(schedule_properties)
+            .merge(session_properties)
+            .merge(behavior_properties)
+        end
+
+        def action_properties
+          {
+            action: {
+              type: "string", enum: VALID_ACTIONS,
+              description: "Action to perform: list, create, update, or delete"
+            },
+            name: { type: "string", description: "Heartbeat name (required for create/update/delete)" },
+            description: { type: "string", description: "Human-readable description of the heartbeat" }
+          }
+        end
+
+        def schedule_properties
+          {
+            cron: { type: "string", description: "Cron expression (e.g. '0 9 * * 1-5' for weekdays at 9am)" },
+            interval: { type: "integer", description: "Interval in seconds between runs (alternative to cron)" },
+            run_at: {
+              type: "integer",
+              description: "Unix timestamp for one-shot execution (alternative to cron/interval). " \
+                           "Must be used with once: true to avoid repeated firing."
+            }
+          }
+        end
+
+        def session_properties
+          {
+            channel_id: { type: "string",
+                          description: "Mattermost channel ID to post results (defaults to current channel)" },
+            working_dir: { type: "string", description: "Working directory for the Claude session" },
+            prompt: { type: "string", description: "The prompt to send to Claude when the heartbeat fires" },
+            permission_mode: {
+              type: "string", enum: %w[auto interactive],
+              description: "Permission mode: auto (no approval) or interactive (requires reaction approval)"
+            }
+          }
+        end
+
+        def behavior_properties
+          {
+            persistent: { type: "boolean", description: "Whether to reuse the same Claude session across runs" },
+            timeout: { type: "integer", description: "Maximum seconds to wait for completion (default: 600)" },
+            enabled: { type: "boolean", description: "Whether the heartbeat is active (default: true)" },
+            once: {
+              type: "boolean",
+              description: "Run once then auto-disable. Combine with run_at for scheduled one-shots, " \
+                           "or omit schedule to fire immediately."
+            }
+          }
+        end
+      end
+
+      include ToolDefinitionBuilder
+    end
+  end
+end

data/lib/earl/mcp/memory_handler.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Earl
+  module Mcp
+    # MCP handler exposing save_memory and search_memory tools.
+    # Conforms to the Server handler interface: tool_definitions, handles?, call.
+    class MemoryHandler
+      include HandlerBase
+
+      TOOL_NAMES = %w[save_memory search_memory].freeze
+
+      def initialize(store:, username: nil)
+        @store = store
+        @username = username
+      end
+
+      def tool_definitions
+        [save_memory_definition, search_memory_definition]
+      end
+
+      DISPATCH = { "save_memory" => :handle_save, "search_memory" => :handle_search }.freeze
+
+      def call(name, arguments)
+        method = DISPATCH[name]
+        return unless method
+
+        send(method, arguments)
+      end
+
+      private
+
+      def handle_save(arguments)
+        text = arguments["text"] || arguments["fact"] || ""
+        username = arguments["username"] || @username || "unknown"
+
+        result = @store.save(username: username, text: text)
+        text_content("Saved: #{result[:entry]}")
+      end
+
+      def handle_search(arguments)
+        query = arguments["query"] || ""
+        limit = (arguments["limit"] || 20).to_i
+
+        results = @store.search(query: query, limit: limit)
+        return text_content("No memories found for: #{query}") if results.empty?
+
+        text_content(format_search_results(results))
+      end
+
+      def format_search_results(results)
+        count = results.size
+        formatted = results.map { |result| "**#{result[:file]}**: #{result[:line]}" }.join("\n")
+        "Found #{count} memor#{count == 1 ? "y" : "ies"}:\n#{formatted}"
+      end
+
+      def text_content(text)
+        { content: [{ type: "text", text: text }] }
+      end
+
+      def save_memory_definition
+        build_tool_definition(
+          "save_memory",
+          "Save a fact or observation to persistent memory. " \
+          "Use this to remember important information about users, preferences, or context.",
+          text: { type: "string", description: "The fact or observation to save" },
+          username: { type: "string", description: "The username this memory relates to (optional)" }
+        )
+      end
+
+      def search_memory_definition
+        build_tool_definition(
+          "search_memory",
+          "Search persistent memory for previously saved facts. " \
+          "Use this to recall information about users, preferences, or past interactions.",
+          query: { type: "string", description: "Keywords to search for" },
+          limit: { type: "integer", description: "Maximum results to return (default: 20)" }
+        )
+      end
+
+      def build_tool_definition(name, description, **properties)
+        required = name == "save_memory" ? %w[text] : %w[query]
+        {
+          name: name, description: description,
+          inputSchema: { type: "object", properties: properties, required: required }
+        }
+      end
+    end
+  end
+end

data/lib/earl/mcp/server.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Earl
+  module Mcp
+    # Minimal JSON-RPC 2.0 server over stdio for the Claude CLI MCP integration.
+    # Routes tools/list and tools/call to registered handlers via duck-typed interface:
+    #   #tool_definitions → Array of tool hashes
+    #   #handles?(tool_name) → Boolean
+    #   #call(tool_name, arguments) → result hash
+    class Server
+      include Logging
+
+      def initialize(handlers:, input: $stdin, output: $stdout)
+        @handlers = Array(handlers)
+        @input = input
+        @output = output
+        @output.sync = true
+      end
+
+      def run
+        @input.each_line do |line|
+          request = parse_request(line)
+          next unless request
+
+          response = handle_request(request)
+          write_response(response) if response
+        end
+      end
+
+      private
+
+      def parse_request(line)
+        JSON.parse(line.strip)
+      rescue JSON::ParserError => error
+        log(:warn, "MCP: unparsable input: #{error.message}")
+        nil
+      end
+
+      def handle_request(request)
+        method_name, request_id, params = request.values_at("method", "id", "params")
+        dispatch_method(method_name, request_id, params || {})
+      end
+
+      def dispatch_method(method_name, request_id, params)
+        case method_name
+        when "initialize" then initialize_response(request_id)
+        when "notifications/initialized" then nil
+        when "tools/list" then tools_list_response(request_id)
+        when "tools/call" then tools_call_response(request_id, params)
+        else error_response(request_id, -32_601, "Method not found: #{method_name}")
+        end
+      end
+
+      def initialize_response(id)
+        {
+          jsonrpc: "2.0",
+          id: id,
+          result: {
+            protocolVersion: "2024-11-05",
+            capabilities: { tools: {} },
+            serverInfo: { name: "earl-mcp-server", version: "1.0.0" }
+          }
+        }
+      end
+
+      def tools_list_response(id)
+        {
+          jsonrpc: "2.0",
+          id: id,
+          result: {
+            tools: @handlers.flat_map(&:tool_definitions)
+          }
+        }
+      end
+
+      def tools_call_response(id, params)
+        tool_name, arguments = extract_tool_params(params)
+        handler = find_tool_handler(tool_name)
+        return error_response(id, -32_602, "No handler for tool: #{tool_name}") unless handler
+
+        log(:info, "MCP tool call: #{tool_name}")
+        result = handler.call(tool_name, arguments)
+        log_tool_result(tool_name, result)
+
+        { jsonrpc: "2.0", id: id, result: result }
+      rescue StandardError => error
+        handle_tool_error(id, error)
+      end
+
+      def extract_tool_params(args)
+        tool_name = args["name"] || args.dig("arguments", "tool_name") || "unknown"
+        [tool_name, args["arguments"] || {}]
+      end
+
+      def find_tool_handler(tool_name)
+        @handlers.find { |candidate| candidate.handles?(tool_name) }
+      end
+
+      def log_tool_result(tool_name, result)
+        log(:info, "MCP tool result for #{tool_name}: #{result.inspect[0..200]}")
+      end
+
+      def handle_tool_error(id, error)
+        msg = error.message
+        log(:error, "MCP tool call error: #{error.class}: #{msg}")
+        log(:error, error.backtrace&.first(3)&.join("\n"))
+        error_response(id, -32_603, "Internal error: #{msg}")
+      end
+
+      def error_response(id, code, message)
+        {
+          jsonrpc: "2.0",
+          id: id,
+          error: { code: code, message: message }
+        }
+      end
+
+      def write_response(response)
+        @output.puts(JSON.generate(response))
+      end
+    end
+  end
+end