superkick 0.1.0

data/lib/superkick/mcp_server.rb

@@ -0,0 +1,596 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module Superkick
+  # MCP stdio server — spawned by the AI CLI as a subprocess.
+  # Translates MCP tool calls into Control::Client requests to the server.
+  #
+  # Reads SUPERKICK_AGENT_ID from the environment (set by PtyProxy when spawning
+  # the AI CLI). All tools that need the agent identity use this automatically
+  # rather than requiring the AI to pass it as a parameter.
+  #
+  # Tools exposed:
+  #   superkick_discover_monitors — list available monitor types and probe-detected configs
+  #   superkick_discover_goals    — list available goal types for worker agents
+  #   superkick_add_monitor    — add a monitor to this agent
+  #   superkick_remove_monitor — remove a monitor from this agent
+  #   superkick_signal_goal    — signal agent goal status (completed, failed, errored, in_progress)
+  #   superkick_status           — report server/agent status
+  class McpServer
+    def self.start
+      new.run
+    end
+
+    def initialize(control_client: nil)
+      @agent_id = ENV["SUPERKICK_AGENT_ID"]
+      raise "SUPERKICK_AGENT_ID must be set. The MCP server should be started via `superkick agent`." unless @agent_id
+      @control_client = control_client || Control.client_from
+    end
+
+    def run
+      server = build_server
+      transport = MCP::Server::Transports::StdioTransport.new(server)
+      server.transport = transport
+      transport.open
+    end
+
+    # Build the MCP::Server with all tools defined. Exposed for integration
+    # testing — callers can use server.handle_json(request) directly without
+    # starting the stdio transport.
+    def build_server
+      server = MCP::Server.new(name: "superkick", version: Superkick::VERSION)
+      define_tools(server)
+      server
+    end
+
+    private
+
+    def define_tools(server) # rubocop:disable Metrics/MethodLength
+      # Capture helpers as lambdas so tool blocks (which run with self = Tool class)
+      # can call back into the McpServer instance via closures.
+      request = method(:server_request)
+      agent_id = @agent_id
+      do_discover_monitors = method(:discover_monitors)
+      do_discover_goals = method(:discover_goals)
+      do_discover_notifiers = method(:discover_notifiers)
+      do_symbolize_keys = method(:symbolize_keys)
+      do_symbolize_keys_deep = method(:symbolize_keys_deep)
+
+      # MCP gem 0.7+ expects tool blocks to return MCP::Tool::Response, not plain strings.
+      text_response = ->(text) {
+        MCP::Tool::Response.new([{type: "text", text: text}])
+      }
+
+      server.define_tool(
+        name: "superkick_discover_monitors",
+        description: "List all available Superkick monitor types, their descriptions, required configuration, " \
+          "and event types. Optionally runs environment probes to detect monitors that can be auto-configured " \
+          "for the current working directory (e.g. detecting the GitHub repo and branch from git remotes). " \
+          "Use this to discover what monitors you can start before calling superkick_add_monitor.",
+        input_schema: {
+          type: "object",
+          properties: {
+            run_probes: {
+              type: "boolean",
+              description: "Run environment probes to detect auto-configurable monitors (default: true)"
+            }
+          }
+        }
+      ) do |run_probes: true, **_|
+        text_response.call(do_discover_monitors.call(run_probes:))
+      end
+
+      server.define_tool(
+        name: "superkick_discover_notifiers",
+        description: "List all available Superkick notifier types, their descriptions, and configuration options. " \
+          "Use this to discover what notifier types you can attach to agents or workers " \
+          "before calling superkick_add_notifier or superkick_spawn_worker.",
+        input_schema: {type: "object", properties: {}}
+      ) do |**_|
+        text_response.call(do_discover_notifiers.call)
+      end
+
+      server.define_tool(
+        name: "superkick_discover_goals",
+        description: "List all available Superkick goal types, their descriptions, and required configuration. " \
+          "Use this to understand what goal types you can assign to workers when calling superkick_spawn_worker.",
+        input_schema: {type: "object", properties: {}}
+      ) do |**_|
+        text_response.call(do_discover_goals.call)
+      end
+
+      server.define_tool(
+        name: "superkick_discover_repositories",
+        description: "List all configured repositories with their descriptions, tags, dependencies, " \
+          "and paths. Use this to discover which repositories are available for spawning workers " \
+          "or understanding the project landscape.",
+        input_schema: {type: "object", properties: {}}
+      ) do |**_|
+        text = begin
+          result = request.call("discover_repositories")
+          result.success? ? JSON.pretty_generate(result.payload) : "Error: #{result.error_message}"
+        rescue Control::Client::ServerUnavailable => e
+          "Superkick server unavailable: #{e.message}"
+        end
+        text_response.call(text)
+      end
+
+      server.define_tool(
+        name: "superkick_add_monitor",
+        description: "Add a named monitor to this agent.",
+        input_schema: {
+          type: "object",
+          required: %w[monitor_name],
+          properties: {
+            monitor_name: {type: "string", description: "Unique instance name (e.g. 'github', 'disk_check')"},
+            monitor_type: {type: "string", description: "Monitor class type (e.g. 'shell'). Inferred from name if omitted."},
+            config: {type: "object", description: "Monitor-specific configuration"}
+          }
+        }
+      ) do |monitor_name:, monitor_type: nil, config: {}, **_|
+        text = begin
+          config = config.dup
+          config[:type] = monitor_type if monitor_type
+          result = request.call("add_monitor",
+            agent_id:,
+            monitor_name:,
+            config:)
+          result.success? ? "Monitor #{monitor_name} added." : "Error: #{result.error_message}"
+        rescue Control::Client::ServerUnavailable => e
+          "Superkick server unavailable: #{e.message}"
+        end
+        text_response.call(text)
+      end
+
+      server.define_tool(
+        name: "superkick_remove_monitor",
+        description: "Remove a named monitor from this agent.",
+        input_schema: {
+          type: "object",
+          required: %w[monitor_name],
+          properties: {
+            monitor_name: {type: "string", description: "The monitor instance name to remove"}
+          }
+        }
+      ) do |monitor_name:, **_|
+        text = begin
+          result = request.call("remove_monitor",
+            agent_id:,
+            monitor_name:)
+          result.success? ? "Monitor removed." : "Error: #{result.error_message}"
+        rescue Control::Client::ServerUnavailable => e
+          "Superkick server unavailable: #{e.message}"
+        end
+        text_response.call(text)
+      end
+
+      server.define_tool(
+        name: "superkick_add_notifier",
+        description: "Add a named notifier to this agent. Per-agent notifiers fire " \
+          "alongside global notifiers for this agent's events only.",
+        input_schema: {
+          type: "object",
+          required: %w[notifier_name],
+          properties: {
+            notifier_name: {type: "string", description: "Unique instance name (e.g. 'slack_ops', 'datadog')"},
+            notifier_type: {type: "string", description: "Notifier class type (e.g. 'slack'). Inferred from name if omitted."},
+            config: {type: "object", description: "Notifier-specific configuration"}
+          }
+        }
+      ) do |notifier_name:, notifier_type: nil, config: {}, **_|
+        text = begin
+          config = do_symbolize_keys.call(config.dup)
+          config[:type] = notifier_type if notifier_type
+          result = request.call("add_notifier",
+            agent_id:,
+            notifier_name:,
+            config:)
+          result.success? ? "Notifier #{notifier_name} added." : "Error: #{result.error_message}"
+        rescue Control::Client::ServerUnavailable => e
+          "Superkick server unavailable: #{e.message}"
+        end
+        text_response.call(text)
+      end
+
+      server.define_tool(
+        name: "superkick_remove_notifier",
+        description: "Remove a named notifier from this agent.",
+        input_schema: {
+          type: "object",
+          required: %w[notifier_name],
+          properties: {
+            notifier_name: {type: "string", description: "The notifier instance name to remove"}
+          }
+        }
+      ) do |notifier_name:, **_|
+        text = begin
+          result = request.call("remove_notifier",
+            agent_id:,
+            notifier_name:)
+          result.success? ? "Notifier removed." : "Error: #{result.error_message}"
+        rescue Control::Client::ServerUnavailable => e
+          "Superkick server unavailable: #{e.message}"
+        end
+        text_response.call(text)
+      end
+
+      server.define_tool(
+        name: "superkick_signal_goal",
+        description: "Signal the status of this agent's goal. Use this to report progress, " \
+          "completion, or failure of your assigned task. Terminal statuses (completed, failed) " \
+          "tell Superkick to clean up resources and optionally trigger downstream workflows.",
+        input_schema: {
+          type: "object",
+          required: %w[status],
+          properties: {
+            status: {
+              type: "string",
+              enum: %w[completed failed errored in_progress],
+              description: "Goal status: 'completed' = task succeeded (terminal), " \
+                "'failed' = irrecoverable failure (terminal), " \
+                "'errored' = potentially recoverable issue, " \
+                "'in_progress' = actively working"
+            },
+            message: {type: "string", description: "Optional message describing the outcome"},
+            summary: {
+              type: "string",
+              description: "Brief summary of what happened. For failures, explain what went wrong " \
+                "and what was tried. This summary is forwarded to retry agents in workflow chains."
+            }
+          }
+        }
+      ) do |status:, summary: nil, **_|
+        text = begin
+          result = request.call("signal_goal",
+            agent_id:,
+            status:,
+            summary:)
+          result.success? ? "Signal received: #{status}" : "Error: #{result.error_message}"
+        rescue Control::Client::ServerUnavailable => e
+          "Superkick server unavailable: #{e.message}"
+        end
+        text_response.call(text)
+      end
+
+      server.define_tool(
+        name: "superkick_report_cost",
+        description: "Report token usage and cost for this agent session. " \
+          "Call this periodically or at task completion to enable cost tracking. " \
+          "Values should be cumulative totals (not incremental deltas).",
+        input_schema: {
+          type: "object",
+          properties: {
+            tokens_in: {type: "integer", description: "Total input tokens used so far"},
+            tokens_out: {type: "integer", description: "Total output tokens used so far"},
+            cost_usd: {type: "number", description: "Total cost in USD so far"}
+          }
+        }
+      ) do |tokens_in: nil, tokens_out: nil, cost_usd: nil, **_|
+        text = begin
+          result = request.call("report_cost",
+            agent_id:,
+            tokens_in:,
+            tokens_out:,
+            cost_usd:,
+            source: :mcp_report)
+          result.success? ? "Cost recorded." : "Error: #{result.error_message}"
+        rescue Control::Client::ServerUnavailable => e
+          "Superkick server unavailable: #{e.message}"
+        end
+        text_response.call(text)
+      end
+
+      server.define_tool(
+        name: "superkick_status",
+        description: "Report Superkick server status and active agents.",
+        input_schema: {type: "object", properties: {}}
+      ) do |**_|
+        text = begin
+          ping = begin
+            request.call("ping")
+          rescue Control::Client::ServerUnavailable
+            nil
+          end
+          unless ping&.success?
+            next text_response.call("Superkick server is not running.")
+          end
+
+          agents_resp = request.call("list_agents")
+          agents = agents_resp[:agents] || []
+
+          if agents.empty?
+            "Superkick server running (v#{ping[:version]}). No active agents."
+          else
+            lines = agents.map do |s|
+              buf = s[:has_buffer] ? "pty-connected" : "no-pty"
+              line = "  agent #{s[:agent_id]}: #{s[:monitor_count]} monitor(s), #{buf}"
+              if s[:cost] && s[:cost][:total_cost_usd] > 0
+                line += " cost=$#{s[:cost][:total_cost_usd].round(2)}"
+              end
+              line
+            end
+            "Superkick server running (v#{ping[:version]}).\n#{lines.join("\n")}"
+          end
+        rescue Control::Client::ServerUnavailable => e
+          "Superkick server unavailable: #{e.message}"
+        end
+        text_response.call(text)
+      end
+
+      # ── Team tools ────────────────────────────────────────────────────
+
+      server.define_tool(
+        name: "superkick_post_update",
+        description: "Post an update or send a message. Without target_agent_id, " \
+          "broadcasts to all configured notification channels (Slack, team log, etc.). " \
+          "With target_agent_id, sends a direct message injected into that teammate's prompt. " \
+          "Use kind to categorize: 'blocker' gets high priority routing.",
+        input_schema: {
+          type: "object",
+          required: %w[message],
+          properties: {
+            message: {type: "string", description: "The update or message text"},
+            kind: {
+              type: "string",
+              enum: %w[status decision blocker progress completed failed],
+              description: "Type of update (for broadcast mode)"
+            },
+            target_agent_id: {
+              type: "string",
+              description: "Send a direct message to this teammate instead of broadcasting. " \
+                "Both agents must be on the same team."
+            }
+          }
+        }
+      ) do |message:, kind: nil, target_agent_id: nil, **_|
+        text = begin
+          result = request.call("post_update",
+            agent_id:,
+            message:,
+            kind:,
+            target_agent_id:)
+          result.success? ? "Update posted." : "Error: #{result.error_message}"
+        rescue Control::Client::ServerUnavailable => e
+          "Superkick server unavailable: #{e.message}"
+        end
+        text_response.call(text)
+      end
+
+      server.define_tool(
+        name: "superkick_team_status",
+        description: "Get the current status of your team. Returns each teammate's " \
+          "latest update and any unresolved blockers.",
+        input_schema: {
+          type: "object",
+          properties: {
+            full_log: {
+              type: "boolean",
+              description: "If true, returns the full team log instead of just the summary",
+              default: false
+            }
+          }
+        }
+      ) do |full_log: false, **_|
+        text = begin
+          result = request.call("team_status",
+            agent_id:,
+            full_log:)
+          result.success? ? JSON.pretty_generate(result.payload) : "Error: #{result.error_message}"
+        rescue Control::Client::ServerUnavailable => e
+          "Superkick server unavailable: #{e.message}"
+        end
+        text_response.call(text)
+      end
+
+      server.define_tool(
+        name: "superkick_list_teammates",
+        description: "List all agents on your team, including their roles, " \
+          "current status, and what they're working on.",
+        input_schema: {type: "object", properties: {}}
+      ) do |**_|
+        text = begin
+          result = request.call("list_teammates", agent_id:)
+          result.success? ? JSON.pretty_generate(result.payload) : "Error: #{result.error_message}"
+        rescue Control::Client::ServerUnavailable => e
+          "Superkick server unavailable: #{e.message}"
+        end
+        text_response.call(text)
+      end
+
+      server.define_tool(
+        name: "superkick_spawn_worker",
+        description: "Spawn a worker agent to work on a specific repository as " \
+          "part of your team. The worker will be set up with a git worktree and " \
+          "given your instructions as its kickoff prompt.",
+        input_schema: {
+          type: "object",
+          required: %w[repository task agent_suffix],
+          properties: {
+            repository: {type: "string", description: "Name of the repository from the repository registry"},
+            task: {type: "string", description: "Detailed instructions for what the worker should do"},
+            agent_suffix: {
+              type: "string",
+              description: "Short suffix for the agent ID (e.g. 'api', 'web'). " \
+                "The full ID will be {team_id}-{suffix}."
+            },
+            goal: {
+              type: "object",
+              description: "Goal configuration for the worker. Defaults to agent_signal.",
+              properties: {type: {type: "string"}}
+            },
+            role: {
+              type: "string",
+              description: "Short label describing the worker's function (e.g. 'API migration', 'Test writer')"
+            },
+            depends_on: {
+              type: "array",
+              items: {type: "string"},
+              description: "Agent IDs this worker depends on. The worker's " \
+                "instructions will note these dependencies."
+            },
+            monitors: {
+              type: "object",
+              description: "Named monitors to attach to the worker. " \
+                "Each key is a monitor name, each value is its configuration " \
+                "(must include 'type' if the name doesn't match a registered monitor type). " \
+                "Use superkick_discover_monitors to see available types.",
+              additionalProperties: {type: "object"}
+            },
+            notifiers: {
+              type: "object",
+              description: "Named notifiers to attach to the worker. " \
+                "Each key is a notifier name, each value is its configuration " \
+                "(must include 'type'). These fire alongside global notifiers for " \
+                "this worker's events only. Use superkick_discover_notifiers to see available types.",
+              additionalProperties: {type: "object"}
+            }
+          }
+        }
+      ) do |repository:, task:, agent_suffix:, goal: nil, role: nil, depends_on: nil, monitors: nil, notifiers: nil, **_|
+        text = begin
+          goal = goal.transform_keys(&:to_sym) if goal
+          monitors = do_symbolize_keys_deep.call(monitors) if monitors
+          notifiers = do_symbolize_keys_deep.call(notifiers) if notifiers
+
+          result = request.call("spawn_worker",
+            agent_id:,
+            repository:,
+            task:,
+            agent_suffix:,
+            role:,
+            goal:,
+            depends_on:,
+            monitors:,
+            notifiers:)
+          result.success? ? "Worker spawned: #{result[:agent_id]}" : "Error: #{result.error_message}"
+        rescue Control::Client::ServerUnavailable => e
+          "Superkick server unavailable: #{e.message}"
+        end
+        text_response.call(text)
+      end
+
+      # ── Artifact tools ──────────────────────────────────────────────
+
+      server.define_tool(
+        name: "superkick_publish_artifact",
+        description: "Publish a named artifact to your team's shared store. Use this to share " \
+          "implementation plans, summaries, API contracts, or any structured data with teammates. " \
+          "Artifacts are visible to the entire team. Publishing to an existing name updates it.",
+        input_schema: {
+          type: "object",
+          required: %w[name content],
+          properties: {
+            name: {type: "string", description: "Artifact name (e.g. 'implementation-plan', 'api-contract')"},
+            content: {type: "string", description: "The artifact content (text, JSON, YAML, etc.)"}
+          }
+        }
+      ) do |name:, content:, **_|
+        text = begin
+          result = request.call("publish_artifact",
+            agent_id:,
+            name:,
+            content:)
+          result.success? ? "Artifact '#{name}' published." : "Error: #{result.error_message}"
+        rescue Control::Client::ServerUnavailable => e
+          "Superkick server unavailable: #{e.message}"
+        end
+        text_response.call(text)
+      end
+
+      server.define_tool(
+        name: "superkick_read_artifact",
+        description: "Read an artifact published by a teammate. Use superkick_list_artifacts " \
+          "to discover available artifacts first.",
+        input_schema: {
+          type: "object",
+          required: %w[author name],
+          properties: {
+            author: {type: "string", description: "The agent ID that published the artifact"},
+            name: {type: "string", description: "The artifact name"}
+          }
+        }
+      ) do |author:, name:, **_|
+        text = begin
+          result = request.call("read_artifact",
+            agent_id:,
+            author:,
+            name:)
+          result.success? ? JSON.pretty_generate(result.payload) : "Error: #{result.error_message}"
+        rescue Control::Client::ServerUnavailable => e
+          "Superkick server unavailable: #{e.message}"
+        end
+        text_response.call(text)
+      end
+
+      server.define_tool(
+        name: "superkick_list_artifacts",
+        description: "List artifacts published by your team. Returns metadata (name, author, " \
+          "timestamps) without content. Optionally filter by author.",
+        input_schema: {
+          type: "object",
+          properties: {
+            author: {type: "string", description: "Filter by author agent ID (optional)"}
+          }
+        }
+      ) do |author: nil, **_|
+        text = begin
+          result = request.call("list_artifacts",
+            agent_id:,
+            author:)
+          result.success? ? JSON.pretty_generate(result.payload) : "Error: #{result.error_message}"
+        rescue Control::Client::ServerUnavailable => e
+          "Superkick server unavailable: #{e.message}"
+        end
+        text_response.call(text)
+      end
+    end
+
+    def discover_monitors(run_probes:)
+      result = server_request("discover_monitors", agent_id: run_probes ? @agent_id : nil)
+      if result.success?
+        JSON.pretty_generate(result.payload)
+      else
+        "Error: #{result.error_message}"
+      end
+    rescue Control::Client::ServerUnavailable => e
+      "Superkick server unavailable: #{e.message}"
+    end
+
+    def discover_goals
+      result = server_request("discover_goals")
+      if result.success?
+        JSON.pretty_generate(result.payload)
+      else
+        "Error: #{result.error_message}"
+      end
+    rescue Control::Client::ServerUnavailable => e
+      "Superkick server unavailable: #{e.message}"
+    end
+
+    def discover_notifiers
+      result = server_request("discover_notifiers")
+      if result.success?
+        JSON.pretty_generate(result.payload)
+      else
+        "Error: #{result.error_message}"
+      end
+    rescue Control::Client::ServerUnavailable => e
+      "Superkick server unavailable: #{e.message}"
+    end
+
+    def symbolize_keys(hash)
+      hash.transform_keys(&:to_sym)
+    end
+
+    def symbolize_keys_deep(hash)
+      hash.each_with_object({}) do |(k, v), result|
+        result[k.to_sym] = v.is_a?(Hash) ? symbolize_keys_deep(v) : v
+      end
+    end
+
+    def server_request(command, **params)
+      @control_client.request(command, **params)
+    end
+  end
+end