Skip to content

SharedTools

SharedTools

A comprehensive Ruby gem providing LLM-callable tools for browser automation, file operations, code evaluation, database operations, document processing, network queries, data science, workflow management, and more.

Overview

SharedTools provides a collection of reusable tools designed to work seamlessly with the RubyLLM framework. Each tool extends RubyLLM::Tool and provides a clean, consistent interface for common operations that LLM agents need to perform.

Key Features

  • Browser Automation: Control web browsers with Watir for visiting pages, clicking elements, filling forms, and taking screenshots
  • File System Operations: Secure file and directory operations with path traversal protection
  • Code Evaluation: Execute Ruby, Python, and shell commands with authorization controls
  • Database Operations: Execute SQL queries against SQLite, PostgreSQL, and other databases
  • Document Processing: Read plain text, PDF, Word (.docx), and spreadsheet files (CSV, XLSX, ODS)
  • Network & DNS: DNS lookups, WHOIS queries, IP geolocation, and external IP detection
  • Data Science: Statistical analysis, correlation, time series, clustering, and prediction
  • Workflow Management: Persistent multi-step workflow orchestration with state tracking
  • System Utilities: Date/time, system info, clipboard, cron scheduling, and more
  • Authorization System: Human-in-the-loop confirmation for potentially dangerous operations
  • Driver Architecture: Pluggable driver system for extensibility

Design Principles

Facade Pattern: Each tool acts as a facade, providing a unified interface to complex subsystems:

# Single tool, multiple actions
browser = SharedTools::Tools::BrowserTool.new
browser.execute(action: "visit", url: "https://example.com")
browser.execute(action: "click", selector: "button[type='submit']")
browser.execute(action: "screenshot")

Safety First: Authorization system protects against unintended operations:

# By default, requires human confirmation
SharedTools.execute?(tool: 'eval_tool', stuff: 'rm -rf /')  # Prompts user

# Can be disabled for automation
SharedTools.auto_execute(true)  # Bypass confirmation

Driver-Based: Extensible architecture allows custom implementations:

# Use built-in driver
disk = SharedTools::Tools::DiskTool.new  # Uses LocalDriver

# Or provide custom driver
custom_driver = MyCustomDriver.new
disk = SharedTools::Tools::DiskTool.new(driver: custom_driver)

Quick Example

require 'shared_tools'

# Initialize tools
browser = SharedTools::Tools::BrowserTool.new
disk = SharedTools::Tools::DiskTool.new

# Scrape data from a website
browser.execute(action: "visit", url: "https://example.com/products")
html = browser.execute(action: "page_inspect", full_html: true)

# Save to file
disk.execute(action: "file_create", path: "./scraped_data.html")
disk.execute(action: "file_write", path: "./scraped_data.html", text: html)

# Clean up
browser.cleanup!

Getting Started

Available Tools

Core Tools

Data & Analysis

Network & System

Workflow & DevOps

MCP Clients

SharedTools bundles MCP (Model Context Protocol) clients that connect AI agents to external services. Each client is opt-in — require only the ones you need.

Remote HTTP (API key only)

Client Env var Provides
require 'shared_tools/mcp/tavily_client' TAVILY_API_KEY Web search, news, research, URL extraction

Brew-installed (auto-installs via Homebrew)

Client Env var Provides
require 'shared_tools/mcp/github_client' GITHUB_PERSONAL_ACCESS_TOKEN Repos, issues, PRs, code search
require 'shared_tools/mcp/notion_client' NOTION_TOKEN Pages, databases, search, content CRUD
require 'shared_tools/mcp/slack_client' SLACK_MCP_XOXP_TOKEN Channels, messages, threads, user info
require 'shared_tools/mcp/hugging_face_client' HF_TOKEN Models, datasets, Spaces, model cards

npx Auto-download (Node.js required)

Client Provides
require 'shared_tools/mcp/memory_client' Persistent knowledge graph
require 'shared_tools/mcp/sequential_thinking_client' Chain-of-thought reasoning
require 'shared_tools/mcp/chart_client' Chart and visualisation generation
require 'shared_tools/mcp/brave_search_client' Web and news search (BRAVE_API_KEY)
require 'shared_tools/mcp/playwright_client' Browser automation: navigate, click, fill, screenshot, extract 
# Load all available clients at once (skips any whose env vars are missing)
require 'shared_tools/mcp'

# Or load a specific client
require 'shared_tools/mcp/notion_client'
client = RubyLLM::MCP.clients["notion"]
chat   = RubyLLM.chat.with_tools(*client.tools)
chat.ask("Find my project planning pages and summarise what's in them")

See MCP Clients README for full configuration details.

Guides

Requirements

  • Ruby >= 3.3.0
  • RubyLLM gem
  • Optional: watir (browser), sqlite3/pg (databases), pdf-reader (PDFs), docx (Word), roo (spreadsheets)

License

MIT License - see LICENSE for details.

Credits

Originally inspired by Kevin Sylvestre's omniai-tools gem. SharedTools has evolved to focus exclusively on RubyLLM support with an extended tool collection.