DOCSEARCHbyAlgolia
Submit Docs

rails-mcp-server

repository·main·Indexed 20 days ago

https://github.com/maquina-app/rails-mcp-server

A Ruby implementation of a Model Context Protocol (MCP) server for Rails projects. It enables LLMs to perform code analysis, explore project structures, inspect routes, models, and schemas, and access Rails-specific documentation. The server supports STDIO and HTTP modes and integrates with clients like Claude Desktop and GitHub Copilot Agent via a progressive tool discovery architecture using bootstrap tools: switch_project, search_tools, and execute_tool.

Tokens
11.1K
Snippets
33
Records
51
Agent score
66%

What's inside rails-mcp-server

  1. How the Rails MCP Server works

    main

    The Rails MCP Server implements the Model Context Protocol using two modes:

    • STDIO mode: Reads JSON-RPC 2.0 requests from standard input and returns responses to standard output. This is the default mode for integration with LLM clients like Claude Desktop.
    • HTTP mode: Provides HTTP endpoints for JSON-RPC 2.0 requests and Server-Sent Events.

    Context-Efficient Architecture

    The server uses a progressive tool discovery architecture to minimize context usage. Instead of exposing all tools upfront, it provides 3 bootstrap tools that allow LLMs to discover and invoke introspection analyzers on-demand:

    1. switch_project: Select the active Rails project.
    2. search_tools: Discover available tools by category or keyword.
    3. execute_tool: Invoke internal analyzers with parameters.

    This design keeps the initial context small while exposing the full set of analyzers only when needed.

  2. What are Resources in Rails MCP Server

    main

    Resources are documentation guides accessible via two methods:

    1. Tool-based access: Using the load_guide tool to retrieve specific guides.
    2. Direct resource access: MCP clients can query resources directly using URI templates.

    Resources are stored locally in your configuration directory and fall into two types:

    • Predefined resources: Official documentation for Rails, Turbo, Stimulus, and Kamal.
    • Custom resources: Your own markdown files imported into the system.

    Storage Locations:

    • macOS: ~/.config/rails-mcp/resources/
    • Windows: %APPDATA%\rails-mcp\resources\

  3. Import Custom Markdown Guides

    main

    You can import your own markdown files into the custom guides category using the --file option. The system performs filename normalization (converting to lowercase with underscores) and updates a custom manifest.

    Importing Methods:

    • Single File: Pass the path to a specific .md file.
    • Directory: Pass a directory path to import all markdown files within it.

    Normalization Example:

    • API Documentation.md becomes api_documentation.md.
    • Setup-Guide.md becomes setup_guide.md.
    # Import a single markdown file
rails-mcp-server-download-resources --file /path/to/guide.md

# Force import even if file hasn't changed
rails-mcp-server-download-resources --force --file /path/to/api-docs.md

# Import all markdown files from a directory
rails-mcp-server-download-resources --file /path/to/docs/

# Verbose import with progress information
rails-mcp-server-download-resources --verbose --file /path/to/project-docs/

  4. Start the Rails MCP Server in different modes

    main

    The server supports two communication modes:

    1. STDIO mode (default): Used 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.

    HTTP Mode Endpoints

    • JSON-RPC: http://localhost:<port>/mcp/messages
    • SSE: http://localhost:<port>/mcp/sse
    # 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

  5. Configure Claude Desktop integration

    main

    You can integrate the Rails MCP Server with Claude Desktop using one of three methods:

    Option 1: Configuration Tool (Recommended)

    Run rails-mcp-config and select "Claude Desktop integration". It handles path detection and configuration automatically.

    Option 2: Legacy Setup Script

    Run rails-mcp-setup-claude to automatically update your Claude Desktop configuration.

    Option 3: Direct Configuration

    Manually add the server to your claude_desktop_config.json file.

    Note for Ruby Version Manager users: If you use rbenv, asdf, mise, or rvm, you must point the command in your Claude configuration to the absolute path of your Ruby shim (e.g., /home/user/.rbenv/shims/ruby) to ensure the server starts correctly.

    {
  "mcpServers": {
    "railsMcpServer": {
      "command": "/home/your_user/.rbenv/shims/ruby",
      "args": ["/full/path/to/rails-mcp-server/exe/rails-mcp-server"]
    }
  }
}

  6. Start Rails MCP Server for Governed Client Integration

    main

    Depending on your integration needs (local development vs. proxy/SSE testing), use one of the following commands to start the server:

    • Standard Mode (STDIO): Best for local development or direct client connections.
    • HTTP Mode: Best for testing via HTTP/SSE or when using a local proxy/control plane.
    # For local development (STDIO mode)
rails-mcp-server

# For HTTP/SSE testing or a local proxy
rails-mcp-server --mode http

  7. Download Predefined Documentation Resources

    main

    Before using predefined resources, you must download them using the rails-mcp-server-download-resources CLI tool. This tool sets up the directory structure, fetches documentation from official repositories, and generates a manifest.yaml to track files.

    Available Categories:

    • rails (Official Rails 8.0.2 documentation)
    • turbo (Official Turbo framework documentation)
    • stimulus (Official Stimulus JavaScript framework documentation)
    • kamal (Official Kamal deployment tool documentation)
    # Download Rails guides
rails-mcp-server-download-resources rails

# Download Turbo guides
rails-mcp-server-download-resources turbo

# Download Stimulus guides
rails-mcp-server-download-resources stimulus

# Download Kamal guides
rails-mcp-server-download-resources kamal

  8. Use an MCP Proxy for HTTP/SSE support in STDIO clients

    main

    If you want to use the HTTP/SSE capabilities of the server with a client that only supports STDIO (like Claude Desktop), use an MCP proxy like mcp-remote.

    1. Start the server in HTTP mode: rails-mcp-server --mode http.
    2. Run the proxy pointing to the SSE endpoint.
    3. Configure your client to use the proxy command.
    # 1. Start server
rails-mcp-server --mode http

# 2. Run proxy
npx mcp-remote http://localhost:6029/mcp/sse

# 3. Claude Desktop config
{
  "mcpServers": {
    "railsMcpServer": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:6029/mcp/sse"]
    }
  }
}

  9. Security Best Practices for Governed MCP Deployments

    main

    When using Rails MCP Server within a governed workflow or production AI pipeline, follow these security guidelines:

    • Network Isolation: Never expose Rails MCP Server on an untrusted network.
    • Mode Selection: Prefer STDIO or localhost HTTP mode unless you are on a trusted network with explicit access controls.
    • Credential Safety: Keep Rails project paths, credentials, and .env files strictly local to the server environment.
    • Risk Mitigation: Use your governed client to restrict access to high-risk tools, such as code execution or broad project scans.
    • Observability: When possible, preserve request IDs or trace IDs in client metadata to correlate tool calls with model calls.

  10. Integrate Rails MCP Server with GitHub Copilot Agent

    main

    To use Rails MCP Server with the GitHub Copilot coding agent, you must configure the agent to run the server in its ephemeral GitHub Actions environment. This requires two main configuration files in your repository: an MCP configuration file and a GitHub Actions workflow to set up the environment.

    Prerequisites

    • A Rails application repository on GitHub
    • GitHub Copilot with coding agent enabled
    • Ruby 3.3+ (recommended: 3.4)

    Step 1: MCP Configuration

    Create .github/copilot/mcp.json to define the server. It is recommended to use the --single-project flag to ensure the agent uses the current directory as the project root.

    Step 2: Setup Steps Workflow

    Create .github/workflows/copilot-setup-steps.yml to prepare the environment. This workflow must install Ruby, the rails-mcp-server gem, and your project's dependencies (bundle install).

    // .github/copilot/mcp.json
{
  "mcpServers": {
    "rails": {
      "type": "local",
      "command": "rails-mcp-server",
      "args": ["--single-project"],
      "tools": ["switch_project", "search_tools", "execute_tool"]
    }
  }
}

  11. Integrate Rails MCP Server with a Governed AI Client

    main

    To manage tool access, audit trails, approvals, and cost controls centrally, you can connect Rails MCP Server to a governed AI client or control plane (such as Tuning Engines).

    In this architecture, Rails MCP Server remains the owner of the Rails project tools and resources, while the governed client/gateway manages model access, policy decisions, and cross-application reporting.

    Integration Pattern

    1. Start the server: Run Rails MCP Server in either STDIO or HTTP mode.
    2. Register: Add the server to your MCP-compatible client or control plane.
    3. Enforce Policy: Use the client to decide which users, roles, or agents are permitted to call specific Rails MCP tools.
    4. Isolate Credentials: Ensure Rails project paths and credentials remain local to the Rails MCP Server environment.

  12. Integrate with GitHub Copilot Agent

    main

    The Rails MCP Server works with GitHub Copilot coding agents. You can configure it by creating a .github/copilot/mcp.json file in your repository or by using the RAILS_MCP_PROJECT_PATH environment variable.

    Limitations: GitHub Copilot Agent only supports MCP tools (not resources or prompts). The load_guide analyzer requires guides to be downloaded during setup via execute_tool.

    // .github/copilot/mcp.json
{
  "mcpServers": {
    "rails": {
      "type": "local",
      "command": "rails-mcp-server",
      "args": ["--single-project"],
      "tools": ["switch_project", "search_tools", "execute_tool"]
    }
  }
}