Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit ba8019c

Browse files
MadBomberMadBomber
committed
feat(mcp): add support for new MCP clients
This commit adds support for several new MCP (Model Context Protocol) clients in the SharedTools library: - Tavily (web search, news, research, URL extraction) - requires API key only - GitHub (repos, issues, PRs, code search) - auto-installs via Homebrew - Notion (pages, databases, search, content CRUD) - auto-installs via Homebrew - Slack (channels, messages, threads, user info) - auto-installs via Homebrew - Hugging Face (models, datasets, Spaces, model cards) - auto-installs via Homebrew - Memory (persistent knowledge graph) - auto-downloads via npx - Sequential Thinking (chain-of-thought reasoning) - auto-downloads via npx - Chart (chart and visualisation generation) - auto-downloads via npx - Brave Search (web and news search) - auto-downloads via npx The new clients are opt-in, with each one requiring a specific environment variable to be set for authentication. Documentation on the new clients has been added to the README. This change introduces several new features and capabilities to the SharedTools library, allowing users to integrate a wide range of external services and tools into their applications.
1 parent 625a8b7 commit ba8019c

5 files changed

Lines changed: 627 additions & 10 deletions

File tree

‎README.md‎

Lines changed: 53 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -410,6 +410,49 @@ error_tool.execute(
410410

411411
---
412412

413+
## MCP Clients
414+
415+
SharedTools bundles [Model Context Protocol](https://modelcontextprotocol.io) clients that connect AI agents to external services. Each client is opt-in — require only the ones you need.
416+
417+
### Remote HTTP (API key only)
418+
419+
| Client | Env var | Provides |
420+
|--------|---------|----------|
421+
| `require 'shared_tools/mcp/tavily_client'` | `TAVILY_API_KEY` | Web search, news, research, URL extraction |
422+
423+
### Brew-installed (auto-installs via Homebrew)
424+
425+
| Client | Env var | Provides |
426+
|--------|---------|----------|
427+
| `require 'shared_tools/mcp/github_client'` | `GITHUB_PERSONAL_ACCESS_TOKEN` | Repos, issues, PRs, code search |
428+
| `require 'shared_tools/mcp/notion_client'` | `NOTION_TOKEN` | Pages, databases, search, content CRUD |
429+
| `require 'shared_tools/mcp/slack_client'` | `SLACK_MCP_XOXP_TOKEN` | Channels, messages, threads, user info |
430+
| `require 'shared_tools/mcp/hugging_face_client'` | `HF_TOKEN` | Models, datasets, Spaces, model cards |
431+
432+
### npx Auto-download (Node.js required)
433+
434+
| Client | Provides |
435+
|--------|----------|
436+
| `require 'shared_tools/mcp/memory_client'` | Persistent knowledge graph |
437+
| `require 'shared_tools/mcp/sequential_thinking_client'` | Chain-of-thought reasoning |
438+
| `require 'shared_tools/mcp/chart_client'` | Chart and visualisation generation |
439+
| `require 'shared_tools/mcp/brave_search_client'` | Web and news search (`BRAVE_API_KEY`) |
440+
441+
```ruby
442+
# Load all available clients at once (skips any whose env vars are missing)
443+
require 'shared_tools/mcp'
444+
445+
# Or load a specific client
446+
require 'shared_tools/mcp/notion_client'
447+
client = RubyLLM::MCP.clients["notion"]
448+
chat = RubyLLM.chat.with_tools(*client.tools)
449+
chat.ask("Find my project planning pages and summarise what's in them")
450+
```
451+
452+
See [MCP Clients README](lib/shared_tools/mcp/README.md) for full configuration details.
453+
454+
---
455+
413456
## Authorization System
414457

415458
SharedTools includes a human-in-the-loop authorization system for safety:
@@ -470,7 +513,16 @@ bundle exec ruby -I examples examples/doc_tool_demo.rb
470513
| `doc_tool_demo.rb` | Text, PDF, Word, spreadsheets |
471514
| `error_handling_tool_demo.rb` | Error handling patterns |
472515
| `eval_tool_demo.rb` | Code evaluation |
473-
| `mcp_client_demo.rb` | MCP client integration |
516+
| `mcp_client_demo.rb` | MCP client overview |
517+
| `mcp/tavily_demo.rb` | Tavily web search (HTTP) |
518+
| `mcp/github_demo.rb` | GitHub repos, issues, PRs |
519+
| `mcp/notion_demo.rb` | Notion pages and databases |
520+
| `mcp/slack_demo.rb` | Slack channels and messages |
521+
| `mcp/hugging_face_demo.rb` | Hugging Face models and datasets |
522+
| `mcp/memory_demo.rb` | Persistent knowledge graph |
523+
| `mcp/sequential_thinking_demo.rb` | Chain-of-thought reasoning |
524+
| `mcp/chart_demo.rb` | Chart generation |
525+
| `mcp/brave_search_demo.rb` | Brave web search |
474526
| `notification_tool_demo.rb` | Desktop notifications, alerts, TTS |
475527
| `system_info_tool_demo.rb` | System info |
476528
| `weather_tool_demo.rb` | Weather + local forecast |

‎docs/getting-started/installation.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,22 @@ brew install python3
102102
apt-get install python3
103103
```
104104

105+
## MCP Clients
106+
107+
SharedTools bundles optional MCP (Model Context Protocol) clients. Each is opt-in via an extra require:
108+
109+
```ruby
110+
gem 'ruby_llm-mcp', '>= 0.7.0' # Add to Gemfile
111+
```
112+
113+
| Transport | What's needed |
114+
|-----------|---------------|
115+
| Remote HTTP (Tavily) | Only an API key — no binaries |
116+
| Brew-installed (GitHub, Notion, Slack, Hugging Face) | Homebrew — binaries are auto-installed on first use |
117+
| npx (Memory, Sequential Thinking, Chart, Brave Search) | Node.js / npx — packages are auto-downloaded on first use |
118+
119+
See [MCP Clients README](https://github.com/madbomber/shared_tools/blob/main/lib/shared_tools/mcp/README.md) for full configuration details.
120+
105121
## Complete Setup Example
106122

107123
For a full-featured installation with all optional dependencies:

‎examples/README.md‎

Lines changed: 146 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -260,18 +260,149 @@ bundle exec ruby -I examples examples/notification_tool_demo.rb
260260

261261
### `mcp_client_demo.rb`
262262

263-
Model Context Protocol (MCP) client integration: connecting to MCP servers (Tavily, GitHub, iMCP), using MCP tools in LLM conversations, multi-client orchestration, and accessing MCP resources.
263+
Model Context Protocol (MCP) client overview: loading multiple clients, using MCP tools in LLM conversations, and multi-client orchestration.
264264

265-
**Requires:**
266-
- `ruby_llm-mcp` gem
267-
- `TAVILY_API_KEY` for web search
268-
- `GITHUB_PERSONAL_ACCESS_TOKEN` for GitHub operations
269-
- `brew install github-mcp-server` and `brew install --cask loopwork/tap/iMCP` (macOS)
265+
**Requires:** `ruby_llm-mcp` gem
266+
267+
```bash
268+
bundle exec ruby -I examples examples/mcp_client_demo.rb
269+
```
270+
271+
---
272+
273+
## MCP Client Demos (`mcp/` subdirectory)
274+
275+
Individual demos for each MCP client. Run from the project root with both `examples` and `examples/mcp` on the load path:
276+
277+
```bash
278+
bundle exec ruby -I lib -I examples examples/mcp/tavily_demo.rb
279+
```
280+
281+
All MCP demos share a `examples/mcp/common.rb` helper and use the same `title`/`ask`/`new_chat` helpers as the main demos.
282+
283+
---
284+
285+
### `mcp/tavily_demo.rb`
286+
287+
AI-optimized web search, news, research, and URL extraction via the Tavily API. Uses the remote HTTP transport — no local binary required.
288+
289+
**Requires:** `TAVILY_API_KEY` (free tier at https://tavily.com)
270290

271291
```bash
272292
export TAVILY_API_KEY="your-key"
293+
bundle exec ruby -I lib -I examples examples/mcp/tavily_demo.rb
294+
```
295+
296+
---
297+
298+
### `mcp/github_demo.rb`
299+
300+
GitHub repository exploration: listing repos, reading issues and PRs, code search, contributor analysis, and release history.
301+
302+
**Requires:**
303+
- `GITHUB_PERSONAL_ACCESS_TOKEN`
304+
- Homebrew (auto-installs `github-mcp-server`)
305+
306+
```bash
273307
export GITHUB_PERSONAL_ACCESS_TOKEN="your-token"
274-
bundle exec ruby -I examples examples/mcp_client_demo.rb
308+
bundle exec ruby -I lib -I examples examples/mcp/github_demo.rb
309+
```
310+
311+
---
312+
313+
### `mcp/notion_demo.rb`
314+
315+
Full Notion workspace access: search pages and databases, read content, explore recent activity, and retrieve page summaries.
316+
317+
**Requires:**
318+
- `NOTION_TOKEN` (create at https://www.notion.so/profile/integrations)
319+
- Homebrew (auto-installs `notion-mcp-server`)
320+
- Pages and databases must be shared with the integration
321+
322+
```bash
323+
export NOTION_TOKEN="ntn_..."
324+
bundle exec ruby -I lib -I examples examples/mcp/notion_demo.rb
325+
```
326+
327+
---
328+
329+
### `mcp/slack_demo.rb`
330+
331+
Slack workspace browsing: channel overview, recent message summaries, thread deep-dives, and team activity analysis.
332+
333+
**Requires:**
334+
- `SLACK_MCP_XOXP_TOKEN` (user OAuth, recommended) **or** `SLACK_MCP_XOXB_TOKEN` (bot token)
335+
- Homebrew (auto-installs `slack-mcp-server`)
336+
337+
```bash
338+
export SLACK_MCP_XOXP_TOKEN="xoxp-..."
339+
bundle exec ruby -I lib -I examples examples/mcp/slack_demo.rb
340+
```
341+
342+
---
343+
344+
### `mcp/hugging_face_demo.rb`
345+
346+
Browse the Hugging Face Hub: trending models, Ruby/Rails model search, small model discovery, dataset exploration, and model card retrieval.
347+
348+
**Requires:**
349+
- `HF_TOKEN` (create at https://huggingface.co/settings/tokens)
350+
- Homebrew (auto-installs `hf-mcp-server`)
351+
352+
```bash
353+
export HF_TOKEN="hf_..."
354+
bundle exec ruby -I lib -I examples examples/mcp/hugging_face_demo.rb
355+
```
356+
357+
---
358+
359+
### `mcp/memory_demo.rb`
360+
361+
Persistent knowledge graph across conversations using the `@modelcontextprotocol/server-memory` npm package. Store and retrieve facts, entities, and relations.
362+
363+
**Requires:** Node.js / npx (package auto-downloaded on first use)
364+
365+
```bash
366+
bundle exec ruby -I lib -I examples examples/mcp/memory_demo.rb
367+
```
368+
369+
---
370+
371+
### `mcp/sequential_thinking_demo.rb`
372+
373+
Structured chain-of-thought reasoning using the `@modelcontextprotocol/server-sequential-thinking` npm package.
374+
375+
**Requires:** Node.js / npx (package auto-downloaded on first use)
376+
377+
```bash
378+
bundle exec ruby -I lib -I examples examples/mcp/sequential_thinking_demo.rb
379+
```
380+
381+
---
382+
383+
### `mcp/chart_demo.rb`
384+
385+
Chart and visualisation generation using the `@antv/mcp-server-chart` npm package.
386+
387+
**Requires:** Node.js / npx (package auto-downloaded on first use)
388+
389+
```bash
390+
bundle exec ruby -I lib -I examples examples/mcp/chart_demo.rb
391+
```
392+
393+
---
394+
395+
### `mcp/brave_search_demo.rb`
396+
397+
Web and news search via the Brave Search API using the `@modelcontextprotocol/server-brave-search` npm package.
398+
399+
**Requires:**
400+
- `BRAVE_API_KEY` (free tier at https://brave.com/search/api/)
401+
- Node.js / npx (package auto-downloaded on first use)
402+
403+
```bash
404+
export BRAVE_API_KEY="your-key"
405+
bundle exec ruby -I lib -I examples examples/mcp/brave_search_demo.rb
275406
```
276407

277408
---
@@ -364,8 +495,14 @@ Debug logging (`RUBY_LLM_DEBUG=true`) is set in each demo's header so tool calls
364495
| `ANTHROPIC_API_KEY` | All demos (if using Anthropic) |
365496
| `OLLAMA_HOST` | All demos (if using Ollama; default: `http://localhost:11434`) |
366497
| `OPENWEATHER_API_KEY` | `weather_tool_demo.rb` |
367-
| `TAVILY_API_KEY` | `mcp_client_demo.rb` |
368-
| `GITHUB_PERSONAL_ACCESS_TOKEN` | `mcp_client_demo.rb` |
498+
| `TAVILY_API_KEY` | `mcp/tavily_demo.rb` |
499+
| `GITHUB_PERSONAL_ACCESS_TOKEN` | `mcp/github_demo.rb` |
500+
| `NOTION_TOKEN` | `mcp/notion_demo.rb` |
501+
| `SLACK_MCP_XOXP_TOKEN` | `mcp/slack_demo.rb` (user OAuth, recommended) |
502+
| `SLACK_MCP_XOXB_TOKEN` | `mcp/slack_demo.rb` (bot token alternative) |
503+
| `HF_TOKEN` | `mcp/hugging_face_demo.rb` |
504+
| `BRAVE_API_KEY` | `mcp/brave_search_demo.rb` |
505+
| `MEMORY_FILE_PATH` | `mcp/memory_demo.rb` (optional — path to `.jsonl` persistence file) |
369506

370507
---
371508

0 commit comments

Comments
 (0)