shared_tools 0.4.4 → 0.6.0

data/lib/shared_tools/mcp/client_support.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+# lib/shared_tools/mcp/client_support.rb
+#
+# Class-level helpers shared by the SharedTools MCP server classes.
+#
+# Each client in this directory is a plain RubyLLM::MCP subclass (ruby_llm >= 2.1)
+# that describes ONE server with the class-level DSL (command / env / url /
+# bearer_token / timeout ...). Defining the class has no side effects: no process
+# is started, nothing is downloaded and no network connection is made until a
+# chat or robot first asks the server for its tools.
+#
+# This module adds a little SharedTools-specific metadata on top of that DSL:
+#
+#   class SharedTools::MCP::GitHub < RubyLLM::MCP
+#     extend SharedTools::MCP::ClientSupport
+#     requires_envars  "GITHUB_PERSONAL_ACCESS_TOKEN"
+#     requires_packages "github-mcp-server"
+#     command "github-mcp-server", "stdio"
+#   end
+#
+#   SharedTools::MCP::GitHub.available?        #=> false when the token is unset
+#   SharedTools::MCP::GitHub.missing_envars    #=> ["GITHUB_PERSONAL_ACCESS_TOKEN"]
+#   SharedTools::MCP::GitHub.install_packages! # brew/apt/dnf install, on demand only
+
+require "ruby_llm"
+require_relative "../utilities"
+
+module SharedTools
+  module MCP
+    @clients = []
+
+    class << self
+      # Every SharedTools MCP server class that has been loaded.
+      def clients
+        @clients.dup
+      end
+
+      # The loaded server classes whose required environment variables are set.
+      #
+      #   RobotLab.build(mcp: SharedTools::MCP.available)
+      def available
+        @clients.select(&:available?)
+      end
+
+      def register(klass) # :nodoc:
+        @clients << klass unless @clients.include?(klass)
+        klass
+      end
+    end
+
+    module ClientSupport
+      def self.extended(klass)
+        SharedTools::MCP.register(klass)
+      end
+
+      # Declares (or, with no arguments, returns) the environment variables
+      # the server needs. All of them must be set for #available? to be true.
+      def requires_envars(*names)
+        return @required_envars || [] if names.empty?
+
+        @required_envars = names.flatten.map(&:to_s)
+      end
+
+      # Declares (or returns) the OS packages that provide the server binary.
+      # They are only installed when #install_packages! is called.
+      def requires_packages(*names)
+        return @required_packages || [] if names.empty?
+
+        @required_packages = names.flatten.map(&:to_s)
+      end
+
+      def missing_envars
+        requires_envars.select { |name| ENV.fetch(name, "").empty? }
+      end
+
+      def available?
+        missing_envars.empty?
+      end
+
+      # Raises LoadError (like SharedTools.verify_envars) when a required
+      # environment variable is missing; returns the class otherwise.
+      def verify!
+        missing = missing_envars
+        raise LoadError, "Missing envars: #{missing.join(', ')}" unless missing.empty?
+
+        self
+      end
+
+      # Installs the server's OS packages via SharedTools.package_install.
+      def install_packages!
+        SharedTools.package_install(*requires_packages) unless requires_packages.empty?
+        self
+      end
+
+      # An environment variable read when the server process starts rather
+      # than when the class is defined. Missing variables resolve to "".
+      def env_from(name)
+        -> { ENV.fetch(name, "") }
+      end
+    end
+  end
+end

data/lib/shared_tools/mcp/github_client.rb

@@ -1,38 +1,42 @@
+# frozen_string_literal: true
+
 # shared_tools/mcp/github_client.rb
 #
-# GitHub MCP Server Client — requires brew installation
+# GitHub MCP Server — local binary over stdio
 #
 # Provides full GitHub API access: repositories, issues, pull requests,
 # code search, commits, branches, releases, and more.
 #
 # Prerequisites:
-#   - Homebrew (https://brew.sh)
+#   - The github-mcp-server binary on PATH. Install it with
+#     SharedTools::MCP::GitHub.install_packages! (Homebrew/apt/dnf) or by hand.
 #   - A GitHub Personal Access Token
-#   The github-mcp-server binary is installed automatically via brew if missing.
 #
 # Configuration:
 #   export GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here
 #
 # Usage:
 #   require 'shared_tools/mcp/github_client'
-#   client = RubyLLM::MCP.clients["github"]
-#   chat = RubyLLM.chat.with_tools(*client.tools)
+#   chat  = RubyLLM.chat.with_mcp(SharedTools::MCP::GitHub)
+#   robot = RobotLab.build(name: "dev", mcp: [SharedTools::MCP::GitHub])
 #
-# Compatible with ruby_llm-mcp >= 0.7.0
+# Requires ruby_llm >= 2.1 (built-in RubyLLM::MCP). Nothing starts until the
+# server's tools are first requested.
+
+require_relative "client_support"
 
-require_relative "../utilities"
+module SharedTools
+  module MCP
+    class GitHub < ::RubyLLM::MCP
+      extend ClientSupport
 
-SharedTools.verify_envars("GITHUB_PERSONAL_ACCESS_TOKEN")
-SharedTools.package_install("github-mcp-server")
+      self.default_name = "github"
 
-require "ruby_llm/mcp"
+      requires_envars   "GITHUB_PERSONAL_ACCESS_TOKEN"
+      requires_packages "github-mcp-server"
 
-RubyLLM::MCP.add_client(
-  name: "github",
-  transport_type: :stdio,
-  config: {
-    command: "github-mcp-server",
-    args:    ["stdio"],
-    env:     { "GITHUB_PERSONAL_ACCESS_TOKEN" => ENV.fetch("GITHUB_PERSONAL_ACCESS_TOKEN", "") },
-  },
-)
+      command "github-mcp-server", "stdio"
+      env "GITHUB_PERSONAL_ACCESS_TOKEN" => env_from("GITHUB_PERSONAL_ACCESS_TOKEN")
+    end
+  end
+end

data/lib/shared_tools/mcp/hugging_face_client.rb

@@ -1,43 +1,43 @@
+# frozen_string_literal: true
+
 # shared_tools/mcp/hugging_face_client.rb
 #
-# Hugging Face MCP Server Client — requires brew installation
+# Hugging Face MCP Server — local binary over stdio
 #
 # Provides access to the Hugging Face Hub: search and inspect models,
 # datasets, and Spaces; read model cards; run inference; browse
 # trending repositories.
 #
 # Prerequisites:
-#   - Homebrew (https://brew.sh)
+#   - The hf-mcp-server binary on PATH. Install it with
+#     SharedTools::MCP::HuggingFace.install_packages! (Homebrew/apt/dnf) or by hand.
 #   - A Hugging Face user access token (free)
 #     Create one at https://huggingface.co/settings/tokens
-#   The hf-mcp-server binary is installed automatically via brew if missing.
 #
 # Configuration:
 #   export HF_TOKEN=hf_your_access_token_here
 #
 # Usage:
 #   require 'shared_tools/mcp/hugging_face_client'
-#   client = RubyLLM::MCP.clients["hugging-face"]
-#   chat = RubyLLM.chat.with_tools(*client.tools)
+#   chat  = RubyLLM.chat.with_mcp(SharedTools::MCP::HuggingFace)
+#   robot = RobotLab.build(name: "ml", mcp: [SharedTools::MCP::HuggingFace])
 #
-# Compatible with ruby_llm-mcp >= 0.7.0
+# Requires ruby_llm >= 2.1 (built-in RubyLLM::MCP). Nothing starts until the
+# server's tools are first requested.
 
-require_relative "../utilities"
+require_relative "client_support"
 
-SharedTools.verify_envars("HF_TOKEN")
-SharedTools.package_install("hf-mcp-server")
+module SharedTools
+  module MCP
+    class HuggingFace < ::RubyLLM::MCP
+      extend ClientSupport
 
-require "ruby_llm/mcp"
+      requires_envars   "HF_TOKEN"
+      requires_packages "hf-mcp-server"
 
-RubyLLM::MCP.add_client(
-  name: "hugging-face",
-  transport_type: :stdio,
-  config: {
-    command: "hf-mcp-server",
-    args:    [],
-    env:     {
-      "TRANSPORT"        => "stdio",
-      "DEFAULT_HF_TOKEN" => ENV.fetch("HF_TOKEN", ""),
-    },
-  },
-)
+      command "hf-mcp-server"
+      env "TRANSPORT"        => "stdio",
+          "DEFAULT_HF_TOKEN" => env_from("HF_TOKEN")
+    end
+  end
+end

data/lib/shared_tools/mcp/memory_client.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # shared_tools/mcp/memory_client.rb
 #
 # MCP Memory Server — npx auto-download (no pre-installation required)
@@ -8,26 +10,29 @@
 # Prerequisites:
 #   - Node.js and npx (https://nodejs.org)
 #   The @modelcontextprotocol/server-memory package is downloaded automatically
-#   on first use via `npx -y`.
+#   the first time the server is started, via `npx -y`.
 #
 # Configuration (all optional):
-#   export MEMORY_FILE_PATH=/path/to/memory.jsonl   # default: memory.jsonl in cwd
+#   export MEMORY_FILE_PATH=/path/to/memory.jsonl   # default: the server's own default
 #
 # Usage:
 #   require 'shared_tools/mcp/memory_client'
-#   client = RubyLLM::MCP.clients["memory"]
-#   chat = RubyLLM.chat.with_tools(*client.tools)
+#   chat  = RubyLLM.chat.with_mcp(SharedTools::MCP::Memory)
+#   robot = RobotLab.build(name: "assistant", mcp: [SharedTools::MCP::Memory])
 #
-# Compatible with ruby_llm-mcp >= 0.7.0
+# Requires ruby_llm >= 2.1 (built-in RubyLLM::MCP). Nothing starts until the
+# server's tools are first requested.
+
+require_relative "client_support"
 
-require "ruby_llm/mcp"
+module SharedTools
+  module MCP
+    class Memory < ::RubyLLM::MCP
+      extend ClientSupport
 
-RubyLLM::MCP.add_client(
-  name: "memory",
-  transport_type: :stdio,
-  config: {
-    command: "npx",
-    args:    ["-y", "@modelcontextprotocol/server-memory"],
-    env:     ENV['MEMORY_FILE_PATH'] ? { "MEMORY_FILE_PATH" => ENV['MEMORY_FILE_PATH'] } : {},
-  },
-)
+      command "npx", "-y", "@modelcontextprotocol/server-memory"
+      # An unset MEMORY_FILE_PATH resolves to "", which the server treats as unset.
+      env "MEMORY_FILE_PATH" => env_from("MEMORY_FILE_PATH")
+    end
+  end
+end

data/lib/shared_tools/mcp/notion_client.rb

@@ -1,40 +1,42 @@
+# frozen_string_literal: true
+
 # shared_tools/mcp/notion_client.rb
 #
-# Notion MCP Server Client — requires brew installation
+# Notion MCP Server — local binary over stdio
 #
 # Provides full Notion workspace access: search pages and databases,
 # read and update content, create pages, and query databases.
 #
 # Prerequisites:
-#   - Homebrew (https://brew.sh)
+#   - The notion-mcp-server binary on PATH. Install it with
+#     SharedTools::MCP::Notion.install_packages! (Homebrew/apt/dnf) or by hand.
 #   - A Notion internal integration token
 #     Create one at https://www.notion.so/profile/integrations
 #     then share the relevant pages/databases with the integration.
-#   The notion-mcp-server binary is installed automatically via brew if missing.
 #
 # Configuration:
 #   export NOTION_TOKEN=ntn_your_integration_token_here
 #
 # Usage:
 #   require 'shared_tools/mcp/notion_client'
-#   client = RubyLLM::MCP.clients["notion"]
-#   chat = RubyLLM.chat.with_tools(*client.tools)
+#   chat  = RubyLLM.chat.with_mcp(SharedTools::MCP::Notion)
+#   robot = RobotLab.build(name: "notes", mcp: [SharedTools::MCP::Notion])
 #
-# Compatible with ruby_llm-mcp >= 0.7.0
+# Requires ruby_llm >= 2.1 (built-in RubyLLM::MCP). Nothing starts until the
+# server's tools are first requested.
 
-require_relative "../utilities"
+require_relative "client_support"
 
-SharedTools.verify_envars("NOTION_TOKEN")
-SharedTools.package_install("notion-mcp-server")
+module SharedTools
+  module MCP
+    class Notion < ::RubyLLM::MCP
+      extend ClientSupport
 
-require "ruby_llm/mcp"
+      requires_envars   "NOTION_TOKEN"
+      requires_packages "notion-mcp-server"
 
-RubyLLM::MCP.add_client(
-  name: "notion",
-  transport_type: :stdio,
-  config: {
-    command: "notion-mcp-server",
-    args:    [],
-    env:     { "NOTION_TOKEN" => ENV.fetch("NOTION_TOKEN", "") },
-  },
-)
+      command "notion-mcp-server"
+      env "NOTION_TOKEN" => env_from("NOTION_TOKEN")
+    end
+  end
+end

data/lib/shared_tools/mcp/playwright_client.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 # shared_tools/mcp/playwright_client.rb
 #
-# Playwright MCP Server Client — npx auto-download (no pre-installation required)
+# Playwright MCP Server — npx auto-download (no pre-installation required)
 #
 # Provides browser automation via Playwright: navigate pages, click elements,
 # fill forms, take screenshots, extract text/HTML, and interact with web apps.
@@ -9,26 +11,28 @@
 #
 # Prerequisites:
 #   - Node.js and npx (https://nodejs.org)
-#   The @playwright/mcp package is downloaded automatically on first use via `npx -y`.
+#   The @playwright/mcp package is downloaded automatically the first time the
+#   server is started, via `npx -y`.
 #
 # Configuration:
 #   No environment variables required.
 #
 # Usage:
 #   require 'shared_tools/mcp/playwright_client'
-#   client = RubyLLM::MCP.clients["playwright"]
-#   chat = RubyLLM.chat.with_tools(*client.tools)
+#   chat  = RubyLLM.chat.with_mcp(SharedTools::MCP::Playwright)
+#   robot = RobotLab.build(name: "browser", mcp: [SharedTools::MCP::Playwright])
 #
-# Compatible with ruby_llm-mcp >= 0.7.0
+# Requires ruby_llm >= 2.1 (built-in RubyLLM::MCP). Nothing starts until the
+# server's tools are first requested.
+
+require_relative "client_support"
 
-require "ruby_llm/mcp"
+module SharedTools
+  module MCP
+    class Playwright < ::RubyLLM::MCP
+      extend ClientSupport
 
-RubyLLM::MCP.add_client(
-  name: "playwright",
-  transport_type: :stdio,
-  config: {
-    command: "npx",
-    args:    ["-y", "@playwright/mcp"],
-    env:     {},
-  },
-)
+      command "npx", "-y", "@playwright/mcp"
+    end
+  end
+end

data/lib/shared_tools/mcp/sequential_thinking_client.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # shared_tools/mcp/sequential_thinking_client.rb
 #
 # MCP Sequential Thinking Server — npx auto-download (no pre-installation required)
@@ -9,25 +11,26 @@
 # Prerequisites:
 #   - Node.js and npx (https://nodejs.org)
 #   The @modelcontextprotocol/server-sequential-thinking package is downloaded
-#   automatically on first use via `npx -y`.
+#   automatically the first time the server is started, via `npx -y`.
 #
 # No API key required.
 #
 # Usage:
 #   require 'shared_tools/mcp/sequential_thinking_client'
-#   client = RubyLLM::MCP.clients["sequential-thinking"]
-#   chat = RubyLLM.chat.with_tools(*client.tools)
+#   chat  = RubyLLM.chat.with_mcp(SharedTools::MCP::SequentialThinking)
+#   robot = RobotLab.build(name: "thinker", mcp: [SharedTools::MCP::SequentialThinking])
 #
-# Compatible with ruby_llm-mcp >= 0.7.0
+# Requires ruby_llm >= 2.1 (built-in RubyLLM::MCP). Nothing starts until the
+# server's tools are first requested.
+
+require_relative "client_support"
 
-require "ruby_llm/mcp"
+module SharedTools
+  module MCP
+    class SequentialThinking < ::RubyLLM::MCP
+      extend ClientSupport
 
-RubyLLM::MCP.add_client(
-  name: "sequential-thinking",
-  transport_type: :stdio,
-  config: {
-    command: "npx",
-    args:    ["-y", "@modelcontextprotocol/server-sequential-thinking"],
-    env:     {},
-  },
-)
+      command "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"
+    end
+  end
+end

data/lib/shared_tools/mcp/slack_client.rb

@@ -1,16 +1,18 @@
+# frozen_string_literal: true
+
 # shared_tools/mcp/slack_client.rb
 #
-# Slack MCP Server Client — requires brew installation
+# Slack MCP Server — local binary over stdio
 #
 # Provides Slack workspace access: read channels, messages, and threads,
 # search message history, list users, and (optionally) post messages.
 #
 # Prerequisites:
-#   - Homebrew (https://brew.sh)
+#   - The slack-mcp-server binary on PATH. Install it with
+#     SharedTools::MCP::Slack.install_packages! (Homebrew/apt/dnf) or by hand.
 #   - A Slack token — at least one of the following must be set:
 #       SLACK_MCP_XOXP_TOKEN — user OAuth token (xoxp-...) — full access
 #       SLACK_MCP_XOXB_TOKEN — bot token (xoxb-...) — limited to invited channels, no search
-#   The slack-mcp-server binary is installed automatically via brew if missing.
 #
 # Configuration:
 #   export SLACK_MCP_XOXP_TOKEN=xoxp-your-user-token   # recommended
@@ -23,32 +25,35 @@
 #
 # Usage:
 #   require 'shared_tools/mcp/slack_client'
-#   client = RubyLLM::MCP.clients["slack"]
-#   chat = RubyLLM.chat.with_tools(*client.tools)
+#   chat  = RubyLLM.chat.with_mcp(SharedTools::MCP::Slack)
+#   robot = RobotLab.build(name: "slacker", mcp: [SharedTools::MCP::Slack])
 #
-# Compatible with ruby_llm-mcp >= 0.7.0
+# Requires ruby_llm >= 2.1 (built-in RubyLLM::MCP). Nothing starts until the
+# server's tools are first requested. Variables are read when the server
+# process starts; unset ones are passed as "", which the server treats as unset.
+
+require_relative "client_support"
 
-require_relative "../utilities"
+module SharedTools
+  module MCP
+    class Slack < ::RubyLLM::MCP
+      extend ClientSupport
 
-xoxp = ENV.fetch("SLACK_MCP_XOXP_TOKEN", "")
-xoxb = ENV.fetch("SLACK_MCP_XOXB_TOKEN", "")
-raise LoadError, "SLACK_MCP_XOXP_TOKEN or SLACK_MCP_XOXB_TOKEN must be set" if xoxp.empty? && xoxb.empty?
+      TOKEN_ENVARS = %w[SLACK_MCP_XOXP_TOKEN SLACK_MCP_XOXB_TOKEN].freeze
 
-SharedTools.package_install("slack-mcp-server")
+      requires_packages "slack-mcp-server"
 
-require "ruby_llm/mcp"
+      command "slack-mcp-server"
+      env "SLACK_MCP_XOXP_TOKEN"       => env_from("SLACK_MCP_XOXP_TOKEN"),
+          "SLACK_MCP_XOXB_TOKEN"       => env_from("SLACK_MCP_XOXB_TOKEN"),
+          "SLACK_MCP_ADD_MESSAGE_TOOL" => env_from("SLACK_MCP_ADD_MESSAGE_TOOL")
 
-slack_env = {}
-slack_env["SLACK_MCP_XOXP_TOKEN"] = xoxp unless xoxp.empty?
-slack_env["SLACK_MCP_XOXB_TOKEN"] = xoxb unless xoxb.empty?
-slack_env["SLACK_MCP_ADD_MESSAGE_TOOL"] = ENV["SLACK_MCP_ADD_MESSAGE_TOOL"] if ENV["SLACK_MCP_ADD_MESSAGE_TOOL"]
+      # Either token is enough, so this replaces the all-of requires_envars check.
+      def self.missing_envars
+        return [] if TOKEN_ENVARS.any? { |name| !ENV.fetch(name, "").empty? }
 
-RubyLLM::MCP.add_client(
-  name: "slack",
-  transport_type: :stdio,
-  config: {
-    command: "slack-mcp-server",
-    args:    [],
-    env:     slack_env,
-  },
-)
+        ["SLACK_MCP_XOXP_TOKEN or SLACK_MCP_XOXB_TOKEN"]
+      end
+    end
+  end
+end

data/lib/shared_tools/mcp/tavily_client.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 # shared_tools/mcp/tavily_client.rb
 #
-# Tavily MCP Server Client — Remote HTTP (no local installation required)
+# Tavily MCP Server — Remote Streamable HTTP (no local installation required)
 #
-# Connects directly to Tavily's hosted MCP endpoint via Streamable HTTP transport.
+# Connects directly to Tavily's hosted MCP endpoint.
 # No npx, no Node.js, no local binary required — only a Tavily API key.
 #
 # Provides:
@@ -16,26 +18,24 @@
 #
 # Usage:
 #   require 'shared_tools/mcp/tavily_client'
-#   client = RubyLLM::MCP.clients["tavily"]
-#   chat = RubyLLM.chat.with_tools(*client.tools)
+#   chat  = RubyLLM.chat.with_mcp(SharedTools::MCP::Tavily)
+#   robot = RobotLab.build(name: "researcher", mcp: [SharedTools::MCP::Tavily])
 #
-# Compatible with ruby_llm-mcp >= 0.7.0
+# Requires ruby_llm >= 2.1 (built-in RubyLLM::MCP). No request is made until
+# the server's tools are first requested.
+
+require_relative "client_support"
 
-require_relative "../utilities"
-require_relative "streamable_http_patch"
+module SharedTools
+  module MCP
+    class Tavily < ::RubyLLM::MCP
+      extend ClientSupport
 
-SharedTools.verify_envars("TAVILY_API_KEY")
+      requires_envars "TAVILY_API_KEY"
 
-RubyLLM::MCP.add_client(
-  name:            "tavily",
-  transport_type:  :streamable,
-  request_timeout: 30_000,
-  config: {
-    url:     "https://mcp.tavily.com/mcp/",
-    version: :http1,
-    headers: {
-      "Authorization" => "Bearer #{ENV.fetch('TAVILY_API_KEY', '')}",
-      "Accept"        => "application/json, text/event-stream",
-    },
-  },
-)
+      url "https://mcp.tavily.com/mcp/"
+      bearer_token { ENV.fetch("TAVILY_API_KEY", "") }
+      timeout 30
+    end
+  end
+end