shared_tools 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6c52f4b0cd9b70b60f1e0a9ed50c752d440f17c4d3a638932976cb4796a64e6
-  data.tar.gz: 8c15bd8b3c71f42265f4ef4b7dbc98fae5297dde626d510f43a02cd952e2a069
+  metadata.gz: 32a08d19c86e31c666473a9c3158500e969eb77dec788427183506e7ff9bec1c
+  data.tar.gz: c9d1f53340c99b733dcb629435ba55a6fc0a7ff142d71e456ff290013599dd1f
 SHA512:
-  metadata.gz: aad7b1f18772c7b4407f86fd811141ee5c9c0cc4cddf1a5ca312a27c2f7096cb4502a6295d8c16ec0e5bfa740949faeb7f2d1106cf828f9445b5c80f31e4d2c1
-  data.tar.gz: 394c9b6b1d3f22320b3c151d8477912c34fa4e86c9e3a46a023983581d0325886a2abb6a5df536ba11c165a6d4e9454097528794122cd842cabb9a03111d75be
+  metadata.gz: e35bfb242027c468469b37542ecc20c2f5c9748c60f95925bb2796339d73f038704b29facc2f648eb0bb0c5c3b827d564371bfbb2970b1eddb4f3e736519c80e
+  data.tar.gz: abafd44a016e354e4fd84df3b518ccd1715b37f8a31e795df9f499301ac5a2ef5aa78fcdbd2e4673ac2aa2d76cce42bbcd973484e9ad487f4feddbaf3cba88b6

data/CHANGELOG.md

@@ -1,11 +1,19 @@
 # Changelog
 
 ## Unreleased
-### [0.1.3] 2025-06-18
-- tweaking the load all tools process
 
 ## Released
 
+### [0.2.0] 2025-07-01
+- added ruby_llm/mcp/github_mcp_server.rb example
+- added SharedTools.mcp_servers as an Array of MCP servers
+- added class method name to tool classes as a snake_case of the class name
+- added ruby_llm/mcp/imcp.rb to get stuff from MacOS apps
+- added ruby_llm/incomplete directory with some under-development example tools
+
+### [0.1.3] 2025-06-18
+- tweaking the load all tools process
+
 ### [0.1.2] 2025-06-10
 - added `zeitwerk` gem
 

data/README.md

@@ -10,56 +10,59 @@ A Ruby gem providing a collection of common tools (call-back functions) for use
 - omniai: multi-provider `gem install omniai-tools` (Not part of the SharedTools namespace)
 - more to come ...
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'shared_tools'
-```
-
-And then execute:
-
-```bash
-bundle install
-```
-
-Or install it yourself as:
-
-```bash
-gem install shared_tools
-```
+## Recent Changes
 
-## Usage
+### Version 0.2.0
 
-### Basic Loading
+- ability to use the `ruby_llm-mcp` gem was added with two example MCP client instances for some useful MCP servers: github-mcp-server and iMCP.app
+- added `SharedTools.mcp_servers` Array to hold defined client instances.
+- added a class method `name` to `RubyLLM::Tool` subclasses to define the snake_case String format of the class basename.
 
-```ruby
-require 'shared_tools'
-```
-
-### Loading RubyLLM Tools
-
-RubyLLM tools are loaded conditionally when needed:
+## Installation
 
 ```ruby
-require 'shared_tools'
+gem install shared_tools
 
 # Load all RubyLLM tools (requires ruby_llm gem to be available and loaded first)
-require 'shared_tools/ruby_llm'
+require 'shared_tools/ruby_llm' # multiple API libraries are supported besides ruby_llm
 
 # Or load a specific tool directly
 require 'shared_tools/ruby_llm/edit_file'
 require 'shared_tools/ruby_llm/read_file'
 require 'shared_tools/ruby_llm/python_eval'
-# etc.
+
+# Or load clients for defined MCP servers
+# Load all the MCP clients for the ruby_llm library
+require 'shared_tools/ruby_llm/mcp'
+
+# Or just the ones you want
+require 'shared_tools/ruby_llm/mcp/github_mcp_server'
+require 'shared_tools/ruby_llm/mcp/icmp' # MacOS data server
+
+# The client instances for ruby_llm/mcp servers are available
+SharedTools.mcp_servers # An Array of MCP clients
+
+# In ruby_llm library access the tools from MCP servers
+@tools = []
+SharedTools.mcp_servers.size.time  do |server_inx|
+  @tools += SharedTools.mcp_servers[server_inx].tools
+end
+chat = RubyLLM.chat
+chat.with_tools(@tools)
 ```
 
-### Rails and Autoloader Compatibility
+## Tips for Tool Authors
+
+- Provide a clear comprehensive description for your tool and its parameters
+- Include usage examples in your documentation
+- Ensure your tool is compatible with different Ruby versions and environments
+- Make sure your tool is in the correct directory for the library to which it belongs
+
+## Rails and Autoloader Compatibility
 
 This gem uses Zeitwerk for autoloading, making it fully compatible with Rails and other Ruby applications that use modern autoloaders. RubyLLM tools are excluded from autoloading and loaded manually to avoid namespace conflicts.
 
 
-### Special Thanks
+ Special Thanks
 
 A special shout-out to Kevin's [omniai-tools](https://github.com/your-github-url/omniai-tools) gem, which is a curated collection of tools for use with his OmniAI gem.

data/lib/shared_tools/raix/what_is_the_weather.rb

@@ -3,11 +3,11 @@
 require_relative "../../shared_tools"
 
 module SharedTools
-  verify_gem :ruby_llm
+  verify_gem :raix
 
   class WhatIsTheWeather
-    include Raix::ChatCompletion
-    include Raix::FunctionDispatch
+    include ::Raix::ChatCompletion
+    include ::Raix::FunctionDispatch
 
     function :check_weather,
              "Check the weather for a location",

data/lib/shared_tools/ruby_llm/edit_file.rb

@@ -6,6 +6,7 @@ module SharedTools
   verify_gem :ruby_llm
 
   class EditFile < ::RubyLLM::Tool
+      def self.name = 'edit_file'
 
     description <<~DESCRIPTION
                   Make edits to a text file.

data/lib/shared_tools/ruby_llm/incomplete/calculator_tool.rb

@@ -0,0 +1,70 @@
+# calculator_tool.rb - Simple custom tool example
+require 'ruby_llm/tool'
+
+module Tools
+  class Calculator < RubyLLM::Tool
+    def self.name = "calculator"
+
+    description <<~DESCRIPTION
+      Perform advanced mathematical calculations with comprehensive error handling and validation.
+      This tool supports basic arithmetic operations, parentheses, and common mathematical functions.
+      It provides safe evaluation of mathematical expressions without executing arbitrary code,
+      making it suitable for use in AI-assisted calculations where security is important.
+      The tool returns formatted results with configurable precision and helpful error messages
+      when invalid expressions are provided.
+    DESCRIPTION
+
+    param :expression,
+          desc: <<~DESC,
+            Mathematical expression to evaluate using standard arithmetic operators and parentheses.
+            Supported operations include: addition (+), subtraction (-), multiplication (*), division (/),
+            and parentheses for grouping. Examples: '2 + 2', '(10 * 5) / 2', '15.5 - 3.2'.
+            Only numeric characters, operators, parentheses, decimal points, and spaces are allowed
+            for security reasons. Complex mathematical functions are not supported in this version.
+          DESC
+          type: :string,
+          required: true
+
+    param :precision,
+          desc: <<~DESC,
+            Number of decimal places to display in the result. Must be a non-negative integer.
+            Set to 0 for whole numbers only, or higher values for more precise decimal results.
+            Default is 2 decimal places, which works well for most financial and general calculations.
+            Maximum precision is limited to 10 decimal places to prevent excessive output.
+          DESC
+          type: :integer,
+          default: 2
+
+    def execute(expression:, precision: 2)
+      begin
+        # Use safe evaluation instead of raw eval
+        result = safe_eval(expression)
+        formatted_result = result.round(precision)
+
+        {
+          success: true,
+          result:  formatted_result,
+          expression: expression,
+          precision: precision
+        }
+      rescue => e
+        {
+          success: false,
+          error:   "Invalid expression: #{e.message}",
+          expression: expression,
+          suggestion: "Try expressions like '2 + 2' or '10 * 5'"
+        }
+      end
+    end
+
+    private
+
+    def safe_eval(expression)
+      # Implement safe mathematical evaluation
+      # This is a simplified example - use a proper math parser in production
+      allowed_chars = /\A[0-9+\-*\/\(\)\.\s]+\z/
+      raise "Invalid characters in expression" unless expression.match?(allowed_chars)
+      eval(expression)
+    end
+  end
+end

data/lib/shared_tools/ruby_llm/incomplete/composite_analysis_tool.rb

@@ -0,0 +1,89 @@
+# composite_analysis_tool.rb - Tool that uses other tools
+require 'ruby_llm/tool'
+
+module Tools
+  class CompositeAnalysis < RubyLLM::Tool
+    def self.name = "composite_analysis"
+
+    description <<~DESCRIPTION
+      Perform comprehensive multi-stage data analysis by orchestrating multiple specialized tools
+      to provide complete insights from various data sources. This composite tool automatically
+      determines the appropriate data fetching method (web scraping for URLs, file reading for
+      local paths), analyzes data structure and content, generates statistical insights,
+      and suggests appropriate visualizations based on the data characteristics.
+      Ideal for exploratory data analysis workflows where you need a complete picture
+      from initial data loading through final insights.
+    DESCRIPTION
+
+    param :data_source,
+          desc: <<~DESC,
+            Primary data source to analyze. Can be either a local file path or a web URL.
+            For files: Use relative or absolute paths to CSV, JSON, XML, or text files.
+            For URLs: Use complete HTTP/HTTPS URLs to accessible data endpoints or web pages.
+            The tool automatically detects the source type and uses appropriate fetching methods.
+            Examples: './data/sales.csv', '/home/user/data.json', 'https://api.example.com/data'
+          DESC
+          type: :string,
+          required: true
+
+    def execute(data_source:)
+      results = {}
+
+      begin
+        # Step 1: Fetch data using appropriate tool
+        if data_source.start_with?('http')
+          results[:data] = fetch_web_data(data_source)
+        else
+          results[:data] = read_file_data(data_source)
+        end
+
+        # Step 2: Analyze data structure
+        results[:structure] = analyze_data_structure(results[:data])
+
+        # Step 3: Generate insights
+        results[:insights] = generate_insights(results[:data], results[:structure])
+
+        # Step 4: Create visualizations if applicable
+        if results[:structure][:numeric_columns]&.any?
+          results[:visualizations] = suggest_visualizations(results[:structure])
+        end
+
+        {
+          success:     true,
+          analysis:    results,
+          data_source: data_source,
+          analyzed_at: Time.now.iso8601
+        }
+      rescue => e
+        {
+          success:        false,
+          error:          e.message,
+          data_source:    data_source,
+          partial_results: results
+        }
+      end
+    end
+
+    private
+
+    def fetch_web_data(url)
+      # Use shared web tools or custom HTTP client
+    end
+
+    def read_file_data(file_path)
+      # Use shared file tools
+    end
+
+    def analyze_data_structure(data)
+      # Implementation for data structure analysis
+    end
+
+    def generate_insights(data, structure)
+      # Implementation for insight generation
+    end
+
+    def suggest_visualizations(structure)
+      # Implementation for visualization suggestions
+    end
+  end
+end

data/lib/shared_tools/ruby_llm/incomplete/data_science_kit.rb

@@ -0,0 +1,128 @@
+# data_science_kit.rb - Analytics and ML tools
+require 'ruby_llm/tool'
+
+module Tools
+  class DataScienceKit < RubyLLM::Tool
+    def self.name = "data_science_kit"
+
+    description <<~DESCRIPTION
+      Comprehensive data science and analytics toolkit for performing statistical analysis,
+      machine learning tasks, and data exploration on various data sources. This tool provides
+      a unified interface for common data science operations including descriptive statistics,
+      correlation analysis, time series analysis, clustering algorithms, and predictive modeling.
+      It automatically handles data loading, validation, preprocessing, and result formatting.
+      Supports multiple data formats and provides detailed analysis results with visualizations
+      recommendations and statistical significance testing where applicable.
+    DESCRIPTION
+
+    param :analysis_type,
+          desc: <<~DESC,
+            Type of data science analysis to perform:
+            - 'statistical_summary': Descriptive statistics, distributions, outlier detection
+            - 'correlation_analysis': Correlation matrices, feature relationships, dependency analysis
+            - 'time_series': Trend analysis, seasonality detection, forecasting
+            - 'clustering': K-means, hierarchical clustering, cluster analysis
+            - 'prediction': Regression analysis, classification, predictive modeling
+            Each analysis type requires specific data formats and optional parameters.
+          DESC
+          type: :string,
+          required: true,
+          enum: ["statistical_summary", "correlation_analysis", "time_series", "clustering", "prediction"]
+
+    param :data_source,
+          desc: <<~DESC,
+            Data source specification for analysis. Can be:
+            - File path: Relative or absolute path to CSV, JSON, Excel, or Parquet files
+            - Database query: SQL SELECT statement for database-sourced data
+            - API endpoint: HTTP URL for REST API data sources
+            The tool automatically detects the format and applies appropriate parsing.
+            Examples: './sales_data.csv', 'SELECT * FROM transactions', 'https://api.company.com/data'
+          DESC
+          type: :string,
+          required: true
+
+    param :parameters,
+          desc: <<~DESC,
+            Hash of analysis-specific parameters and configuration options:
+            - statistical_summary: confidence_level, include_quartiles, outlier_method
+            - correlation_analysis: method (pearson/spearman), significance_level
+            - time_series: date_column, value_column, frequency, forecast_periods
+            - clustering: n_clusters, algorithm (kmeans/hierarchical), distance_metric
+            - prediction: target_column, feature_columns, model_type, validation_split
+            Default empty hash uses standard parameters for each analysis type.
+          DESC
+          type: :hash,
+          default: {}
+
+    def execute(analysis_type:, data_source:, parameters: {})
+      begin
+        # Load and validate data
+        data = load_data(data_source)
+        validate_data_for_analysis(data, analysis_type)
+
+        # Perform analysis
+        result = case analysis_type
+        when "statistical_summary"
+          generate_statistical_summary(data, parameters)
+        when "correlation_analysis"
+          perform_correlation_analysis(data, parameters)
+        when "time_series"
+          analyze_time_series(data, parameters)
+        when "clustering"
+          perform_clustering(data, parameters)
+        when "prediction"
+          generate_predictions(data, parameters)
+        end
+
+        {
+          success:      true,
+          analysis_type: analysis_type,
+          result:       result,
+          data_summary: summarize_data(data),
+          analyzed_at:  Time.now.iso8601
+        }
+      rescue => e
+        {
+          success:     false,
+          error:       e.message,
+          analysis_type: analysis_type,
+          data_source: data_source
+        }
+      end
+    end
+
+    private
+
+    def load_data(source)
+      # Implementation for data loading from various sources
+    end
+
+    def validate_data_for_analysis(data, analysis_type)
+      # Implementation for data validation
+    end
+
+    def generate_statistical_summary(data, parameters)
+      # Implementation for statistical summary
+    end
+
+    def perform_correlation_analysis(data, parameters)
+      # Implementation for correlation analysis
+    end
+
+    def analyze_time_series(data, parameters)
+      # Implementation for time series analysis
+    end
+
+    def perform_clustering(data, parameters)
+      # Implementation for clustering
+    end
+
+    def generate_predictions(data, parameters)
+      # Implementation for prediction
+    end
+
+    def summarize_data(data)
+      # Implementation for data summary
+    end
+  end
+end

data/lib/shared_tools/ruby_llm/incomplete/database_query_tool.rb

@@ -0,0 +1,100 @@
+# database_query_tool.rb - Database interaction example
+require 'ruby_llm/tool'
+require 'sequel'
+
+module Tools
+  class DatabaseQuery < RubyLLM::Tool
+    def self.name = "database_query"
+
+    description <<~DESCRIPTION
+      Execute safe, read-only database queries with automatic connection management and security controls.
+      This tool is designed for secure data retrieval operations only, restricting access to SELECT statements
+      to prevent any data modification. It includes automatic connection pooling, query result limiting,
+      and comprehensive error handling. The tool supports multiple database configurations through
+      environment variables and ensures all connections are properly closed after use.
+      Perfect for AI-assisted data analysis and reporting workflows where read-only access is required.
+    DESCRIPTION
+
+    param :query,
+          desc: <<~DESC,
+            SQL SELECT query to execute against the database. Only SELECT statements are permitted
+            for security reasons - INSERT, UPDATE, DELETE, and DDL statements will be rejected.
+            The query should be well-formed SQL appropriate for the target database system.
+            Examples: 'SELECT * FROM users WHERE active = true', 'SELECT COUNT(*) FROM orders'.
+            Table and column names should match the database schema exactly.
+          DESC
+          type: :string,
+          required: true
+
+    param :database,
+          desc: <<~DESC,
+            Database configuration name to use for the connection. This corresponds to environment
+            variables like DATABASE_URL, STAGING_DATABASE_URL, etc. The tool will look for
+            an environment variable named {DATABASE_NAME}_DATABASE_URL (uppercase).
+            Default is 'default' which looks for DEFAULT_DATABASE_URL environment variable.
+            Common values: 'default', 'staging', 'analytics', 'reporting'.
+          DESC
+          type: :string,
+          default: "default"
+
+    param :limit,
+          desc: <<~DESC,
+            Maximum number of rows to return from the query to prevent excessive memory usage
+            and long response times. The tool automatically adds a LIMIT clause if one is not
+            present in the original query. Set to a reasonable value based on expected data size.
+            Minimum: 1, Maximum: 10000, Default: 100. For large datasets, consider using
+            pagination or more specific WHERE clauses.
+          DESC
+          type: :integer,
+          default: 100
+
+    def execute(query:, database: "default", limit: 100)
+      begin
+        # Security: Only allow SELECT queries
+        normalized_query = query.strip.downcase
+        unless normalized_query.start_with?('select')
+          raise "Only SELECT queries are allowed for security"
+        end
+
+        db = connect_to_database(database)
+        limited_query = add_limit_to_query(query, limit)
+
+        results = db[limited_query].all
+
+        {
+          success:     true,
+          query:       limited_query,
+          row_count:   results.length,
+          data:        results,
+          database:    database,
+          executed_at: Time.now.iso8601
+        }
+      rescue => e
+        {
+          success:  false,
+          error:    e.message,
+          query:    query,
+          database: database
+        }
+      ensure
+        db&.disconnect
+      end
+    end
+
+    private
+
+    def connect_to_database(database_name)
+      # Implementation depends on your database setup
+      connection_string = ENV["#{database_name.upcase}_DATABASE_URL"]
+      raise "Database connection not configured for #{database_name}" unless connection_string
+
+      Sequel.connect(connection_string)
+    end
+
+    def add_limit_to_query(query, limit)
+      # Add LIMIT clause if not present
+      query += " LIMIT #{limit}" unless query.downcase.include?('limit')
+      query
+    end
+  end
+end

data/lib/shared_tools/ruby_llm/incomplete/devops_toolkit.rb

@@ -0,0 +1,112 @@
+# devops_toolkit.rb - System administration tools
+require 'ruby_llm/tool'
+require 'securerandom'
+
+module Tools
+  class DevOpsToolkit < RubyLLM::Tool
+    def self.name = "devops_toolkit"
+
+    description <<~DESCRIPTION
+      Comprehensive DevOps and system administration toolkit for managing application deployments,
+      monitoring system health, and performing operational tasks across different environments.
+      This tool provides secure, audited access to common DevOps operations including deployments,
+      rollbacks, health checks, log analysis, and metrics collection. It includes built-in safety
+      mechanisms for production environments, comprehensive logging for compliance, and support
+      for multiple deployment environments. All operations are logged and require appropriate
+      permissions and confirmations for sensitive environments.
+    DESCRIPTION
+
+    param :operation,
+          desc: <<~DESC,
+            Specific DevOps operation to perform:
+            - 'deploy': Deploy application code to the specified environment
+            - 'rollback': Revert to the previous stable deployment version
+            - 'health_check': Perform comprehensive health and status checks
+            - 'log_analysis': Analyze application and system logs for issues
+            - 'metric_collection': Gather and report system and application metrics
+            Each operation has specific requirements and safety checks.
+          DESC
+          type: :string,
+          required: true,
+          enum: ["deploy", "rollback", "health_check", "log_analysis", "metric_collection"]
+
+    param :environment,
+          desc: <<~DESC,
+            Target environment for the DevOps operation:
+            - 'development': Local or shared development environment (minimal restrictions)
+            - 'staging': Pre-production environment for testing (moderate restrictions)
+            - 'production': Live production environment (maximum restrictions and confirmations)
+            Production operations require explicit confirmation via the 'production_confirmed' option.
+          DESC
+          type: :string,
+          default: "staging",
+          enum: ["development", "staging", "production"]
+
+    param :options,
+          desc: <<~DESC,
+            Hash of operation-specific options and parameters:
+            - For deploy: version, branch, rollback_on_failure, notification_channels
+            - For rollback: target_version, confirmation_required
+            - For health_check: services_to_check, timeout_seconds
+            - For log_analysis: time_range, log_level, search_patterns
+            - For metric_collection: metric_types, time_window, output_format
+            Production operations require 'production_confirmed: true' for safety.
+          DESC
+          type: :hash,
+          default: {}
+
+    def execute(operation:, environment: "staging", options: {})
+      # Security: Require explicit production confirmation
+      if environment == "production" && !options[:production_confirmed]
+        return {
+          success:         false,
+          error:           "Production operations require explicit confirmation",
+          required_option: "production_confirmed: true"
+        }
+      end
+
+      case operation
+      when "deploy"
+        perform_deployment(environment, options)
+      when "rollback"
+        perform_rollback(environment, options)
+      when "health_check"
+        perform_health_check(environment, options)
+      when "log_analysis"
+        analyze_logs(environment, options)
+      when "metric_collection"
+        collect_metrics(environment, options)
+      end
+    end
+
+    private
+
+    def perform_deployment(environment, options)
+      # Implementation for deployment logic
+      {
+        success:       true,
+        operation:     "deploy",
+        environment:   environment,
+        deployed_at:   Time.now.iso8601,
+        deployment_id: SecureRandom.uuid,
+        details:       "Deployment completed successfully"
+      }
+    end
+
+    def perform_rollback(environment, options)
+      # Implementation for rollback logic
+    end
+
+    def perform_health_check(environment, options)
+      # Implementation for health check logic
+    end
+
+    def analyze_logs(environment, options)
+      # Implementation for log analysis logic
+    end
+
+    def collect_metrics(environment, options)
+      # Implementation for metric collection logic
+    end
+  end
+end