active_mcp 0.3.4 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c67705b1452f86930b120080e883a10cdb4d231bf2a8a533621adb55b3099c6
-  data.tar.gz: 62d30c1eba1c08c25b6c0e8a74337e3c735a3d14fe85c8f81a19505a0db248cd
+  metadata.gz: 36a188cb2b45d872122cddac68b6d7ce052c432d11e36dab471b0b050b86cecc
+  data.tar.gz: 1704a7bb34a996d3168a419bc425147eccc941d1f9c4b11f14abc38c3632e41a
 SHA512:
-  metadata.gz: ce288f544ec46e5a5c44da9651c344fa985e17b730dbd463230cb86143f1bb8ddd2992c64219ee3eacb9dc3264820ae1b92d4c751938dd01dcac5ac3b2a6d2e0
-  data.tar.gz: 9709e2ce17bbe2f86fd3e15a3ecee1748a7708b69b5ecf79843cd94a342fabb1009563d2651d0d8377f0335c663e9d9e26b3017587d33d1fdb3ab7e580577aca
+  metadata.gz: '0380f2010e79b71a2beb552448129eebe646895fb2af2c35490d093b93714e45453da3403f6c1a85b3bd3ea8df84ab4fff6d6d21ba38dc7f94c7b14340d789bf'
+  data.tar.gz: 758c49617295edeba4231a8b80cf64758739b14e722b23a3904695c29d0b4ff1e3a003d195e589c69a6b933019bf4f2a27ed847dc831ad4fcdf2bdf7ef65b7b8

data/README.md

@@ -1,8 +1,54 @@
-# Active MCP
-
-A Ruby on Rails engine that provides [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) capabilities to Rails applications. This gem allows you to easily create and expose MCP-compatible tools from your Rails application.
-
-## Installation
+# Active MCP 🔌
+
+<div align="center">
+
+[![Gem Version](https://badge.fury.io/rb/active_mcp.svg)](https://badge.fury.io/rb/active_mcp)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Rails](https://img.shields.io/badge/Rails-%3E%3D%206.0.0-red.svg)](https://rubyonrails.org/)
+
+A Ruby on Rails engine for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) - connect your Rails apps to AI tools with minimal effort.
+</div>
+
+## 📖 Table of Contents
+
+- [Active MCP 🔌](#active-mcp-)
+  - [📖 Table of Contents](#-table-of-contents)
+  - [✨ Features](#-features)
+  - [📦 Installation](#-installation)
+  - [🚀 Setup](#-setup)
+    - [Using the Install Generator (Recommended)](#using-the-install-generator-recommended)
+    - [Manual Setup](#manual-setup)
+  - [🔌 MCP Connection Methods](#-mcp-connection-methods)
+    - [1. Direct HTTP Connection](#1-direct-http-connection)
+    - [2. Standalone MCP Server](#2-standalone-mcp-server)
+  - [🛠 Rails Generators](#-rails-generators)
+    - [Install Generator](#install-generator)
+    - [Tool Generator](#tool-generator)
+  - [🧰 Creating MCP Tools](#-creating-mcp-tools)
+  - [📋 Input Schema](#-input-schema)
+  - [🔐 Authorization \& Authentication](#-authorization--authentication)
+    - [Authorization for Tools](#authorization-for-tools)
+    - [Authentication Options](#authentication-options)
+      - [1. Server Configuration](#1-server-configuration)
+      - [2. Token Verification in Tools](#2-token-verification-in-tools)
+  - [⚙️ Advanced Configuration](#️-advanced-configuration)
+    - [Custom Controller](#custom-controller)
+  - [💡 Best Practices](#-best-practices)
+    - [1. Create Specific Tool Classes](#1-create-specific-tool-classes)
+    - [2. Validate and Sanitize Inputs](#2-validate-and-sanitize-inputs)
+    - [3. Return Structured Responses](#3-return-structured-responses)
+  - [🧪 Development](#-development)
+  - [👥 Contributing](#-contributing)
+  - [📄 License](#-license)
+
+## ✨ Features
+
+- **Simple Integration**: Easily expose Rails functionality as MCP tools
+- **Powerful Generators**: Quickly scaffold MCP tools with Rails generators
+- **Authentication Support**: Built-in authentication and authorization capabilities
+- **Flexible Configuration**: Multiple deployment and connection options
+
+## 📦 Installation
 
 Add this line to your application's Gemfile:
 
@@ -22,7 +68,7 @@ Or install it yourself as:
 $ gem install active_mcp
 ```
 
-## Setup
+## 🚀 Setup
 
 ### Using the Install Generator (Recommended)
 
@@ -36,6 +82,8 @@ This generator will:
 
 1. Create a configuration initializer at `config/initializers/active_mcp.rb`
 2. Mount the ActiveMcp engine in your routes
+3. Create an MCP server script at `script/mcp_server.rb`
+4. Show instructions for next steps
 
 After running the generator, follow the displayed instructions to create and configure your MCP tools.
 
@@ -57,50 +105,58 @@ end
 
 ```ruby
 class CreateNoteTool < ActiveMcp::Tool
-  description "Create Note!!"
+  description "Create Note"
 
-  argument :title, :string
-  argument :content, :string
+  argument :title, :string, required: true
+  argument :content, :string, required: true
 
   def call(title:, content:)
-    Note.create(title:, content:)
+    note = Note.create(title: title, content: content)
 
-    "Created!"
+    "Created note with ID: #{note.id}"
   end
 end
 ```
 
-#### with streamable HTTP
+## 🔌 MCP Connection Methods
+
+Active MCP supports two connection methods:
 
-Set MCP destination to `https:your-app.example.com/mcp`
+### 1. Direct HTTP Connection
+
+Set your MCP client to connect directly to your Rails application:
+
+```
+https://your-app.example.com/mcp
+```
 
-#### with independent MCP Server
+### 2. Standalone MCP Server
 
-Start the MCP server:
+Start a dedicated MCP server that communicates with your Rails app:
 
 ```ruby
-# server.rb
+# script/mcp_server.rb
 server = ActiveMcp::Server.new(
-  name: "ActiveMcp DEMO",
+  name: "My App MCP Server",
   uri: 'https://your-app.example.com/mcp'
 )
 server.start
 ```
 
-Set up MCP Client
+Then configure your MCP client:
 
 ```json
 {
   "mcpServers": {
-    "active-mcp-demo": {
+    "my-rails-app": {
       "command": "/path/to/ruby",
-      "args": ["/path/to/server.rb"]
+      "args": ["/path/to/script/mcp_server.rb"]
     }
   }
 }
 ```
 
-## Rails Generators
+## 🛠 Rails Generators
 
 Active MCP provides generators to help you quickly set up and extend your MCP integration:
 
@@ -112,39 +168,46 @@ Initialize Active MCP in your Rails application:
 $ rails generate active_mcp:install
 ```
 
-This sets up all necessary configuration files and mounts the MCP engine in your routes.
-
 ### Tool Generator
 
 Create new MCP tools quickly:
 
 ```bash
-# Generate a new MCP tool
 $ rails generate active_mcp:tool search_users
 ```
 
-This creates a new tool file at `app/tools/search_users_tool.rb` with the following starter code:
+This creates a new tool file at `app/tools/search_users_tool.rb` with ready-to-customize starter code.
+
+## 🧰 Creating MCP Tools
+
+MCP tools are Ruby classes that inherit from `ActiveMcp::Tool` and define an interface for AI to interact with your application:
 
 ```ruby
 class SearchUsersTool < ActiveMcp::Tool
-  description 'Search users'
+  description 'Search users by criteria'
 
-  argument :param1, :string, required: true, description: 'First parameter description'
-  argument :param2, :string, required: false, description: 'Second parameter description'
-  # Add more parameters as needed
+  argument :email, :string, required: false, description: 'Email to search for'
+  argument :name, :string, required: false, description: 'Name to search for'
+  argument :limit, :integer, required: false, description: 'Maximum number of records to return'
 
-  def call(param1:, param2: nil, auth_info: nil, **args)
-    # auth_info = { type: :bearer, token: 'xxx', header: 'Bearer xxx' }
+  def call(email: nil, name: nil, limit: 10)
+    criteria = {}
+    criteria[:email] = email if email.present?
+    criteria[:name] = name if name.present?
 
-    # Implement your tool logic here
-    "Tool executed successfully with #{param1}"
+    users = User.where(criteria).limit(limit)
+
+    {
+      type: "text",
+      content: users.to_json(only: [:id, :name, :email, :created_at])
+    }
   end
 end
 ```
 
-You can then customize the generated tool to fit your needs.
+## 📋 Input Schema
 
-## Input Schema
+Define arguments for your tools using the `argument` method:
 
 ```ruby
 argument :name, :string, required: true, description: 'User name'
@@ -153,45 +216,35 @@ argument :addresses, :array, required: false, description: 'User addresses'
 argument :preferences, :object, required: false, description: 'User preferences'
 ```
 
-Supported types include:
-
-- `:string`
-- `:integer`
-- `:number` (float/decimal)
-- `:boolean`
-- `:array`
-- `:object` (hash/dictionary)
-- `:null`
-
-## Using with MCP Clients
+Supported types:
 
-Any MCP-compatible client can connect to your server. The most common way is to provide the MCP server URL:
-
-```
-http://your-app.example.com/mcp
-```
+| Type | Description |
+| --- | --- |
+| `:string` | Text values |
+| `:integer` | Whole numbers |
+| `:number` | Decimal numbers (float/decimal) |
+| `:boolean` | True/false values |
+| `:array` | Lists of values |
+| `:object` | Hash/dictionary structures |
+| `:null` | Null values |
 
-Clients will discover the available tools and their input schemas automatically through the MCP protocol.
-
-## Authorization & Authentication
-
-ActiveMcp supports both authentication (verifying who a user is) and authorization (controlling what resources they can access).
+## 🔐 Authorization & Authentication
 
 ### Authorization for Tools
 
-You can control which tools are visible and accessible to different users by overriding the `visible?` class method:
+Control access to tools by overriding the `visible?` class method:
 
 ```ruby
 class AdminOnlyTool < ActiveMcp::Tool
-  description "This tool is only accessible by admins"
+  description "Admin-only tool"
 
-  argument :command, :string, required: true, description: "Admin command to execute"
+  argument :command, :string, required: true, description: "Admin command"
 
-  # Define authorization logic - only admin tokens can access this tool
+  # Only allow admins to access this tool
   def self.visible?(auth_info)
     return false unless auth_info
     return false unless auth_info[:type] == :bearer
-
+    
     # Check if the token belongs to an admin
     auth_info[:token] == "admin-token" || User.find_by_token(auth_info[:token])&.admin?
   end
@@ -202,125 +255,56 @@ class AdminOnlyTool < ActiveMcp::Tool
 end
 ```
 
-When a user makes a request to the MCP server:
-
-1. Only tools that return `true` from their `authorized?` method will be included in the tools list
-2. Users can only call tools that they're authorized to use
-3. Unauthorized access attempts will return a 403 Forbidden response
-
-This makes it easy to create role-based access control for your MCP tools.
+### Authentication Options
 
-### Authentication Flow
-
-ActiveMcp supports receiving authentication credentials from MCP clients and forwarding them to your Rails application. There are two ways to handle authentication:
-
-### 1. Using Server Configuration
-
-When creating your MCP server, you can pass authentication options that will be included in every request:
+#### 1. Server Configuration
 
 ```ruby
 server = ActiveMcp::Server.new(
-  name: "ActiveMcp DEMO",
+  name: "My Secure MCP Server",
   uri: 'http://localhost:3000/mcp',
   auth: {
-    type: :bearer, # or :basic
-    token: ENV[:ACCESS_TOKEN]
+    type: :bearer,
+    token: ENV['MCP_AUTH_TOKEN']
   }
 )
 server.start
 ```
 
-### 2. Custom Controller with Auth Handling
-
-For more advanced authentication, create a custom controller that handles the authentication flow:
+#### 2. Token Verification in Tools
 
 ```ruby
-class CustomController < ActiveMcpController
-  before_action :authenticate
-
-  private
-
-  def authenticate
-    # Extract auth from MCP request
-    auth_header = request.headers['Authorization']
-
-    if auth_header.present?
-      # Process the auth header (Bearer token, etc.)
-      token = auth_header.split(' ').last
-
-      # Validate the token against your auth system
-      user = User.find_by_token(token)
-
-      unless user
-        render_error(-32600, "Authentication failed")
-        return false
-      end
-
-      # Set current user for tool access
-      Current.user = user
-    else
-      render_error(-32600, "Authentication required")
-      return false
-    end
+def call(resource_id:, auth_info: nil, **args)
+  # Check if authentication is provided
+  unless auth_info.present?
+    raise "Authentication required"
   end
-end
-```
-
-### 3. Using Auth in Tools
-
-Authentication information is automatically passed to your tools through the `auth_info` parameter:
-
-```ruby
-class SecuredDataTool < ActiveMcp::Tool
-  description 'Access secured data'
-
-  argument :resource_id, :string, required: true, description: 'ID of the resource to access'
-
-  def call(resource_id:, auth_info: nil, **args)
-    # Check if auth info exists
-    unless auth_info.present?
-      raise "Authentication required to access this resource"
-    end
-
-    # Extract token from auth info
-    token = auth_info[:token]
-
-    # Validate token and get user
-    user = User.authenticate_with_token(token)
-
-    unless user
-      raise "Invalid authentication token"
-    end
-
-    # Check if user has access to the resource
-    resource = Resource.find(resource_id)
-
-    if resource.user_id != user.id
-      raise "Access denied to this resource"
-    end
 
-    # Return the secured data
-    {
-      type: "text",
-      content: resource.to_json
-    }
+  # Verify the token
+  user = User.authenticate_with_token(auth_info[:token])
+  
+  unless user
+    raise "Invalid authentication token"
   end
+  
+  # Proceed with authenticated operation
+  # ...
 end
 ```
 
-## Advanced Configuration
+## ⚙️ Advanced Configuration
 
 ### Custom Controller
 
-If you need to customize the MCP controller behavior, you can create your own controller that inherits from `ActiveMcpController`:
+Create a custom controller for advanced needs:
 
 ```ruby
-class CustomController < ActiveContexController
-  # Add custom behavior, authentication, etc.
+class CustomMcpController < ActiveMcp::BaseController
+  # Custom MCP handling logic
 end
 ```
 
-And update your routes:
+Update routes:
 
 ```ruby
 Rails.application.routes.draw do
@@ -328,72 +312,69 @@ Rails.application.routes.draw do
 end
 ```
 
-## Best Practices
+## 💡 Best Practices
 
-### Create a Tool for Each Model
+### 1. Create Specific Tool Classes
 
-For security reasons, it's recommended to create specific tools for each model rather than generic tools that dynamically determine the model class. This approach:
-
-1. Increases security by avoiding dynamic class loading
-2. Makes your tools more explicit and easier to understand
-3. Provides better validation and error handling specific to each model
-
-For example, instead of creating a generic search tool, create specific search tools for each model:
+Create dedicated tool classes for each model or operation instead of generic tools:
 
 ```ruby
-# Good: Specific tool for searching users
+# ✅ GOOD: Specific tool for a single purpose
 class SearchUsersTool < ActiveMcp::Tool
-  description 'Search users by criteria'
+  # ...specific implementation
+end
 
-  argument :email, :string, required: false, description: 'Email to search for'
-  argument :name, :string, required: false, description: 'Name to search for'
-  argument :limit, :integer, required: false, description: 'Maximum number of records to return'
+# ❌ BAD: Generic tool that dynamically loads models
+class GenericSearchTool < ActiveMcp::Tool
+  # Avoid this pattern - security and maintainability issues
+end
+```
 
-  def call(email: nil, name: nil, limit: 10)
-    criteria = {}
-    criteria[:email] = email if email.present?
-    criteria[:name] = name if name.present?
+### 2. Validate and Sanitize Inputs
 
-    users = User.where(criteria).limit(limit)
+Always validate and sanitize inputs in your tool implementations:
 
-    {
-      type: "text",
-      content: users.to_json(only: [:id, :name, :email, :created_at])
-    }
+```ruby
+def call(user_id:, **args)
+  # Validate input
+  unless user_id.is_a?(Integer) || user_id.to_s.match?(/^\d+$/)
+    return { error: "Invalid user ID format" }
   end
+  
+  # Proceed with validated data
+  user = User.find_by(id: user_id)
+  # ...
 end
+```
 
-# Good: Specific tool for searching posts
-class SearchPostsTool < ActiveMcp::Tool
-  description 'Search posts by criteria'
-
-  argument :title, :string, required: false, description: 'Title to search for'
-  argument :author_id, :integer, required: false, description: 'Author ID to filter by'
-  argument :limit, :integer, required: false, description: 'Maximum number of records to return'
-
-  def call(title: nil, author_id: nil, limit: 10)
-    criteria = {}
-    criteria[:title] = title if title.present?
-    criteria[:author_id] = author_id if author_id.present?
+### 3. Return Structured Responses
 
-    posts = Post.where(criteria).limit(limit)
+Return structured responses that are easy for AI to parse:
 
-    {
-      type: "text",
-      content: posts.to_json(only: [:id, :title, :author_id, :created_at])
+```ruby
+def call(query:, **args)
+  results = User.search(query)
+  
+  {
+    type: "text",
+    content: results.to_json(only: [:id, :name, :email]),
+    metadata: {
+      count: results.size,
+      query: query
     }
-  end
+  }
 end
 ```
 
-## Development
+## 🧪 Development
 
 After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rake` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-## Contributing
+## 👥 Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/kawakamimoeki/active_mcp. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/kawakamimoeki/active_mcp/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/moekiorg/active_mcp. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/moekiorg/active_mcp/blob/main/CODE_OF_CONDUCT.md).
 
-## License
+## 📄 License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+

data/lib/active_mcp/engine.rb

@@ -10,12 +10,5 @@ module ActiveMcp
         end
       end
     end
-    
-    initializer "active_mcp.configure_jbuilder" do |app|
-      if Rails.env.development?
-        Jbuilder.key_format camelize: :lower
-        Jbuilder.prettify if Jbuilder.respond_to?(:prettify) 
-      end
-    end
   end
 end

data/lib/active_mcp/version.rb

@@ -1,3 +1,3 @@
 module ActiveMcp
-  VERSION = "0.3.4"
+  VERSION = "0.3.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_mcp
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.5
 platform: ruby
 authors:
 - Moeki Kawakami