mcp_on_ruby 1.0.0 → 2.0.1

data/CONTRIBUTING.md

@@ -1,86 +0,0 @@
-# Contributing to MCP on Ruby
-
-We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:
-
-- Reporting a bug
-- Discussing the current state of the code
-- Submitting a fix
-- Proposing new features
-- Becoming a maintainer
-
-## Development Process
-
-We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.
-
-## Pull Requests
-
-1. Fork the repo and create your branch from `main`.
-2. If you've added code that should be tested, add tests.
-3. If you've changed APIs, update the documentation.
-4. Ensure the test suite passes.
-5. Make sure your code lints.
-6. Issue that pull request!
-
-## Development Setup
-
-```bash
-# Clone your fork
-git clone https://github.com/nagstler/mcp_on_ruby.git
-cd mcp_on_ruby
-
-# Install dependencies
-bundle install
-
-# Run the generators to test Rails integration
-mkdir test_app && cd test_app
-rails new . --skip-git
-echo "gem 'mcp_on_ruby', path: '..' " >> Gemfile
-bundle install
-rails generate mcp_on_ruby:install
-
-# Test the gem
-cd .. && ruby -e "require './lib/mcp_on_ruby'; puts 'Gem loads successfully'"
-```
-
-## Code Style
-
-- Follow standard Ruby conventions
-- Use meaningful variable and method names
-- Add documentation for public APIs
-- Keep methods focused and small
-
-## Testing
-
-Currently, we use manual testing and examples. In the future, we plan to add:
-- RSpec test suite
-- Integration tests with Rails
-- CI/CD pipeline
-
-## Bug Reports
-
-We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/nagstler/mcp_on_ruby/issues).
-
-**Great Bug Reports** tend to have:
-
-- A quick summary and/or background
-- Steps to reproduce
-  - Be specific!
-  - Give sample code if you can
-- What you expected would happen
-- What actually happens
-- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
-
-## Feature Requests
-
-We use GitHub issues to track feature requests. Propose a feature by [opening a new issue](https://github.com/nagstler/mcp_on_ruby/issues).
-
-**Great Feature Requests** include:
-
-- Clear use case description
-- Why this feature would be useful
-- Proposed API or implementation approach
-- Examples of how it would be used
-
-## License
-
-By contributing, you agree that your contributions will be licensed under the same MIT License that covers the project.

data/bin/console

@@ -1,11 +0,0 @@
-#!/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

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

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();
-  });
-}