shared_tools 0.4.4 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 679fe640e745e716a1ec2c9cb77fd9af47b67b09ddd5caba23ef9b6fbbf50d24
-  data.tar.gz: afa308531e5afc205b244771db0ed2e8965e5532d5f642d81c3284819db6f7b6
+  metadata.gz: 95941947776da1920fb3f5d5a5c0a1866d2170810e23cbcfb53e55e79ee32847
+  data.tar.gz: be6b46bce0292f7c0092146fe85b09d6572ea1c2fbd0daf8268cfb6e417d3ea3
 SHA512:
-  metadata.gz: 87264d8b31d6b016e56ac361fa528a73071163f4dfaa4d562e877e20b7d011aa85a0de033212aa326fe9e8983940893d046237eab043c5ee6f61306dc126c21b
-  data.tar.gz: eee3b6364a669539ff7d1ffb290e1255416c0a20f32f68873a4d69061dcf41e5675a23b2ecb3fcacaf7714f6ad0b69d726cf3577642bceef611895574870d44c
+  metadata.gz: 28c25227c7fa22fe93e56c48136855edb59193dbcc3ea3ca7236e1de4e9512d76f70256dd6d00f47386243fed9aa2589a9d98ba57703cd68f7c8c4139f0588e3
+  data.tar.gz: ca6d285368be559a1642e344c4909a05b44fa143ce5d76ebc21471a347912ff3553ec866b416b560b3bacc56672fb275427426d87a52f538e493b4b447cbb8b0

data/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 ## Unreleased
 
+#### ruby_llm 2.1 migration (breaking)
+- **Breaking:** Requires `ruby_llm >= 2.1.1, < 3`. Under ruby_llm 2.x every tool that used the 1.x `params do ... end` macro raised `NoMethodError` inside its class body; the constant already existed, so a half-built class loaded without `#execute`, and calling the tool failed with `NotImplementedError: Subclasses must implement #execute`. All 81 tool files now use `parameters do ... end` (same block DSL, now provided by `schematist`), and `Tools::Enabler`'s `param :tool, desc:` is now `parameter :tool, description:`. The generated argument schemas are unchanged apart from the top-level `"strict": true` marker that ruby_llm 1.x added and 2.x does not. Read a tool's schema with `tool.parameters_schema` (was `params_schema`).
+- **Breaking:** Dropped the `ruby_llm-mcp` dependency; it cannot be loaded alongside ruby_llm 2.1's built-in `RubyLLM::MCP`, which has no `add_client` / `clients` registry. Each MCP client in `lib/shared_tools/mcp/` is now a `RubyLLM::MCP` subclass that describes one server with the class DSL (`command`, `env`, `url`, `bearer_token`, `timeout`): `SharedTools::MCP::GitHub`, `Notion`, `Slack`, `HuggingFace`, `Tavily`, `Memory`, `SequentialThinking`, `Chart`, `BraveSearch`, `Playwright`. Pass the class to a chat or robot (`RubyLLM.chat.with_mcp(SharedTools::MCP::GitHub)`, `RobotLab.build(mcp: [SharedTools::MCP::GitHub])`) instead of looking it up with `RubyLLM::MCP.clients["github"]`.
+- **Breaking:** Requiring a client file no longer has side effects. It does not check environment variables, does not run `brew`/`apt`/`dnf`, and does not connect; environment variables are read when the server process starts. Use `Klass.available?` / `missing_envars` / `verify!` (raises `LoadError` like before) and `Klass.install_packages!`. `require 'shared_tools/mcp'` loads every definition, records availability for `SharedTools.mcp_status`, and `SharedTools::MCP.available` lists the usable classes.
+- **Breaking:** MCP server names are now symbol-friendly: `brave-search` → `brave_search`, `hugging-face` → `hugging_face`, `sequential-thinking` → `sequential_thinking` (others unchanged). These are the names in `SharedTools.mcp_status` and `chat.mcp[...]`.
+- Removed `lib/shared_tools/mcp/streamable_http_patch.rb`; it patched a `ruby_llm-mcp` internal. ruby_llm 2.1's spec-compliant SSE parser already handles mixed CRLF/LF line endings.
+- Added `test/shared_tools/tool_classes_test.rb`: every shipped `RubyLLM::Tool` subclass must define its own `#execute`, expose an object `parameters_schema` whose properties `#execute` accepts, and no 1.x `params do` / `param :` may remain in `lib/`. It also calls `current_date_time`, `system_info` and `dns` (used by aia's demo 18) through `Tool#call` and checks the data they return. Added `test/shared_tools/mcp/clients_test.rb` (class-level only; no servers are started).
+- Updated the MCP examples, `lib/shared_tools/mcp/README.md`, `README.md` and `docs/` for the new MCP classes.
+
+#### Tools
+- Added Git tools, ported from `ruby_llm-toolbox`: `SharedTools::Tools::Git::StatusTool`, `DiffTool`, `LogTool`, `ShowTool`, `BlameTool`, `BranchTool`, and `GrepTool` (read-only), plus `AddTool`, `CommitTool`, and `CheckoutTool` (mutating, require `SharedTools.execute?` authorization). All shell out to `git` with `core.fsmonitor` disabled and `--no-ext-diff --no-textconv`, so an untrusted checkout can't turn a read into command execution; refs are validated against option injection and paths are confined to `repo_root`. Also added `SharedTools::Tools::GitTool`, a facade dispatching on `action`.
+- Added `SharedTools::Tools::JsonQueryTool`, `YamlQueryTool`, and `TomlQueryTool` — query JSON/YAML/TOML (from a file or inline string) with a dot/bracket path expression (`users[0].name`, `services[].image`), or pretty-print with no query. YAML uses `safe_load`; TOML is parsed with a new dependency-free `SharedTools::TomlParser`, also ported from `ruby_llm-toolbox`. Path traversal is shared via a new `SharedTools::DataPath` module.
+- Added `SharedTools::Tools::CsvReadTool` (read-only) and `SharedTools::Tools::CsvWriteTool` (mutating, requires authorization).
+- Added `SharedTools::Tools::DiffTool`, ported from `ruby_llm-toolbox` — compares two in-memory blocks of text and returns a readable unified diff, via a new dependency-free `SharedTools::TextDiff` module. Read-only, no filesystem access.
+- Added `SharedTools::Tools::MultiEditTool` — applies several find/replace edits to one file atomically; each edit's `old_string` must match exactly once (or `replace_all`) or the whole batch is rejected and nothing is written. Mutating, requires `SharedTools.execute?` authorization.
+- Added `SharedTools::Tools::ApplyPatchTool` — applies a unified diff via `git apply`, validated with `--check` first; every touched path is confined to `root`. Set `check: true` for a dry run. Mutating, requires authorization.
+- Added `SharedTools::Tools::GlobTool`, ported from `ruby_llm-toolbox` — finds files matching a glob pattern (`**/*.rb`), returns sorted paths relative to `base`. Read-only, in-process.
+- Added `SharedTools::Tools::TreeTool`, ported from `ruby_llm-toolbox` — renders a depth-limited directory tree, skipping `.git`/`node_modules`/hidden entries by default. Read-only, in-process.
+- **Breaking:** Replaced `SharedTools::Tools::SearchCodebaseTool`'s implementation with a pure-Ruby scanner ported from `ruby_llm-toolbox`'s `grep_files`, dropping the `rg`/`grep` shell-out dependency entirely. The regex is compiled with a per-match timeout so a malicious pattern can't hang the process (ReDoS guard), and `context`/`before`/`after` params add grep-style context lines around matches. **Param changes:** `term:` → `pattern:` (already treated as a regex by `rg`/`grep`, now explicit and validated), `extension:` → `glob:` (a filename glob like `"*.rb"` instead of a bare extension like `"rb"`). `max_results:` is unchanged. `result[:tool]` now always reports `"ruby"` instead of `"rg"`/`"grep"`.
+- Added `SharedTools::Tools::ReplaceInFilesTool` — batch find/replace across files matching a glob (literal or regex, ReDoS-guarded), with `dry_run` preview. Mutating, requires authorization.
+- Added Ruby dev tools, ported from `ruby_llm-toolbox`: `SharedTools::Tools::GemTool` (read-only RubyGems.org metadata lookup), `BundleTool` (Bundler install/update/outdated/check/lock/add), `LintTool` (RuboCop/Standard, auto-detected), and `ParseRubyTool` (structural outline of a Ruby file via a new `SharedTools::RubyOutline` module — Prism on Ruby 3.3+, Ripper stdlib fallback otherwise). Bundle/Lint require authorization; Gem/ParseRuby are read-only.
+- Added background process management, ported from `ruby_llm-toolbox`: `SharedTools::Tools::ProcessStartTool`, `ProcessListTool`, `ProcessOutputTool`, and `ProcessKillTool`, backed by new `SharedTools::ProcessRegistry`/`ManagedProcess` support (thread-safe registry, bounded output buffers, SIGTERM→SIGKILL escalation across the whole process group, all processes cleaned up at exit). `ProcessStartTool` requires an executable on `allowed_commands` (empty by default) via a new `SharedTools::CommandGuard`, and requires authorization. `ProcessKillTool` requires no authorization — always available so a runaway can be stopped.
+- Added guarded network tools, ported from `ruby_llm-toolbox`: `SharedTools::Tools::WebFetchTool` (fetch a URL, HTML stripped to text; read-only), `HttpRequestTool` (general HTTP client; GET/HEAD read-only, POST/PUT/PATCH/DELETE require authorization), and `DownloadFileTool` (download a URL to a file within `root`; requires authorization). All three go through a new `SharedTools::UrlGuard` (SSRF protection: http/https only, no embedded credentials, blocks private/loopback/link-local/cloud-metadata addresses, and pins the connection to the vetted IP to close the DNS-rebinding window).
+- Added `SharedTools::Tools::TodoWriteTool` — maintains a replace-the-whole-list task tracker for multi-step work. Read-only (in-memory only), no authorization needed.
+- Added `SharedTools::Tools::BashTool` — runs one allowlisted executable with argv-only arguments (no shell, so no pipes/redirects/globs/injection surface). `allowed_commands` is empty by default. Requires authorization.
+- Added `SharedTools::Tools::RunTestsTool` (RSpec/Minitest, auto-detected) and `SharedTools::Tools::PythonTestsTool` (pytest/unittest), both via a new `SharedTools::Tools::ToolchainHelpers` module shared with BundleTool/LintTool. Both require authorization.
+- **Scope note:** `ruby_llm-toolbox`'s `run_rust`/`run_python`/`run_ruby` (Docker-sandboxed code execution) were intentionally not ported — they depend on a much larger Docker sandbox subsystem this gem doesn't have. Also dropped: the toolbox's `allow_unsafe`/operator-override escape hatches on `bash_tool`, `process_start`, `http_request`, and `web_fetch` — shared_tools has no equivalent global-override concept, so commands/URLs are simply allowed or refused.
+
+#### Tests
+- Added `test/shared_tools/tools/git/*_tool_test.rb` (10 files) and `test/shared_tools/tools/git_tool_test.rb` covering all git tools, including ref-injection and path-jail rejection.
+- Added `test/shared_tools/tools/{json,yaml,toml,csv}_*_tool_test.rb` covering the structured-data tools.
+- Added `test/shared_tools/tools/{diff,multi_edit,apply_patch,replace_in_files}_tool_test.rb` covering the file-editing tools, including atomicity-on-failure and path-jail rejection.
+- Added `test/shared_tools/tools/{glob,tree}_tool_test.rb` and rewrote `test/shared_tools/tools/search_codebase_tool_test.rb` for the new `pattern:`/`glob:` params, context blocks, and regex-error handling.
+- Added `test/shared_tools/tools/{gem,bundle,lint,parse_ruby}_tool_test.rb` covering the Ruby dev tools.
+- Added `test/shared_tools/tools/process_{start,list,output,kill}_tool_test.rb` covering the process-management tools, including allowlist rejection, the concurrency limit, and full start/list/output/kill lifecycles.
+- Added `test/shared_tools/tools/{web_fetch,http_request,download_file}_tool_test.rb` covering the network tools, including live SSRF-block assertions against loopback and cloud-metadata addresses.
+- Added `test/shared_tools/url_guard_test.rb` and `test/shared_tools/command_guard_test.rb` covering the new security modules directly.
+- Added `test/shared_tools/tools/{todo_write,bash,run_tests,python_tests}_tool_test.rb`.
+- Added `init_git_repo` / `git_commit_all` test helpers to `test/test_helper.rb`.
+
 ### [0.4.4] - 2026-06-06
 
 #### Tools

data/README.md

@@ -16,7 +16,7 @@ SharedTools is a comprehensive collection of production-ready tools designed for
 
 ### Key Features
 
-- 🔧 **21+ Production Tools** — Browser automation, file operations, database queries, code evaluation, document processing, DNS and WHOIS lookups, IP geolocation, data science, weather data, workflow management, system utilities, notifications, and more
+- 🔧 **45+ Production Tools** — Browser automation, file discovery and editing (glob/tree/diff/multi-edit/patch/replace), git, structured data (JSON/YAML/TOML/CSV), Ruby dev tooling (gem/bundle/lint/parse), background process management, guarded HTTP (fetch/request/download), database queries, code evaluation, document processing, DNS and WHOIS lookups, IP geolocation, data science, weather data, workflow management, system utilities, notifications, and more
 - 🔒 **Human-in-the-Loop Authorization** — Built-in safety system for sensitive operations
 - 🎯 **Facade Pattern** — Simplified interfaces with complex capabilities under the hood
 - 🔌 **Pluggable Drivers** — Swap implementations for testing or different backends
@@ -120,6 +120,148 @@ content = disk.execute(action: "file_read", path: "./report.txt")
 
 ---
 
+### 🔍 File Discovery Tools
+
+Find files and content without shelling out to `rg`/`grep`/`find`. Pure Ruby, no external binary dependency.
+
+- **`GlobTool`** — finds files matching a glob pattern (`**/*.rb`, `app/models/*.rb`), returns sorted paths relative to `base`.
+- **`TreeTool`** — renders a depth-limited directory tree, skipping `.git`/`node_modules`/hidden entries by default.
+- **`SearchCodebaseTool`** — searches file contents for a regular expression, returning `path:line: text` hits (or context blocks with `context`/`before`/`after`). ReDoS-guarded with a per-match regex timeout, and caps results at `max_results` (default 50, max 500).
+
+```ruby
+glob = SharedTools::Tools::GlobTool.new
+glob.execute(pattern: "**/*.rb", base: "./lib")
+
+tree = SharedTools::Tools::TreeTool.new
+tree.execute(path: "./lib", max_depth: 2)
+
+search = SharedTools::Tools::SearchCodebaseTool.new
+search.execute(pattern: "def execute", glob: "*.rb")
+search.execute(pattern: "TODO", context: 2) # 2 lines of context around each match
+```
+
+> **Note:** `SearchCodebaseTool`'s implementation changed from shelling out to `rg`/`grep` to a pure-Ruby, ReDoS-guarded scanner. The `term:` and `extension:` params were renamed to `pattern:` (a regex) and `glob:` (a filename glob, e.g. `"*.rb"` instead of `"rb"`); `max_results:` is unchanged. The `tool:` result key now always reports `"ruby"`.
+
+---
+
+### ✂️ File Editing Tools
+
+Precise, deterministic text editing that complements `DiskTool` and `GitTool` — an alternative to `Disk::FileReplaceTool`'s single global replace for coding-agent workflows.
+
+- **`DiffTool`** — compares two in-memory blocks of text and returns a readable unified diff. Read-only, no filesystem access.
+- **`MultiEditTool`** — applies several find/replace edits to one file atomically. Each edit's `old_string` must match exactly once (add context or set `replace_all`) or the whole batch is rejected and nothing is written. Requires authorization.
+- **`ApplyPatchTool`** — applies a unified diff (as produced by `git diff`, `DiffTool`, or `diff -u`) via `git apply`, validating with `--check` first. Every touched path is confined to `root`. Set `check: true` for a dry run. Requires authorization.
+- **`ReplaceInFilesTool`** — batch find/replace across every file in `root` matching a glob (default `**/*`). Literal by default; set `regex: true` for a pattern with `\1`-style backreferences. ReDoS-guarded, skips binary files and ignored directories. Set `dry_run: true` to preview without writing. Requires authorization (dry runs don't).
+
+```ruby
+diff = SharedTools::Tools::DiffTool.new
+diff.execute(old: old_text, new: new_text)
+
+multi_edit = SharedTools::Tools::MultiEditTool.new(root: "./my-project")
+multi_edit.execute(path: "lib/foo.rb", edits: [
+  { old_string: "def bar", new_string: "def baz" },
+  { old_string: "BAR", new_string: "BAZ", replace_all: true }
+])
+
+apply_patch = SharedTools::Tools::ApplyPatchTool.new(root: "./my-project")
+apply_patch.execute(patch: unified_diff_text, check: true) # dry run
+apply_patch.execute(patch: unified_diff_text)
+
+replace = SharedTools::Tools::ReplaceInFilesTool.new(root: "./my-project")
+replace.execute(pattern: "OldClassName", replacement: "NewClassName", glob: "**/*.rb")
+```
+
+---
+
+### 🔀 Git Tools
+
+Read a repository's history and working-tree state, and make basic mutating changes. Read-only actions (`status`, `diff`, `log`, `show`, `blame`, `branch`, `grep`) require no authorization; mutating actions (`add`, `commit`, `checkout`) require user authorization. External diff drivers, textconv filters, and `core.fsmonitor` are disabled so an untrusted checkout can't turn a read into command execution.
+
+**Actions:** `status`, `diff`, `log`, `show`, `blame`, `branch`, `grep`, `add`, `commit`, `checkout`
+
+```ruby
+git = SharedTools::Tools::GitTool.new(repo_root: "./my-project")
+git.execute(action: "status")
+git.execute(action: "diff", staged: true)
+git.execute(action: "log", count: 10, path: "lib/foo.rb")
+git.execute(action: "blame", path: "lib/foo.rb", start_line: 10, end_line: 20)
+git.execute(action: "commit", message: "Fix the thing", all: true)
+```
+
+Each action is also available as a standalone tool, e.g. `SharedTools::Tools::Git::StatusTool`, `SharedTools::Tools::Git::DiffTool`, `SharedTools::Tools::Git::CommitTool`.
+
+---
+
+### 💎 Ruby Dev Tools
+
+Tooling for working on a Ruby project: gem metadata, Bundler, linting, and structural code navigation.
+
+- **`GemTool`** — read-only RubyGems.org metadata lookup (`info`, `version`, `dependencies`, `search`). No authorization needed.
+- **`BundleTool`** — runs Bundler (`install`, `update`, `outdated`, `check`, `lock`, `add`) in a project. Requires a Gemfile and authorization.
+- **`LintTool`** — runs RuboCop or Standard, auto-detected (Standard if `.standard.yml` is present) or forced explicitly. Uses `bundle exec` when a Gemfile exists. Offenses are a normal result, not an error; `autocorrect: true` rewrites files in place. Requires authorization.
+- **`ParseRubyTool`** — outlines a Ruby file's structure (classes, modules, methods, constants with line numbers) via Prism (Ruby 3.3+) or the Ripper stdlib fallback — parses, never executes. Filter with `query`/`kind` to locate a specific definition. Read-only.
+
+```ruby
+gem = SharedTools::Tools::GemTool.new
+gem.execute(name: "ruby_llm", action: "version")
+
+bundle = SharedTools::Tools::BundleTool.new(root: "./my-project")
+bundle.execute(action: "add", gem: "rack")
+
+lint = SharedTools::Tools::LintTool.new(root: "./my-project")
+lint.execute(path: "lib/foo.rb", autocorrect: true)
+
+parse = SharedTools::Tools::ParseRubyTool.new
+parse.execute(path: "./lib/foo.rb")
+parse.execute(path: "./lib/foo.rb", kind: "method", query: "initialize")
+```
+
+---
+
+### ⚙️ Process Management Tools
+
+Start, monitor, and stop long-running background processes (dev servers, watchers, log tails) without blocking the caller.
+
+- **`ProcessStartTool`** — starts a command as a background process and returns its id immediately. The executable must be on `allowed_commands` (empty by default — nothing is allowed until configured); argv only, no shell. Runs in its own process group. Requires authorization.
+- **`ProcessListTool`** — lists background processes: id, status, pid, age, command. Read-only.
+- **`ProcessOutputTool`** — reads new stdout/stderr since the last read (poll it to follow output), plus status and exit code. Read-only.
+- **`ProcessKillTool`** — SIGTERM the process group, escalating to SIGKILL if it doesn't exit, then returns final output. Always available with no authorization prompt, so a runaway process can always be stopped.
+
+```ruby
+start = SharedTools::Tools::ProcessStartTool.new(allowed_commands: ["rackup"])
+started = start.execute(command: "rackup", args: ["-p", "9292"], name: "web server")
+id = started[/proc_\d+/]
+
+output = SharedTools::Tools::ProcessOutputTool.new
+output.execute(id: id) # poll this in a loop to stream output
+
+SharedTools::Tools::ProcessListTool.new.execute
+SharedTools::Tools::ProcessKillTool.new.execute(id: id)
+```
+
+---
+
+### 🌐 Network Tools
+
+Guarded HTTP — every request and redirect hop is checked against SSRF (server-side request forgery): only http/https, no embedded credentials, and the resolved IP is rejected (and the connection pinned to it) if it's private, loopback, link-local, cloud-metadata, or otherwise reserved.
+
+- **`WebFetchTool`** — fetches a URL and returns readable text (HTML is stripped to text). Read-only, no authorization needed.
+- **`HttpRequestTool`** — a general HTTP client returning status, key headers, and body. GET/HEAD need no authorization; POST/PUT/PATCH/DELETE require it.
+- **`DownloadFileTool`** — downloads a URL to a file within `root`, size-capped. Requires authorization.
+
+```ruby
+fetch = SharedTools::Tools::WebFetchTool.new
+fetch.execute(url: "https://example.com")
+
+request = SharedTools::Tools::HttpRequestTool.new
+request.execute(url: "https://api.example.com/items", method: "POST", body: '{"name":"x"}')
+
+download = SharedTools::Tools::DownloadFileTool.new(root: "./downloads")
+download.execute(url: "https://example.com/release.zip", path: "release.zip")
+```
+
+---
+
 ### 🗄️ Database Tools
 
 Execute SQL operations on databases.
@@ -162,6 +304,39 @@ output = eval_tool.execute(language: "shell", code: "ls -la")
 
 ---
 
+### 🖥️ Bash & Test Runner Tools
+
+- **`BashTool`** — runs ONE allowlisted executable with arguments. Deliberately not a shell: no pipes, redirects, globs, or variable expansion, so OS command injection has no surface to exploit. `allowed_commands` is empty by default — nothing runs until configured. Requires authorization.
+- **`RunTestsTool`** — runs a Ruby project's test suite (RSpec or Minitest, auto-detected). A failing suite is a normal result, not a tool error. Requires authorization.
+- **`PythonTestsTool`** — runs a Python project's tests (pytest or unittest). Requires authorization.
+
+```ruby
+bash = SharedTools::Tools::BashTool.new(allowed_commands: ["ls", "cat"])
+bash.execute(command: "ls", args: ["-la"])
+
+tests = SharedTools::Tools::RunTestsTool.new(root: "./my-project")
+tests.execute(path: "spec/models/user_spec.rb")
+
+py_tests = SharedTools::Tools::PythonTestsTool.new(root: "./my-project")
+py_tests.execute(framework: "unittest")
+```
+
+---
+
+### ✅ Task Tracking
+
+**`TodoWriteTool`** maintains a task list for multi-step work. Each call replaces the whole list and renders it back; state lives on the tool instance for the duration of a chat session. No authorization needed.
+
+```ruby
+todo = SharedTools::Tools::TodoWriteTool.new
+todo.execute(todos: [
+  { content: "Write the tool", status: "completed" },
+  { content: "Write the tests", status: "in_progress" }
+])
+```
+
+---
+
 ### 📄 Doc Tools
 
 Read and reason over documents in any format.
@@ -208,6 +383,31 @@ dns.execute(action: "ip_location", host: "8.8.8.8")  # geolocate any IP
 
 ---
 
+### 🧩 Structured Data Tools
+
+Query and edit JSON, YAML, TOML, and CSV without writing a parser. Each query tool accepts either a file path or an inline string, and supports a dot/bracket path expression to extract a value (`users[0].name`, `services[].image`, `dependencies.serde.version`) — omit the query to pretty-print the whole document. YAML is loaded with `safe_load` (no arbitrary object deserialization) and TOML is parsed with a small dependency-free parser.
+
+```ruby
+json = SharedTools::Tools::JsonQueryTool.new
+json.execute(path: "./config.json", query: "servers[0].host")
+
+yaml = SharedTools::Tools::YamlQueryTool.new
+yaml.execute(path: "./docker-compose.yml", query: "services[].image")
+
+toml = SharedTools::Tools::TomlQueryTool.new
+toml.execute(path: "./Cargo.toml", query: "dependencies.serde.version")
+
+csv_read = SharedTools::Tools::CsvReadTool.new
+csv_read.execute(path: "./sales.csv", limit: 20)
+
+csv_write = SharedTools::Tools::CsvWriteTool.new
+csv_write.execute(path: "./out.csv", headers: ["name", "age"], rows: [["Alice", "30"]])
+```
+
+`CsvWriteTool` is mutating and requires user authorization (see [Authorization System](#authorization-system)); the query tools and `CsvReadTool` are read-only.
+
+---
+
 ### 🌤️ Weather Tool
 
 Real-time weather data from OpenWeatherMap API. Combine with DnsTool for automatic local forecasts.
@@ -440,14 +640,16 @@ SharedTools bundles [Model Context Protocol](https://modelcontextprotocol.io) cl
 | `require 'shared_tools/mcp/playwright_client'` | Browser automation: navigate, click, fill, screenshot, extract |
 
 ```ruby
-# Load all available clients at once (skips any whose env vars are missing)
-require 'shared_tools/mcp'
-
-# Or load a specific client
+# Each client is a RubyLLM::MCP subclass (ruby_llm >= 2.1). Defining it starts
+# nothing; the server is launched/connected when its tools are first requested.
 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)
 chat.ask("Find my project planning pages and summarise what's in them")
+
+# Load every definition; .available skips those whose env vars are missing
+require 'shared_tools/mcp'
+chat  = RubyLLM.chat.with_mcp(*SharedTools::MCP.available)
+robot = RobotLab.build(name: "helper", mcp: SharedTools::MCP.available)
 ```
 
 See [MCP Clients README](lib/shared_tools/mcp/README.md) for full configuration details.
@@ -596,6 +798,8 @@ This gem is available as open source under the terms of the [MIT License](LICENS
 
 This gem was originally inspired by Kevin Sylvestre's [omniai-tools](https://github.com/ksylvest/omniai-tools) gem. SharedTools has since evolved to focus exclusively on RubyLLM support with enhanced features and comprehensive documentation.
 
+Also checkout the wonderful ruby gem [ruby_llm-toolbox](https://rubygems.org/gems/ruby_llm-toolbox)
+
 ## Links
 
 - **Documentation**: [madbomber.github.io/shared_tools](https://madbomber.github.io/shared_tools)

data/lib/shared_tools/apply_patch_tool.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+# Shim: require 'shared_tools/apply_patch_tool'
+require 'shared_tools'
+require 'shared_tools/tools/apply_patch_tool'

data/lib/shared_tools/bash_tool.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+# Shim: require 'shared_tools/bash_tool'
+require 'shared_tools'
+require 'shared_tools/tools/bash_tool'

data/lib/shared_tools/bundle_tool.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+# Shim: require 'shared_tools/bundle_tool'
+require 'shared_tools'
+require 'shared_tools/tools/bundle_tool'

data/lib/shared_tools/command_guard.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SharedTools
+  # Validates the executable name for BashTool and ProcessStartTool. The
+  # actual execution path uses array-form spawning (no shell), so this guard
+  # only has to ensure the program itself is on the allowlist and isn't
+  # smuggling a path or shell metacharacters. Arguments are passed verbatim as
+  # argv and are therefore inert — there is no shell to interpret them.
+  class CommandGuard
+    class Blocked < StandardError; end
+
+    SHELL_META = /[;&|<>`$(){}\[\]*?!#~\n\r]/
+    PATH_SEP = %r{[/\\]}
+
+    def initialize(allowed)
+      @allowed = Array(allowed).map(&:to_s)
+    end
+
+    # Returns the validated executable name, or raises Blocked.
+    def check!(command)
+      cmd = command.to_s
+      raise Blocked, "no command given" if cmd.empty?
+
+      raise Blocked, "executable name may not contain a path: #{cmd.inspect}" if cmd.match?(PATH_SEP)
+      raise Blocked, "executable name may not contain shell metacharacters: #{cmd.inspect}" if cmd.match?(SHELL_META)
+
+      unless @allowed.include?(cmd)
+        raise Blocked, "command not allowed: #{cmd.inspect} " \
+                       "(allowed: #{@allowed.empty? ? '(none)' : @allowed.join(', ')})"
+      end
+
+      cmd
+    end
+  end
+end

data/lib/shared_tools/csv_read_tool.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+# Shim: require 'shared_tools/csv_read_tool'
+require 'shared_tools'
+require 'shared_tools/tools/csv_read_tool'

data/lib/shared_tools/csv_write_tool.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+# Shim: require 'shared_tools/csv_write_tool'
+require 'shared_tools'
+require 'shared_tools/tools/csv_write_tool'

data/lib/shared_tools/data_path.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SharedTools
+  # Shared path-navigation for the structured-data query tools (JsonQueryTool,
+  # YamlQueryTool, TomlQueryTool). Path syntax: dot-separated keys, [n] for
+  # array indices, and [] to map a field across an array. Examples:
+  #   users[0].name        users[].email        config.server.port
+  module DataPath
+    class Error < StandardError; end
+
+    module_function
+
+    def query(data, path)
+      apply(data, parse(path))
+    end
+
+    def parse(path)
+      cleaned = path.to_s.strip.sub(/\A\$?\.?/, "")
+      tokens = []
+      cleaned.scan(/[^.\[\]]+|\[\d+\]|\[\]/) do |match|
+        tokens << case match
+                  when "[]" then :map
+                  when /\A\[(\d+)\]\z/ then Regexp.last_match(1).to_i
+                  else match
+                  end
+      end
+      raise Error, "could not parse path: #{path.inspect}" if tokens.empty?
+
+      tokens
+    end
+
+    def apply(data, tokens)
+      return data if tokens.empty? || data.nil?
+
+      token, *rest = tokens
+      case token
+      when :map
+        raise Error, "[] expects an array, got #{data.class}" unless data.is_a?(Array)
+
+        data.map { |element| apply(element, rest) }
+      when Integer
+        raise Error, "index [#{token}] expects an array, got #{data.class}" unless data.is_a?(Array)
+
+        apply(data[token], rest)
+      else
+        raise Error, "key '#{token}' expects an object, got #{data.class}" unless data.is_a?(Hash)
+
+        apply(data[token], rest)
+      end
+    end
+  end
+end

data/lib/shared_tools/diff_tool.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+# Shim: require 'shared_tools/diff_tool'
+require 'shared_tools'
+require 'shared_tools/tools/diff_tool'

data/lib/shared_tools/download_file_tool.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+# Shim: require 'shared_tools/download_file_tool'
+require 'shared_tools'
+require 'shared_tools/tools/download_file_tool'

data/lib/shared_tools/gem_tool.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+# Shim: require 'shared_tools/gem_tool'
+require 'shared_tools'
+require 'shared_tools/tools/gem_tool'

data/lib/shared_tools/git_tool.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+# Shim: require 'shared_tools/git_tool'
+require 'shared_tools'
+require 'shared_tools/tools/git'       # sub-tools (Git::StatusTool, Git::DiffTool, etc.)
+require 'shared_tools/tools/git_tool'  # facade (GitTool)

data/lib/shared_tools/glob_tool.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+# Shim: require 'shared_tools/glob_tool'
+require 'shared_tools'
+require 'shared_tools/tools/glob_tool'

data/lib/shared_tools/http_request_tool.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+# Shim: require 'shared_tools/http_request_tool'
+require 'shared_tools'
+require 'shared_tools/tools/http_request_tool'

data/lib/shared_tools/json_query_tool.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+# Shim: require 'shared_tools/json_query_tool'
+require 'shared_tools'
+require 'shared_tools/tools/json_query_tool'

data/lib/shared_tools/lint_tool.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+# Shim: require 'shared_tools/lint_tool'
+require 'shared_tools'
+require 'shared_tools/tools/lint_tool'

data/lib/shared_tools/mcp/brave_search_client.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # shared_tools/mcp/brave_search_client.rb
 #
 # Brave Search MCP Server — npx auto-download (no pre-installation required)
@@ -8,30 +10,30 @@
 #   - Node.js and npx (https://nodejs.org)
 #   - A Brave Search API key (free tier available at https://brave.com/search/api/)
 #   The @modelcontextprotocol/server-brave-search package is downloaded
-#   automatically on first use via `npx -y`.
+#   automatically the first time the server is started, via `npx -y`.
 #
 # Configuration:
 #   export BRAVE_API_KEY=your_api_key_here
 #
 # Usage:
 #   require 'shared_tools/mcp/brave_search_client'
-#   client = RubyLLM::MCP.clients["brave-search"]
-#   chat = RubyLLM.chat.with_tools(*client.tools)
+#   chat  = RubyLLM.chat.with_mcp(SharedTools::MCP::BraveSearch)
+#   robot = RobotLab.build(name: "researcher", mcp: [SharedTools::MCP::BraveSearch])
 #
-# 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("BRAVE_API_KEY")
+module SharedTools
+  module MCP
+    class BraveSearch < ::RubyLLM::MCP
+      extend ClientSupport
 
-require "ruby_llm/mcp"
+      requires_envars "BRAVE_API_KEY"
 
-RubyLLM::MCP.add_client(
-  name: "brave-search",
-  transport_type: :stdio,
-  config: {
-    command: "npx",
-    args:    ["-y", "@modelcontextprotocol/server-brave-search"],
-    env:     { "BRAVE_API_KEY" => ENV.fetch("BRAVE_API_KEY", "") },
-  },
-)
+      command "npx", "-y", "@modelcontextprotocol/server-brave-search"
+      env "BRAVE_API_KEY" => env_from("BRAVE_API_KEY")
+    end
+  end
+end

data/lib/shared_tools/mcp/chart_client.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # shared_tools/mcp/chart_client.rb
 #
 # AntV Chart MCP Server — npx auto-download (no pre-installation required)
@@ -7,26 +9,27 @@
 #
 # Prerequisites:
 #   - Node.js and npx (https://nodejs.org)
-#   The @antv/mcp-server-chart package is downloaded automatically on first use
-#   via `npx -y`.
+#   The @antv/mcp-server-chart package is downloaded automatically the first
+#   time the server is started, via `npx -y`.
 #
 # No API key required.
 #
 # Usage:
 #   require 'shared_tools/mcp/chart_client'
-#   client = RubyLLM::MCP.clients["chart"]
-#   chat = RubyLLM.chat.with_tools(*client.tools)
+#   chat  = RubyLLM.chat.with_mcp(SharedTools::MCP::Chart)
+#   robot = RobotLab.build(name: "analyst", mcp: [SharedTools::MCP::Chart])
 #
-# 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 Chart < ::RubyLLM::MCP
+      extend ClientSupport
 
-RubyLLM::MCP.add_client(
-  name: "chart",
-  transport_type: :stdio,
-  config: {
-    command: "npx",
-    args:    ["-y", "@antv/mcp-server-chart"],
-    env:     {},
-  },
-)
+      command "npx", "-y", "@antv/mcp-server-chart"
+    end
+  end
+end