rails-mcp-server

# 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, providing capabilities for code analysis, exploration, and development assistance. ## 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 with filtering options - Inspect model information and relationships (with Prism static analysis) - Get database schema information - Analyze controller-view relationships - Analyze environment configurations - Execute sandboxed Ruby code for custom queries - Access comprehensive Rails, Turbo, Stimulus, and Kamal documentation - Context-efficient architecture with progressive tool discovery - Seamless integration with LLM clients ## Installation Install the gem: ```bash gem install rails-mcp-server ``` After installation, the following executables will be available in your PATH: - `rails-mcp-server` - The MCP server itself - `rails-mcp-config` - Interactive configuration tool (recommended) - `rails-mcp-setup-claude` - Legacy Claude Desktop setup script - `rails-mcp-server-download-resources` - Legacy resource download script ## Configuration ### Using the Configuration Tool (Recommended) The easiest way to configure the Rails MCP Server is using the interactive configuration tool: ```bash rails-mcp-config ``` This provides a user-friendly TUI (Terminal User Interface) for: - **Managing Projects**: Add, edit, remove, and validate Rails projects - **Downloading Guides**: Download Rails, Turbo, Stimulus, and Kamal documentation - **Importing Custom Guides**: Add your own markdown documentation - **Claude Desktop Integration**: Automatically configure Claude Desktop The tool uses [Gum](https://github.com/charmbracelet/gum) for an enhanced experience if installed, but works with a basic terminal fallback. ```bash # Install Gum for best experience (optional) brew install gum # macOS sudo apt install gum # Debian/Ubuntu yay -S gum # Arch Linux ``` ### Manual 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 manually: 1. Edit the `projects.yml` file in your config directory to include your Rails projects: ```yaml store: "~/projects/store" blog: "~/projects/rails-blog" ecommerce: "/full/path/to/ecommerce-app" ``` 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. ## Usage ### Starting the server The Rails MCP Server can run in two modes: 1. **STDIO mode (default)**: Communicates over standard input/output for direct integration with clients like Claude Desktop. 2. **HTTP mode**: Runs as an HTTP server with JSON-RPC and Server-Sent Events (SSE) endpoints. ```bash # Start in default STDIO mode rails-mcp-server # Start in HTTP mode on the default port (6029) rails-mcp-server --mode http # Start in HTTP mode on a custom port rails-mcp-server --mode http -p 8080 # Start in HTTP mode binding to all interfaces (for local network access) rails-mcp-server --mode http --bind-all ``` When running in HTTP mode, the server provides two endpoints: - JSON-RPC endpoint: `http://localhost:<port>/mcp/messages` - SSE endpoint: `http://localhost:<port>/mcp/sse` ### Network Access (HTTP Mode) By default, the HTTP server only binds to localhost for security. If you need to access the server from other machines on your local network (e.g., for testing with multiple devices), you can use the `--bind-all` flag: ```bash # Allow access from any machine on your local network rails-mcp-server --mode http --bind-all # With a custom port rails-mcp-server --mode http --bind-all -p 8080 ``` When using `--bind-all`: - The server binds to `0.0.0.0` instead of `localhost` - Access is allowed from local network IP ranges (192.168.x.x, 10.x.x.x) - The server accepts connections from `.local` domain names (e.g., `my-computer.local`) - Security features remain active to prevent unauthorized access **Security Note**: Only use `--bind-all` on trusted networks. The server includes built-in security features to validate origins and IP addresses, but exposing any service to your network increas