trak_flow 0.1.3

data/examples/mcp/Gemfile.lock

@@ -0,0 +1,226 @@
+PATH
+  remote: .
+  specs:
+    trak_flow (0.1.0)
+      anyway_config (~> 2.0)
+      debug_me
+      fast-mcp
+      oj (~> 3.16)
+      pastel (~> 0.8)
+      puma (~> 6.0)
+      rackup (~> 2.0)
+      sequel (~> 5.0)
+      sqlite3 (~> 2.0)
+      thor (~> 1.3)
+      tty-spinner (~> 0.9)
+      tty-table (~> 0.12)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.8)
+      public_suffix (>= 2.0.2, < 8.0)
+    ansi (1.5.0)
+    anyway_config (2.7.2)
+      ruby-next-core (~> 1.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (3.3.1)
+    builder (3.3.0)
+    concurrent-ruby (1.3.6)
+    debug_me (1.1.3)
+    docile (1.4.1)
+    dry-configurable (1.3.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-core (1.2.0)
+      concurrent-ruby (~> 1.0)
+      logger
+      zeitwerk (~> 2.6)
+    dry-inflector (1.2.0)
+    dry-initializer (3.2.0)
+    dry-logic (1.6.0)
+      bigdecimal
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-schema (1.14.1)
+      concurrent-ruby (~> 1.0)
+      dry-configurable (~> 1.0, >= 1.0.1)
+      dry-core (~> 1.1)
+      dry-initializer (~> 3.2)
+      dry-logic (~> 1.5)
+      dry-types (~> 1.8)
+      zeitwerk (~> 2.6)
+    dry-types (1.8.3)
+      bigdecimal (~> 3.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.0)
+      dry-inflector (~> 1.0)
+      dry-logic (~> 1.4)
+      zeitwerk (~> 2.6)
+    fast-mcp (1.6.0)
+      addressable (~> 2.8)
+      base64
+      dry-schema (~> 1.14)
+      json (~> 2.0)
+      mime-types (~> 3.4)
+      rack (>= 2.0, < 4.0)
+    json (2.18.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    mime-types (3.7.0)
+      logger
+      mime-types-data (~> 3.2025, >= 3.2025.0507)
+    mime-types-data (3.2025.0924)
+    minitest (5.27.0)
+    minitest-reporters (1.7.1)
+      ansi
+      builder
+      minitest (>= 5.0)
+      ruby-progressbar
+    nio4r (2.7.5)
+    oj (3.16.13)
+      bigdecimal (>= 3.0)
+      ostruct (>= 0.2)
+    ostruct (0.6.3)
+    parallel (1.27.0)
+    parser (3.3.10.0)
+      ast (~> 2.4.1)
+      racc
+    pastel (0.8.0)
+      tty-color (~> 0.5)
+    prism (1.7.0)
+    public_suffix (7.0.0)
+    puma (6.6.1)
+      nio4r (~> 2.0)
+    racc (1.8.1)
+    rack (3.2.4)
+    rackup (2.3.1)
+      rack (>= 3)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
+    rubocop (1.82.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.48.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-next-core (1.1.2)
+    ruby-progressbar (1.13.0)
+    sequel (5.100.0)
+      bigdecimal
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    sqlite3 (2.9.0-arm64-darwin)
+    strings (0.2.1)
+      strings-ansi (~> 0.2)
+      unicode-display_width (>= 1.5, < 3.0)
+      unicode_utils (~> 1.4)
+    strings-ansi (0.2.0)
+    thor (1.4.0)
+    tty-color (0.6.0)
+    tty-cursor (0.7.1)
+    tty-screen (0.8.2)
+    tty-spinner (0.9.3)
+      tty-cursor (~> 0.7)
+    tty-table (0.12.0)
+      pastel (~> 0.8)
+      strings (~> 0.2.0)
+      tty-screen (~> 0.8)
+    unicode-display_width (2.6.0)
+    unicode_utils (1.4.0)
+    zeitwerk (2.7.4)
+
+PLATFORMS
+  arm64-darwin-25
+
+DEPENDENCIES
+  bundler
+  minitest (~> 5.0)
+  minitest-reporters (~> 1.6)
+  rake (~> 13.0)
+  rubocop (~> 1.0)
+  simplecov (~> 0.22)
+  trak_flow!
+
+CHECKSUMS
+  addressable (2.8.8) sha256=7c13b8f9536cf6364c03b9d417c19986019e28f7c00ac8132da4eb0fe393b057
+  ansi (1.5.0)
+  anyway_config (2.7.2)
+  ast (2.4.3)
+  base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  bigdecimal (3.3.1) sha256=eaa01e228be54c4f9f53bf3cc34fe3d5e845c31963e7fcc5bedb05a4e7d52218
+  builder (3.3.0)
+  concurrent-ruby (1.3.6)
+  debug_me (1.1.3)
+  docile (1.4.1)
+  dry-configurable (1.3.0)
+  dry-core (1.2.0)
+  dry-inflector (1.2.0)
+  dry-initializer (3.2.0)
+  dry-logic (1.6.0)
+  dry-schema (1.14.1)
+  dry-types (1.8.3)
+  fast-mcp (1.6.0)
+  json (2.18.0) sha256=b10506aee4183f5cf49e0efc48073d7b75843ce3782c68dbeb763351c08fd505
+  language_server-protocol (3.17.0.5)
+  lint_roller (1.1.0)
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  mime-types (3.7.0)
+  mime-types-data (3.2025.0924)
+  minitest (5.27.0)
+  minitest-reporters (1.7.1)
+  nio4r (2.7.5)
+  oj (3.16.13)
+  ostruct (0.6.3)
+  parallel (1.27.0)
+  parser (3.3.10.0)
+  pastel (0.8.0)
+  prism (1.7.0)
+  public_suffix (7.0.0) sha256=f7090b5beb0e56f9f10d79eed4d5fbe551b3b425da65877e075dad47a6a1b095
+  puma (6.6.1)
+  racc (1.8.1)
+  rack (3.2.4)
+  rackup (2.3.1)
+  rainbow (3.1.1)
+  rake (13.3.1)
+  regexp_parser (2.11.3)
+  rubocop (1.82.1)
+  rubocop-ast (1.49.0)
+  ruby-next-core (1.1.2)
+  ruby-progressbar (1.13.0)
+  sequel (5.100.0)
+  simplecov (0.22.0)
+  simplecov-html (0.13.2)
+  simplecov_json_formatter (0.1.4)
+  sqlite3 (2.9.0-arm64-darwin)
+  strings (0.2.1)
+  strings-ansi (0.2.0)
+  thor (1.4.0)
+  trak_flow (0.1.0)
+  tty-color (0.6.0)
+  tty-cursor (0.7.1)
+  tty-screen (0.8.2)
+  tty-spinner (0.9.3)
+  tty-table (0.12.0)
+  unicode-display_width (2.6.0)
+  unicode_utils (1.4.0)
+  zeitwerk (2.7.4) sha256=2bef90f356bdafe9a6c2bd32bcd804f83a4f9b8bc27f3600fff051eb3edcec8b
+
+BUNDLED WITH
+  4.0.3

data/examples/mcp/http_demo.rb

@@ -0,0 +1,232 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Demo: TrakFlow MCP Server with HTTP Transport
+#
+# This example shows how to connect to the TrakFlow MCP server
+# using HTTP/SSE transport with the ruby_llm and ruby_llm-mcp gems.
+#
+# The demo demonstrates:
+#   - Connecting via HTTP/SSE transport
+#   - Listing available tools and resources
+#   - Creating a task via MCP tool
+#   - Starting and closing the task (showing state changes)
+#   - Optionally using an LLM with MCP tools
+#
+# Prerequisites:
+#   - Ollama running: ollama serve
+#   - Model available: ollama pull gpt-oss (or set OLLAMA_MODEL env var)
+#
+# The demo will automatically start the MCP server if not running.
+#
+# Usage:
+#   cd examples/mcp
+#   bundle install
+#   ruby http_demo.rb
+
+require "bundler/setup"
+require "ruby_llm"
+require "ruby_llm/mcp"
+require "fileutils"
+require "socket"
+require "tmpdir"
+
+# Configure RubyLLM to use Ollama
+RubyLLM.configure do |config|
+  config.ollama_api_base = ENV["OLLAMA_API_BASE"] || ENV["OLLAMA_URL"] || "http://localhost:11434/v1"
+end
+
+# Model configuration
+OLLAMA_MODEL = ENV.fetch("OLLAMA_MODEL", "gpt-oss:latest")
+
+# MCP server HTTP endpoint (default port from TrakFlow config)
+MCP_PORT = ENV.fetch("MCP_PORT", "3333").to_i
+MCP_HTTP_URL = ENV.fetch("MCP_URL", "http://localhost:#{MCP_PORT}")
+
+# Path to the TrakFlow MCP server executable and project root
+PROJECT_ROOT = File.expand_path("../..", __dir__)
+TF_MCP_PATH = File.join(PROJECT_ROOT, "bin/tf_mcp")
+TF_CLI_PATH = File.join(PROJECT_ROOT, "bin/tf")
+GEMFILE_PATH = File.join(PROJECT_ROOT, "Gemfile")
+
+def port_open?(port, host = "127.0.0.1")
+  Socket.tcp(host, port, connect_timeout: 1) { true }
+rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, SocketError
+  false
+end
+
+def wait_for_server(port, timeout: 10)
+  start = Time.now
+  until port_open?(port)
+    return false if Time.now - start > timeout
+    sleep 0.2
+  end
+  true
+end
+
+puts "TrakFlow MCP HTTP Demo"
+puts "=" * 40
+puts
+
+# Check if server is running, start it if not
+server_pid = nil
+work_dir = nil
+
+unless port_open?(MCP_PORT)
+  puts "MCP server not running on port #{MCP_PORT}. Starting it..."
+
+  # Create a temp directory and initialize TrakFlow there
+  work_dir = Dir.mktmpdir("trakflow_mcp_http_demo")
+  puts "Working directory: #{work_dir}"
+
+  # Initialize TrakFlow in the temp directory
+  Dir.chdir(work_dir) do
+    system({ "BUNDLE_GEMFILE" => GEMFILE_PATH }, "bundle", "exec", TF_CLI_PATH, "init", out: File::NULL, err: File::NULL)
+  end
+
+  # Start the MCP server in the background
+  server_pid = spawn(
+    { "BUNDLE_GEMFILE" => GEMFILE_PATH },
+    "bundle", "exec", TF_MCP_PATH, "--http", "--port", MCP_PORT.to_s,
+    chdir: work_dir,
+    out: File::NULL,
+    err: File::NULL
+  )
+  Process.detach(server_pid)
+
+  puts "Started MCP server (PID: #{server_pid})"
+
+  unless wait_for_server(MCP_PORT)
+    puts "ERROR: Server failed to start within timeout"
+    Process.kill("TERM", server_pid) rescue nil
+    FileUtils.rm_rf(work_dir) if work_dir
+    exit 1
+  end
+
+  puts "MCP server is ready."
+else
+  puts "MCP server already running on port #{MCP_PORT}"
+end
+
+puts
+puts "Connecting to: #{MCP_HTTP_URL}"
+puts
+
+# Create MCP client with SSE transport (HTTP-based)
+client = RubyLLM::MCP.client(
+  name: "trakflow",
+  transport_type: :sse,
+  config: {
+    url: "#{MCP_HTTP_URL}/mcp/sse"
+  }
+)
+
+begin
+  # The client connects automatically on creation
+  puts "Connected to TrakFlow MCP server via HTTP/SSE..."
+  puts "Connection alive: #{client.alive?}"
+
+  # List available tools
+  puts "\nAvailable Tools:"
+  puts "-" * 40
+  client.tools.each do |tool|
+    puts "  - #{tool.name}: #{tool.description}"
+  end
+
+  # List available resources
+  puts "\nAvailable Resources:"
+  puts "-" * 40
+  client.resources.each do |resource|
+    puts "  - #{resource.uri}: #{resource.name}"
+  end
+
+  # Example: Create a task using the MCP tool
+  puts "\n" + "=" * 40
+  puts "Creating a test task..."
+  puts "-" * 40
+
+  tool = client.tool("task_create")
+  result = tool.execute(
+    title: "Demo task from HTTP",
+    description: "Created via MCP HTTP transport demo"
+  )
+
+  puts "Result: #{result}"
+
+  # Example: Create a plan
+  puts "\n" + "=" * 40
+  puts "Creating a plan..."
+  puts "-" * 40
+
+  plan_tool = client.tool("plan_create")
+  plan_result = plan_tool.execute(
+    title: "Example workflow plan",
+    description: "A demo plan with steps"
+  )
+  puts "Plan created: #{plan_result}"
+
+  # Extract the task ID from the creation result
+  # result may be a String or object with .to_s
+  result_str = result.to_s
+  task_id = result_str.match(/id: "([^"]+)"/)[1] rescue nil
+
+  # Example: Start the task to demonstrate a second tool call
+  if task_id
+    puts "\n" + "=" * 40
+    puts "Starting the task via MCP tool..."
+    puts "-" * 40
+
+    start_tool = client.tool("task_start")
+    start_result = start_tool.execute(id: task_id)
+    puts "Task started: #{start_result}"
+
+    # Close the task
+    puts "\n" + "=" * 40
+    puts "Closing the task via MCP tool..."
+    puts "-" * 40
+
+    close_tool = client.tool("task_close")
+    close_result = close_tool.execute(id: task_id)
+    puts "Task closed: #{close_result}"
+  end
+
+  # Example: Use with RubyLLM chat (optional - requires Ollama)
+  if ENV["SKIP_LLM"] != "1"
+    puts "\n" + "=" * 40
+    puts "Sending prompt to LLM with MCP tools..."
+    puts "-" * 40
+
+    chat = RubyLLM.chat(model: OLLAMA_MODEL, provider: :ollama, assume_model_exists: true)
+    chat.with_tools(*client.tools)
+    response = chat.ask("Use the available tools to list all tasks and summarize what you find.")
+
+    puts "\nLLM Response:"
+    puts response.content
+  else
+    puts "\n" + "=" * 40
+    puts "Skipping LLM test (SKIP_LLM=1)"
+    puts "-" * 40
+  end
+
+rescue Errno::ECONNREFUSED
+  puts "Error: Could not connect to MCP server at #{MCP_HTTP_URL}"
+rescue StandardError => e
+  puts "Error: #{e.message}"
+  puts e.backtrace.first(5).join("\n")
+ensure
+  client.cleanup if client.respond_to?(:cleanup)
+
+  # Stop server if we started it
+  if server_pid
+    Process.kill("TERM", server_pid) rescue nil
+    puts "Stopped MCP server (PID: #{server_pid})"
+  end
+
+  # Clean up temp directory if we created it
+  if work_dir && File.exist?(work_dir)
+    FileUtils.rm_rf(work_dir)
+    puts "Cleaned up temp directory."
+  end
+
+  puts "\nCleaned up MCP client."
+end

data/examples/mcp/stdio_demo.rb

@@ -0,0 +1,146 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Demo: TrakFlow MCP Server with STDIO Transport
+#
+# This example shows how to connect to the TrakFlow MCP server
+# using STDIO transport with the ruby_llm and ruby_llm-mcp gems.
+#
+# Prerequisites:
+#   - Ollama running: ollama serve
+#   - Model available: ollama pull gpt-oss (or set OLLAMA_MODEL env var)
+#
+# Usage:
+#   cd examples/mcp
+#   bundle install
+#   ruby stdio_demo.rb
+
+require "bundler/setup"
+require "ruby_llm"
+require "ruby_llm/mcp"
+require "tmpdir"
+require "fileutils"
+
+# Configure RubyLLM to use Ollama
+RubyLLM.configure do |config|
+  config.ollama_api_base = ENV["OLLAMA_API_BASE"] || ENV["OLLAMA_URL"] || "http://localhost:11434/v1"
+end
+
+# Model configuration
+OLLAMA_MODEL = ENV.fetch("OLLAMA_MODEL", "gpt-oss:latest")
+
+# Path to the TrakFlow MCP server executable and project root
+PROJECT_ROOT = File.expand_path("../..", __dir__)
+TF_MCP_PATH = File.join(PROJECT_ROOT, "bin/tf_mcp")
+TF_CLI_PATH = File.join(PROJECT_ROOT, "bin/tf")
+GEMFILE_PATH = File.join(PROJECT_ROOT, "Gemfile")
+
+puts "TrakFlow MCP STDIO Demo"
+puts "=" * 40
+puts
+
+# Create a temp directory and initialize TrakFlow there
+WORK_DIR = Dir.mktmpdir("trakflow_mcp_demo")
+puts "Working directory: #{WORK_DIR}"
+
+# Initialize TrakFlow in the temp directory
+Dir.chdir(WORK_DIR) do
+  system({ "BUNDLE_GEMFILE" => GEMFILE_PATH }, "bundle", "exec", TF_CLI_PATH, "init", out: File::NULL, err: File::NULL)
+end
+
+puts "TrakFlow initialized."
+puts
+
+# Create MCP client with STDIO transport
+# Use a shell wrapper to cd to work dir and run with proper bundle
+client = RubyLLM::MCP.client(
+  name: "trakflow",
+  transport_type: :stdio,
+  config: {
+    command: "/bin/sh",
+    args: ["-c", "cd #{WORK_DIR} && BUNDLE_GEMFILE=#{GEMFILE_PATH} bundle exec #{TF_MCP_PATH}"]
+  }
+)
+
+begin
+  # The client connects automatically on creation
+  puts "Connected to TrakFlow MCP server via STDIO..."
+  puts "Connection alive: #{client.alive?}"
+
+  # List available tools
+  puts "\nAvailable Tools:"
+  puts "-" * 40
+  client.tools.each do |tool|
+    puts "  - #{tool.name}: #{tool.description}"
+  end
+
+  # List available resources
+  puts "\nAvailable Resources:"
+  puts "-" * 40
+  client.resources.each do |resource|
+    puts "  - #{resource.uri}: #{resource.name}"
+  end
+
+  # Example: Create a task using the MCP tool
+  puts "\n" + "=" * 40
+  puts "Creating a test task..."
+  puts "-" * 40
+
+  tool = client.tool("task_create")
+  result = tool.execute(
+    title: "Demo task from STDIO",
+    description: "Created via MCP STDIO transport demo"
+  )
+
+  puts "Result: #{result}"
+
+  # Extract the task ID from the creation result
+  result_str = result.to_s
+  task_id = result_str.match(/id: "([^"]+)"/)[1] rescue nil
+
+  # Example: Start the task to demonstrate a second tool call
+  if task_id
+    puts "\n" + "=" * 40
+    puts "Starting the task via MCP tool..."
+    puts "-" * 40
+
+    start_tool = client.tool("task_start")
+    start_result = start_tool.execute(id: task_id)
+    puts "Task started: #{start_result}"
+
+    # Close the task
+    puts "\n" + "=" * 40
+    puts "Closing the task via MCP tool..."
+    puts "-" * 40
+
+    close_tool = client.tool("task_close")
+    close_result = close_tool.execute(id: task_id)
+    puts "Task closed: #{close_result}"
+  end
+
+  # Example: Use with RubyLLM chat (optional - requires Ollama)
+  if ENV["SKIP_LLM"] != "1"
+    puts "\n" + "=" * 40
+    puts "Sending prompt to LLM with MCP tools..."
+    puts "-" * 40
+
+    chat = RubyLLM.chat(model: OLLAMA_MODEL, provider: :ollama, assume_model_exists: true)
+    chat.with_tools(*client.tools)
+    response = chat.ask("Use the available tools to list all tasks and summarize what you find.")
+
+    puts "\nLLM Response:"
+    puts response.content
+  else
+    puts "\n" + "=" * 40
+    puts "Skipping LLM test (SKIP_LLM=1)"
+    puts "-" * 40
+  end
+
+rescue StandardError => e
+  puts "Error: #{e.message}"
+  puts e.backtrace.first(5).join("\n")
+ensure
+  client.cleanup if client.respond_to?(:cleanup)
+  FileUtils.rm_rf(WORK_DIR) if defined?(WORK_DIR) && File.exist?(WORK_DIR)
+  puts "\nCleaned up MCP client and temp directory."
+end