rails-mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ba176e0f681ca2aded9b387f58c157431daba9643297cc455ddfba82757bd4cd
+  data.tar.gz: 23b82ff6a767507ffbe990ea84a0632a5d8528b0d53ad34ff68942068f306a80
+SHA512:
+  metadata.gz: 49aebae4786a931d12b49da05884261f2aa20d81412056aa234833709749f69296b37e3ef116c0326666b3f69395a0a3d64ee00b0accac4b98ddde357c2b43c6
+  data.tar.gz: f5f1cc5fdbb077df43b792ffbe2e4b515563da28ea97f60dd7d94eeb3391fc5690b18fb55f5732fd093f323f68d898906126db7284e309ff33b0826b1e74c88b

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025
+
+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,175 @@
+# rails-mcp
+
+> **Setting this up?** Point your coding agent (Cursor, Claude Code, etc.) at [`llms.txt`](./llms.txt) and ask it to self-configure rails-mcp in your project.
+
+A Ruby gem that provides AI assistants with ruby code execution capabilities within the context of existing running application server. Think of it giving AI assistant lighting-speed access to ruby console without the need to write script, reload or restart.
+
+Works with Rails, Sinatra, Hanami, Roda, and any other Rack-based framework. The code is executed in your application's context for debugging and investigation. 
+
+<img src="docs/assets/screen.gif" alt="rails console mcp in cursor" width="400"/>
+
+<a href="https://youtu.be/lhhOGq6l42s?si=gE4jfwow2aqAtvvk">YouTube Link</a>
+
+## Used at
+
+<a href="https://www.apollo.io/"><img src="docs/assets/apollo-logo.jpg" alt="Apollo.io" width="100"/></a>
+
+Used at Apollo.io against a Rails codebase with 20k+ Ruby files.
+
+## Use cases
+
+1. Learn a new codebase or code areas quickly. With your AI client and a running server, you can ask it to research while executing snippets from your actual application code. It effectively acts as an in-loop code-verification block.
+2. Perform quick, preliminary investigations of customer escalations using a read-only copy of the production environment. It can execute your application code, locate models, and run relevant class methods or code paths from the codebase to do preliminary root-cause analysis (RCA). Even better if your application uses an event-sourcing framework (i.e., change logs). The AI client, together with the code-execution capabilities via rails-mcp, can deliver fast preliminary RCAs.
+3. Use it for quick data analytics and export reports as CSV.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "rails-mcp"
+```
+
+Or install locally for development:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Mounting the MCP Server
+
+**Rails** (`config/routes.rb`):
+```ruby
+require "rails_mcp/mcp/server"
+
+Rails.application.routes.draw do
+  mount RailsMcp::MCP::Server.new => "/mcp"
+end
+```
+
+**Rack** (`config.ru`):
+```ruby
+require "rails_mcp"
+require "rails_mcp/mcp/server"
+
+map "/mcp" do
+  run RailsMcp::MCP::Server.new
+end
+```
+
+**Sinatra**:
+```ruby
+require "rails_mcp/mcp/server"
+
+mount RailsMcp::MCP::Server.new, at: "/mcp"
+```
+
+### Starting the Server
+
+```bash
+# Standalone with Rackup
+bundle exec rackup -p 9292
+
+# With Rails
+bundle exec rails server
+```
+
+### Environment-scoped mounting
+
+This gem ships without authentication — the MCP endpoint will accept any request that reaches it. You are responsible for ensuring it is only mounted where appropriate. A typical Rails setup gates it on environment:
+
+```ruby
+Rails.application.routes.draw do
+  mount RailsMcp::MCP::Server.new => "/mcp" if Rails.env.development?
+end
+```
+
+For staging or production access, combine that with network-level restrictions (firewall, VPC, SSH port-forward, VPN) so the endpoint is never reachable from the open internet.
+
+## MCP Protocol
+
+### Endpoint
+
+The MCP server exposes a single JSON-RPC endpoint:
+
+- **POST /mcp/rpc** - JSON-RPC request and response
+
+### Available Tools
+
+**evaluate_ruby_code**
+- Description: Evaluates Ruby code and returns the result with captured stdout/stderr
+- Parameters:
+  - `code` (string, required): Ruby code to execute
+
+## Connecting AI Assistants
+
+### Cursor/ Claude Desktop
+
+Add to your MCP client configuration (`.cursor/mcp.json` for Cursor or `claude_desktop_config.json` for Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "rails-mcp": {
+      "url": "http://localhost:3001/mcp/rpc"
+    }
+  }
+}
+```
+
+For Claude Code, add it from the command line:
+
+```bash
+claude mcp add rails-mcp --transport http http://localhost:3001/mcp/rpc
+```
+
+![MCP integration in Cursor](docs/assets/mcp-in-cursor.png)
+
+### Other MCP Clients
+
+Any MCP-compatible client can connect to the server by making JSON-RPC requests to the `/mcp/rpc` endpoint.
+
+Example with curl:
+
+```bash
+curl -X POST "http://localhost:3001/mcp/rpc" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/list"
+  }'
+```
+
+## Testing
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+## Security Warning
+
+⚠️ **This gem executes arbitrary Ruby code.** 
+
+**Important security considerations:**
+- **No built-in authentication.** Gate the mount on environment (e.g., `if Rails.env.development?`) so the endpoint isn't exposed in production by accident
+- Only use in development environments or secure, isolated production environments
+- Rely on network-level restrictions (firewall, VPC, SSH port-forward, VPN) to limit access
+- Consider running in a sandboxed or containerized environment
+- Monitor and log all code execution requests
+
+## Concurrency Note
+
+This gem uses global `$stdout/$stderr` redirection during evaluation, which can clash in multi-threaded servers. For production use with concurrency, consider:
+- Running in a single worker/thread mode
+- Isolating evaluation per request (e.g., via `fork`)
+- Using a dedicated job worker for code execution
+
+## License
+
+MIT License - see LICENSE file for details.
+

data/lib/rails_mcp/executor.rb

@@ -0,0 +1,38 @@
+# typed: strict
+require "stringio"
+
+module RailsMcp
+  class Executor
+    # Evaluates Ruby code and captures stdout/stderr.
+    def self.eval(code)
+      code = code.to_s
+      raise ArgumentError, "code can't be blank" if code.strip.empty?
+
+      out, err = StringIO.new, StringIO.new
+      old_out, old_err = $stdout, $stderr
+      result = nil
+      error = nil
+
+      begin
+        $stdout, $stderr = out, err
+        result = TOPLEVEL_BINDING.eval(code)
+      rescue SyntaxError, StandardError => e
+        error = e
+      ensure
+        $stdout, $stderr = old_out, old_err
+      end
+
+      if error
+        backtrace = error.backtrace&.first(3)&.join("\n  ")
+        return "#{error.class}: #{error.message}\n#{backtrace ? "  #{backtrace}\n" : ""}"
+      end
+
+      parts = []
+      parts << "=> #{result.inspect}\n" unless result.nil?
+      parts << out.string unless out.string.empty?
+      parts << err.string unless err.string.empty?
+      parts.join
+    end
+  end
+end
+

data/lib/rails_mcp/mcp/server.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+require "json"
+require "rack"
+require_relative "../version"
+require_relative "../executor"
+
+module RailsMcp
+  module MCP
+    # Minimal MCP-over-HTTP (JSON-RPC) server.
+    # Single-session, single-process demo: fine for local/dev usage.
+    class Server
+      def initialize
+        @tools = [
+          {
+            "name" => "evaluate_ruby_code",
+            "description" => "Evaluate the Ruby code in the context of the current application, returns the result of the code execution",
+            "inputSchema" => {
+              "type" => "object",
+              "properties" => {
+                "code" => {
+                  "type" => "string",
+                  "description" => "The Ruby code to evaluate, must be a valid Ruby expression or statement"
+                }
+              },
+              "required" => ["code"]
+            }
+          }
+        ]
+      end
+
+      def call(env)
+        req = Rack::Request.new(env)
+
+        case [req.request_method, req.path_info]
+        when ["POST", "/rpc"] then handle_rpc(req)
+        else
+          [404, {"content-type" => "text/plain"}, ["Not Found\n"]]
+        end
+      end
+
+      private
+
+      def handle_rpc(req)
+        payload = JSON.parse(req.body.read)
+        id      = payload["id"]
+        method  = payload["method"]
+
+        result =
+          case method
+          when "initialize"
+            {
+              "protocolVersion" => "2025-06-18",
+              "serverInfo"      => { "name" => "rails_mcp", "version" => RailsMcp::VERSION },
+              "capabilities"    => { "tools" => {} }
+            }
+
+          when "tools/list"
+            { "tools" => @tools }
+
+          when "tools/call"
+            name = payload.dig("params", "name")
+            args = payload.dig("params", "arguments") || {}
+
+            if name == "evaluate_ruby_code"
+              out = RailsMcp::Executor.eval(args["code"].to_s)
+              { "content" => [{ "type" => "text", "text" => out }] }
+            else
+              raise "Unknown tool: #{name}"
+            end
+
+          else
+            raise "Unknown method: #{method}"
+          end
+
+        # Return JSON-RPC response directly
+        response = { "jsonrpc" => "2.0", "id" => id, "result" => result }
+        [200, {"content-type" => "application/json"}, [JSON.generate(response)]]
+      rescue => e
+        response = { "jsonrpc" => "2.0", "id" => id, "error" => { "code" => -32601, "message" => e.message } }
+        [200, {"content-type" => "application/json"}, [JSON.generate(response)]]
+      end
+    end
+  end
+end
+

data/lib/rails_mcp/version.rb

@@ -0,0 +1,5 @@
+# typed: strict
+module RailsMcp
+  VERSION = "0.1.0"
+end
+

data/lib/rails_mcp.rb

@@ -0,0 +1,7 @@
+# typed: strict
+require "rails_mcp/version"
+require "rails_mcp/executor"
+
+module RailsMcp
+end
+

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: rails-mcp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Raja Jamwal
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rackup
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A Rack-based MCP server that enables AI assistants to execute Ruby code
+  via the Model Context Protocol.
+email:
+- linux.experi@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/rails_mcp.rb
+- lib/rails_mcp/executor.rb
+- lib/rails_mcp/mcp/server.rb
+- lib/rails_mcp/version.rb
+homepage: https://github.com/raja-jamwal/rails-mcp
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Model Context Protocol (MCP) server for Ruby code execution
+test_files: []