mcp_on_ruby 0.3.0 → 1.0.0

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "mcp_on_ruby"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install

data/docs/advanced-usage.md

@@ -0,0 +1,132 @@
+# 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

@@ -0,0 +1,35 @@
+# 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

@@ -0,0 +1,55 @@
+# 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

@@ -0,0 +1,171 @@
+# 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

@@ -0,0 +1,122 @@
+#!/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/configuration.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module McpOnRuby
+  # Configuration class for MCP server
+  class Configuration
+    attr_accessor :log_level,
+                  :path,
+                  :authentication_required,
+                  :authentication_token,
+                  :allowed_origins,
+                  :localhost_only,
+                  :rate_limit_per_minute,
+                  :enable_sse,
+                  :request_timeout,
+                  :cors_enabled,
+                  :dns_rebinding_protection
+
+    def initialize
+      @log_level = Logger::INFO
+      @path = '/mcp'
+      @authentication_required = false
+      @authentication_token = nil
+      @allowed_origins = []
+      @localhost_only = false
+      @rate_limit_per_minute = 60
+      @enable_sse = true
+      @request_timeout = 30
+      @cors_enabled = true
+      @dns_rebinding_protection = true
+    end
+
+    # Check if authentication is configured
+    # @return [Boolean] True if authentication is properly configured
+    def authentication_configured?
+      authentication_required && !authentication_token.nil?
+    end
+
+    # Check if origin is allowed
+    # @param origin [String] The origin to check
+    # @return [Boolean] True if origin is allowed
+    def origin_allowed?(origin)
+      return true if allowed_origins.empty?
+      
+      allowed_origins.any? do |allowed|
+        case allowed
+        when String
+          origin == allowed
+        when Regexp
+          origin =~ allowed
+        else
+          false
+        end
+      end
+    end
+
+    # Check if localhost only mode and origin is localhost
+    # @param origin [String] The origin to check
+    # @return [Boolean] True if localhost only and origin is localhost
+    def localhost_allowed?(origin)
+      return true unless localhost_only
+      
+      localhost_patterns = [
+        'http://localhost',
+        'https://localhost',
+        'http://127.0.0.1',
+        'https://127.0.0.1'
+      ]
+      
+      localhost_patterns.any? { |pattern| origin&.start_with?(pattern) }
+    end
+  end
+end