rails-mcp-server 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7d6b13d9872252c1545e274913eb23db3d29d9e9df89e8943d6bc81b36bc530c
+  data.tar.gz: 888854cbf2bd61251c0908462deee4ed2579bade5ccb4fb28cf6e050fcd47bdd
+SHA512:
+  metadata.gz: 7181f3eb02a5cc1d85bb0503df37d5c6985a95a26f3634d3c677e4be51204ed761a5e50041c66817fa341f460d083e036510699b380b119d0506bcadc6ee95fd
+  data.tar.gz: 7ed062c493c6b9071086a96161dc7f1c63f54f8227a48ad3aa5492c6fd81904abab548e1e4bc9438599ab9a69a068f2ebebe1b9c21a19a8195d3f20d08020748

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 [Mario Alberto Chávez Cárdenas]
+
+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,482 @@
+# Rails MCP Server
+
+A Ruby implementation of a Model Context Protocol (MCP) server for Rails projects. This server allows LLMs (Large Language Models) to interact with Rails projects through the Model Context Protocol.
+
+## What is MCP?
+
+The Model Context Protocol (MCP) is a standardized way for AI models to interact with their environment. It defines a structured method for models to request and use tools, access resources, and maintain context during interactions.
+
+This Rails MCP Server implements the MCP specification to give AI models access to Rails projects for code analysis, exploration, and assistance.
+
+## Features
+
+- Manage multiple Rails projects
+- Browse project files and structures
+- View Rails routes
+- Inspect model information
+- Get database schema information
+- Follow the Model Context Protocol standard
+
+## Installation
+
+Install the gem:
+
+```bash
+gem install rails-mcp-server
+```
+
+After installation, the `rails-mcp-server` and `rails-mcp-setup-claude` executables will be available in your PATH.
+
+## Configuration
+
+The Rails MCP Server follows the XDG Base Directory Specification for configuration files:
+
+- On macOS: `$XDG_CONFIG_HOME/rails-mcp` or `~/.config/rails-mcp` if XDG_CONFIG_HOME is not set
+- On Windows: `%APPDATA%\rails-mcp`
+
+The server will automatically create these directories and an empty `projects.yml` file the first time it runs.
+
+To configure your projects:
+
+1. Edit the `projects.yml` file in your config directory to include your Rails projects:
+
+```yaml
+store: "~/projects/store"
+blog: "~/projects/rails-blog"
+```
+
+Each key in the YAML file is a project name (which will be used with the `switch_project` tool), and each value is the path to the project directory.
+
+## Claude Desktop Integration
+
+The Rails MCP Server can be used with Claude Desktop. There are two options to set this up:
+
+### Option 1: Use the setup script (recommended)
+
+Run the setup script which will automatically configure Claude Desktop and set up the proper XDG-compliant directory structure:
+
+```bash
+rails-mcp-setup-claude
+```
+
+The script will:
+
+- Create the appropriate config directory for your platform
+- Create an empty `projects.yml` file if it doesn't exist
+- Update the Claude Desktop configuration
+
+After running the script, restart Claude Desktop to apply the changes.
+
+### Option 2: Manual configuration
+
+1. Create the appropriate config directory for your platform:
+   - macOS: `$XDG_CONFIG_HOME/rails-mcp` or `~/.config/rails-mcp`
+   - Windows: `%APPDATA%\rails-mcp`
+
+2. Create a `projects.yml` file in that directory with your Rails projects.
+
+3. Find or create the Claude Desktop configuration file:
+   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+4. Add or update the MCP server configuration:
+
+```json
+{
+  "mcpServers": {
+    "railsMcpServer": {
+      "command": "ruby",
+      "args": ["/full/path/to/rails-mcp-server/exe/rails-mcp-server"] 
+    }
+  }
+}
+```
+
+5. Restart Claude Desktop to apply the changes.
+
+### Ruby Version Manager Users
+
+Claude Desktop launches the MCP server using your system's default Ruby environment, bypassing version manager initialization (e.g., rbenv, RVM). The MCP server needs to use the same Ruby version where it was installed, as MCP server startup failures can occur when using an incompatible Ruby version.
+
+If you are using a Ruby version manager such as rbenv, you can create a symbolic link to your Ruby shim to ensure the correct version is used:
+
+```
+
+sudo ln -s /home/your_user/.rbenv/shims/ruby /usr/local/bin/ruby
+
+```
+
+Replace "/home/your_user/.rbenv/shims/ruby" with your actual path for the Ruby shim.
+
+## Usage
+
+Start the server:
+
+```bash
+rails-mcp-server
+```
+
+### Logging Options
+
+The server logs to a file in the `./log` directory by default. You can customize logging with these options:
+
+```bash
+# Set the log level (debug, info, warn, error, fatal)
+rails-mcp-server --log-level debug
+```
+
+## How the Server Works
+
+The Rails MCP Server implements the Model Context Protocol over standard input/output (stdio). It:
+
+1. Reads JSON-RPC 2.0 requests from standard input
+2. Processes the requests using the appropriate tools
+3. Returns JSON-RPC 2.0 responses to standard output
+
+Each request includes a sequence number to match requests with responses, as defined in the MCP specification.
+
+## Available Tools
+
+The server provides the following tools for interacting with Rails projects:
+
+### 1. `switch_project`
+
+Switch the active Rails project.
+
+**Parameters:**
+
+- `project_name`: (String, required) Name of the project to switch to, as defined in the projects.yml file
+
+**Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "123",
+  "method": "tools/call",
+  "params": {
+    "name": "switch_project",
+    "arguments": {
+      "project_name": "blog"
+    }
+  }
+}
+```
+
+**Description:** Change the active Rails project to interact with a different codebase. Must be called before using other tools. Available projects are defined in the projects.yml configuration file.
+
+Examples:
+
+```
+Can you switch to the "store" project so we can explore it?
+```
+
+```
+I'd like to analyze my "blog" application. Please switch to that project first.
+```
+
+```
+Switch to the "ecommerce" project and give me a summary of the codebase.
+```
+
+### 2. `get_project_info`
+
+Get information about the current Rails project, including version, directory structure, and configuration.
+
+**Parameters:** None
+
+**Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "124",
+  "method": "tools/call",
+  "params": {
+    "name": "get_project_info",
+    "arguments": {}
+  }
+}
+```
+
+**Description:** Retrieve comprehensive information about the current Rails project, including Rails version, directory structure, API-only status, and overall project organization.
+
+Examples:
+
+```
+Now that we're in the blog project, can you give me an overview of the project structure and Rails version?
+```
+
+```
+Tell me about this Rails application. What version is it running and how is it organized?
+```
+
+```
+I'd like to understand the high-level architecture of this project. Can you provide the project information?
+```
+
+### 3. `list_files`
+
+List files in the Rails project, with optional directory path and pattern filtering.
+
+**Parameters:**
+
+- `directory`: (String, optional) Directory path relative to the project root
+- `pattern`: (String, optional) File pattern to match (e.g., "*.rb")
+
+**Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "125",
+  "method": "tools/call",
+  "params": {
+    "name": "list_files",
+    "arguments": {
+      "directory": "app/models",
+      "pattern": "*.rb"
+    }
+  }
+}
+```
+
+**Description:** List files in the Rails project matching specific criteria. Use this to explore project directories or locate specific file types.
+
+Examples:
+
+```
+Can you list all the model files in this project?
+```
+
+```
+Show me all the controller files in the app/controllers directory.
+```
+
+```
+I need to see all the view templates in the users section. Can you list the files in app/views/users?
+```
+
+```
+List all the JavaScript files in the app/javascript directory.
+```
+
+### 4. `get_file`
+
+Get the content of a file in the Rails project with syntax highlighting.
+
+**Parameters:**
+
+- `path`: (String, required) File path relative to the project root
+
+**Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "126",
+  "method": "tools/call",
+  "params": {
+    "name": "get_file",
+    "arguments": {
+      "path": "app/models/user.rb"
+    }
+  }
+}
+```
+
+**Description:** Retrieve the complete content of a specific file with syntax highlighting.
+
+Examples:
+
+```
+Can you show me the content of the User model file?
+```
+
+```
+I need to see what's in app/controllers/products_controller.rb. Can you retrieve that file?
+```
+
+```
+Please show me the application.rb file so I can check the configuration settings.
+```
+
+```
+I'd like to examine the routes file. Can you display the content of config/routes.rb?
+```
+
+### 5. `get_routes`
+
+Get the routes defined in the Rails project.
+
+**Parameters:** None
+
+**Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "127",
+  "method": "tools/call",
+  "params": {
+    "name": "get_routes",
+    "arguments": {}
+  }
+}
+```
+
+**Description:** Retrieve all HTTP routes defined in the Rails application with their associated controllers and actions.
+
+Examples:
+
+```
+Can you show me all the routes defined in this application?
+```
+
+```
+I need to understand the API endpoints available in this project. Can you list the routes?
+```
+
+```
+Show me the routing configuration for this Rails app so I can see how the URLs are structured.
+```
+
+### 6. `get_models`
+
+Get information about the models in the Rails project, including schema, associations, and definitions.
+
+**Parameters:**
+
+- `model_name`: (String, optional) Name of a specific model to get information for
+
+**Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "128",
+  "method": "tools/call",
+  "params": {
+    "name": "get_models",
+    "arguments": {
+      "model_name": "User"
+    }
+  }
+}
+```
+
+**Description:** Retrieve detailed information about Active Record models in the project.
+
+Examples:
+
+```
+Can you list all the models in this Rails project?
+```
+
+```
+I'd like to understand the User model in detail. Can you show me its schema, associations, and code?
+```
+
+```
+Show me the Product model's definition, including its relationships with other models.
+```
+
+```
+What are all the models in this application, and can you then show me details for the Order model specifically?
+```
+
+### 7. `get_schema`
+
+Get the database schema for the Rails project or for a specific table.
+
+**Parameters:**
+
+- `table_name`: (String, optional) Name of a specific table to get schema for
+
+**Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "129",
+  "method": "tools/call",
+  "params": {
+    "name": "get_schema",
+    "arguments": {
+      "table_name": "users"
+    }
+  }
+}
+```
+
+**Description:** Retrieve database schema information for the Rails application.
+
+Examples:
+
+```
+Can you show me the complete database schema for this Rails application?
+```
+
+```
+I'd like to see the structure of the users table. Can you retrieve that schema information?
+```
+
+```
+Show me the columns and their data types in the products table.
+```
+
+```
+I need to understand the database design. Can you first list all tables and then show me details for the orders table?
+```
+
+## Integration with LLM Clients
+
+This server is designed to be integrated with LLM clients that support the Model Context Protocol, such as Claude Desktop or other MCP-compatible applications.
+
+To use with an MCP client:
+
+1. Start the Rails MCP Server
+2. Connect your MCP-compatible client to the server
+3. The client will be able to use the available tools to interact with your Rails projects
+
+## Manual Testing
+
+You can manually test the server by sending JSON-RPC requests to its standard input:
+
+```bash
+echo '0 {"jsonrpc":"2.0","id":"test-123","method":"ping"}' | rails-mcp-server
+```
+
+Expected response:
+
+```
+0 {"jsonrpc":"2.0","id":"test-123","result":{"version":"1.0.0"}}
+```
+
+Or test multiple commands in sequence:
+
+```bash
+(echo '0 {"jsonrpc":"2.0","id":"test-123","method":"tools/list"}'; sleep 1; echo '1 {"jsonrpc":"2.0","id":"test-456","method":"tools/call","params":{"name":"switch_project","arguments":{"project_name":"blog"}}}') | rails-mcp-server
+```
+
+You can also use `jq` to parse the output and format it nicely:
+
+```bash
+echo '0 {"jsonrpc":"2.0","id":"list-tools","method":"tools/list"}' | rails-mcp-server | sed 's/^[0-9]* //' | jq '.result.tools'
+```
+
+## License
+
+This Rails MCP server is released under the MIT License, a permissive open-source license that allows for free use, modification, distribution, and private use.
+
+Copyright (c) 2025 Mario Alberto Chávez Cárdenas
+
+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.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at <https://github.com/maquina-app/rails-mcp-server>.

data/exe/rails-mcp-server

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+
+require "pathname"
+
+# Get script directory and project root
+bin_dir = Pathname.new(__FILE__).dirname
+root_dir = bin_dir.parent
+
+# Check if server script exists
+server_script = root_dir.join("lib", "rails_mcp_server.rb")
+unless server_script.exist?
+  puts "Error: rails_mcp_server.rb not found in lib directory (#{root_dir}/lib)"
+  exit 1
+end
+
+# Show version if requested
+if ARGV[0] == "version"
+  puts "Rails MCP Server version 1.0.0"
+  exit 0
+end
+
+# Help message
+if ARGV[0] == "--help" || ARGV[0] == "-h"
+  puts "Rails MCP Server - MCP protocol server for Rails projects"
+  puts ""
+  puts "Usage: #{File.basename($0)} [options]"
+  puts ""
+  puts "Options:"
+  puts "  --log-level LEVEL      Log level: debug, info, warn, error (default: info)"
+  puts "  version                Display version information"
+  puts "  --help, -h             Display this help message"
+  puts ""
+  puts "Example:"
+  puts "  #{File.basename($0)} --log-level debug"
+  exit 0
+end
+
+# Change to root directory and execute server script
+Dir.chdir(root_dir)
+load server_script

data/exe/rails-mcp-setup-claude

@@ -0,0 +1,146 @@
+#!/usr/bin/env ruby
+
+require "pathname"
+require "fileutils"
+require "json"
+
+# ANSI color codes
+class String
+  def colorize(color_code)
+    "\e[#{color_code}m#{self}\e[0m"
+  end
+
+  def green
+    colorize(32)
+  end
+
+  def blue
+    colorize(34)
+  end
+
+  def yellow
+    colorize(33)
+  end
+
+  def red
+    colorize(31)
+  end
+end
+
+# Get the absolute path to the project directory
+project_dir = Pathname.new(__FILE__).dirname.parent.expand_path
+
+# Print banner
+puts "============================================".blue
+puts "     Rails MCP Server Setup for Claude      ".blue
+puts "============================================".blue
+puts
+
+# Determine the Rails MCP config directory based on platform
+def get_rails_mcp_config_dir
+  if RUBY_PLATFORM.match?(/mswin|mingw|cygwin/)
+    # Windows
+    File.join(ENV["APPDATA"], "rails-mcp")
+  else
+    # Linux/Unix - honor XDG_CONFIG_HOME
+    xdg_config_home = ENV["XDG_CONFIG_HOME"]
+    if xdg_config_home && !xdg_config_home.empty?
+      File.join(xdg_config_home, "rails-mcp")
+    else
+      File.join(Dir.home, ".config", "rails-mcp")
+    end
+  end
+end
+
+rails_mcp_config_dir = get_rails_mcp_config_dir
+rails_mcp_log_dir = File.join(rails_mcp_config_dir, "log")
+
+# Create config and log directories
+FileUtils.mkdir_p(rails_mcp_log_dir)
+puts "✓".green + " Created Rails MCP config directory: #{rails_mcp_config_dir}"
+puts "✓".green + " Created Rails MCP log directory: #{rails_mcp_log_dir}"
+
+# Create projects.yml in the config dir if it doesn't exist
+projects_yml = File.join(rails_mcp_config_dir, "projects.yml")
+
+if !File.exist?(projects_yml)
+  # Create a new projects.yml with explanatory comments
+  File.write(projects_yml, "# Rails MCP Projects\n# Format: project_name: /path/to/project\n")
+  puts "✓".green + " Created projects.yml file"
+  puts "!".yellow + " Please edit #{projects_yml} to add your Rails projects"
+else
+  puts "✓".green + " projects.yml already exists at #{projects_yml}"
+end
+
+# Detect OS for Claude Desktop config
+claude_config_dir = if RUBY_PLATFORM.match?(/mswin|mingw|cygwin/)
+  File.join(ENV["APPDATA"], "Claude")
+else
+  File.expand_path("~/Library/Application Support/Claude")
+end
+claude_config_file = File.join(claude_config_dir, "claude_desktop_config.json")
+
+puts
+puts "This script will configure Claude Desktop to use your Rails MCP Server.".blue
+puts "This will modify: #{claude_config_file}".blue
+puts "Rails MCP config directory: #{rails_mcp_config_dir}".blue
+puts
+
+# Ask for confirmation
+print "Do you want to continue? (y/n) "
+unless gets.chomp.casecmp("y").zero?
+  puts "Setup canceled.".yellow
+  exit(0)
+end
+
+# Create the config directory if it doesn't exist
+FileUtils.mkdir_p(claude_config_dir)
+
+# Full path to the rails-mcp-server executable
+server_path = File.join(project_dir, "exe", "rails-mcp-server")
+
+# Ensure the server is executable
+FileUtils.chmod("+x", server_path)
+puts "✓".green + " Made server executable"
+
+# Create or update the Claude Desktop config file
+config = {}
+
+if File.exist?(claude_config_file)
+  begin
+    config = JSON.parse(File.read(claude_config_file))
+  rescue JSON::ParserError
+    puts "Error:".red + " Existing config file is not valid JSON. Creating backup and new config."
+    FileUtils.cp(claude_config_file, "#{claude_config_file}.bak")
+    config = {}
+  end
+end
+
+# Update configuration
+config["mcpServers"] ||= {}
+config["mcpServers"]["railsMcpServer"] = {"command" => "ruby", "args" => [server_path]}
+
+# Write configuration back to file
+File.write(claude_config_file, JSON.pretty_generate(config))
+
+puts "✓".green + " Updated Claude Desktop configuration"
+puts
+puts "Setup completed!".blue
+puts "!".yellow + " Please restart Claude Desktop to apply the changes."
+puts
+puts "Your Rails MCP Server is now configured at:".blue
+puts "  #{server_path}"
+puts
+puts "Using config:".blue
+puts "  Projects file: #{projects_yml}"
+puts "  Log directory: #{rails_mcp_log_dir}"
+puts
+puts "To use it in Claude Desktop:".blue
+puts "1. Restart Claude Desktop"
+puts "2. Click on the plugin icon in the chat interface"
+puts "3. Select 'Rails MCP Server' from the list"
+puts
+puts "!".yellow + " Don't forget to edit your projects.yml file to add your Rails projects:"
+puts "  #{projects_yml}"
+puts
+puts "============================================".blue

data/lib/rails-mcp-server/version.rb

@@ -0,0 +1,3 @@
+module RailsMcpServer
+  VERSION = "1.0.0"
+end

data/lib/rails_mcp_server.rb

@@ -0,0 +1,509 @@
+#!/usr/bin/env ruby
+
+require "mcp"
+require "yaml"
+require "logger"
+require "json"
+require "fileutils"
+require_relative "rails-mcp-server/version"
+
+module RailsMcpServer
+  class Error < StandardError; end
+end
+
+# rubocop:disable Style/GlobalVars
+# Initialize configuration
+def get_config_dir
+  # Use XDG_CONFIG_HOME if set, otherwise use ~/.config
+  xdg_config_home = ENV["XDG_CONFIG_HOME"]
+  if xdg_config_home && !xdg_config_home.empty?
+    File.join(xdg_config_home, "rails-mcp")
+  else
+    File.join(Dir.home, ".config", "rails-mcp")
+  end
+end
+
+# Create config directory if it doesn't exist
+config_dir = get_config_dir
+FileUtils.mkdir_p(File.join(config_dir, "log"))
+
+# Default paths
+projects_file = File.join(config_dir, "projects.yml")
+log_file = File.join(config_dir, "log", "rails_mcp_server.log")
+log_level = :info
+
+# Parse command-line arguments
+i = 0
+while i < ARGV.length
+  case ARGV[i]
+  when "--log-level"
+    log_level = ARGV[i + 1].to_sym
+    i += 2
+  else
+    i += 1
+  end
+end
+
+# Initialize logger
+$logger = Logger.new(log_file)
+$logger.level = Logger.const_get(log_level.to_s.upcase)
+
+# Set a nicer formatter
+$logger.formatter = proc do |severity, datetime, progname, msg|
+  "[#{datetime.strftime("%Y-%m-%d %H:%M:%S")}] #{severity}: #{msg}\n"
+end
+
+def log(level, message)
+  levels = {debug: Logger::DEBUG, info: Logger::INFO, warn: Logger::WARN, error: Logger::ERROR, fatal: Logger::FATAL}
+  log_level = levels[level] || Logger::INFO
+  $logger.add(log_level, message)
+end
+
+log(:info, "Starting Rails MCP Server...")
+log(:info, "Using config directory: #{config_dir}")
+
+# Create empty projects file if it doesn't exist
+unless File.exist?(projects_file)
+  log(:info, "Creating empty projects file: #{projects_file}")
+  FileUtils.mkdir_p(File.dirname(projects_file))
+  File.write(projects_file, "# Rails MCP Projects\n# Format: project_name: /path/to/project\n")
+end
+
+# Load projects
+projects_file = File.expand_path(projects_file)
+projects = {}
+
+if File.exist?(projects_file)
+  log(:info, "Loading projects from: #{projects_file}")
+  projects = YAML.load_file(projects_file) || {}
+  log(:info, "Loaded #{projects.size} projects: #{projects.keys.join(", ")}")
+else
+  log(:warn, "Projects file not found: #{projects_file}")
+end
+
+# Initialize state
+$active_project = nil
+$active_project_path = nil
+
+# Define MCP server using the mcp-rb DSL
+name "rails-mcp-server"
+version RailsMcpServer::VERSION
+
+# Utility functions for Rails operations
+def get_directory_structure(path, max_depth: 3, current_depth: 0, prefix: "")
+  return "" if current_depth > max_depth || !File.directory?(path)
+
+  output = ""
+  directories = []
+  files = []
+
+  Dir.foreach(path) do |entry|
+    next if entry == "." || entry == ".."
+    full_path = File.join(path, entry)
+
+    if File.directory?(full_path)
+      directories << entry
+    else
+      files << entry
+    end
+  end
+
+  directories.sort.each do |dir|
+    output << "#{prefix}└── #{dir}/\n"
+    full_path = File.join(path, dir)
+    output << get_directory_structure(full_path, max_depth: max_depth,
+      current_depth: current_depth + 1,
+      prefix: "#{prefix}    ")
+  end
+
+  files.sort.each do |file|
+    output << "#{prefix}└── #{file}\n"
+  end
+
+  output
+end
+
+def get_file_extension(path)
+  case File.extname(path).downcase
+  when ".rb"
+    "ruby"
+  when ".js"
+    "javascript"
+  when ".html", ".erb"
+    "html"
+  when ".css"
+    "css"
+  when ".json"
+    "json"
+  when ".yml", ".yaml"
+    "yaml"
+  else
+    ""
+  end
+end
+
+def execute_rails_command(project_path, command)
+  full_command = "cd #{project_path} && bin/rails #{command}"
+  `#{full_command}`
+end
+
+def underscore(string)
+  string.gsub("::", "/")
+    .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+    .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+    .tr("-", "_")
+    .downcase
+end
+
+# Define tools using the mcp-rb DSL
+tool "switch_project" do
+  description "Change the active Rails project to interact with a different codebase. Must be called before using other tools. Available projects are defined in the projects.yml configuration file."
+
+  argument :project_name, String, required: true,
+    description: "Name of the project as defined in the projects.yml file (case-sensitive)"
+
+  call do |args|
+    project_name = args[:project_name]
+
+    if projects.key?(project_name)
+      $active_project = project_name
+      $active_project_path = File.expand_path(projects[project_name])
+      log(:info, "Switched to project: #{project_name} at path: #{$active_project_path}")
+      "Switched to project: #{project_name} at path: #{$active_project_path}"
+    else
+      log(:warn, "Project not found: #{project_name}")
+      raise "Project '#{project_name}' not found. Available projects: #{projects.keys.join(", ")}"
+    end
+  end
+end
+
+tool "get_project_info" do
+  description "Retrieve comprehensive information about the current Rails project, including Rails version, directory structure, API-only status, and overall project organization. Useful for initial project exploration and understanding the codebase structure."
+
+  call do |args|
+    unless $active_project
+      raise "No active project. Please switch to a project first."
+    end
+
+    # Get additional project information
+    gemfile_path = File.join($active_project_path, "Gemfile")
+    gemfile_content = File.exist?(gemfile_path) ? File.read(gemfile_path) : "Gemfile not found"
+
+    # Get Rails version
+    rails_version = gemfile_content.match(/gem ['"]rails['"],\s*['"](.+?)['"]/)&.captures&.first || "Unknown"
+
+    # Check if it's an API-only app
+    config_application_path = File.join($active_project_path, "config", "application.rb")
+    is_api_only = File.exist?(config_application_path) &&
+      File.read(config_application_path).include?("config.api_only = true")
+
+    log(:info, "Project info: Rails v#{rails_version}, API-only: #{is_api_only}")
+
+    <<~INFO
+      Current project: #{$active_project}
+      Path: #{$active_project_path}
+      Rails version: #{rails_version}
+      API only: #{is_api_only ? "Yes" : "No"}
+      
+      Project structure:
+      #{get_directory_structure($active_project_path, max_depth: 2)}
+    INFO
+  end
+end
+
+tool "list_files" do
+  description "List files in the Rails project matching specific criteria. Use this to explore project directories or locate specific file types. If no parameters are provided, lists files in the project root."
+
+  argument :directory, String, required: false,
+    description: "Directory path relative to the project root (e.g., 'app/models', 'config'). Leave empty to list files at the root."
+
+  argument :pattern, String, required: false,
+    description: "File pattern using glob syntax (e.g., '*.rb' for Ruby files, '*.erb' for ERB templates, '*_controller.rb' for controllers)"
+
+  call do |args|
+    unless $active_project
+      raise "No active project. Please switch to a project first."
+    end
+
+    directory = args[:directory] || ""
+    pattern = args[:pattern] || "*"
+
+    full_path = File.join($active_project_path, directory)
+
+    unless File.directory?(full_path)
+      raise "Directory '#{directory}' not found in the project."
+    end
+
+    # Use Dir.glob to get matching files
+    files = Dir.glob(File.join(full_path, pattern))
+      .map { |f| f.sub("#{$active_project_path}/", "") }
+      .sort # rubocop:disable Performance/ChainArrayAllocation
+
+    log(:debug, "Found #{files.size} files matching pattern")
+
+    "Files in #{directory.empty? ? "project root" : directory} matching '#{pattern}':\n\n#{files.join("\n")}"
+  end
+end
+
+tool "get_file" do
+  description "Retrieve the complete content of a specific file with syntax highlighting. Use this to examine implementation details, configurations, or any text file in the project."
+
+  argument :path, String, required: true,
+    description: "File path relative to the project root (e.g., 'app/models/user.rb', 'config/routes.rb'). Use list_files first if you're not sure about the exact path."
+
+  call do |args|
+    unless $active_project
+      raise "No active project. Please switch to a project first."
+    end
+
+    path = args[:path]
+    full_path = File.join($active_project_path, path)
+
+    unless File.exist?(full_path)
+      raise "File '#{path}' not found in the project."
+    end
+
+    content = File.read(full_path)
+    log(:debug, "Read file: #{path} (#{content.size} bytes)")
+
+    "File: #{path}\n\n```#{get_file_extension(path)}\n#{content}\n```"
+  end
+end
+
+tool "get_routes" do
+  description "Retrieve all HTTP routes defined in the Rails application with their associated controllers and actions. Equivalent to running 'rails routes' command. This helps understand the API endpoints or page URLs available in the application."
+
+  call do |args|
+    unless $active_project
+      raise "No active project. Please switch to a project first."
+    end
+
+    # Execute the Rails routes command
+    routes_output = execute_rails_command($active_project_path, "routes")
+    log(:debug, "Routes command completed, output size: #{routes_output.size} bytes")
+
+    "Rails Routes:\n\n```\n#{routes_output}\n```"
+  end
+end
+
+tool "get_models" do
+  description "Retrieve detailed information about Active Record models in the project. When called without parameters, lists all model files. When a specific model is specified, returns its schema, associations (has_many, belongs_to, has_one), and complete source code."
+
+  argument :model_name, String, required: false,
+    description: "Class name of a specific model to get detailed information for (e.g., 'User', 'Product'). Use CamelCase, not snake_case. If omitted, returns a list of all models."
+
+  call do |args|
+    unless $active_project
+      raise "No active project. Please switch to a project first."
+    end
+
+    model_name = args[:model_name]
+
+    if model_name
+      log(:info, "Getting info for specific model: #{model_name}")
+
+      # Check if the model file exists
+      model_file = File.join($active_project_path, "app", "models", "#{underscore(model_name)}.rb")
+      unless File.exist?(model_file)
+        log(:warn, "Model file not found: #{model_name}")
+        raise "Model '#{model_name}' not found."
+      end
+
+      log(:debug, "Reading model file: #{model_file}")
+
+      # Get the model file content
+      model_content = File.read(model_file)
+
+      # Try to get schema information
+      log(:debug, "Executing Rails runner to get schema information")
+      schema_info = execute_rails_command(
+        $active_project_path,
+        "runner \"puts #{model_name}.column_names\""
+      )
+
+      # Try to get associations
+      associations = []
+      if model_content.include?("has_many")
+        has_many = model_content.scan(/has_many\s+:(\w+)/).flatten
+        associations << "Has many: #{has_many.join(", ")}" unless has_many.empty?
+      end
+
+      if model_content.include?("belongs_to")
+        belongs_to = model_content.scan(/belongs_to\s+:(\w+)/).flatten
+        associations << "Belongs to: #{belongs_to.join(", ")}" unless belongs_to.empty?
+      end
+
+      if model_content.include?("has_one")
+        has_one = model_content.scan(/has_one\s+:(\w+)/).flatten
+        associations << "Has one: #{has_one.join(", ")}" unless has_one.empty?
+      end
+
+      log(:debug, "Found #{associations.size} associations for model: #{model_name}")
+
+      # Format the output
+      <<~INFO
+        Model: #{model_name}
+        
+        Schema:
+        #{schema_info}
+        
+        Associations:
+        #{associations.empty? ? "None found" : associations.join("\n")}
+        
+        Model Definition:
+        ```ruby
+        #{model_content}
+        ```
+      INFO
+    else
+      log(:info, "Listing all models")
+
+      # List all models
+      models_dir = File.join($active_project_path, "app", "models")
+      unless File.directory?(models_dir)
+        raise "Models directory not found."
+      end
+
+      # Get all .rb files in the models directory and its subdirectories
+      model_files = Dir.glob(File.join(models_dir, "**", "*.rb"))
+        .map { |f| f.sub("#{models_dir}/", "").sub(/\.rb$/, "") }
+        .sort # rubocop:disable Performance/ChainArrayAllocation
+
+      log(:debug, "Found #{model_files.size} model files")
+
+      "Models in the project:\n\n#{model_files.join("\n")}"
+    end
+  end
+end
+
+tool "get_schema" do
+  description "Retrieve database schema information for the Rails application. Without parameters, returns all tables and the complete schema.rb. With a table name, returns detailed column information including data types, constraints, and foreign keys for that specific table."
+
+  argument :table_name, String, required: false,
+    description: "Database table name to get detailed schema information for (e.g., 'users', 'products'). Use snake_case, plural form. If omitted, returns complete database schema."
+
+  call do |args|
+    unless $active_project
+      raise "No active project. Please switch to a project first."
+    end
+
+    table_name = args[:table_name]
+
+    if table_name
+      log(:info, "Getting schema for table: #{table_name}")
+
+      # Execute the Rails schema command for a specific table
+      schema_output = execute_rails_command(
+        $active_project_path,
+        "runner \"require 'active_record'; puts ActiveRecord::Base.connection.columns('#{table_name}').map{|c| [c.name, c.type, c.null, c.default].inspect}.join('\n')\""
+      )
+
+      if schema_output.strip.empty?
+        raise "Table '#{table_name}' not found or has no columns."
+      end
+
+      # Parse the column information
+      columns = schema_output.strip.split("\n").map do |column_info|
+        eval(column_info) # This is safe because we're generating the string ourselves # rubocop:disable Security/Eval
+      end
+
+      # Format the output
+      formatted_columns = columns.map do |name, type, nullable, default|
+        "#{name} (#{type})#{nullable ? ", nullable" : ""}#{default ? ", default: #{default}" : ""}"
+      end
+
+      output = <<~SCHEMA
+        Table: #{table_name}
+        
+        Columns:
+        #{formatted_columns.join("\n")}
+      SCHEMA
+
+      # Try to get foreign keys
+      begin
+        fk_output = execute_rails_command(
+          $active_project_path,
+          "runner \"require 'active_record'; puts ActiveRecord::Base.connection.foreign_keys('#{table_name}').map{|fk| [fk.from_table, fk.to_table, fk.column, fk.primary_key].inspect}.join('\n')\""
+        )
+
+        unless fk_output.strip.empty?
+          foreign_keys = fk_output.strip.split("\n").map do |fk_info|
+            eval(fk_info) # This is safe because we're generating the string ourselves # rubocop:disable Security/Eval
+          end
+
+          formatted_fks = foreign_keys.map do |from_table, to_table, column, primary_key|
+            "#{column} -> #{to_table}.#{primary_key}"
+          end
+
+          output += <<~FK
+            
+            Foreign Keys:
+            #{formatted_fks.join("\n")}
+          FK
+        end
+      rescue => e
+        log(:warn, "Error fetching foreign keys: #{e.message}")
+      end
+
+      output
+    else
+      log(:info, "Getting full schema")
+
+      # Execute the Rails schema:dump command
+      # First, check if we need to create the schema file
+      schema_file = File.join($active_project_path, "db", "schema.rb")
+      unless File.exist?(schema_file)
+        log(:info, "Schema file not found, attempting to generate it")
+        execute_rails_command($active_project_path, "db:schema:dump")
+      end
+
+      if File.exist?(schema_file)
+        # Read the schema file
+        schema_content = File.read(schema_file)
+
+        # Try to get table list
+        tables_output = execute_rails_command(
+          $active_project_path,
+          "runner \"require 'active_record'; puts ActiveRecord::Base.connection.tables.sort.join('\n')\""
+        )
+
+        tables = tables_output.strip.split("\n")
+
+        <<~SCHEMA
+          Database Schema
+          
+          Tables:
+          #{tables.join("\n")}
+          
+          Schema Definition:
+          ```ruby
+          #{schema_content}
+          ```
+        SCHEMA
+
+      else
+        # If we can't get the schema file, try to get the table list
+        tables_output = execute_rails_command(
+          $active_project_path,
+          "runner \"require 'active_record'; puts ActiveRecord::Base.connection.tables.sort.join('\n')\""
+        )
+
+        if tables_output.strip.empty?
+          raise "Could not retrieve schema information. Try running 'rails db:schema:dump' in your project first."
+        end
+
+        tables = tables_output.strip.split("\n")
+
+        <<~SCHEMA
+          Database Schema
+          
+          Tables:
+          #{tables.join("\n")}
+          
+          Note: Full schema definition is not available. Run 'rails db:schema:dump' to generate the schema.rb file.
+        SCHEMA
+      end
+    end
+  end
+end
+# rubocop:enable Style/GlobalVars

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: rails-mcp-server
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Mario Alberto Chávez Cárdenas
+bindir: exe
+cert_chain: []
+date: 2025-03-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mcp-rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  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 Ruby implementation of Model Context Protocol server for Rails projects
+email:
+- mario.chavez@gmail.com
+executables:
+- rails-mcp-server
+- rails-mcp-setup-claude
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/rails-mcp-server
+- exe/rails-mcp-setup-claude
+- lib/rails-mcp-server/version.rb
+- lib/rails_mcp_server.rb
+homepage: https://github.com/maquina-app/rails-mcp-server
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/maquina-app/rails-mcp-server
+  source_code_uri: https://github.com/maquina-app/rails-mcp-server
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: MCP server for Rails projects
+test_files: []