mcp_on_ruby 1.0.0 → 2.0.0

data/docs/advanced-usage.md

@@ -1,132 +0,0 @@
-# Advanced Usage
-
-## Custom Authorization
-
-```ruby
-class ApplicationTool < McpOnRuby::Tool
-  def authorize(context)
-    token = context[:auth_token]
-    user = authenticate_token(token)
-    user&.has_permission?(:mcp_access)
-  end
-
-  private
-
-  def authenticate_token(token)
-    # Your authentication logic
-    JWT.decode(token, Rails.application.secret_key_base).first
-  rescue JWT::DecodeError
-    nil
-  end
-end
-```
-
-## Resource Caching
-
-```ruby
-class ApplicationResource < McpOnRuby::Resource
-  def read(params = {}, context = {})
-    cache_key = "mcp:#{uri}:#{params.hash}"
-    Rails.cache.fetch(cache_key, expires_in: 5.minutes) do
-      super
-    end
-  end
-end
-```
-
-## Manual Server Configuration
-
-```ruby
-# For advanced scenarios where auto-registration isn't sufficient
-McpOnRuby.mount_in_rails(Rails.application) do |server|
-  # Register tools manually
-  server.register_tool(CustomTool.new)
-  
-  # Define tools with DSL
-  server.tool 'database_query', 'Execute read-only database queries' do |args|
-    query = args['query']
-    raise 'Only SELECT allowed' unless query.strip.upcase.start_with?('SELECT')
-    
-    result = ActiveRecord::Base.connection.execute(query)
-    { rows: result.to_a }
-  end
-  
-  # Define resources with DSL
-  server.resource 'health' do
-    {
-      status: 'healthy',
-      database: database_healthy?,
-      redis: redis_healthy?,
-      timestamp: Time.current
-    }
-  end
-end
-```
-
-## Production Configuration
-
-### Security Setup
-
-```ruby
-# config/initializers/mcp_on_ruby.rb
-McpOnRuby.configure do |config|
-  # Authentication
-  config.authentication_required = true
-  config.authentication_token = ENV['MCP_AUTH_TOKEN']
-  
-  # Security
-  config.dns_rebinding_protection = true
-  config.allowed_origins = [
-    ENV['ALLOWED_ORIGIN'],
-    /\A#{Regexp.escape(ENV['DOMAIN'])}\z/
-  ]
-  config.localhost_only = false
-  
-  # Rate limiting
-  config.rate_limit_per_minute = 100
-  
-  # Features
-  config.cors_enabled = true
-end
-```
-
-### Monitoring & Logging
-
-```ruby
-class ApplicationTool < McpOnRuby::Tool
-  def call(arguments = {}, context = {})
-    start_time = Time.current
-    result = super
-    duration = Time.current - start_time
-    
-    Rails.logger.info("MCP Tool executed", {
-      tool: name,
-      duration: duration,
-      success: !result.key?(:error),
-      user_ip: context[:remote_ip]
-    })
-    
-    result
-  end
-end
-```
-
-### Error Monitoring
-
-```ruby
-# config/initializers/mcp_on_ruby.rb
-class CustomTool < ApplicationTool
-  def execute(arguments, context)
-    # Your tool logic
-  rescue => error
-    # Report to error monitoring service
-    Bugsnag.notify(error, {
-      tool: name,
-      arguments: arguments,
-      context: context
-    })
-    
-    raise
-  end
-end
-```

data/docs/api-reference.md

@@ -1,35 +0,0 @@
-# API Reference
-
-## Server Methods
-
-```ruby
-server = McpOnRuby.server do |s|
-  s.tool(name, description, input_schema, **options, &block)
-  s.resource(uri, **options, &block)
-  s.register_tool(tool_instance)
-  s.register_resource(resource_instance)
-end
-
-# Handle requests
-server.handle_request(json_string, context)
-```
-
-## Tool Class
-
-```ruby
-class MyTool < McpOnRuby::Tool
-  def initialize(name:, description: '', input_schema: {}, **options)
-  def execute(arguments, context) # Override this
-  def authorize(context) # Optional override
-end
-```
-
-## Resource Class
-
-```ruby
-class MyResource < McpOnRuby::Resource
-  def initialize(uri:, name: nil, description: '', mime_type: 'application/json', **options)
-  def fetch_content(params, context) # Override this
-  def authorize(context) # Optional override
-end
-```

data/docs/testing.md

@@ -1,55 +0,0 @@
-# Testing Guide
-
-## RSpec Integration
-
-```ruby
-# spec/tools/user_manager_tool_spec.rb
-require 'rails_helper'
-
-RSpec.describe UserManagerTool do
-  subject(:tool) { described_class.new }
-
-  describe '#execute' do
-    context 'creating a user' do
-      let(:arguments) do
-        {
-          'action' => 'create',
-          'attributes' => { 'name' => 'John Doe', 'email' => 'john@example.com' }
-        }
-      end
-      
-      it 'creates user successfully' do
-        result = tool.call(arguments, { authenticated: true })
-        
-        expect(result[:success]).to be true
-        expect(result[:user]['name']).to eq 'John Doe'
-      end
-    end
-  end
-end
-```
-
-## Integration Testing
-
-```ruby
-# spec/integration/mcp_server_spec.rb
-require 'rails_helper'
-
-RSpec.describe 'MCP Server Integration' do
-  let(:server) { Rails.application.config.mcp_server }
-
-  it 'handles tool calls' do
-    request = {
-      jsonrpc: '2.0',
-      method: 'tools/call',
-      params: { name: 'user_manager', arguments: { action: 'create' } },
-      id: 1
-    }
-
-    response = server.handle_request(request.to_json)
-    parsed = JSON.parse(response)
-
-    expect(parsed['result']).to be_present
-  end
-end
-```

data/examples/claude/README.md

@@ -1,171 +0,0 @@
-# Claude Desktop Integration with MCP on Ruby
-
-This example demonstrates how to connect Claude Desktop to your Rails application using MCP on Ruby. We'll walk through the complete setup process that bridges the protocol difference between Claude Desktop (stdio) and Rails (HTTP).
-
-## The Challenge
-
-Claude Desktop communicates with MCP servers using **stdio** (standard input/output), but MCP on Ruby runs as an **HTTP server** within your Rails application. We need a bridge to convert between these two protocols.
-
-## Complete Setup Guide
-
-### Step 1: Prepare Your Rails Application
-
-1. **Add MCP on Ruby to your Rails app:**
-   ```bash
-   # In your Rails app directory
-   bundle add mcp_on_ruby
-   rails generate mcp_on_ruby:install
-   ```
-
-2. **Configure MCP settings:**
-   ```ruby
-   # config/initializers/mcp_on_ruby.rb
-   McpOnRuby.configure do |config|
-     config.authentication_required = true
-     config.authentication_token = 'my-secure-token'
-     config.rate_limit_per_minute = 60
-   end
-   
-   Rails.application.configure do
-     config.mcp.enabled = true
-     config.mcp.auto_register_tools = true
-   end
-   ```
-
-3. **Create a sample tool for testing:**
-   ```bash
-   rails generate mcp_on_ruby:tool UserManager --description "Manage application users"
-   ```
-
-   This creates `app/tools/user_manager_tool.rb`. You can customize it or use the default implementation to test the connection.
-
-### Step 2: Set Up the Bridge Script
-
-1. **Copy the bridge script:**
-   Copy `claude-bridge.js` from this directory to your preferred location (e.g., `~/mcp-bridge/claude-bridge.js`)
-
-2. **Make it executable:**
-   ```bash
-   chmod +x ~/mcp-bridge/claude-bridge.js
-   ```
-
-3. **Update the bridge script configuration:**
-   Edit the top of `claude-bridge.js` to match your setup:
-   ```javascript
-   const RAILS_PORT = 3001;  // Your Rails server port
-   const AUTH_TOKEN = 'my-secure-token';  // Must match your Rails config
-   ```
-
-### Step 3: Configure Claude Desktop
-
-1. **Locate Claude Desktop config file:**
-   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-
-2. **Add your MCP server configuration:**
-   ```json
-   {
-     "mcpServers": {
-       "my-rails-app": {
-         "command": "node",
-         "args": ["/Users/yourusername/mcp-bridge/claude-bridge.js"]
-       }
-     }
-   }
-   ```
-   
-   Replace `/Users/yourusername/mcp-bridge/claude-bridge.js` with the actual path to your bridge script.
-
-### Step 4: Start Everything
-
-1. **Start your Rails server:**
-   ```bash
-   cd your-rails-app
-   rails server -p 3001
-   ```
-
-2. **Restart Claude Desktop** to load the new MCP server configuration
-
-### Step 5: Test the Integration
-
-1. Open Claude Desktop
-2. Look for your MCP tools in the available tools (they should appear automatically)
-3. Try asking Claude to use your tools:
-   - "Use the user manager tool to help me understand what it does"
-   - "What tools are available from my Rails application?"
-   - Test any specific functionality you've implemented in your tools
-
-## How the Bridge Works
-
-```
-┌─────────────────┐    stdio     ┌─────────────────┐    HTTP     ┌─────────────────┐
-│   Claude        │ ←──────────→ │   Bridge        │ ←─────────→ │   Rails MCP     │
-│   Desktop       │              │   Script        │             │   Server        │
-└─────────────────┘              └─────────────────┘             └─────────────────┘
-```
-
-The bridge script (`claude-bridge.js`):
-1. Receives JSON-RPC messages from Claude Desktop via stdin
-2. Adds authentication headers (Bearer token from your configuration)
-3. Forwards requests to Rails at `http://localhost:3001/mcp`
-4. Returns responses to Claude Desktop via stdout
-5. Handles errors and ensures proper JSON-RPC formatting
-
-## Directory Structure
-
-```
-your-rails-app/
-├── app/
-│   └── tools/
-│       └── user_manager_tool.rb  # Your generated tool
-├── config/
-│   └── initializers/
-│       └── mcp_on_ruby.rb        # MCP configuration
-└── config/routes.rb              # MCP route added automatically
-
-~/mcp-bridge/                     # Or your preferred location
-└── claude-bridge.js              # Bridge script
-```
-
-## Troubleshooting
-
-**Claude Desktop shows "Connection failed":**
-- Ensure Rails server is running on port 3001
-- Check that the bridge script path in Claude config is correct
-
-**"Unexpected end of JSON input":**
-- Verify authentication token matches exactly in both Rails config (`my-secure-token`) and bridge script (`AUTH_TOKEN`)
-- Check Rails server logs for authentication errors
-
-**Tools not appearing in Claude:**
-- Restart Claude Desktop after configuration changes
-- Verify tools are being auto-registered (check Rails logs)
-
-**Bridge script not executing:**
-- Ensure Node.js is installed and accessible
-- Make sure the script has execute permissions
-
-## Customizing the Setup
-
-To modify ports or authentication:
-
-1. **Change Rails port:**
-   ```bash
-   rails server -p 3002  # Use different port
-   ```
-
-2. **Update bridge script:**
-   Edit `RAILS_PORT` in `claude-bridge.js`
-
-3. **Change authentication token:**
-   Update both Rails config (`config.authentication_token`) and `AUTH_TOKEN` in bridge script
-
-## What You Get
-
-Once connected, Claude Desktop can:
-- Discover and use any tools you create in `app/tools/`
-- Access resources you define in `app/resources/`
-- Interact with your Rails application's data and functionality
-- Provide a natural language interface to your application's capabilities
-
-This setup provides a secure, production-ready connection between Claude Desktop and your Rails application via MCP on Ruby.

data/examples/claude/claude-bridge.js

@@ -1,122 +0,0 @@
-#!/usr/bin/env node
-
-const http = require('http');
-const { stdin, stdout, stderr } = process;
-
-// MCP server configuration
-const RAILS_HOST = 'localhost';
-const RAILS_PORT = 3001;
-const RAILS_PATH = '/mcp';
-const AUTH_TOKEN = 'test-db-inspector-token';
-
-// Set up stdio
-stdin.setEncoding('utf8');
-process.on('SIGTERM', () => process.exit(0));
-process.on('SIGINT', () => process.exit(0));
-
-let buffer = '';
-
-stdin.on('data', (chunk) => {
-  buffer += chunk;
-  
-  // Process complete JSON-RPC messages
-  const lines = buffer.split('\n');
-  buffer = lines.pop() || ''; // Keep incomplete line
-  
-  for (const line of lines) {
-    if (line.trim()) {
-      handleRequest(line.trim());
-    }
-  }
-});
-
-stdin.on('end', () => {
-  if (buffer.trim()) {
-    handleRequest(buffer.trim());
-  }
-});
-
-async function handleRequest(requestLine) {
-  let requestId = 1; // Default ID
-  
-  try {
-    // Parse and validate JSON-RPC request
-    const request = JSON.parse(requestLine);
-    requestId = request.id || 1; // Use request ID or default to 1
-    
-    // Forward to Rails MCP server
-    const response = await forwardToRails(requestLine);
-    
-    // Parse response to ensure it has correct ID
-    try {
-      const parsedResponse = JSON.parse(response);
-      if (parsedResponse.id === null || parsedResponse.id === undefined) {
-        parsedResponse.id = requestId;
-      }
-      stdout.write(JSON.stringify(parsedResponse) + '\n');
-    } catch {
-      // If response is not valid JSON, create proper response
-      const successResponse = {
-        jsonrpc: "2.0",
-        id: requestId,
-        result: { message: response }
-      };
-      stdout.write(JSON.stringify(successResponse) + '\n');
-    }
-    
-  } catch (error) {
-    // Send JSON-RPC error response with proper ID
-    const errorResponse = {
-      jsonrpc: "2.0",
-      id: requestId,
-      error: {
-        code: -32700,
-        message: "Parse error",
-        data: error.message
-      }
-    };
-    stdout.write(JSON.stringify(errorResponse) + '\n');
-  }
-}
-
-function forwardToRails(requestData) {
-  return new Promise((resolve, reject) => {
-    const options = {
-      hostname: RAILS_HOST,
-      port: RAILS_PORT,
-      path: RAILS_PATH,
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Authorization': `Bearer ${AUTH_TOKEN}`,
-        'Content-Length': Buffer.byteLength(requestData)
-      },
-      timeout: 30000
-    };
-
-    const req = http.request(options, (res) => {
-      let responseData = '';
-      
-      res.on('data', (chunk) => {
-        responseData += chunk;
-      });
-      
-      res.on('end', () => {
-        resolve(responseData);
-      });
-    });
-
-    req.on('error', (error) => {
-      // Return error as string to be wrapped in proper JSON-RPC format
-      resolve(`Connection failed: ${error.message}`);
-    });
-
-    req.on('timeout', () => {
-      req.destroy();
-      resolve('Request timeout');
-    });
-
-    req.write(requestData);
-    req.end();
-  });
-}

data/lib/mcp_on_ruby/errors.rb

@@ -1,137 +0,0 @@
-# frozen_string_literal: true
-
-module McpOnRuby
-  # Base error class for MCP-related errors
-  class Error < StandardError
-    attr_reader :code, :data
-
-    def initialize(message, code: nil, data: nil)
-      super(message)
-      @code = code
-      @data = data
-    end
-
-    # Convert error to JSON-RPC error format
-    def to_json_rpc
-      {
-        code: @code || default_error_code,
-        message: message,
-        data: @data
-      }.compact
-    end
-
-    private
-
-    def default_error_code
-      -32603 # Internal error
-    end
-  end
-
-  # JSON-RPC parsing error
-  class ParseError < Error
-    private
-
-    def default_error_code
-      -32700
-    end
-  end
-
-  # Invalid JSON-RPC request
-  class InvalidRequestError < Error
-    private
-
-    def default_error_code
-      -32600
-    end
-  end
-
-  # Method not found
-  class MethodNotFoundError < Error
-    private
-
-    def default_error_code
-      -32601
-    end
-  end
-
-  # Invalid method parameters
-  class InvalidParamsError < Error
-    private
-
-    def default_error_code
-      -32602
-    end
-  end
-
-  # Tool or resource not found
-  class NotFoundError < Error
-    private
-
-    def default_error_code
-      -32603
-    end
-  end
-
-  # Authorization/authentication failed
-  class AuthorizationError < Error
-    private
-
-    def default_error_code
-      -32600
-    end
-  end
-
-  # Validation error for tool arguments or resource parameters
-  class ValidationError < Error
-    private
-
-    def default_error_code
-      -32602
-    end
-  end
-
-  # Tool execution error
-  class ToolExecutionError < Error
-    private
-
-    def default_error_code
-      -32603
-    end
-  end
-
-  # Resource read error
-  class ResourceReadError < Error
-    private
-
-    def default_error_code
-      -32603
-    end
-  end
-
-  # Rate limiting error
-  class RateLimitError < Error
-    private
-
-    def default_error_code
-      -32603
-    end
-  end
-
-  # Configuration error
-  class ConfigurationError < Error
-    private
-
-    def default_error_code
-      -32603
-    end
-  end
-
-  # Transport error
-  class TransportError < Error
-    private
-
-    def default_error_code
-      -32603
-    end
-  end
-end

data/lib/mcp_on_ruby/generators/install_generator.rb

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-require 'rails/generators'
-
-module McpOnRuby
-  module Generators
-    # Generator for installing MCP server in Rails application
-    class InstallGenerator < Rails::Generators::Base
-      source_root File.expand_path('templates', __dir__)
-
-      desc "Install MCP server in Rails application"
-
-      def create_initializer
-        template 'initializer.rb', 'config/initializers/mcp_on_ruby.rb'
-      end
-
-      def create_application_classes
-        template 'application_tool.rb', 'app/tools/application_tool.rb'
-        template 'application_resource.rb', 'app/resources/application_resource.rb'
-      end
-
-      def create_example_tool
-        template 'sample_tool.rb', 'app/tools/sample_tool.rb'
-      end
-
-      def create_example_resource
-        template 'sample_resource.rb', 'app/resources/sample_resource.rb'
-      end
-
-      def add_route
-        say "MCP server will be available at /mcp via middleware", :green
-        say "No route configuration needed - handled by Railtie", :blue
-      end
-
-      def show_readme
-        readme 'README' if behavior == :invoke
-      end
-
-      private
-
-      def readme(path)
-        say IO.read(File.join(self.class.source_root, path)), :green if File.exist?(File.join(self.class.source_root, path))
-      end
-    end
-  end
-end