agentf 0.3.0 → 0.4.0

data/lib/agentf/installer.rb

@@ -6,25 +6,25 @@ require "yaml"
 module Agentf
   class Installer
     READ_ACTIONS = {
-      "get_recent_memories" => { cli: "agentf memory recent -n 10", tool: "agentf_memory_recent" },
-      "get_pitfalls" => { cli: "agentf memory pitfalls -n 10", tool: "agentf_memory_recent" },
-      "get_lessons" => { cli: "agentf memory lessons -n 10", tool: "agentf_memory_recent" },
-      "get_successes" => { cli: "agentf memory successes -n 10", tool: "agentf_memory_recent" },
-      "get_intents" => { cli: "agentf memory intents", tool: "agentf_memory_recent" },
-      "get_all_tags" => { cli: "agentf memory tags", tool: "agentf_memory_recent" },
-      "get_by_tag" => { cli: "agentf memory by-tag <tag> -n 10", tool: "agentf_memory_search" },
-      "get_by_type" => { cli: "agentf memory by-type <type> -n 10", tool: "agentf_memory_search" },
-      "get_by_agent" => { cli: "agentf memory by-agent <agent> -n 10", tool: "agentf_memory_search" },
-      "search" => { cli: "agentf memory search \"<query>\" -n 10", tool: "agentf_memory_search" },
-      "get_summary" => { cli: "agentf memory summary", tool: "agentf_memory_recent" }
+      "get_recent_memories" => { cli: "agentf memory recent -n 10", tool: "agentf-memory-recent" },
+      "get_pitfalls" => { cli: "agentf memory pitfalls -n 10", tool: "agentf-memory-recent" },
+      "get_lessons" => { cli: "agentf memory lessons -n 10", tool: "agentf-memory-recent" },
+      "get_successes" => { cli: "agentf memory successes -n 10", tool: "agentf-memory-recent" },
+      "get_intents" => { cli: "agentf memory intents", tool: "agentf-memory-recent" },
+      "get_all_tags" => { cli: "agentf memory tags", tool: "agentf-memory-recent" },
+      "get_by_tag" => { cli: "agentf memory by-tag <tag> -n 10", tool: "agentf-memory-search" },
+      "get_by_type" => { cli: "agentf memory by-type <type> -n 10", tool: "agentf-memory-search" },
+      "get_by_agent" => { cli: "agentf memory by-agent <agent> -n 10", tool: "agentf-memory-search" },
+      "search" => { cli: "agentf memory search \"<query>\" -n 10", tool: "agentf-memory-search" },
+      "get_summary" => { cli: "agentf memory summary", tool: "agentf-memory-recent" }
     }.freeze
 
     WRITE_ACTIONS = {
-      "store_lesson" => { cli: "agentf memory add-lesson \"<title>\" \"<description>\" --agent=<AGENT> --tags=learning", tool: "agentf_memory_add_lesson" },
-      "store_success" => { cli: "agentf memory add-success \"<title>\" \"<description>\" --agent=<AGENT> --tags=success", tool: "agentf_memory_add_success" },
-      "store_pitfall" => { cli: "agentf memory add-pitfall \"<title>\" \"<description>\" --agent=<AGENT> --tags=pitfall", tool: "agentf_memory_add_pitfall" },
-      "store_business_intent" => { cli: "agentf memory add-business-intent \"<title>\" \"<description>\" --tags=strategy", tool: "agentf_memory_add_lesson" },
-      "store_feature_intent" => { cli: "agentf memory add-feature-intent \"<title>\" \"<description>\" --acceptance=\"<criteria>\"", tool: "agentf_memory_add_lesson" }
+      "store_lesson" => { cli: "agentf memory add-lesson \"<title>\" \"<description>\" --agent=<AGENT> --tags=learning", tool: "agentf-memory-add-lesson" },
+      "store_success" => { cli: "agentf memory add-success \"<title>\" \"<description>\" --agent=<AGENT> --tags=success", tool: "agentf-memory-add-success" },
+      "store_pitfall" => { cli: "agentf memory add-pitfall \"<title>\" \"<description>\" --agent=<AGENT> --tags=pitfall", tool: "agentf-memory-add-pitfall" },
+      "store_business_intent" => { cli: "agentf memory add-business-intent \"<title>\" \"<description>\" --tags=strategy", tool: "agentf-memory-add-lesson" },
+      "store_feature_intent" => { cli: "agentf memory add-feature-intent \"<title>\" \"<description>\" --acceptance=\"<criteria>\"", tool: "agentf-memory-add-lesson" }
     }.freeze
 
     PROVIDER_LAYOUTS = {
@@ -116,7 +116,7 @@ module Agentf
     def write_opencode_helpers(root:)
       writes = []
       writes << write_manifest(
-        File.join(root, ".opencode/agents/agentf-workflow-engine.md"),
+        File.join(root, ".opencode/agents/agentf-orchestrator.md"),
         render_workflow_engine_manifest
       )
       writes << write_manifest(
@@ -160,7 +160,7 @@ module Agentf
 
     def render_agent_manifest(klass, provider:)
       meta = {
-        "name" => klass.typed_name,
+        "name" => agent_identifier(klass),
         "description" => klass.description,
         "commands" => klass.commands,
         "memory" => klass.memory_concepts,
@@ -171,6 +171,18 @@ module Agentf
         #{meta.to_yaml}---
         #{klass.prompt}
 
+        ## Core Mission
+        #{klass.description}
+
+        ## When To Use
+        #{klass.when_to_use}
+
+        ## Deliverables
+        #{Array(klass.deliverables).map { |item| "- #{item}" }.join("\n")}
+
+        ## Working Style
+        #{klass.working_style}
+
         ## Memory Integration
         - Reads: #{Array(klass.memory_concepts["reads"]).join(", ")}
         - Writes: #{Array(klass.memory_concepts["writes"]).join(", ")}
@@ -211,10 +223,10 @@ module Agentf
       end
 
       if actions.none? { |a| a.start_with?("- Read:") }
-        actions << "- Read: Use `agentf_memory_recent` tool"
+        actions << "- Read: Use `agentf-memory-recent` tool"
       end
       if actions.none? { |a| a.start_with?("- Write:") }
-        actions << "- Write: Use `agentf_memory_add_lesson` tool"
+        actions << "- Write: Use `agentf-memory-add-lesson` tool"
       end
 
       actions
@@ -234,10 +246,18 @@ module Agentf
       end
     end
 
+    def agent_identifier(klass)
+      "agentf-#{klass.typed_name.downcase}"
+    end
+
+    def command_identifier(name)
+      "agentf-#{name.to_s.downcase}"
+    end
+
     def render_command_manifest(manifest, provider:)
       commands = Array(manifest.fetch("commands"))
       frontmatter = {
-        "name" => manifest.fetch("name"),
+        "name" => command_identifier(manifest.fetch("name")),
         "description" => manifest.fetch("description"),
         "commands" => commands
       }
@@ -260,9 +280,9 @@ module Agentf
 
         Copilot should call the local `agentf` MCP server tools for runtime actions.
 
-        - Code discovery tools: `code_glob`, `code_grep`, `code_tree`, `code_related_files`
-        - Memory read tools: `memory_recent`, `memory_search`
-        - Memory write tools (if enabled): `memory_add_lesson`, `memory_add_success`, `memory_add_pitfall`
+        - Code discovery tools: `agentf-code-glob`, `agentf-code-grep`, `agentf-code-tree`, `agentf-code-related-files`
+        - Memory read tools: `agentf-memory-recent`, `agentf-memory-search`
+        - Memory write tools (if enabled): `agentf-memory-add-lesson`, `agentf-memory-add-success`, `agentf-memory-add-pitfall`
 
         MCP server is started via `agentf mcp-server` and runs locally over stdio.
       MARKDOWN
@@ -273,12 +293,12 @@ module Agentf
 
       command_name = manifest.fetch("name")
       recommended_tools = case command_name
-                          when "explorer"
-                            "`code_glob`, `code_grep`, `code_tree`, `code_related_files`"
-                          when "memory"
-                            "`memory_recent`, `memory_search`, `memory_add_lesson`, `memory_add_success`, `memory_add_pitfall`"
-                          else
-                            "`code_glob`, `code_grep`, `memory_recent`, `memory_search`"
+                           when "explorer"
+                             "`agentf-code-glob`, `agentf-code-grep`, `agentf-code-tree`, `agentf-code-related-files`"
+                           when "memory"
+                             "`agentf-memory-recent`, `agentf-memory-search`, `agentf-memory-add-lesson`, `agentf-memory-add-success`, `agentf-memory-add-pitfall`"
+                           else
+                             "`agentf-code-glob`, `agentf-code-grep`, `agentf-memory-recent`, `agentf-memory-search`"
                           end
 
       <<~MARKDOWN
@@ -294,9 +314,15 @@ module Agentf
       <<~MARKDOWN
         # AGENTF-WORKFLOW-ENGINE Agent
 
+        ## Identity
+
+        - Role: ORCHESTRATOR
+        - Division: strategy
+        - Specialty: orchestration
+
         ## Role
 
-        The WORKFLOW_ENGINE coordinates end-to-end workflows by selecting a provider adapter (`opencode` or `copilot`), creating an execution plan, and running agents in sequence.
+        The ORCHESTRATOR coordinates end-to-end workflows by selecting a provider adapter (`opencode` or `copilot`), creating an execution plan, and running agents in sequence.
 
         Implemented in `lib/agentf/workflow_engine.rb`.
 
@@ -311,11 +337,11 @@ module Agentf
 
         ## Execution Flow
 
-        1. WORKFLOW_ENGINE → Requests provider plan
-        2. WORKFLOW_ENGINE → Captures feature intent in memory
-        3. WORKFLOW_ENGINE → Executes planned agents sequentially
+        1. ORCHESTRATOR → Requests provider plan
+        2. ORCHESTRATOR → Captures feature intent in memory
+        3. ORCHESTRATOR → Executes planned agents sequentially
         4. Each agent → Reads relevant context + writes lessons
-        5. WORKFLOW_ENGINE → Summarizes status and returns results
+        5. ORCHESTRATOR → Summarizes status and returns results
 
         ## Notes
 
@@ -384,8 +410,8 @@ module Agentf
 
         export const agentfPlugin: Plugin = async () => {
           return {
-            tool: {
-              agentf_code_glob: tool({
+            tools: {
+              "agentf-code-glob": tool({
                 description: "Find files using project glob patterns via Agentf code CLI.",
                 args: {
                   pattern: tool.schema.string().describe("Glob pattern, example: lib/**/*.rb"),
@@ -400,7 +426,7 @@ module Agentf
                   return runAgentfCli(context.directory, "code", "glob", [args.pattern, ...commandArgs]);
                 },
               }),
-              agentf_code_grep: tool({
+              "agentf-code-grep": tool({
                 description: "Search file contents via Agentf code CLI.",
                 args: {
                   pattern: tool.schema.string().describe("Regex/text to search"),
@@ -415,7 +441,7 @@ module Agentf
                   return runAgentfCli(context.directory, "code", "grep", [args.pattern, ...commandArgs]);
                 },
               }),
-              agentf_code_tree: tool({
+              "agentf-code-tree": tool({
                 description: "Get directory tree data via Agentf code CLI.",
                 args: {
                   depth: tool.schema.number().int().min(1).max(10).optional().describe("Max traversal depth"),
@@ -425,7 +451,7 @@ module Agentf
                   return runAgentfCli(context.directory, "code", "tree", [`--depth=${depth}`]);
                 },
               }),
-              agentf_code_related_files: tool({
+              "agentf-code-related-files": tool({
                 description: "Find import and related file hints for a target file.",
                 args: {
                   targetFile: tool.schema.string().describe("Workspace-relative file path"),
@@ -434,7 +460,7 @@ module Agentf
                   return runAgentfCli(context.directory, "code", "related", [args.targetFile]);
                 },
               }),
-              agentf_memory_recent: tool({
+              "agentf-memory-recent": tool({
                 description: "Get recent Agentf memories from Redis.",
                 args: {
                   limit: tool.schema.number().int().min(1).max(100).optional().describe("How many memories to return"),
@@ -444,7 +470,7 @@ module Agentf
                   return runAgentfCli(context.directory, "memory", "recent", ["-n", String(limit)]);
                 },
               }),
-              agentf_memory_search: tool({
+              "agentf-memory-search": tool({
                 description: "Search Agentf memories by keyword.",
                 args: {
                   query: tool.schema.string().describe("Search query"),
@@ -455,7 +481,7 @@ module Agentf
                   return runAgentfCli(context.directory, "memory", "search", [args.query, "-n", String(limit)]);
                 },
               }),
-              agentf_memory_add_lesson: tool({
+              "agentf-memory-add-lesson": tool({
                 description: "Store a lesson memory in Redis.",
                 args: {
                   title: tool.schema.string(),
@@ -473,7 +499,7 @@ module Agentf
                   return runAgentfCli(context.directory, "memory", "add-lesson", commandArgs);
                 },
               }),
-              agentf_memory_add_success: tool({
+              "agentf-memory-add-success": tool({
                 description: "Store a success memory in Redis.",
                 args: {
                   title: tool.schema.string(),
@@ -491,7 +517,7 @@ module Agentf
                   return runAgentfCli(context.directory, "memory", "add-success", commandArgs);
                 },
               }),
-              agentf_memory_add_pitfall: tool({
+              "agentf-memory-add-pitfall": tool({
                 description: "Store a pitfall memory in Redis.",
                 args: {
                   title: tool.schema.string(),
@@ -512,6 +538,8 @@ module Agentf
             },
           };
         };
+
+        export default agentfPlugin;
       TYPESCRIPT
     end
 

data/lib/agentf/mcp/server.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
-require "mcp"
+begin
+  require "mcp"
+rescue LoadError
+  require_relative "stub"
+end
 require "json"
 
 module Agentf
@@ -17,22 +21,24 @@ module Agentf
     #   AGENTF_MCP_MAX_ARG_LENGTH - max length per string argument
     class Server
       KNOWN_TOOLS = %w[
-        code_glob
-        code_grep
-        code_tree
-        code_related_files
-        architecture_analyze_layers
-        memory_recent
-        memory_search
-        memory_add_lesson
-        memory_add_success
-        memory_add_pitfall
+        agentf-code-glob
+        agentf-code-grep
+        agentf-code-tree
+        agentf-code-related-files
+        agentf-architecture-analyze-layers
+        agentf-memory-recent
+        agentf-memory-search
+        agentf-memory-neighbors
+        agentf-memory-subgraph
+        agentf-memory-add-lesson
+        agentf-memory-add-success
+        agentf-memory-add-pitfall
       ].freeze
 
       WRITE_TOOLS = Set.new(%w[
-        memory_add_lesson
-        memory_add_success
-        memory_add_pitfall
+        agentf-memory-add-lesson
+        agentf-memory-add-success
+        agentf-memory-add-pitfall
       ]).freeze
 
       attr_reader :server, :guardrails
@@ -132,25 +138,25 @@ module Agentf
         explorer = @explorer
         mcp_server = self
 
-        s.tool("code_glob") do
+        s.tool("agentf-code-glob") do
           description "Find files using project glob patterns."
           argument :pattern, String, required: true, description: "Glob pattern, e.g. lib/**/*.rb"
           argument :types, Array, required: false, items: String, description: "File extensions to filter, e.g. [\"rb\",\"py\"]"
           call do |args|
-            mcp_server.send(:guard!, "code_glob", **args)
+            mcp_server.send(:guard!, "agentf-code-glob", **args)
             file_types = args[:types]&.empty? ? nil : args[:types]
             results = explorer.glob(args[:pattern], file_types: file_types)
             JSON.generate(pattern: args[:pattern], matches: results, count: results.length)
           end
         end
 
-        s.tool("code_grep") do
+        s.tool("agentf-code-grep") do
           description "Search file contents with regex."
           argument :pattern, String, required: true, description: "Regex or text to search"
           argument :file_pattern, String, required: false, description: "Include pattern, e.g. *.rb"
           argument :context_lines, Integer, required: false, description: "Context lines (0-20)"
           call do |args|
-            mcp_server.send(:guard!, "code_grep", **args)
+            mcp_server.send(:guard!, "agentf-code-grep", **args)
             ctx = args[:context_lines] || 2
             matches = explorer.grep(args[:pattern], file_pattern: args[:file_pattern], context_lines: ctx)
             serialized = matches.map { |m| m.respond_to?(:to_h) ? m.to_h : m }
@@ -158,22 +164,22 @@ module Agentf
           end
         end
 
-        s.tool("code_tree") do
+        s.tool("agentf-code-tree") do
           description "Get directory tree structure."
           argument :depth, Integer, required: false, description: "Max traversal depth (1-10)"
           call do |args|
-            mcp_server.send(:guard!, "code_tree", **args)
+            mcp_server.send(:guard!, "agentf-code-tree", **args)
             max_depth = args[:depth] || 3
             tree = explorer.get_file_tree(max_depth: max_depth)
             JSON.generate(max_depth: max_depth, tree: tree)
           end
         end
 
-        s.tool("code_related_files") do
+        s.tool("agentf-code-related-files") do
           description "Find imports and related files for a target file."
           argument :target_file, String, required: true, description: "Workspace-relative file path"
           call do |args|
-            mcp_server.send(:guard!, "code_related_files", **args)
+            mcp_server.send(:guard!, "agentf-code-related-files", **args)
             related = explorer.find_related_files(args[:target_file])
             JSON.generate(target_file: args[:target_file], related: related)
           end
@@ -187,28 +193,64 @@ module Agentf
         memory = @memory
         mcp_server = self
 
-        s.tool("memory_recent") do
+        s.tool("agentf-memory-recent") do
           description "Get recent memories from Redis."
           argument :limit, Integer, required: false, description: "How many memories to return (1-100)"
           call do |args|
-            mcp_server.send(:guard!, "memory_recent", **args)
+            mcp_server.send(:guard!, "agentf-memory-recent", **args)
             result = reviewer.get_recent_memories(limit: args[:limit] || 10)
             JSON.generate(result)
           end
         end
 
-        s.tool("memory_search") do
+        s.tool("agentf-memory-search") do
           description "Search memories by keyword."
           argument :query, String, required: true, description: "Search query"
           argument :limit, Integer, required: false, description: "How many results to return (1-100)"
           call do |args|
-            mcp_server.send(:guard!, "memory_search", **args)
+            mcp_server.send(:guard!, "agentf-memory-search", **args)
             result = reviewer.search(args[:query], limit: args[:limit] || 10)
             JSON.generate(result)
           end
         end
 
-        s.tool("memory_add_lesson") do
+        s.tool("agentf-memory-neighbors") do
+          description "Get neighboring memory nodes by edge traversal."
+          argument :node_id, String, required: true, description: "Starting node id"
+          argument :relation, String, required: false, description: "Optional relation filter"
+          argument :depth, Integer, required: false, description: "Traversal depth"
+          argument :limit, Integer, required: false, description: "Maximum edges"
+          call do |args|
+            mcp_server.send(:guard!, "agentf-memory-neighbors", **args)
+            result = reviewer.neighbors(
+              args[:node_id],
+              relation: args[:relation],
+              depth: args[:depth] || 1,
+              limit: args[:limit] || 50
+            )
+            JSON.generate(result)
+          end
+        end
+
+        s.tool("agentf-memory-subgraph") do
+          description "Build a subgraph from seed ids."
+          argument :seed_ids, Array, required: true, items: String, description: "Seed node ids"
+          argument :relation_filters, Array, required: false, items: String, description: "Optional relations"
+          argument :depth, Integer, required: false, description: "Traversal depth"
+          argument :limit, Integer, required: false, description: "Maximum edges"
+          call do |args|
+            mcp_server.send(:guard!, "agentf-memory-subgraph", **args)
+            result = reviewer.subgraph(
+              seed_ids: args[:seed_ids] || [],
+              relation_filters: args[:relation_filters],
+              depth: args[:depth] || 2,
+              limit: args[:limit] || 200
+            )
+            JSON.generate(result)
+          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"
@@ -216,12 +258,12 @@ module Agentf
           argument :tags, Array, required: false, items: String, description: "Tags"
           argument :context, String, required: false, description: "Context"
           call do |args|
-            mcp_server.send(:guard!, "memory_add_lesson", **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] || "SPECIALIST",
+              agent: args[:agent] || Agentf::AgentRoles::ENGINEER,
               tags: args[:tags] || [],
               context: args[:context].to_s,
               code_snippet: ""
@@ -230,7 +272,7 @@ module Agentf
           end
         end
 
-        s.tool("memory_add_success") do
+        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"
@@ -238,12 +280,12 @@ module Agentf
           argument :tags, Array, required: false, items: String, description: "Tags"
           argument :context, String, required: false, description: "Context"
           call do |args|
-            mcp_server.send(:guard!, "memory_add_success", **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] || "SPECIALIST",
+              agent: args[:agent] || Agentf::AgentRoles::ENGINEER,
               tags: args[:tags] || [],
               context: args[:context].to_s,
               code_snippet: ""
@@ -252,7 +294,7 @@ module Agentf
           end
         end
 
-        s.tool("memory_add_pitfall") do
+        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"
@@ -260,12 +302,12 @@ module Agentf
           argument :tags, Array, required: false, items: String, description: "Tags"
           argument :context, String, required: false, description: "Context"
           call do |args|
-            mcp_server.send(:guard!, "memory_add_pitfall", **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] || "SPECIALIST",
+              agent: args[:agent] || Agentf::AgentRoles::ENGINEER,
               tags: args[:tags] || [],
               context: args[:context].to_s,
               code_snippet: ""
@@ -279,13 +321,13 @@ module Agentf
         architecture = @architecture
         mcp_server = self
 
-        s.tool("architecture_analyze_layers") do
+        s.tool("agentf-architecture-analyze-layers") do
           description "Analyze architecture layers, review violations, or create gradual adoption plans."
           argument :mode, String, required: false, description: "analyze|review|gradual"
           argument :limit, Integer, required: false, description: "Maximum violations to return for review mode"
           argument :goal, String, required: false, description: "Adoption goal for gradual mode"
           call do |args|
-            mcp_server.send(:guard!, "architecture_analyze_layers", **args)
+            mcp_server.send(:guard!, "agentf-architecture-analyze-layers", **args)
             case (args[:mode] || "analyze").to_s
             when "review"
               JSON.generate(architecture.review_layer_violations(limit: args[:limit] || 20))

data/lib/agentf/mcp/stub.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module MCP
+  # Minimal stub of the MCP::Server DSL so specs can run without the
+  # official MCP gem. Provides just enough behavior for tool
+  # registration, listing, and invocation.
+  class Server
+    Tool = Struct.new(:name, :description, :arguments, :handler, keyword_init: true)
+
+    def initialize(name:, version:)
+      @name = name
+      @version = version
+      @tools = {}
+    end
+
+    def tool(name, &block)
+      builder = ToolBuilder.new(name)
+      builder.instance_eval(&block)
+      @tools[name] = Tool.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
+      raise "Stub MCP::Server cannot run"
+    end
+
+    class ToolBuilder
+      attr_reader :description, :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:, **_opts)
+        @arguments[name] = {
+          required: required,
+          schema: {
+            description: description
+          }
+        }
+      end
+
+      def call(&block)
+        @handler = block
+      end
+    end
+  end
+end