mcp_lite 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 577f4745501390e1f5c3bda2faa1fe07f75fe6bca6588f4d513ac8fac012f5a0
+  data.tar.gz: 7c39bf43bb1f21aee0786dc3e1c962f0d9d7f33c4b1d6e462b3ee26e90f7950b
+SHA512:
+  metadata.gz: 1745e12fccb017eda42788736dd9776dc8e6bdd1ffa0743f5c7e3b20feee9344a9eb970156cd159c261569eab2f1bff06ea7c2a7c1ae8eff64e8f8462a3a01c5
+  data.tar.gz: 2f2aaf233e0838d656ace6b62a4442fbc75b57193072b80fa4ea5eb5cb24c41aff2b93b91b9e370f3850ed2374932007ee0e496da510b88fabf10c8c343d6d29

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2024 Moeki Kawakami
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,584 @@
+<div align="center">
+<img src="./website/public/logo.png" alt="MCP Lite" width="200"></i>
+</div>
+
+<div align="center">
+
+<h1>MCP Lite</h1>
+
+[![Gem Version](https://badge.fury.io/rb/mcp_lite.svg)](https://badge.fury.io/rb/mcp_lite)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+The Lightweight implementation of Model Context Protocol (MCP) in Ruby.
+
+</div>
+
+### Caution
+
+This is an early version of MCP Lite. The API may change in future releases. Please check the [CHANGELOG](CHANGELOG.md) for updates.
+
+[Active MCP](https://rubygems.org/gems/active_mcp) is deprecated. This library is a lightweight implementation of the Model Context Protocol (MCP) in Ruby, designed to be easy to use and integrate into your applications.
+
+## 📖 Table of Contents
+
+- [📖 Table of Contents](#-table-of-contents)
+- [✨ Features](#-features)
+- [📦 Installation](#-installation)
+- [🚀 Setup](#-setup)
+- [🔌 MCP Connection](#-mcp-connection)
+- [🧰 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)
+- [📦 MCP Resources](#-mcp-resources)
+  - [Creating Resources](#creating-resources)
+  - [Resource Types](#resource-types)
+- [📦 MCP Resource Templates](#-mcp-resource-templates)
+  - [Creating Resource Templates](#creating-resource-templates)
+- [💬 MCP Prompts](#-mcp-prompts)
+  - [Creating Prompt](#creating-prompt)
+- [💡 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)
+
+## 📦 Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mcp_lite'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install mcp_lite
+```
+
+## 🚀 Setup
+
+```ruby
+class CreateNoteTool < McpLite::Tool::Base
+  tool_name "create_note"
+
+  description "Create Note"
+
+  argument :title, :string, required: true
+  argument :content, :string, required: true
+  argument :published_at, :string, required: true,
+    visible: ->(context) { context[:role] == "admin" }
+
+  def call(title:, content:, context:)
+    note = Note.create(title: title, content: content)
+
+    [{ type: "text", text: "Created note with ID: #{note.id}" }]
+  end
+end
+```
+
+```ruby
+class MySchema < McpLite::Schema::Base
+  tools CreateNoteTool
+end
+```
+
+```ruby
+class MyMcpController < McpLite::BaseController
+  def index
+    render json: MySchema.execute(param:, context:)
+  end
+end
+```
+
+```ruby
+Rails.application.routes.draw do
+  post "/mcp", to: "my_mcp#index"
+
+  # Your other routes
+end
+```
+
+## 🔌 MCP Connection Methods
+
+Start a dedicated MCP server that communicates with your Ruby app:
+
+```ruby
+# script/mcp_server.rb
+server = McpLite::Server.new(
+  name: "My App MCP Server",
+  uri: 'https://your-app.example.com/mcp'
+)
+server.start
+```
+
+Then configure your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "my-rails-app": {
+      "command": "/path/to/ruby",
+      "args": ["/path/to/script/mcp_server.rb"]
+    }
+  }
+}
+```
+
+## 🧰 Creating MCP Tools
+
+MCP tools are Ruby classes that inherit from `McpLite::Tool::Base` and define an interface for AI to interact with your application:
+
+```ruby
+class SearchUsersTool < McpLite::Tool::Base
+  tool_name "Search Users"
+
+  description 'Search users by criteria'
+
+  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(email: nil, name: nil, limit: 10, context: {})
+    criteria = {}
+    criteria[:email] = email if email.present?
+    criteria[:name] = name if name.present?
+
+    users = User.where(criteria).limit(limit)
+
+    [{ type: "text", text: users.attributes.to_json }]
+  end
+end
+```
+
+## 📋 Input Schema
+
+Define arguments for your tools using the `argument` method:
+
+```ruby
+argument :name, :string, required: true, description: 'User name'
+argument :age, :integer, required: false, description: 'User age'
+argument :addresses, :array, required: false, description: 'User addresses'
+argument :preferences, :object, required: false, description: 'User preferences'
+```
+
+Supported types:
+
+| 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                     |
+
+## 🔐 Authorization & Authentication
+
+### Authorization for Tools
+
+Control access to tools by overriding the `visible?` class method:
+
+```ruby
+class AdminOnlyTool < McpLite::Tool::Base
+  tool_name "admin_only_tool"
+
+  description "Admin-only tool"
+
+  argument :command, :string, required: true, description: "Admin command"
+
+  # Only allow admins to access this tool
+  def self.visible?(context:)
+    return false unless context
+    return false unless context[:current_user]
+
+    # Check if the token belongs to an admin
+    User.find_by_token(context[:current_user][:token])&.admin?
+  end
+
+  def call(command:, context: {})
+    # Tool implementation
+  end
+end
+```
+
+### Authentication Options
+
+#### 1. Server Configuration
+
+```ruby
+server = McpLite::Server.new(
+  name: "My Secure MCP Server",
+  uri: 'http://localhost:3000/mcp',
+  auth: {
+    type: :bearer,
+    token: ENV['MCP_AUTH_TOKEN']
+  }
+)
+server.start
+```
+
+#### 2. Token Verification in Tools
+
+```ruby
+def call(resource_id:, context: {})
+  # Check if authentication is provided
+  unless context[:current_user].present?
+    raise "Authentication required"
+  end
+
+  # Proceed with authenticated operation
+  # ...
+end
+```
+
+## 📦 MCP Resources
+
+MCP Resources allow you to share data and files with AI assistants. Resources have a URI, MIME type, and can return either text or binary data.
+
+### Creating Resources
+
+Resources are Ruby classes `**Resource`:
+
+```ruby
+class UserResource < McpLite::Resource::Base
+  mime_type "application/json"
+
+  def initialize(id:)
+    @user = User.find(id)
+  end
+
+  def resource_name
+    @user.name
+  end
+
+  def uri
+    "data://localhost/users/#{@user.id}"
+  end
+
+  def description
+    @user.profile
+  end
+
+  def self.visible?(context:)
+    # Your logic...
+  end
+
+  def text
+    # Return JSON data
+    {
+      id: @user.id,
+      name: @user.name,
+      email: @user.email,
+      created_at: @user.created_at
+    }
+  end
+end
+```
+
+```ruby
+class MySchema < McpLite::Schema::Base
+  resource UserResource, items: User.all.each do |user|
+    { id: user.id }
+  end
+end
+```
+
+### Resource Types
+
+Resources can return two types of content:
+
+1. **Text Content** - Use the `text` method to return structured data:
+
+```ruby
+def text
+  # Return strings, arrays, hashes, or any JSON-serializable object
+  { items: Product.all.map(&:attributes) }
+end
+```
+
+2. **Binary Content** - Use the `blob` method to return binary files:
+
+```ruby
+class ImageResource < McpLite::Resource::Base
+  mime_type "image/png"
+
+  def resource_name
+    "profile_image"
+  end
+
+  def uri
+    "data://localhost/image"
+  end
+
+  def description
+    "Profile image"
+  end
+
+  def blob
+    # Return binary file content
+    File.read(Rails.root.join("public", "profile.png"))
+  end
+end
+```
+
+Resources can be protected using the same authorization mechanism as tools:
+
+```ruby
+def visible?(context: {})
+  return false unless context
+  return false unless context[:current_user]
+
+  # Check if the token belongs to an admin
+  User.find_by_token(context[:current_user][:token])&.admin?
+end
+```
+
+## 📦 MCP Resource Templates
+
+MCP Resource Teamplates allow you to define template of resources.
+
+### Creating Resource Templates
+
+Resource teamplates are Ruby classes `**Resource`:
+
+```ruby
+class UserResource < McpLite::Resource::Base
+  resource_template_name "users"
+
+  uri_template "data://localhost/users/{id}"
+
+  mime_type "application/json"
+
+  description "This is a test."
+
+  argument :id, complete: ->(value, context) do
+    User.all.pluck(:id).filter { _1.match(value) }
+  end
+
+  def self.visible?(context:)
+    # Your logic...
+  end
+
+  def initialize(id:)
+    @user = User.find(id)
+  end
+
+  def resource_name
+    @user.name
+  end
+
+  def description
+    @user.profile
+  end
+
+  def uri
+    "data://localhost/users/#{@user.name}"
+  end
+
+  def text
+    { name: @user.name }
+  end
+end
+```
+
+```ruby
+class MySchema < McpLite::Schema::Base
+  resource UserResource, items: User.all.each do |user|
+    { id: user.id }
+  end
+end
+```
+
+## 💬 MCP Prompts
+
+MCP Prompts allow you to define prompt set.
+
+### Creating Prompt
+
+Resources are Ruby classes `**Prompt`:
+
+```ruby
+class HelloPrompt < McpLite::Prompt::Base
+  prompt_name "hello"
+
+  description "This is a test."
+
+  argument :name, required: true, description: "User name", complete: ->(value, context) do
+    User.all.pluck(:name).filter { _1.match(value) }
+  end
+
+  def self.visible?(context:)
+    # Your logic...
+  end
+
+  def messages(name:)
+    [
+      McpLite::Message::Text.new(
+        role: "user",
+        text: "Hello! #{name}"
+      ),
+      McpLite::Message::Image.new(
+        role: "assistant",
+        data: File.read(file),
+        mime_type: "image/png"
+      ),
+      McpLite::Message::Audio.new(
+        role: "user",
+        data: File.read(file),
+        mime_type: "audio/mpeg"
+      ),
+      McpLite::Message::Resource.new(
+        role: "assistant",
+        resource: UserResource.new(name: @name)
+      )
+    ]
+  end
+end
+```
+
+```ruby
+class MySchema < McpLite::Schema::Base
+  prompt HelloPrompt
+end
+```
+
+## 💡 Best Practices
+
+### 1. Create Specific Tool Classes
+
+Create dedicated tool classes for each model or operation instead of generic tools:
+
+```ruby
+# ✅ GOOD: Specific tool for a single purpose
+class SearchUsersTool < McpLite::Tool::Base
+  # ...specific implementation
+end
+
+# ❌ BAD: Generic tool that dynamically loads models
+class GenericSearchTool < McpLite::Tool::Base
+  # Avoid this pattern - security and maintainability issues
+end
+```
+
+### 2. Validate and Sanitize Inputs
+
+Always validate and sanitize inputs in your tool implementations:
+
+```ruby
+def call(user_id:, context: {})
+  # Validate input
+  unless user_id.is_a?(Integer) || user_id.to_s.match?(/^\d+$/)
+    raise "Invalid user ID format"
+  end
+
+  # Proceed with validated data
+  user = User.find_by(id: user_id)
+  # ...
+end
+```
+
+### 3. Return Structured Responses
+
+Return structured responses that are easy for AI to parse:
+
+```ruby
+def call(query:, context: {})
+  results = User.search(query)
+
+  [{
+    type: "text",
+    text: {
+      content: results.to_json(only: [:id, :name, :email]),
+      metadata: {
+        count: results.size,
+        query: query
+      }
+    }.to_json
+  }]
+end
+```
+
+## 🧪 Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rake` to run the tests.
+
+## 👥 Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/moekiorg/mcp_lite. 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/mcp_lite/blob/main/CODE_OF_CONDUCT.md).
+
+## 📄 License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+# MCP Lite
+
+Model Context Protocol (MCP) implementation in Ruby.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mcp_lite'
+```
+
+## Usage
+
+### Basic Usage (Without Rails)
+
+```ruby
+require 'mcp_lite'
+
+class MySchema < McpLite::Schema::Base
+  tool SearchTool
+  resource UserResource, items: [
+    {name: "UserA"},
+    {name: "UserB"}
+  ]
+  prompt HelloPrompt
+end
+
+# Execute MCP request
+result = MySchema.execute(
+  params: {
+    method: "tools/list",
+    params: {},
+    jsonrpc: "2.0"
+  },
+  context: {
+    current_user: User.find_by_token(token)
+  }
+)
+```
+
+### Rails Integration
+
+```ruby
+# app/controllers/mcp_controller.rb
+class McpController < McpLite::BaseController
+  def index
+    render json: MySchema.execute(param:, context:)
+  end
+end
+
+# config/routes.rb
+Rails.application.routes.draw do
+  post "/mcp", to: "mcp#index"
+end
+```
+
+// ...existing documentation...

data/Rakefile

@@ -0,0 +1,9 @@
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/lib/mcp_lite/completion.rb

@@ -0,0 +1,21 @@
+module McpLite
+  class Completion
+    def complete(params: {}, context: {}, refs: [])
+      ref_name = params.dig(:ref, :name)
+      uri_template = params.dig(:ref, :uri)
+      arg_name = params.dig(:argument, :name)
+      value = params.dig(:argument, :value)
+
+      if uri_template
+        resource_class = refs.find { _1.uri_template_value == uri_template }
+        values = resource_class.arguments[arg_name.to_sym].call(value, context)
+        {values:, total: values.length}
+      elsif ref_name
+        prompt = refs.find { _1.prompt_name_value == ref_name }
+        values = prompt.arguments.find { _1[:name] == arg_name.to_sym }[:complete].call(value, context)
+
+        {values:, total: values.length}
+      end
+    end
+  end
+end

data/lib/mcp_lite/configuration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module McpLite
+  class Configuration
+    attr_accessor :server_name, :server_version
+
+    def initialize
+      @server_name = "MCP Server"
+      @server_version = "1.0.0"
+    end
+  end
+
+  class << self
+    def configure
+      yield config
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+  end
+end