Merge pull request #114 from patvice/spec-2025-11-25-support

Add MCP 2025-11-25 support with tasks + schema updates

Author: patvice

README.md

@@ -1,276 +1,147 @@
-<img src="/docs/assets/images/rubyllm-mcp-logo-text.svg" alt="RubyLLM" height="120" width="250">
+<div align="center">
+  <img src="/docs/assets/images/rubyllm-mcp-logo-text.svg" alt="RubyLLM::MCP" height="120" width="250">
 
-**Aiming to make using MCPs with RubyLLM and Ruby as easy as possible.**
+  <strong>MCP made simple for RubyLLM.</strong>
 
-This project is a Ruby client for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), designed to work seamlessly with [RubyLLM](https://github.com/crmne/ruby_llm). This gem enables Ruby applications to connect to MCP servers and use their tools, resources and prompts as part of LLM conversations.
-
-For a more detailed guide, see the [RubyLLM::MCP docs](https://rubyllm-mcp.com/).
-
-Currently full support for MCP protocol version up to `2025-06-18`.
-
-<div class="badge-container">
-  <a href="https://badge.fury.io/rb/ruby_llm-mcp"><img src="https://badge.fury.io/rb/ruby_llm-mcp.svg" alt="Gem Version" /></a>
-  <a href="https://rubygems.org/gems/ruby_llm-mcp"><img alt="Gem Downloads" src="https://img.shields.io/gem/dt/ruby_llm-mcp"></a>
+  <p>
+    <a href="https://badge.fury.io/rb/ruby_llm-mcp"><img src="https://badge.fury.io/rb/ruby_llm-mcp.svg" alt="Gem Version" /></a>
+    <a href="https://rubygems.org/gems/ruby_llm-mcp"><img alt="Gem Downloads" src="https://img.shields.io/gem/dt/ruby_llm-mcp"></a>
+  </p>
 </div>
 
-## RubyLLM::MCP Features
-
-- 🎛️ **Dual SDK Support** _(v0.8+)_: Choose between native full-featured implementation or official MCP SDK
-- 🔌 **Multiple Transport Types**: Streamable HTTP, STDIO, and SSE transports
-- 🛠️ **Tool Integration**: Automatically converts MCP tools into RubyLLM-compatible tools
-- 📄 **Resource Management**: Access and include MCP resources (files, data) and resource templates in conversations
-- 🎯 **Prompt Integration**: Use predefined MCP prompts with arguments for consistent interactions
-- 🎨 **Client Features**: Support for sampling, roots, progress tracking, human-in-the-loop, and elicitation
-- 🔧 **Enhanced Chat Interface**: Extended RubyLLM chat methods for seamless MCP integration
-- 🔄 **Multiple Client Management**: Create and manage multiple MCP clients simultaneously for different servers and purposes
-- 📚 **Simple API**: Easy-to-use interface that integrates seamlessly with RubyLLM
-
-## Installation
-
-```bash
-bundle add ruby_llm-mcp
-```
+`ruby_llm-mcp` connects Ruby applications to [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers and integrates them directly with [RubyLLM](https://github.com/crmne/ruby_llm).
 
-or add this line to your application's Gemfile:
+## Simple Configuration
 
 ```ruby
-gem 'ruby_llm-mcp'
-```
-
-And then execute:
-
-```bash
-bundle install
-```
-
-Or install it yourself as:
-
-```bash
-gem install ruby_llm-mcp
-```
-
-## Choosing an Adapter
-
-Starting with version 0.8.0, RubyLLM MCP supports multiple SDK adapters:
+require 'ruby_llm/mcp'
 
-### RubyLLM Adapter (Default)
+RubyLLM.configure do |config|
+  config.openai_api_key = ENV.fetch('OPENAI_API_KEY')
+end
 
-The native implementation with full MCP protocol support:
+RubyLLM::MCP.configure do |config|
+  config.request_timeout = 8_000
+end
 
-```ruby
 client = RubyLLM::MCP.client(
-  name: "server",
-  adapter: :ruby_llm,  # Default, can be omitted
+  name: 'filesystem',
   transport_type: :stdio,
-  config: { command: "mcp-server" }
+  config: {
+    command: 'npx',
+    args: ['@modelcontextprotocol/server-filesystem', Dir.pwd]
+  }
 )
 ```
 
-**Features**: All MCP features including SSE transport, sampling, roots, progress tracking, etc.
-
-### MCP SDK Adapter
-
-The official Anthropic-maintained SDK:
+## Core Use Cases
 
 ```ruby
-# Add to Gemfile
-gem 'mcp', '~> 0.7'
+# Use MCP tools in a chat
+chat = RubyLLM.chat(model: 'gpt-4o-mini')
+chat.with_tools(*client.tools)
 
-# Use in code
-client = RubyLLM::MCP.client(
-  name: "server",
-  adapter: :mcp_sdk,
-  transport_type: :stdio,
-  config: { command: "mcp-server" }
-)
+puts chat.ask('List the Ruby files in this project and summarize what you find.')
 ```
 
-**Features**: Core MCP features (tools, resources, prompts, resource templates, logging). No sampling, roots, or other advanced client features.
-
-See the [Adapters Guide](https://rubyllm-mcp.com/guides/adapters.html) for detailed comparison.
-
-## Usage
-
-### Basic Setup
-
-First, configure your RubyLLM client and create an MCP connection:
-
 ```ruby
-require 'ruby_llm/mcp'
-
-# Configure RubyLLM
-RubyLLM.configure do |config|
-  config.openai_api_key = "your-api-key"
-end
-
-# Connect to an MCP server via SSE
-client = RubyLLM::MCP.client(
-  name: "my-mcp-server",
-  transport_type: :sse,
-  config: {
-    url: "http://localhost:9292/mcp/sse"
-  }
-)
+# Add a server resource to chat context
+resource = client.resource('project_readme')
 
-# Or connect via stdio
-client = RubyLLM::MCP.client(
-  name: "my-mcp-server",
-  transport_type: :stdio,
-  config: {
-    command: "node",
-    args: ["path/to/mcp-server.js"],
-    env: { "NODE_ENV" => "production" }
-  }
-)
+chat = RubyLLM.chat(model: 'gpt-4o-mini')
+chat.with_resource(resource)
 
-# Or connect via streamable HTTP
-client = RubyLLM::MCP.client(
-  name: "my-mcp-server",
-  transport_type: :streamable,
-  config: {
-    url: "http://localhost:8080/mcp",
-    headers: { "Authorization" => "Bearer your-token" }
-  }
-)
+puts chat.ask('Summarize this project in 5 bullets.')
 ```
 
-### Using MCP Tools with RubyLLM
-
 ```ruby
-# Get available tools from the MCP server
-tools = client.tools
-puts "Available tools:"
-tools.each do |tool|
-  puts "- #{tool.name}: #{tool.description}"
-end
+# Execute a predefined MCP prompt with arguments
+prompt = client.prompt('code_review')
+chat = RubyLLM.chat(model: 'gpt-4o-mini')
 
-# Create a chat session with MCP tools
-chat = RubyLLM.chat(model: "gpt-4")
-chat.with_tools(*client.tools)
+response = chat.ask_prompt(prompt, arguments: {
+  language: 'ruby',
+  focus: 'security'
+})
 
-# Ask a question that will use the MCP tools
-response = chat.ask("Can you help me search for recent files in my project?")
 puts response
 ```
 
-### Manual Tool Execution
-
-You can also execute MCP tools directly:
-
 ```ruby
-# Tools Execution
-tool = client.tool("search_files")
-
-# Execute a specific tool
-result = tool.execute(
-  name: "search_files",
-  parameters: {
-    query: "*.rb",
-    directory: "/path/to/search"
+# Authenticate to a protected MCP server with browser OAuth
+client = RubyLLM::MCP.client(
+  name: 'oauth-server',
+  transport_type: :streamable,
+  start: false,
+  config: {
+    url: 'https://mcp.example.com/mcp',
+    oauth: { scope: 'mcp:read mcp:write' }
   }
 )
 
-puts result
+client.oauth(type: :browser).authenticate
+client.start
 ```
 
-### Working with Resources
-
-MCP servers can provide access to resources - structured data that can be included in conversations. Resources come in two types: normal resources and resource templates.
-
-#### Normal Resources
-
 ```ruby
-# Get available resources from the MCP server
-resources = client.resources
-puts "Available resources:"
-resources.each do |resource|
-  puts "- #{resource.name}: #{resource.description}"
+# Poll a long-running MCP task and fetch its final result
+task = client.task_get('task-123')
+
+until task.completed? || task.failed? || task.cancelled?
+  sleep((task.poll_interval || 250) / 1000.0)
+  task = task.refresh
 end
 
-# Access a specific resource by name
-file_resource = client.resource("project_readme")
-content = file_resource.content
-puts "Resource content: #{content}"
+if task.completed?
+  payload = client.task_result(task.task_id)
+  puts payload.dig('content', 0, 'text')
+else
+  puts "Task ended with status: #{task.status}"
+end
+```
 
-# Include a resource in a chat conversation for reference with an LLM
-chat = RubyLLM.chat(model: "gpt-4")
-chat.with_resource(file_resource)
+## Support At A Glance
 
-# Or add a resource directly to the conversation
-file_resource.include(chat)
+- **Native MCP client implementation (`:ruby_llm`)** with full protocol support through `2025-11-25`
+- **Official MCP SDK adapter support (`:mcp_sdk`)** via the `mcp` gem for teams that prefer SDK-backed integration
+- **OAuth implementation** for authenticated streamable HTTP MCP servers
+- **Transports:** `stdio`, `sse`, `streamable` / `streamable_http`
+- **Core server features:** tools, resources, resource templates, prompts, notifications
+- **Advanced client features:** sampling, roots, progress tracking, human-in-the-loop, elicitation
+- **Task lifecycle APIs** (`tasks/list`, `tasks/get`, `tasks/result`, `tasks/cancel`) are experimental
 
-response = chat.ask("Can you summarize this README file?")
-puts response
-```
+> [!WARNING]
+> MCP task support is experimental and subject to change in both the MCP spec and this gem's implementation.
 
-#### Resource Templates
+## Install
 
-Resource templates are parameterized resources that can be dynamically configured:
+Add to your Gemfile:
 
 ```ruby
-# Get available resource templates
-templates = client.resource_templates
-log_template = client.resource_template("application_logs")
-
-# Use a template with parameters
-chat = RubyLLM.chat(model: "gpt-4")
-chat.with_resource_template(log_template, arguments: {
-  date: "2024-01-15",
-  level: "error"
-})
-
-response = chat.ask("What errors occurred on this date?")
-puts response
-
-# You can also get templated content directly
-content = log_template.to_content(arguments: {
-  date: "2024-01-15",
-  level: "error"
-})
-puts content
+gem 'ruby_llm-mcp'
 ```
 
-### Working with Prompts
-
-MCP servers can provide predefined prompts that can be used in conversations:
+Optional (for `:mcp_sdk` adapter):
 
 ```ruby
-# Get available prompts from the MCP server
-prompts = client.prompts
-puts "Available prompts:"
-prompts.each do |prompt|
-  puts "- #{prompt.name}: #{prompt.description}"
-  prompt.arguments.each do |arg|
-    puts "  - #{arg.name}: #{arg.description} (required: #{arg.required})"
-  end
-end
-
-# Use a prompt in a conversation
-greeting_prompt = client.prompt("daily_greeting")
-chat = RubyLLM.chat(model: "gpt-4")
-
-# Method 1: Ask prompt directly
-response = chat.ask_prompt(greeting_prompt, arguments: { name: "Alice", time: "morning" })
-puts response
-
-# Method 2: Add prompt to chat and then ask
-chat.with_prompt(greeting_prompt, arguments: { name: "Alice", time: "morning" })
-response = chat.ask("Continue with the greeting")
+gem 'mcp', '~> 0.7'
 ```
 
-## Development
-
-After checking out the repo, run `bundle` to install dependencies. Then, run `bundle exec rake` to run the tests. Tests currently use `bun` to run test MCP servers You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-There are also examples you you can run to verify the gem is working as expected.
+Then run:
 
 ```bash
-bundle exec ruby examples/tools/local_mcp.rb
+bundle install
 ```
 
+## Setup
+
+1. Set your RubyLLM provider credentials (for example `OPENAI_API_KEY`).
+2. Start or access an MCP server.
+3. Create a `RubyLLM::MCP.client` and attach its tools/resources/prompts to chat flows.
+
 ## Contributing
 
-We welcome contributions! Bug reports and pull requests are welcome on GitHub at https://github.com/patvice/ruby_llm-mcp.
+Bug reports and pull requests are welcome on [GitHub](https://github.com/patvice/ruby_llm-mcp).
 
 ## License
 

docs/client/elicitation.md

@@ -31,9 +31,9 @@ When elicitation is enabled, MCP servers can send "elicitation" requests to your
 This is useful for servers that need user input or clarification during complex workflows.
 
 {: .new }
-Elicitation is a new feature in MCP Protocol 2025-06-18.
+Elicitation was introduced in MCP Protocol 2025-06-18.
 
-**Note:** Elicitation is only available for clients that support the `2025-06-18` protocol version.
+**Note:** Elicitation is available for clients using protocol version `2025-06-18` or newer.
 
 ## Basic Elicitation Configuration