agentf 0.4.7 → 0.6.0

data/lib/agentf/mcp/server.rb

@@ -3,9 +3,9 @@
 begin
   require "mcp"
 rescue LoadError
-  require_relative "stub"
 end
 require "json"
+require "set"
 
 module Agentf
   module MCP
@@ -20,7 +20,163 @@ module Agentf
     #   AGENTF_MCP_ALLOW_WRITES   - true/false, controls memory write tools
     #   AGENTF_MCP_MAX_ARG_LENGTH - max length per string argument
     class Server
+      ToolDefinition = Struct.new(:name, :description, :arguments, :handler, keyword_init: true)
+
+      class ToolBuilder
+        attr_reader :arguments, :handler
+
+        def initialize(name)
+          @name = name
+          @arguments = {}
+        end
+
+        def description(value = nil)
+          @description = value unless value.nil?
+          @description
+        end
+
+        def argument(name, type, required: false, description:, items: nil, **_opts)
+          @arguments[name] = {
+            type: type,
+            items: items,
+            required: required,
+            schema: {
+              type: schema_type(type),
+              description: description
+            }.tap do |schema|
+              schema[:items] = { type: schema_type(items) } if type == Array && items
+            end
+          }
+        end
+
+        def call(&block)
+          @handler = block
+        end
+
+        private
+
+        def schema_type(type)
+          case type&.name
+          when "String" then "string"
+          when "Integer" then "integer"
+          when "Float" then "number"
+          when "TrueClass", "FalseClass" then "boolean"
+          when "Array" then "array"
+          when "Hash" then "object"
+          else
+            "string"
+          end
+        end
+      end
+
+      class RegistryAdapter
+        def initialize(name:, version:)
+          @name = name
+          @version = version
+          @tools = {}
+        end
+
+        def tool(name, &block)
+          builder = ToolBuilder.new(name)
+          builder.instance_eval(&block)
+          @tools[name] = ToolDefinition.new(
+            name: name,
+            description: builder.description,
+            arguments: builder.arguments,
+            handler: builder.handler
+          )
+        end
+
+        def list_tools
+          @tools.values.map do |tool|
+            {
+              name: tool.name,
+              description: tool.description.to_s,
+              inputSchema: {
+                type: "object",
+                properties: tool.arguments.transform_values { |arg| arg[:schema] },
+                required: tool.arguments.select { |_k, arg| arg[:required] }.keys.map(&:to_s)
+              }
+            }
+          end
+        end
+
+        def call_tool(name, **args)
+          tool = @tools[name]
+          raise "Unknown tool: #{name}" unless tool
+
+          tool.handler.call(args)
+        rescue StandardError => e
+          e.message
+        end
+
+        def run
+          runtime_server = build_runtime_server
+          transport = ::MCP::Server::Transports::StdioTransport.new(runtime_server)
+          runtime_server.transport = transport if runtime_server.respond_to?(:transport=)
+          transport.open
+        end
+
+        private
+
+        def build_runtime_server
+          ensure_runtime_support!
+
+          runtime_server = ::MCP::Server.new(name: @name, version: @version)
+          adapter = self
+          @tools.each_value do |tool|
+            runtime_server.define_tool(
+              name: tool.name,
+              description: tool.description,
+              input_schema: runtime_input_schema(tool.arguments)
+            ) do |**kwargs|
+              result = tool.handler.call(kwargs)
+              adapter.send(:build_response, result)
+            rescue StandardError => e
+              ::MCP::Tool::Response.new([::MCP::Content::Text.new(e.message).to_h], error: true)
+            end
+          end
+          runtime_server
+        end
+
+        def ensure_runtime_support!
+          return if defined?(::MCP::Server::Transports::StdioTransport) && defined?(::MCP::Tool::Response) && defined?(::MCP::Content::Text)
+
+          raise "Installed MCP runtime does not support stdio server transport"
+        end
+
+        def runtime_input_schema(arguments)
+          schema = {
+            type: "object",
+            properties: arguments.transform_keys(&:to_s).transform_values { |arg| arg[:schema].transform_keys(&:to_s) }
+          }
+
+          required = arguments.select { |_k, arg| arg[:required] }.keys.map(&:to_s)
+          schema[:required] = required unless required.empty?
+          schema
+        end
+
+        def build_response(result)
+          return result if result.is_a?(::MCP::Tool::Response)
+
+          text = result.is_a?(String) ? result : JSON.generate(result)
+          structured = parse_structured_content(result)
+          ::MCP::Tool::Response.new([::MCP::Content::Text.new(text).to_h], structured_content: structured)
+        end
+
+        def parse_structured_content(result)
+          return result if result.is_a?(Hash)
+          return JSON.parse(result) if result.is_a?(String)
+          return result.as_json if result.respond_to?(:as_json)
+
+          nil
+        rescue JSON::ParserError
+          nil
+        end
+      end
+
       KNOWN_TOOLS = %w[
+        agentf-mcp-list-tools
         agentf-code-glob
         agentf-code-grep
         agentf-code-tree
@@ -28,29 +184,24 @@ module Agentf
         agentf-architecture-analyze-layers
         agentf-memory-recent
         agentf-memory-search
-        agentf-memory-by-tag
         agentf-memory-by-agent
         agentf-memory-by-type
-        agentf-memory-tags
-        agentf-memory-pitfalls
+        agentf-memory-episodes
         agentf-memory-lessons
-        agentf-memory-successes
         agentf-memory-intents
         agentf-memory-business-intents
         agentf-memory-feature-intents
         agentf-memory-neighbors
         agentf-memory-subgraph
+        agentf-memory-add-playbook
         agentf-memory-add-lesson
-        agentf-memory-add-success
-        agentf-memory-add-pitfall
         agentf-memory-add-business-intent
         agentf-memory-add-feature-intent
       ].freeze
 
       WRITE_TOOLS = Set.new(%w[
+        agentf-memory-add-playbook
         agentf-memory-add-lesson
-        agentf-memory-add-success
-        agentf-memory-add-pitfall
         agentf-memory-add-business-intent
         agentf-memory-add-feature-intent
       ]).freeze
@@ -66,6 +217,25 @@ module Agentf
         @server = build_server
       end
 
+      # Helper to centralize confirmation handling for MCP server write tools.
+      # Yields the block that performs the memory write and returns either the
+      # block result or the normalized confirmation hash produced by
+      # Agentf::Agents::Base#safe_memory_write.
+      def safe_mcp_memory_write(memory, attempted: {})
+        begin
+          yield
+          nil
+        rescue Agentf::Memory::RedisMemory::ConfirmationRequired => e
+          {
+            "confirmation_required" => true,
+            "confirmation_details" => e.details,
+            "attempted" => attempted,
+            "confirmed_write_token" => "confirmed",
+            "confirmation_prompt" => "Ask the user whether to save this memory. If they approve, call the same tool again after confirmation. If they decline, do not retry."
+          }
+        end
+      end
+
       # Start the stdio read loop (blocks until stdin closes).
       def run
         @server.run
@@ -139,7 +309,7 @@ module Agentf
       # ── Server construction ─────────────────────────────────────
 
       def build_server
-        s = ::MCP::Server.new(name: "agentf", version: Agentf::VERSION)
+        s = RegistryAdapter.new(name: "agentf", version: Agentf::VERSION)
         register_code_tools(s)
         register_memory_tools(s)
         register_architecture_tools(s)
@@ -218,7 +388,7 @@ module Agentf
         end
 
         s.tool("agentf-memory-search") do
-          description "Search memories by keyword."
+          description "Search memories semantically."
           argument :query, String, required: true, description: "Search query"
           argument :limit, Integer, required: false, description: "How many results to return (1-100)"
           call do |args|
@@ -228,13 +398,13 @@ module Agentf
           end
         end
 
-        s.tool("agentf-memory-by-tag") do
-          description "Get memories by tag."
-          argument :tag, String, required: true, description: "Tag to filter"
+        s.tool("agentf-memory-episodes") do
+          description "List episode memories with optional outcome filter."
+          argument :outcome, String, required: false, description: "Optional outcome filter: positive|negative|neutral"
           argument :limit, Integer, required: false, description: "How many results to return (1-100)"
           call do |args|
-            mcp_server.send(:guard!, "agentf-memory-by-tag", **args)
-            result = reviewer.get_by_tag(args[:tag], limit: args[:limit] || 10)
+            mcp_server.send(:guard!, "agentf-memory-episodes", **args)
+            result = reviewer.get_episodes(limit: args[:limit] || 10, outcome: args[:outcome])
             JSON.generate(result)
           end
         end
@@ -261,25 +431,6 @@ module Agentf
           end
         end
 
-        s.tool("agentf-memory-tags") do
-          description "List all unique memory tags."
-          call do |args|
-            mcp_server.send(:guard!, "agentf-memory-tags", **args)
-            result = reviewer.get_all_tags
-            JSON.generate(result)
-          end
-        end
-
-        s.tool("agentf-memory-pitfalls") do
-          description "List pitfall memories."
-          argument :limit, Integer, required: false, description: "How many results to return (1-100)"
-          call do |args|
-            mcp_server.send(:guard!, "agentf-memory-pitfalls", **args)
-            result = reviewer.get_pitfalls(limit: args[:limit] || 10)
-            JSON.generate(result)
-          end
-        end
-
         s.tool("agentf-memory-lessons") do
           description "List lesson memories."
           argument :limit, Integer, required: false, description: "How many results to return (1-100)"
@@ -290,16 +441,6 @@ module Agentf
           end
         end
 
-        s.tool("agentf-memory-successes") do
-          description "List success memories."
-          argument :limit, Integer, required: false, description: "How many results to return (1-100)"
-          call do |args|
-            mcp_server.send(:guard!, "agentf-memory-successes", **args)
-            result = reviewer.get_successes(limit: args[:limit] || 10)
-            JSON.generate(result)
-          end
-        end
-
         s.tool("agentf-memory-intents") do
           description "List intents (business|feature)."
           argument :kind, String, required: false, description: "Optional: business|feature"
@@ -344,19 +485,27 @@ module Agentf
           description "Store a business intent in Redis."
           argument :title, String, required: true, description: "Intent title"
           argument :description, String, required: true, description: "Intent description"
-          argument :tags, Array, required: false, items: String, description: "Tags"
           argument :constraints, Array, required: false, items: String, description: "Constraints"
           argument :priority, Integer, required: false, description: "Priority"
           call do |args|
             mcp_server.send(:guard!, "agentf-memory-add-business-intent", **args)
-            id = memory.store_business_intent(
-              title: args[:title],
-              description: args[:description],
-              tags: args[:tags] || [],
-              constraints: args[:constraints] || [],
-              priority: args[:priority] || 1
-            )
-            JSON.generate(id: id, type: "business_intent", status: "stored")
+              begin
+                id = nil
+                res = mcp_server.send(:safe_mcp_memory_write, memory, attempted: { tool: "agentf-memory-add-business-intent", args: args }) do
+                  id = memory.store_business_intent(
+                    title: args[:title],
+                    description: args[:description],
+                    constraints: args[:constraints] || [],
+                    priority: args[:priority] || 1
+                  )
+                end
+
+                if res.is_a?(Hash) && res["confirmation_required"]
+                  JSON.generate(confirmation_required: true, confirmation_details: res["confirmation_details"], attempted: res["attempted"])
+                else
+                  JSON.generate(id: id, type: "business_intent", status: "stored")
+                end
+              end
           end
         end
 
@@ -364,21 +513,29 @@ module Agentf
           description "Store a feature intent in Redis."
           argument :title, String, required: true, description: "Intent title"
           argument :description, String, required: true, description: "Intent description"
-          argument :tags, Array, required: false, items: String, description: "Tags"
           argument :acceptance, Array, required: false, items: String, description: "Acceptance criteria"
           argument :non_goals, Array, required: false, items: String, description: "Non-goals"
           argument :related_task_id, String, required: false, description: "Related task id"
           call do |args|
             mcp_server.send(:guard!, "agentf-memory-add-feature-intent", **args)
-            id = memory.store_feature_intent(
-              title: args[:title],
-              description: args[:description],
-              tags: args[:tags] || [],
-              acceptance_criteria: args[:acceptance] || [],
-              non_goals: args[:non_goals] || [],
-              related_task_id: args[:related_task_id]
-            )
-            JSON.generate(id: id, type: "feature_intent", status: "stored")
+              begin
+                id = nil
+                res = mcp_server.send(:safe_mcp_memory_write, memory, attempted: { tool: "agentf-memory-add-feature-intent", args: args }) do
+                  id = memory.store_feature_intent(
+                    title: args[:title],
+                    description: args[:description],
+                    acceptance_criteria: args[:acceptance] || [],
+                    non_goals: args[:non_goals] || [],
+                    related_task_id: args[:related_task_id]
+                  )
+                end
+
+                if res.is_a?(Hash) && res["confirmation_required"]
+                  JSON.generate(confirmation_required: true, confirmation_details: res["confirmation_details"], attempted: res["attempted"])
+                else
+                  JSON.generate(id: id, type: "feature_intent", status: "stored")
+                end
+              end
           end
         end
 
@@ -418,69 +575,92 @@ module Agentf
           end
         end
 
+        s.tool("agentf-mcp-list-tools") do
+          description "List MCP tools and current guardrail status."
+          call do |_args|
+            # Use guard to ensure the caller is allowed to invoke tools
+            mcp_server.send(:guard!, "agentf-mcp-list-tools", **{})
+
+            tools = s.list_tools
+            guard = {
+              allowed_tools: mcp_server.guardrails[:allowed_tools].to_a,
+              allow_writes: mcp_server.guardrails[:allow_writes],
+              max_arg_length: mcp_server.guardrails[:max_arg_length]
+            }
+
+            JSON.generate({ tools: tools, guardrails: guard })
+          end
+        end
+
         s.tool("agentf-memory-add-lesson") do
           description "Store a lesson memory in Redis."
           argument :title, String, required: true, description: "Lesson title"
           argument :description, String, required: true, description: "Lesson description"
           argument :agent, String, required: false, description: "Agent name"
-          argument :tags, Array, required: false, items: String, description: "Tags"
           argument :context, String, required: false, description: "Context"
           call do |args|
             mcp_server.send(:guard!, "agentf-memory-add-lesson", **args)
-            id = memory.store_episode(
-              type: "lesson",
-              title: args[:title],
-              description: args[:description],
-              agent: args[:agent] || Agentf::AgentRoles::ENGINEER,
-              tags: args[:tags] || [],
-              context: args[:context].to_s,
-              code_snippet: ""
-            )
-            JSON.generate(id: id, type: "lesson", status: "stored")
-          end
-        end
-
-        s.tool("agentf-memory-add-success") do
-          description "Store a success memory in Redis."
-          argument :title, String, required: true, description: "Success title"
-          argument :description, String, required: true, description: "Success description"
-          argument :agent, String, required: false, description: "Agent name"
-          argument :tags, Array, required: false, items: String, description: "Tags"
-          argument :context, String, required: false, description: "Context"
-          call do |args|
-            mcp_server.send(:guard!, "agentf-memory-add-success", **args)
-            id = memory.store_episode(
-              type: "success",
-              title: args[:title],
-              description: args[:description],
-              agent: args[:agent] || Agentf::AgentRoles::ENGINEER,
-              tags: args[:tags] || [],
-              context: args[:context].to_s,
-              code_snippet: ""
-            )
-            JSON.generate(id: id, type: "success", status: "stored")
+              begin
+                id = nil
+                res = mcp_server.send(:safe_mcp_memory_write, memory, attempted: { tool: "agentf-memory-add-lesson", args: args }) do
+                  id = memory.store_episode(
+                    type: "lesson",
+                    title: args[:title],
+                    description: args[:description],
+                    agent: args[:agent] || Agentf::AgentRoles::ENGINEER,
+                    context: args[:context].to_s,
+                    code_snippet: ""
+                  )
+                end
+
+                if res.is_a?(Hash) && res["confirmation_required"]
+                  JSON.generate(
+                    confirmation_required: true,
+                    confirmation_details: res["confirmation_details"],
+                    attempted: res["attempted"],
+                    confirmed_write_token: res["confirmed_write_token"],
+                    confirmation_prompt: res["confirmation_prompt"]
+                  )
+                else
+                  JSON.generate(id: id, type: "lesson", status: "stored")
+                end
+              end
           end
         end
 
-        s.tool("agentf-memory-add-pitfall") do
-          description "Store a pitfall memory in Redis."
-          argument :title, String, required: true, description: "Pitfall title"
-          argument :description, String, required: true, description: "Pitfall description"
+        s.tool("agentf-memory-add-playbook") do
+          description "Store a playbook memory in Redis."
+          argument :title, String, required: true, description: "Playbook title"
+          argument :description, String, required: true, description: "Playbook description"
           argument :agent, String, required: false, description: "Agent name"
-          argument :tags, Array, required: false, items: String, description: "Tags"
-          argument :context, String, required: false, description: "Context"
+          argument :steps, Array, required: false, items: String, description: "Ordered playbook steps"
+          argument :feature_area, String, required: false, description: "Feature area"
           call do |args|
-            mcp_server.send(:guard!, "agentf-memory-add-pitfall", **args)
-            id = memory.store_episode(
-              type: "pitfall",
-              title: args[:title],
-              description: args[:description],
-              agent: args[:agent] || Agentf::AgentRoles::ENGINEER,
-              tags: args[:tags] || [],
-              context: args[:context].to_s,
-              code_snippet: ""
-            )
-            JSON.generate(id: id, type: "pitfall", status: "stored")
+            mcp_server.send(:guard!, "agentf-memory-add-playbook", **args)
+              begin
+                id = nil
+                res = mcp_server.send(:safe_mcp_memory_write, memory, attempted: { tool: "agentf-memory-add-playbook", args: args }) do
+                  id = memory.store_playbook(
+                    title: args[:title],
+                    description: args[:description],
+                    agent: args[:agent] || Agentf::AgentRoles::PLANNER,
+                    steps: args[:steps] || [],
+                    feature_area: args[:feature_area]
+                  )
+                end
+
+                if res.is_a?(Hash) && res["confirmation_required"]
+                  JSON.generate(
+                    confirmation_required: true,
+                    confirmation_details: res["confirmation_details"],
+                    attempted: res["attempted"],
+                    confirmed_write_token: res["confirmed_write_token"],
+                    confirmation_prompt: res["confirmation_prompt"]
+                  )
+                else
+                  JSON.generate(id: id, type: "playbook", status: "stored")
+                end
+              end
           end
         end
       end