mcp_on_ruby 0.3.0 → 2.0.0

data/README.md

@@ -1,590 +1,436 @@
 <div align="center">
 
 # MCP on Ruby
-[![Gem Version](https://badge.fury.io/rb/mcp_on_ruby.svg)](https://badge.fury.io/rb/mcp_on_ruby)
-[![Build](https://github.com/nagstler/ruby_mcp/actions/workflows/build.yml/badge.svg)](https://github.com/nagstler/ruby_mcp/actions/workflows/build.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![RuboCop](https://github.com/nagstler/ruby_mcp/actions/workflows/rubocop.yml/badge.svg)](https://github.com/nagstler/ruby_mcp/actions/workflows/rubocop.yml)
-[![Test](https://github.com/nagstler/ruby_mcp/actions/workflows/test.yml/badge.svg)](https://github.com/nagstler/ruby_mcp/actions/workflows/test.yml)
-[![codecov](https://codecov.io/github/nagstler/ruby_mcp/graph/badge.svg?token=SG4EJEIHW3)](https://codecov.io/github/nagstler/ruby_mcp)
 
-<strong> **Turn your Rails APIs into an MCP server.**</strong> 
+**Make your Rails app usable by AI agents.**
+
+Your existing controllers become [Model Context Protocol](https://modelcontextprotocol.io) tools, running through<br>
+the same authentication, policies, params, and JSON you already ship.
+
+[![Gem Version](https://img.shields.io/gem/v/mcp_on_ruby)](https://rubygems.org/gems/mcp_on_ruby)
+[![CI](https://github.com/nagstler/mcp_on_ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/nagstler/mcp_on_ruby/actions/workflows/ci.yml)
+[![Ruby](https://img.shields.io/badge/ruby-3.2%2B-CC342D)](#compatibility)
+[![Rails](https://img.shields.io/badge/rails-7.1%20%E2%80%93%208.1-D30001)](#compatibility)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE.txt)
+
+[Quick start](#quick-start) ·
+[How it works](#how-it-works) ·
+[Guides](#guides) ·
+[Configuration](#configuration) ·
+[Testing](#testing)
 
 </div>
 
-## 🔍 Introduction
-The [Model Context Protocol](https://modelcontextprotocol.io) standardizes how applications interact with AI models, serving as the "REST for LLMs." **MCP on Ruby** brings this standard to the Ruby ecosystem. Create contexts, manage conversations, connect to multiple providers, and handle streaming responses with clean, Ruby code.
+---
 
-![System Component Flow (Horizontal)](https://github.com/user-attachments/assets/085ad9b8-bee0-4d60-a4b7-ecf02d07f53c)
+```ruby
+class OrdersController < ApplicationController
+  before_action :authenticate_user!
 
-> 📌 If you find this useful, **give it a ⭐ on GitHub**
+  mcp_tool :index, description: "Search the current user's orders",
+                   params: { status: { type: :string, enum: %w[pending paid shipped] } }
+  mcp_tool :show,  description: "Fetch one order by id"
 
-## 📋 Table of Contents
+  def index
+    render json: current_user.orders.where(params.permit(:status))
+  end
 
-- [🔍 Introduction](#-introduction)
-- [🌟 Why MCP on Ruby?](#-why-mcp-on-ruby)
-- [📦 Installation](#-installation)
-- [🚀 Quick Start](#-quick-start)
-  - [🎮 Interactive Demo](#-interactive-demo)
-- [⚙️ Configuration Options](#️-configuration-options)
-- [🛣️ Server Endpoints](#️-server-endpoints)
-- [📚 Detailed Usage](#-detailed-usage)
-  - [Creating a Context](#creating-a-context)
-  - [Adding a Message](#adding-a-message)
-  - [Generating a Response](#generating-a-response)
-  - [Streaming a Response](#streaming-a-response)
-  - [Uploading Content](#uploading-content)
-  - [Using Tool Calls](#using-tool-calls)
-- [🚄 Rails Integration](#-rails-integration)
-- [💾 Storage Backend](#-storage-backends)
-- [🔒 Authentication](#-authentication)
-- [🛠️ Development](#️-development)
-- [🗺️ Roadmap](#️-roadmap)
-- [👥 Contributing](#-contributing)
-- [📄 License](#-license)
+  def show
+    render json: current_user.orders.find(params[:id])
+  end
+end
+```
 
-## 🌟 Why MCP on Ruby?
+That's the whole integration. Claude, Cursor, or any MCP client can now search and read orders **as the signed-in user**. Your `before_action` authenticates the agent, your scopes and policies decide what it can see, and your existing JSON comes back to it. You don't write new tool classes or a second permission system.
 
-**MCP on Ruby** provides a comprehensive implementation of the Model Context Protocol with these features:
+## Why MCP on Ruby
 
-- **Provider-Ready:** Pre-built adapters for OpenAI and Anthropic - just add your API key
-- **Complete Protocol Implementation:** Fully implements the MCP specification for compatibility
-- **Conversation Management:** Context handling for multi-turn conversations
-- **Flexible Storage:** Extensible storage backends
-- **Streaming Support:** Real-time response streaming for dynamic UIs
-- **File Handling:** Upload and reference files in conversations
-- **Tool Calling:** Support for LLM function calling capabilities
-- **Battle-Tested:** Comprehensive test suite ensures reliability
+Most MCP libraries ask you to build a parallel API for agents: new tool classes, new argument parsing, new authorization checks. Over time that second API drifts from the real one, and every rule has to be secured twice.
 
-The library is designed to be straightforward to use while maintaining full compatibility with the MCP specification.
+MCP on Ruby takes the opposite approach. **Your app already has an API: your controllers.** MCP on Ruby makes it callable by agents.
 
-## 📦 Installation
+- **One source of truth.** Agents go through the same routes, filters, policies, validations, and serializers as your users.
+- **Real identity.** Every tool call runs as a real user, using the auth you already have: API tokens, Devise, or Warden.
+- **Safe by default.** Actions that change data must be marked `write: true`, and every tool tells the client whether it is read-only or destructive.
+- **Local and remote.** Serve Streamable HTTP in production, and stdio for Claude Code, Claude Desktop, and Cursor on your machine.
+- **Built on the official SDK.** The protocol layer is the official [`mcp`](https://github.com/modelcontextprotocol/ruby-sdk) gem, so protocol updates arrive without a rewrite.
+- **Works with the Rails you run today.** Rails 7.1 through 8.1 on Ruby 3.2+.
 
-Add this line to your application's Gemfile:
+## Quick start
 
-```ruby
-gem 'mcp_on_ruby'
+**1. Install**
+
+```bash
+bundle add mcp_on_ruby
+bin/rails generate mcp_on_ruby:install
 ```
 
-And then execute:
+The generator creates `config/initializers/mcp_on_ruby.rb` and mounts the endpoint:
 
-```
-$ bundle install
+```ruby
+# config/routes.rb
+mount McpOnRuby::Engine, at: "/mcp"
 ```
 
-Or install it yourself as:
+**2. Expose some actions**
 
+```bash
+bin/rails generate mcp_on_ruby:expose products index show create
 ```
-$ gem install mcp_on_ruby
+
+This adds `mcp_tool` declarations to `ProductsController`, with a params schema for `create` built from the model's columns. Edit the descriptions: they are what the agent reads. Then check what agents will see:
+
+```console
+$ bin/rails mcp:tools
+TOOL             ACTION                     VERB  PATH           ACCESS
+products_create  ProductsController#create  POST  /products      write
+products_index   ProductsController#index   GET   /products      read-only
+products_show    ProductsController#show    GET   /products/:id  read-only
 ```
 
-## 🚀 Quick Start
+**3. Connect an agent**
 
-Here's how to get a basic MCP server running:
+Over HTTP, sending a token your app already accepts:
 
-```ruby
-require 'ruby_mcp'
+```bash
+claude mcp add --transport http my-app http://localhost:3000/mcp \
+  --header "Authorization: Bearer $MY_APP_API_TOKEN"
+```
 
-# Configure RubyMCP
-RubyMCP.configure do |config|
-  config.providers = {
-    openai: { api_key: ENV['OPENAI_API_KEY'] },
-    anthropic: { api_key: ENV['ANTHROPIC_API_KEY'] }
-  }
-end
+Or locally over stdio, acting as a user you choose ([set up `stdio_user`](#authentication) first):
 
-# Start the MCP server
-server = RubyMCP::Server::Controller.new
-server.start
+```bash
+claude mcp add my-app -e MCP_USER=alice@example.com -- bin/rails mcp:stdio
 ```
 
-### 🎮 Interactive Demo
+Then ask: *"Which of my products cost more than $50?"*
 
-The repository includes an interactive demo that walks through all the key MCP concepts:
+## How it works
 
-```bash
-# Terminal 1: Start the server
-cd examples/simple_server
-ruby server.rb
-
-# Terminal 2: Run the client
-cd examples/simple_server
-ruby client.rb
-
-# ActiveRecord Storage Demo
-# Demonstrates database storage with SQLite
-cd examples/simple_server
-ruby activerecord_demo.rb
 ```
+ MCP client (Claude, Cursor, …)
+        │  Streamable HTTP (/mcp)   or   stdio (bin/rails mcp:stdio)
+        ▼
+ official mcp gem ──────── protocol, version negotiation, schema validation
+        │  tools/call  orders_index  { "status": "pending" }
+        ▼
+ MCP on Ruby
+   Registry    which controller actions are exposed, with their routes and schemas
+   Dispatcher  builds an in-process request:  GET /orders?status=pending
+   Identity    the caller's Authorization header and cookies, or the stdio user
+   Result      2xx JSON → structured result; 4xx/5xx → readable tool error
+        ▼
+ Your Rails app: middleware → routes → before_action → controller → render json
+```
+
+Each tool call becomes an ordinary request through your full middleware stack. Anything that protects your API, including `rate_limit`, Rack::Attack, tenant scoping, and audit logging, protects agent traffic too.
 
-This demo provides a guided tour of the MCP functionality, showing each step of creating contexts, adding messages, and generating responses with detailed explanations.
+HTTP is served statelessly: every request is self-contained, so any Puma worker or server behind your load balancer can handle any MCP request, with no sticky sessions.
 
-## ⚙️ Configuration Options
+## Guides
 
-RubyMCP offers several configuration options:
+### Declaring tools
 
 ```ruby
-RubyMCP.configure do |config|
-  # LLM Provider configurations
-  config.providers = {
-    openai: { 
-      api_key: ENV['OPENAI_API_KEY'],
-      api_base: 'https://api.openai.com/v1' # Optional
-    },
-    anthropic: { 
-      api_key: ENV['ANTHROPIC_API_KEY'] 
-    }
-  }
-  
-  # Storage backend
-  
-  # Option 1: Memory storage (default)
-  config.storage = :memory
-  
-  # Option 2: Redis storage
-  config.storage = :redis
-  config.redis = {
-    url: ENV.fetch('REDIS_URL', 'redis://localhost:6379/0'),
-    namespace: 'my_app_mcp',
-    ttl: 86400 # 1 day in seconds
+mcp_tool :index,
+  description: "Search products by name",  # required: what the agent reads
+  title: "Search products",                # optional display name
+  name: "search_products",                 # optional; defaults to "products_index"
+  params: {
+    q:     :string,                                                  # shorthand
+    sort:  { type: :string, enum: %w[name price], default: "name" },
+    limit: { type: :integer, minimum: 1, maximum: 100 }
   }
-  
-  # Option 3: ActiveRecord storage
-  config.storage = :active_record
-  config.active_record = {
-    # Connection settings (not needed in Rails)
-    connection: {
-      adapter: 'sqlite3',
-      database: 'db/mcp.sqlite3'
-    },
-    # Table prefix to avoid name collisions
-    table_prefix: 'mcp_'
-  }
-  
-  # Server settings
-  config.server_port = 3000
-  config.server_host = "0.0.0.0"
-  
-  # Authentication settings
-  config.auth_required = false
-  config.jwt_secret = ENV['JWT_SECRET']
-  config.token_expiry = 3600 # 1 hour
-  
-  # Limits
-  config.max_contexts = 1000
-end
 ```
 
-## 🛣️ Server Endpoints
+Path parameters such as `:id` in `/products/:id` are read from your routes and added to the schema as required parameters. You don't declare them.
 
-The MCP server provides the following RESTful endpoints:
+Use a block for nested input:
 
-### Engines
-- `GET /engines` - List available language models
+```ruby
+mcp_tool :create, description: "Place an order", write: true do
+  param :order, required: true do
+    param :sku,      type: :string,  required: true
+    param :quantity, type: :integer, minimum: 1
+    param :tags,     type: :array,   items: :string
+    param :note,     type: :string,  nullable: true
+  end
+end
+```
 
-### Contexts
-- `POST /contexts` - Create a new conversation context
-- `GET /contexts` - List existing contexts
-- `GET /contexts/:id` - Get details of a specific context
-- `DELETE /contexts/:id` - Delete a context
+Supported types: `:string`, `:integer`, `:number`, `:boolean`, `:array`, `:object`, `:null`, or an array of them. Options use Ruby names for JSON Schema keywords: `description`, `enum`, `default`, `format`, `pattern`, `minimum`, `maximum`, `min_length`, `max_length`, `min_items`, `max_items`, `unique_items`, and more. Unknown types and options raise immediately, so typos don't ship.
 
-### Messages
-- `POST /messages` - Add a message to a context
+The official SDK validates arguments against this schema before your controller runs. Arguments reach `params` exactly as they would from a JSON client, so strong params work unchanged. Read tools receive them as query parameters, write tools as a JSON body.
 
-### Generation
-- `POST /generate` - Generate a response from a language model
-- `POST /generate/stream` - Stream a response with incremental updates
+### Authentication
 
-### Content
-- `POST /content` - Upload content (files)
-- `GET /content/:context_id/:id` - Retrieve uploaded content
+MCP on Ruby never asks you to build a new auth system. It hands the caller's identity to the auth you already have.
 
-## 📚 Detailed Usage
+**Over HTTP**, the client's `Authorization` header and cookies are forwarded to your controller. If your app accepts API tokens, as most API apps and Devise token setups do, there is nothing to configure.
 
-### Creating a Context
+**Over stdio** there is no HTTP request, so you choose who local sessions act as:
 
 ```ruby
-# Using the HTTP API
-response = Faraday.post(
-  "http://localhost:3000/contexts",
-  {
-    messages: [
-      {
-        role: "system",
-        content: "You are a helpful assistant."
-      }
-    ],
-    metadata: {
-      user_id: "user_123",
-      conversation_name: "Technical Support"
-    }
-  }.to_json,
-  "Content-Type" => "application/json"
-)
+# config/initializers/mcp_on_ruby.rb
+McpOnRuby.configure do |config|
+  # Devise / Warden apps: sign in as a user for each tool call (nothing is stored in the session).
+  config.stdio_user = -> { User.find_by!(email: ENV.fetch("MCP_USER")) }
 
-context_id = JSON.parse(response.body)["id"]
+  # Token-authenticated apps: send headers your app already accepts.
+  config.stdio_headers = -> { { "Authorization" => "Bearer #{ENV.fetch("MCP_TOKEN")}" } }
+end
 ```
 
-### Adding a Message
+For Devise and Warden, the user is signed in with the `:user` scope (change it with `config.warden_scope`). Apps with custom authentication can read the stdio user with `mcp_user` in their own `before_action`.
 
-```ruby
-Faraday.post(
-  "http://localhost:3000/messages",
-  {
-    context_id: context_id,
-    role: "user",
-    content: "What is the capital of France?"
-  }.to_json,
-  "Content-Type" => "application/json"
-)
-```
+If authentication fails, the agent gets a clear "Not authenticated (401)" tool error and nothing runs.
 
-### Generating a Response
+### Authorization
 
-```ruby
-response = Faraday.post(
-  "http://localhost:3000/generate",
-  {
-    context_id: context_id,
-    engine_id: "anthropic/claude-3-sonnet-20240229",
-    max_tokens: 1000,
-    temperature: 0.7
-  }.to_json,
-  "Content-Type" => "application/json"
-)
-
-assistant_response = JSON.parse(response.body)["content"]
-```
+There is nothing new to learn, because tool calls run your controller code. `authorize`, `policy_scope`, `can?`, `current_user.orders.find`, and `head :forbidden` behave exactly as they do for any other client. A 403 reaches the agent as "Not permitted (403)".
 
-### Streaming a Response
+Inside a controller, `mcp_request?` tells you whether an agent is calling, and `mcp_tool_name` tells you which tool:
 
 ```ruby
-conn = Faraday.new do |f|
-  f.request :json
-  f.response :json
-  f.adapter :net_http
-end
-
-conn.post("http://localhost:3000/generate/stream") do |req|
-  req.headers["Content-Type"] = "application/json"
-  req.body = {
-    context_id: context_id,
-    engine_id: "openai/gpt-4",
-    temperature: 0.7
-  }.to_json
-  
-  req.options.on_data = Proc.new do |chunk, size, total|
-    event_data = chunk.split("data: ").last.strip
-    next if event_data.empty? || event_data == "[DONE]"
-    
-    event = JSON.parse(event_data)
-    if event["event"] == "generation.content" && event["content"]
-      print event["content"]
-    end
-  end
-end
+before_action :require_admin, if: :mcp_request?
 ```
 
-### Uploading Content
+### Safety
 
-```ruby
-file_data = Base64.strict_encode64(File.read("example.pdf"))
-
-Faraday.post(
-  "http://localhost:3000/content",
-  {
-    context_id: context_id,
-    type: "file",
-    filename: "example.pdf",
-    content_type: "application/pdf",
-    file_data: file_data
-  }.to_json,
-  "Content-Type" => "application/json"
-)
-```
+Agents act on behalf of real users, so the defaults are conservative:
 
-### Using Tool Calls
+- **Writes are explicit.** Declaring `mcp_tool` on an action routed with `POST`, `PUT`, `PATCH`, or `DELETE` without `write: true` raises `McpOnRuby::ConfigurationError`. This happens at boot in production and when running `bin/rails mcp:doctor`.
+- **Honest hints.** Every tool is annotated from its HTTP verb (`readOnlyHint`, `destructiveHint`, `idempotentHint`), so clients like Claude can ask before destructive calls. Override with `annotations:`.
+- **A kill switch.** `config.allow_writes = false` hides and refuses every write tool, for example on a read-only replica or a demo environment.
+- **No accidental exposure.** Only declared actions are reachable, and declarations without a route raise. `bin/rails mcp:tools` shows exactly what is exposed.
+- **No leaked internals.** Server errors reach the agent as a generic error. Details go to `Rails.error` and your logs.
+- **Browser protection.** The endpoint rejects requests from foreign browser origins. Requests dispatched by MCP skip Rails' CSRF token check, which is safe because only the dispatcher can mark a request as MCP. Regular requests to the same actions stay protected.
 
-```ruby
-tools = [
-  {
-    type: "function",
-    function: {
-      name: "get_weather",
-      description: "Get the current weather for a location",
-      parameters: {
-        type: "object",
-        properties: {
-          location: {
-            type: "string",
-            description: "City and state, e.g., San Francisco, CA"
-          }
-        },
-        required: ["location"]
-      }
-    }
-  }
-]
-
-response = Faraday.post(
-  "http://localhost:3000/generate",
-  {
-    context_id: context_id,
-    engine_id: "openai/gpt-4",
-    tools: tools
-  }.to_json,
-  "Content-Type" => "application/json"
-)
-
-if response.body["tool_calls"]
-  # Handle tool calls
-  tool_calls = response.body["tool_calls"]
-  # Process tool calls and add tool response message
-end
-```
+See [SECURITY.md](SECURITY.md) for the full threat model.
 
-## 🚄 Rails Integration
+### Results and errors
 
-For Rails applications, create an initializer at `config/initializers/ruby_mcp.rb`:
+| Your controller returns | The agent receives |
+|---|---|
+| `2xx` with JSON | `structuredContent` plus the JSON as text |
+| `2xx` with plain text | The text |
+| `204 No Content` | A short success message |
+| `401` / `403` / `404` | Tool error: not authenticated / not permitted / not found |
+| `422` with JSON | Tool error including your validation messages, so the agent can correct itself |
+| Other `4xx` | Tool error with the status, plus the body when it is JSON |
+| `3xx` | Tool error naming the redirect target (redirects are not followed) |
+| HTML | Tool error asking for JSON. Use `respond_to` with `format.json`. |
+| `5xx` or an exception | Generic tool error. Details are reported to `Rails.error`, never sent. |
+
+### Tools without a controller
+
+For logic that has no endpoint, add a tool class from the official SDK. It runs alongside your controller tools:
 
 ```ruby
-RubyMCP.configure do |config|
-  config.providers = {
-    openai: { api_key: ENV['OPENAI_API_KEY'] },
-    anthropic: { api_key: ENV['ANTHROPIC_API_KEY'] }
-  }
-  
-  # Use memory storage in development, consider persistent storage in production
-  if Rails.env.development? || Rails.env.test?
-    config.storage = :memory
-  else
-    # Use ActiveRecord for production (uses your Rails database)
-    config.storage = :active_record
-    config.active_record = {
-      table_prefix: "mcp_#{Rails.env}_"  # Environment-specific prefix
-    }
-  end
-  
-  # Enable authentication in production
-  if Rails.env.production?
-    config.auth_required = true
-    config.jwt_secret = ENV["JWT_SECRET"]
+class ReindexSearchTool < MCP::Tool
+  description "Rebuild the search index"
+
+  def self.call(server_context:)
+    SearchIndex.rebuild!
+    MCP::Tool::Response.new([{ type: "text", text: "Reindexed" }])
   end
 end
+
+McpOnRuby.configure { |config| config.tools = [ReindexSearchTool] }
 ```
 
-And mount the server in your `config/routes.rb` file:
+These tools bypass your controllers, so they also bypass your controller authentication. Use them for things that are safe for every caller.
+
+### Observability
+
+Every tool call emits `tool_call.mcp_on_ruby` through `ActiveSupport::Notifications`:
 
 ```ruby
-Rails.application.routes.draw do
-  # Mount RubyMCP at /api/mcp
-  mount_mcp_at = "/api/mcp"
-  
-  Rails.application.config.middleware.use Rack::Config do |env|
-    env["SCRIPT_NAME"] = mount_mcp_at if env["PATH_INFO"].start_with?(mount_mcp_at)
-  end
-  
-  mount RubyMCP::Server::App.new.rack_app, at: mount_mcp_at
-  
-  # Rest of your routes
-  # ...
+ActiveSupport::Notifications.subscribe("tool_call.mcp_on_ruby") do |event|
+  Rails.logger.info(
+    "MCP #{event.payload[:tool]} → #{event.payload[:status]} " \
+    "(#{event.payload[:transport]}, #{event.duration.round}ms)"
+  )
 end
 ```
 
-## 💾 Storage Backends
+Payload: `tool`, `controller`, `action`, `transport` (`:http` or `:stdio`), `status`, and `error`. Tool calls also show up in your normal request logs and APM traces as requests to the underlying routes.
 
-### Redis Storage
+### Connecting clients
 
-MCP on Ruby supports Redis as a persistent storage backend:
+<details>
+<summary><b>Claude Code</b></summary>
 
-1. Add the Redis gem to your Gemfile:
-   ```ruby
-   gem 'redis', '~> 5.0'
-   ```
-
-2. Configure Redis storage:
-   ```ruby
-   RubyMCP.configure do |config|
-     config.storage = :redis
-     config.redis = {
-       url: ENV.fetch('REDIS_URL', 'redis://localhost:6379/0'),
-       namespace: "app_mcp_#{Rails.env}",
-       ttl: 86400  # 1 day in seconds
-     }
-   end
-   ```
-
-3. Access the configured client:
-   ```ruby
-   client = RubyMCP.client
-   ```
+```bash
+# Remote or production
+claude mcp add --transport http my-app https://my-app.example.com/mcp \
+  --header "Authorization: Bearer $MY_APP_API_TOKEN"
 
-For detailed integration examples, see the [[Redis Storage](https://github.com/nagstler/mcp_on_ruby/wiki/Redis-Storage)] wiki page.
+# Local, over stdio (run from your app's directory)
+claude mcp add my-app -e MCP_USER=alice@example.com -- bin/rails mcp:stdio
+```
+</details>
 
-### ActiveRecord Storage
+<details>
+<summary><b>Claude Desktop</b></summary>
 
-For integration with Rails or any app needing database storage:
+Claude Desktop does not load your shell profile, so start Rails through a login shell to pick up rbenv, asdf, or chruby:
 
-```ruby
-# Add to Gemfile
-gem 'activerecord', '~> 6.1'
-gem 'sqlite3', '~> 1.4'  # or pg, mysql2, etc.
-
-# Configure RubyMCP
-RubyMCP.configure do |config|
-  config.storage = :active_record
-  config.active_record = {
-    # Connection (not needed in Rails)
-    connection: {
-      adapter: 'sqlite3',
-      database: 'db/mcp.sqlite3'
-    },
-    # Table prefix to avoid name collisions
-    table_prefix: 'mcp_'
+```json
+{
+  "mcpServers": {
+    "my-app": {
+      "command": "bash",
+      "args": ["-lc", "cd /path/to/my-app && bin/rails mcp:stdio"],
+      "env": { "MCP_USER": "alice@example.com" }
+    }
   }
-end
+}
 ```
+</details>
 
-In Rails applications, it uses your app's database connection automatically:
+<details>
+<summary><b>Cursor</b></summary>
 
-```ruby
-# config/initializers/ruby_mcp.rb
-RubyMCP.configure do |config|
-  config.storage = :active_record
-  config.active_record = {
-    table_prefix: "mcp_#{Rails.env}_"  # Environment-specific prefix
+`.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-app": {
+      "url": "http://localhost:3000/mcp",
+      "headers": { "Authorization": "Bearer YOUR_API_TOKEN" }
+    }
   }
-end
+}
 ```
+</details>
 
-The ActiveRecord adapter automatically creates the necessary tables with appropriate indexes, and handles different types of data (text, binary, JSON) appropriately.
-
-### Custom storage 
-You can implement custom storage backends by extending the base storage class:
+<details>
+<summary><b>MCP Inspector</b></summary>
 
-```ruby
-class RedisStorage < RubyMCP::Storage::Base
-  def initialize(options = {})
-    super
-    @redis = Redis.new(options)
-  end
-  
-  def create_context(context)
-    @redis.set("context:#{context.id}", JSON.dump(context.to_h))
-    context
-  end
-  
-  def get_context(context_id)
-    data = @redis.get("context:#{context_id}")
-    raise RubyMCP::Errors::ContextError, "Context not found: #{context_id}" unless data
-    
-    hash = JSON.parse(data, symbolize_names: true)
-    
-    # Create message objects
-    messages = hash[:messages].map do |msg|
-      RubyMCP::Models::Message.new(
-        role: msg[:role],
-        content: msg[:content],
-        id: msg[:id],
-        metadata: msg[:metadata]
-      )
-    end
-    
-    # Create the context
-    RubyMCP::Models::Context.new(
-      id: hash[:id],
-      messages: messages,
-      metadata: hash[:metadata]
-    )
-  end
-  
-  # Implement other required methods...
-end
+```bash
+# Browse and call tools in the browser
+npx @modelcontextprotocol/inspector bin/rails mcp:stdio
 
-# Configure RubyMCP to use your custom storage
-RubyMCP.configure do |config|
-  config.storage = RedisStorage.new(url: ENV["REDIS_URL"])
-end
+# Or from the command line
+npx @modelcontextprotocol/inspector --cli http://localhost:3000/mcp --transport http \
+  --header "Authorization: Bearer $MY_APP_API_TOKEN" --method tools/list
 ```
+</details>
 
-## 🔒 Authentication
+<details>
+<summary><b>MCP registries and gateways</b></summary>
 
-To enable JWT authentication:
+Register your `/mcp` endpoint with an MCP-compatible registry or gateway when you want discovery, access control, audit trails, and approvals managed centrally. Rails still owns the tools and enforces your app's own authorization on every call.
+</details>
+
+## Testing
+
+Test tools the way agents call them: through the MCP server and your real controllers.
 
 ```ruby
-RubyMCP.configure do |config|
-  config.auth_required = true
-  config.jwt_secret = ENV['JWT_SECRET']
-  config.token_expiry = 3600 # 1 hour
+# spec/rails_helper.rb
+require "mcp_on_ruby/rspec"
+
+# test/test_helper.rb
+class ActiveSupport::TestCase
+  include McpOnRuby::TestHelper
 end
 ```
 
-Then, create and use JWT tokens:
-
 ```ruby
-# Generate a token
-require 'jwt'
+it "shows agents only their own orders" do
+  result = mcp_call :orders_index, { status: "pending" }, headers: { "Authorization" => "Bearer #{alice.api_token}" }
 
-payload = {
-  sub: "user_123",
-  exp: Time.now.to_i + 3600
-}
+  expect(result).to be_success
+  expect(result.structured.pluck("id")).to eq([alice_order.id])
+end
 
-token = JWT.encode(payload, ENV['JWT_SECRET'], 'HS256')
+it "stops agents from reading other users' orders" do
+  result = mcp_call :orders_show, { id: bob_order.id }, as: alice   # signs in through Devise/Warden
 
-# Use the token in requests
-conn = Faraday.new do |f|
-  f.request :json
-  f.response :json
-  f.adapter :net_http
+  expect(result).to be_error
+  expect(result.status).to eq(404)
 end
+```
+
+`mcp_call` returns a result with `success?`, `error?`, `structured` (the parsed JSON), `status` (for failures), `text` (what the agent reads), and `protocol_error` (unknown tool, invalid arguments). `mcp_tools` lists the tool names an agent sees.
+
+## Configuration
 
-conn.get("http://localhost:3000/contexts") do |req|
-  req.headers["Authorization"] = "Bearer #{token}"
+```ruby
+# config/initializers/mcp_on_ruby.rb
+McpOnRuby.configure do |config|
+  config.server_name  = "my-app"
+  config.instructions = "Tools for managing orders in My App. Amounts are in cents."
+  config.stdio_user   = -> { User.find_by!(email: ENV.fetch("MCP_USER")) }
 end
 ```
 
-## 🛠️ Development
+| Option | Default | Description |
+|---|---|---|
+| `server_name` | app name, dasherized | Name reported to clients |
+| `server_version` | `nil` | Version reported to clients |
+| `instructions` | `nil` | Guidance sent to the agent when it connects |
+| `stdio_user` | `nil` | Callable returning the user `mcp:stdio` sessions sign in as (Devise/Warden) |
+| `stdio_headers` | `nil` | Callable returning headers `mcp:stdio` sessions send (token auth) |
+| `warden_scope` | `:user` | Warden scope used for `stdio_user` and `mcp_call(as:)` |
+| `allow_writes` | `true` | Set `false` to hide and refuse every `write: true` tool |
+| `tools` | `[]` | Extra `MCP::Tool` classes served alongside controller tools |
+| `allowed_origins` | `[]` | Browser origins allowed to call the endpoint, in addition to same-origin |
+| `max_request_bytes` | 4 MiB | Largest MCP request body accepted |
+| `tool_name` | `"<controller>_<action>"` | Callable `(controller_path, action)` returning default tool names |
 
-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.
+### Commands
 
-### Running Tests
+| Command | What it does |
+|---|---|
+| `bin/rails g mcp_on_ruby:install [--path=/mcp]` | Adds the initializer and mounts the endpoint |
+| `bin/rails g mcp_on_ruby:expose CONTROLLER ACTION...` | Adds `mcp_tool` declarations to a controller |
+| `bin/rails mcp:tools` | Lists exposed tools, their routes, and their access level |
+| `bin/rails mcp:stdio` | Serves your tools over stdio for local agents |
+| `bin/rails mcp:doctor` | Checks the mount, declarations, and stdio identity; exits non-zero on errors |
 
-```
-bundle exec rspec
-```
+## Compatibility
 
-### Local Development Server
+| | Supported |
+|---|---|
+| Ruby | 3.2, 3.3, 3.4 |
+| Rails | 7.1, 7.2, 8.0, 8.1 |
+| MCP protocol | Every version the official `mcp` gem supports, negotiated per client |
+| Transports | Streamable HTTP (stateless), stdio |
+| Controllers | `ActionController::Base` and `ActionController::API` |
 
-```
-bundle exec ruby examples/simple_server/server.rb
-```
+CI runs the full suite on every supported Ruby and Rails combination.
+
+## When to use something else
 
-## 🗺️ Roadmap
+MCP on Ruby is for exposing an **existing Rails app** to agents. Other tools fit other jobs:
 
-While RubyMCP is functional for basic use cases, there are several areas planned for improvement:
+- **[`mcp`](https://github.com/modelcontextprotocol/ruby-sdk)**, the official Ruby SDK, if you're building a standalone MCP server. MCP on Ruby runs on top of it.
+- **[ActionMCP](https://github.com/seuros/action_mcp)** if you're on Rails 8.1+ and prefer dedicated tool, prompt, and resource classes with a full MCP feature set.
+- **[Tidewave](https://tidewave.ai)** if you want coding agents to understand your codebase while you develop. MCP on Ruby is about your app's *runtime* behavior for your *users*.
 
-- [x] Redis persistent storage backend
-- [x] ActiveRecord storage backend
-- [ ] Complete test coverage, including integration tests
-- [ ] Improved error handling and recovery strategies
-- [ ] Rate limiting for provider APIs
-- [ ] Proper tokenization for context window management
-- [ ] More robust streaming implementation
-- [ ] Additional provider integrations
+## Contributing
 
-:heart: Contributions in any of these areas are welcome!
+Bug reports, ideas, and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+```bash
+git clone https://github.com/nagstler/mcp_on_ruby && cd mcp_on_ruby
+bin/setup
+bundle exec rake                          # specs + RuboCop
+RAILS_VERSION=7.2 bundle update && bundle exec rspec   # another Rails series
+```
 
-## 👥 Contributing
+Release notes are in [CHANGELOG.md](CHANGELOG.md).
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin feature/my-new-feature`)
-5. Create a new Pull Request
+## License
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/nagstler/mcp_on_ruby.
+Released under the [MIT License](LICENSE.txt).
 
-## 📄 License
+## Acknowledgments
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+- The [Model Context Protocol](https://modelcontextprotocol.io) team for the specification.
+- The maintainers of the official [Ruby SDK](https://github.com/modelcontextprotocol/ruby-sdk), on whose work this gem is built.
+- The Rails community, whose conventions this gem tries hard not to break.