Phase 5: Implement Authentication & Security

- Add OAuth 2.1 authentication for secure connections
- Implement JWT token validation and management
- Create permission-based method access control
- Add automatic token refresh capabilities
- Update HTTP transport with authentication integration
- Create HTTP server with authentication middleware
- Add examples for authenticated MCP servers and clients
- Update documentation to reflect authentication features
- Bump version to 0.2.0 for authentication release

Author: nagstler

CHANGELOG.md

@@ -13,17 +13,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Server implementation with tools, resources, prompts, and roots
 - Client implementation for connecting to MCP servers
 - HTTP and STDIO transport options
-- OAuth 2.1 authentication for remote connections
 - Comprehensive test suite
 - Detailed documentation
 
-## [0.2.0] - 2024-xx-xx
+## [0.2.0] - 2024-07-24
 
 ### Added
-- Redis storage backend for conversation persistence
-- Improved error handling and reporting
+- OAuth 2.1 authentication for secure remote connections
+- Permission-based access control for MCP methods
+- JWT token validation and management
+- Automatic token refresh mechanism
+- HTTP transport authentication integration
+- Middleware architecture for server authentication
+- Authentication examples and documentation
 
-## [0.1.0] - 2024-xx-xx
+## [0.1.0] - 2024-06-15
 
 ### Added
-- Initial release with basic REST API functionality
+- Initial implementation of core MCP protocol
+- JSON-RPC 2.0 message format
+- HTTP and STDIO transports
+- Basic server and client functionality
+- Tool definition and execution
+- Resource management
+- Prompt handling
+- Root filesystem access

README.md

@@ -72,6 +72,44 @@ end
 server.start
 ```
 
+### Authenticated Server
+
+Create a server with OAuth 2.1 authentication:
+
+```ruby
+require 'mcp_on_ruby'
+
+# Create the OAuth provider
+oauth_provider = MCP::Server::Auth::OAuth.new(
+  client_id: 'your-client-id',
+  client_secret: 'your-client-secret',
+  token_expiry: 3600,
+  jwt_secret: 'your-jwt-secret',
+  issuer: 'your-server'
+)
+
+# Create the permissions manager
+permissions = MCP::Server::Auth::Permissions.new
+permissions.add_method('tools/list', ['tools:read'])
+permissions.add_method('tools/call', ['tools:call'])
+
+# Create server with authentication
+server = MCP::Server.new
+server.set_auth_provider(oauth_provider, permissions)
+
+# Define tools
+server.tools.define('example') do
+  parameter :name, :string
+  
+  execute do |params|
+    "Hello, #{params[:name]}!"
+  end
+end
+
+# Start the server
+server.start
+```
+
 ## Quick Start: Client
 
 Connect to an MCP server and use its tools:
@@ -86,21 +124,53 @@ client = MCP::Client.new(url: "http://localhost:3000")
 client.connect
 
 # List available tools
-tools = client.list_tools
+tools = client.tools.list
 puts tools
 
 # Call a tool
-result = client.call_tool("weather.get_forecast", location: "San Francisco")
+result = client.tools.call("weather.get_forecast", { location: "San Francisco" })
 puts result.inspect
 
 # Get a resource
-profile = client.get_resource("user.profile")
+profile = client.resources.get("user.profile")
 puts profile.inspect
 
 # Disconnect
 client.disconnect
 ```
 
+### Authenticated Client
+
+Connect to an authenticated MCP server:
+
+```ruby
+require 'mcp_on_ruby'
+
+# Create the client
+client = MCP::Client.new(url: "http://localhost:3000/mcp")
+
+# Set up OAuth credentials
+client.set_oauth_credentials(
+  client_id: 'your-client-id',
+  client_secret: 'your-client-secret',
+  site: 'http://localhost:3000',
+  authorize_url: '/oauth/authorize',
+  token_url: '/oauth/token',
+  scopes: ['tools:read', 'tools:call'],
+  auto_refresh: true
+)
+
+# Exchange authorization code for token (after user authorization)
+token = client.exchange_code('authorization_code')
+
+# Or set token directly
+client.set_access_token('your-access-token')
+
+# Connect and use tools with authentication
+client.connect
+results = client.tools.call('example', { name: 'World' })
+```
+
 ## MCP Implementation
 
 This library is an implementation of the Model Context Protocol specification:
@@ -132,20 +202,47 @@ This library is an implementation of the Model Context Protocol specification:
 MCP on Ruby follows the MCP specification's architecture:
 
 1. **Protocol Layer**: JSON-RPC 2.0 communication over multiple transports
-2. **Server**: Exposes tools, resources, and prompts to clients
+2. **Server**: Exposes tools, resources, prompts, and roots to clients
 3. **Client**: Connects to servers and uses their capabilities
 4. **Authentication**: OAuth 2.1 for secure remote connections
 
+## Security Features
+
+### OAuth 2.1 Authentication
+
+MCP on Ruby supports secure authentication with OAuth 2.1:
+
+- **Token-based Authentication**: Industry-standard OAuth 2.1 flow
+- **JWT Implementation**: Secure token validation and management
+- **Automatic Token Refresh**: Seamless handling of token expiration
+- **Scope-based Authorization**: Fine-grained access control for MCP methods
+
+### Permission Management
+
+- **Method-level Permissions**: Control access to individual MCP methods
+- **Scope Requirements**: Define required scopes for each method
+- **Integration with OAuth**: Leverage OAuth scopes for authorization decisions
+- **Middleware Architecture**: Apply permissions consistently across all requests
+
 ## Advanced Usage
 
 See the [wiki](https://github.com/nagstler/mcp_on_ruby/wiki) for advanced usage, including:
 
 - Creating complex tool hierarchies
-- Implementing custom authentication
+- Implementing custom OAuth providers
+- Configuring method-level permissions
+- Token management and refresh strategies
 - Streaming responses
 - Working with resources and prompts
 - File system integration with roots
 
+Check out the `/examples` directory for complete working examples:
+
+- **Simple Server** - Basic MCP server implementation
+- **Authentication** - OAuth 2.1 integration example
+- **Rails Integration** - Using MCP with Rails
+- **Streaming** - Real-time bidirectional communication
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

examples/auth_server/README.md

@@ -0,0 +1,74 @@
+# Authenticated MCP Server Example
+
+This example demonstrates how to create an MCP server with OAuth 2.1 authentication and permission scopes.
+
+## Components
+
+The example consists of three main components:
+
+1. **OAuth Server** - A simple OAuth 2.1 server implementation for testing purposes
+2. **MCP Server** - An MCP server with authentication enabled
+3. **MCP Client** - A client that connects to the MCP server with authentication
+
+## Setting Up
+
+You'll need to run each component in a separate terminal.
+
+### 1. Start the OAuth Server
+
+```bash
+ruby oauth_server.rb
+```
+
+This will start a simple OAuth server on port 3001.
+
+### 2. Start the MCP Server
+
+```bash
+ruby server.rb
+```
+
+This will start an MCP server on port 3000. The server is configured with OAuth authentication and permission scopes.
+
+### 3. Run the Client
+
+```bash
+ruby client.rb
+```
+
+The client will:
+1. Connect to the MCP server with authentication
+2. List available tools
+3. Call the "hello" tool
+
+## Understanding the Authentication Flow
+
+In a real application, the OAuth flow would typically involve:
+
+1. The client redirecting the user to the authorization server
+2. The user granting permission
+3. The authorization server redirecting back to the client with an authorization code
+4. The client exchanging the code for an access token
+5. The client using the access token to access the API
+
+For simplicity, this example bypasses this flow and creates a token directly. 
+
+## Permission Scopes
+
+The server is configured with the following permission scopes:
+
+- `tools:read` - Required to list tools
+- `tools:call` - Required to call tools
+- `resources:read` - Required to list resources
+- `resources:call` - Required to call resources
+
+The client requests the `tools:read` and `tools:call` scopes, which allows it to list and call tools, but not work with resources.
+
+## How Authentication is Integrated
+
+1. **HTTP Transport** - Adds Authentication headers to requests
+2. **Server Middleware** - Validates tokens and checks permissions
+3. **Client Authentication** - Manages token lifecycle (acquisition, refresh, etc.)
+4. **Permission Manager** - Maps MCP methods to required scopes
+
+This architecture follows the principles of OAuth 2.1 and integrates with the MCP protocol's JSON-RPC 2.0 message format.

examples/auth_server/client.rb

@@ -0,0 +1,65 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'ruby_mcp'
+require 'logger'
+
+# Create a logger
+logger = Logger.new(STDOUT)
+logger.level = Logger::INFO
+
+# Create the client
+client = MCP::Client::Client.new(
+  url: 'http://localhost:3000/mcp',
+  logger: logger
+)
+
+# Set up OAuth credentials for the client authorization code flow
+client.set_oauth_credentials(
+  client_id: 'example-client',
+  client_secret: 'example-secret',
+  site: 'http://localhost:3000',
+  authorize_url: '/oauth/authorize',
+  token_url: '/oauth/token',
+  redirect_uri: 'http://localhost:8000/callback',
+  scopes: ['tools:read', 'tools:call'],
+  auto_refresh: true
+)
+
+# Generate an auth URL
+state = SecureRandom.hex(8)
+auth_url = client.authorization_url(state)
+puts "Visit this URL to authorize the client: #{auth_url}"
+
+# For this example, we'll bypass the authorization flow and directly set a token
+# In a real application, you would need to implement the full OAuth flow
+puts "Since this is an example, we'll create a token directly:"
+
+# Create a sample token (this would normally come from the OAuth authorization flow)
+token = OAuth2::AccessToken.new(
+  OAuth2::Client.new('example-client', 'example-secret'),
+  'example_access_token',
+  refresh_token: 'example_refresh_token',
+  expires_at: Time.now.to_i + 3600,
+  params: { 'scope' => 'tools:read tools:call' }
+)
+
+# Set the access token directly
+client.set_access_token(token)
+puts "Token set: #{token.token}"
+
+# Connect to the server
+begin
+  client.connect
+  puts "Connected to server: #{client.server_info[:name]}"
+  
+  # List available tools
+  tools = client.tools.list
+  puts "Available tools: #{tools.map { |t| t[:name] }.join(', ')}"
+  
+  # Call the hello tool
+  result = client.tools.call('hello', { name: 'Ruby MCP Client' })
+  puts "Result: #{result}"
+rescue => e
+  puts "Error: #{e.message}"
+end