trak_flow 0.1.3

data/lib/trak_flow/mcp/server.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "fast_mcp"
+require "puma"
+require "puma/configuration"
+require "rack"
+require "rackup"
+
+module TrakFlow
+  module Mcp
+    class Server
+      attr_reader :name, :version, :mcp_server
+
+      def initialize(name: "trak_flow", version: TrakFlow::VERSION)
+        @name = name
+        @version = version
+        @mcp_server = FastMcp::Server.new(name: name, version: version)
+        register_tools
+        register_resources
+      end
+
+      def start_stdio
+        # Use warn (stderr) not puts (stdout) - stdout is for MCP protocol
+        warn "Starting TrakFlow MCP Server (stdio transport)..."
+        mcp_server.start
+      end
+
+      def start_http(port: nil)
+        port ||= TrakFlow.config.mcp.port
+        puts "Starting TrakFlow MCP Server (HTTP transport on port #{port})..."
+
+        rack_app = create_rack_app
+
+        # Configure Puma (supports rack.hijack for SSE)
+        puma_config = Puma::Configuration.new do |config|
+          config.bind "tcp://0.0.0.0:#{port}"
+          config.threads 1, 5
+          config.workers 0
+          config.quiet
+          config.app rack_app
+        end
+
+        launcher = Puma::Launcher.new(puma_config)
+
+        trap("INT") { launcher.stop }
+        trap("TERM") { launcher.stop }
+
+        launcher.run
+      end
+
+      def start_both(http_port: nil)
+        http_port ||= TrakFlow.config.mcp.port
+        puts "Starting TrakFlow MCP Server (dual transport)..."
+        puts "  - HTTP: port #{http_port}"
+        puts "  - STDIO: reading from stdin"
+
+        # Start HTTP in a thread
+        http_thread = Thread.new do
+          start_http_server(http_port)
+        end
+
+        # Run STDIO in main thread (blocking)
+        mcp_server.start
+
+        http_thread.join
+      end
+
+      private
+
+      def create_rack_app
+        server = mcp_server
+        Rack::Builder.new do
+          use FastMcp::Transports::RackTransport, server
+          run ->(_env) { [404, { "Content-Type" => "text/plain" }, ["TrakFlow MCP Server - Use /mcp/sse for SSE transport"]] }
+        end.to_app
+      end
+
+      def start_http_server(port)
+        rack_app = create_rack_app
+
+        # Configure Puma (supports rack.hijack for SSE)
+        puma_config = Puma::Configuration.new do |config|
+          config.bind "tcp://0.0.0.0:#{port}"
+          config.threads 1, 5
+          config.workers 0
+          config.quiet
+          config.app rack_app
+        end
+
+        launcher = Puma::Launcher.new(puma_config)
+
+        trap("INT") { launcher.stop }
+        trap("TERM") { launcher.stop }
+
+        launcher.run
+      end
+
+      def register_tools
+        # Task management tools
+        mcp_server.register_tool(Tools::TaskCreate)
+        mcp_server.register_tool(Tools::TaskUpdate)
+        mcp_server.register_tool(Tools::TaskClose)
+        mcp_server.register_tool(Tools::TaskStart)
+        mcp_server.register_tool(Tools::TaskBlock)
+        mcp_server.register_tool(Tools::TaskDefer)
+
+        # Plan/Workflow tools
+        mcp_server.register_tool(Tools::PlanCreate)
+        mcp_server.register_tool(Tools::PlanAddStep)
+        mcp_server.register_tool(Tools::PlanStart)
+        mcp_server.register_tool(Tools::PlanRun)
+        mcp_server.register_tool(Tools::WorkflowDiscard)
+        mcp_server.register_tool(Tools::WorkflowSummarize)
+
+        # Dependency tools
+        mcp_server.register_tool(Tools::DepAdd)
+        mcp_server.register_tool(Tools::DepRemove)
+
+        # Label tools
+        mcp_server.register_tool(Tools::LabelAdd)
+        mcp_server.register_tool(Tools::LabelRemove)
+
+        # Comment tool
+        mcp_server.register_tool(Tools::CommentAdd)
+      end
+
+      def register_resources
+        mcp_server.register_resource(Resources::TaskList)
+        mcp_server.register_resource(Resources::TaskById)
+        mcp_server.register_resource(Resources::TaskNext)
+        mcp_server.register_resource(Resources::PlanList)
+        mcp_server.register_resource(Resources::PlanById)
+        mcp_server.register_resource(Resources::WorkflowList)
+        mcp_server.register_resource(Resources::WorkflowById)
+        mcp_server.register_resource(Resources::LabelList)
+        mcp_server.register_resource(Resources::DependencyGraph)
+      end
+    end
+  end
+end

data/lib/trak_flow/mcp/tools/base_tool.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Mcp
+    module Tools
+      class BaseTool < FastMcp::Tool
+        class << self
+          def with_database
+            TrakFlow.ensure_initialized!
+
+            db = Storage::Database.new
+            db.connect
+
+            jsonl = Storage::Jsonl.new
+            jsonl.import(db) if jsonl.exists?
+
+            result = yield db
+
+            jsonl.export(db) if db.dirty?
+
+            result
+          ensure
+            db&.close
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trak_flow/mcp/tools/comment_add.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Mcp
+    module Tools
+      class CommentAdd < BaseTool
+        tool_name "comment_add"
+        description "Add a comment to a task"
+
+        arguments do
+          required(:task_id).filled(:string).description("Task ID")
+          required(:body).filled(:string).description("Comment text")
+          optional(:author).filled(:string).description("Comment author (default: robot)")
+        end
+
+        def call(task_id:, body:, author: "robot")
+          self.class.with_database do |db|
+            db.find_task!(task_id)
+
+            comment = Models::Comment.new(
+              task_id: task_id,
+              body: body,
+              author: author
+            )
+            db.add_comment(comment)
+
+            comment.to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trak_flow/mcp/tools/dep_add.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Mcp
+    module Tools
+      class DepAdd < BaseTool
+        tool_name "dep_add"
+        description "Add a dependency between two tasks"
+
+        arguments do
+          required(:source_id).filled(:string).description("Source task ID")
+          required(:target_id).filled(:string).description("Target task ID")
+          optional(:type).filled(:string).description("Dependency type: blocks, related, parent-child, discovered-from (default: blocks)")
+        end
+
+        def call(source_id:, target_id:, type: "blocks")
+          self.class.with_database do |db|
+            db.find_task!(source_id)
+            db.find_task!(target_id)
+
+            dep = Models::Dependency.new(
+              source_id: source_id,
+              target_id: target_id,
+              type: type
+            )
+            db.add_dependency(dep)
+
+            { source_id: source_id, target_id: target_id, type: type, success: true }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trak_flow/mcp/tools/dep_remove.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Mcp
+    module Tools
+      class DepRemove < BaseTool
+        tool_name "dep_remove"
+        description "Remove a dependency between two tasks"
+
+        arguments do
+          required(:source_id).filled(:string).description("Source task ID")
+          required(:target_id).filled(:string).description("Target task ID")
+        end
+
+        def call(source_id:, target_id:)
+          self.class.with_database do |db|
+            db.remove_dependency(source_id, target_id)
+
+            { source_id: source_id, target_id: target_id, removed: true }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trak_flow/mcp/tools/label_add.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Mcp
+    module Tools
+      class LabelAdd < BaseTool
+        tool_name "label_add"
+        description "Add a label to a task"
+
+        arguments do
+          required(:task_id).filled(:string).description("Task ID")
+          required(:name).filled(:string).description("Label name")
+        end
+
+        def call(task_id:, name:)
+          self.class.with_database do |db|
+            db.find_task!(task_id)
+
+            label = Models::Label.new(task_id: task_id, name: name)
+            db.add_label(label)
+
+            { task_id: task_id, label: name, success: true }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trak_flow/mcp/tools/label_remove.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Mcp
+    module Tools
+      class LabelRemove < BaseTool
+        tool_name "label_remove"
+        description "Remove a label from a task"
+
+        arguments do
+          required(:task_id).filled(:string).description("Task ID")
+          required(:name).filled(:string).description("Label name")
+        end
+
+        def call(task_id:, name:)
+          self.class.with_database do |db|
+            db.remove_label(task_id, name)
+
+            { task_id: task_id, label: name, removed: true }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trak_flow/mcp/tools/plan_add_step.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Mcp
+    module Tools
+      class PlanAddStep < BaseTool
+        tool_name "plan_add_step"
+        description "Add a step (child task) to a Plan"
+
+        arguments do
+          required(:plan_id).filled(:string).description("Plan ID to add step to")
+          required(:title).filled(:string).description("Step title")
+          optional(:description).filled(:string).description("Step description")
+          optional(:type).filled(:string).description("Task type (default: task)")
+          optional(:priority).filled(:integer).description("Priority 0-4 (default: 2)")
+        end
+
+        def call(plan_id:, title:, description: nil, type: "task", priority: 2)
+          self.class.with_database do |db|
+            plan = db.find_task!(plan_id)
+            raise TrakFlow::Error, "#{plan_id} is not a Plan" unless plan.plan?
+
+            task = db.create_child_task(plan_id, {
+              title: title,
+              description: description || "",
+              type: type,
+              priority: priority
+            })
+            task.to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trak_flow/mcp/tools/plan_create.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Mcp
+    module Tools
+      class PlanCreate < BaseTool
+        tool_name "plan_create"
+        description "Create a new Plan (workflow blueprint)"
+
+        arguments do
+          required(:title).filled(:string).description("Plan title")
+          optional(:description).filled(:string).description("Plan description")
+          optional(:type).filled(:string).description("Task type (default: task)")
+          optional(:priority).filled(:integer).description("Priority 0-4 (default: 2)")
+        end
+
+        def call(title:, description: nil, type: "task", priority: 2)
+          self.class.with_database do |db|
+            plan = Models::Task.new(
+              title: title,
+              description: description || "",
+              type: type,
+              priority: priority,
+              plan: true
+            )
+            db.create_task(plan)
+            plan.to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trak_flow/mcp/tools/plan_run.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Mcp
+    module Tools
+      class PlanRun < BaseTool
+        tool_name "plan_run"
+        description "Create an ephemeral Workflow from a Plan (one-shot, garbage collectible)"
+
+        arguments do
+          required(:plan_id).filled(:string).description("Plan ID to instantiate")
+          optional(:variables).hash.description("Template variables for interpolation")
+        end
+
+        def call(plan_id:, variables: {})
+          self.class.with_database do |db|
+            plan = db.find_task!(plan_id)
+            raise TrakFlow::Error, "#{plan_id} is not a Plan" unless plan.plan?
+
+            workflow = Models::Task.new(
+              title: interpolate_vars(plan.title, variables),
+              description: interpolate_vars(plan.description, variables),
+              type: plan.type,
+              priority: plan.priority,
+              source_plan_id: plan.id,
+              ephemeral: true
+            )
+            db.create_task(workflow)
+            workflow.append_trace("INSTANTIATED", "from Plan #{plan.id} (ephemeral)")
+            db.update_task(workflow)
+
+            db.find_plan_tasks(plan_id).each do |step|
+              db.create_child_task(workflow.id, {
+                title: interpolate_vars(step.title, variables),
+                description: interpolate_vars(step.description, variables),
+                type: step.type,
+                priority: step.priority,
+                ephemeral: true
+              })
+            end
+
+            workflow.to_h
+          end
+        end
+
+        private
+
+        def interpolate_vars(text, vars)
+          return text if text.nil? || vars.empty?
+
+          result = text.dup
+          vars.each { |key, value| result.gsub!("{{#{key}}}", value.to_s) }
+          result
+        end
+      end
+    end
+  end
+end

data/lib/trak_flow/mcp/tools/plan_start.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Mcp
+    module Tools
+      class PlanStart < BaseTool
+        tool_name "plan_start"
+        description "Create a persistent Workflow from a Plan"
+
+        arguments do
+          required(:plan_id).filled(:string).description("Plan ID to instantiate")
+          optional(:variables).hash.description("Template variables for interpolation")
+        end
+
+        def call(plan_id:, variables: {})
+          self.class.with_database do |db|
+            plan = db.find_task!(plan_id)
+            raise TrakFlow::Error, "#{plan_id} is not a Plan" unless plan.plan?
+
+            workflow = Models::Task.new(
+              title: interpolate_vars(plan.title, variables),
+              description: interpolate_vars(plan.description, variables),
+              type: plan.type,
+              priority: plan.priority,
+              source_plan_id: plan.id,
+              ephemeral: false
+            )
+            db.create_task(workflow)
+            workflow.append_trace("INSTANTIATED", "from Plan #{plan.id}")
+            db.update_task(workflow)
+
+            db.find_plan_tasks(plan_id).each do |step|
+              db.create_child_task(workflow.id, {
+                title: interpolate_vars(step.title, variables),
+                description: interpolate_vars(step.description, variables),
+                type: step.type,
+                priority: step.priority,
+                ephemeral: false
+              })
+            end
+
+            workflow.to_h
+          end
+        end
+
+        private
+
+        def interpolate_vars(text, vars)
+          return text if text.nil? || vars.empty?
+
+          result = text.dup
+          vars.each { |key, value| result.gsub!("{{#{key}}}", value.to_s) }
+          result
+        end
+      end
+    end
+  end
+end

data/lib/trak_flow/mcp/tools/task_block.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Mcp
+    module Tools
+      class TaskBlock < BaseTool
+        tool_name "task_block"
+        description "Mark a task as blocked"
+
+        arguments do
+          required(:id).filled(:string).description("Task ID to block")
+          optional(:reason).filled(:string).description("Reason for blocking")
+        end
+
+        def call(id:, reason: nil)
+          self.class.with_database do |db|
+            task = db.find_task!(id)
+            task.status = "blocked"
+            task.append_trace("BLOCKED", reason) if reason
+            db.update_task(task)
+            task.to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trak_flow/mcp/tools/task_close.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Mcp
+    module Tools
+      class TaskClose < BaseTool
+        tool_name "task_close"
+        description "Close a task"
+
+        arguments do
+          required(:id).filled(:string).description("Task ID to close")
+          optional(:reason).filled(:string).description("Reason for closing")
+        end
+
+        def call(id:, reason: nil)
+          self.class.with_database do |db|
+            task = db.find_task!(id)
+            task.close!(reason: reason)
+            db.update_task(task)
+            task.to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trak_flow/mcp/tools/task_create.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Mcp
+    module Tools
+      class TaskCreate < BaseTool
+        tool_name "task_create"
+        description "Create a new task with title, type, and priority"
+
+        arguments do
+          required(:title).filled(:string).description("Task title")
+          optional(:type).filled(:string).description("Task type: bug, feature, task, epic, chore (default: task)")
+          optional(:priority).filled(:integer).description("Priority 0-4: 0=critical, 4=backlog (default: 2)")
+          optional(:description).filled(:string).description("Task description")
+          optional(:assignee).filled(:string).description("Assignee name")
+          optional(:parent_id).filled(:string).description("Parent task ID for creating child tasks")
+          optional(:labels).array(:string).description("Labels to add")
+        end
+
+        def call(title:, type: "task", priority: 2, description: nil, assignee: nil, parent_id: nil, labels: [])
+          self.class.with_database do |db|
+            task = if parent_id
+                db.create_child_task(parent_id, {
+                  title: title,
+                  description: description,
+                  type: type,
+                  priority: priority,
+                  assignee: assignee
+                })
+              else
+                new_task = Models::Task.new(
+                  title: title,
+                  description: description,
+                  type: type,
+                  priority: priority,
+                  assignee: assignee
+                )
+                db.create_task(new_task)
+              end
+
+            labels.each do |label_name|
+              db.add_label(Models::Label.new(task_id: task.id, name: label_name))
+            end
+
+            task.to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trak_flow/mcp/tools/task_defer.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Mcp
+    module Tools
+      class TaskDefer < BaseTool
+        tool_name "task_defer"
+        description "Defer a task for later"
+
+        arguments do
+          required(:id).filled(:string).description("Task ID to defer")
+          optional(:reason).filled(:string).description("Reason for deferring")
+        end
+
+        def call(id:, reason: nil)
+          self.class.with_database do |db|
+            task = db.find_task!(id)
+            task.status = "deferred"
+            task.append_trace("DEFERRED", reason) if reason
+            db.update_task(task)
+            task.to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trak_flow/mcp/tools/task_start.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Mcp
+    module Tools
+      class TaskStart < BaseTool
+        tool_name "task_start"
+        description "Start working on a task (set status to in_progress)"
+
+        arguments do
+          required(:id).filled(:string).description("Task ID to start")
+        end
+
+        def call(id:)
+          self.class.with_database do |db|
+            task = db.find_task!(id)
+            task.status = "in_progress"
+            db.update_task(task)
+            task.to_h
+          end
+        end
+      end
+    end
+  end
+end