Rails MCP Server

Rails MCP 服务

一个面向 Rails 项目的 MCP（模型上下文协议）服务 Ruby 实现。此服务允许大模型通过模型上下文协议与 Rails 项目交互，提供代码分析、探索和开发辅助功能。

什么是 MCP？

模型上下文协议（MCP）是 AI 模型与其环境交互的标准化方式。它定义了一种结构化方法，让模型能够请求和使用工具、访问资源，并在交互过程中维护上下文。

此 Rails MCP 服务实现了 MCP 规范，让 AI 模型能够访问 Rails 项目，以进行代码分析、探索和辅助工作。

功能

• 管理多个 Rails 项目
• 浏览项目文件和结构
• 查看 Rails 路由，并使用筛选选项
• 检查模型信息和关联关系（使用 Prism 静态分析）
• 获取数据库架构信息
• 分析控制器与视图之间的关系
• 分析环境配置
• 访问全面的 Rails、Turbo、Stimulus 和 Kamal 文档
• 采用上下文高效的架构，逐步发现工具
• 与大模型客户端无缝集成

安装

安装 gem：

gem install rails-mcp-server

安装后，以下可执行文件将可在 PATH 中使用：

• rails-mcp-server - MCP 服务本身
• rails-mcp-config - 交互式配置工具（推荐）
• rails-mcp-setup-claude - 旧版 Claude Desktop 设置脚本
• rails-mcp-server-download-resources - 旧版资源下载脚本

配置

使用配置工具（推荐）

配置 Rails MCP 服务最简单的方法是使用交互式配置工具：

rails-mcp-config

此工具提供易用的 TUI（终端用户界面），用于：

• 管理项目：添加、编辑、移除和验证 Rails 项目
• 下载指南：下载 Rails、Turbo、Stimulus 和 Kamal 文档
• 导入自定义指南：添加你自己的 Markdown 文档
• Claude Desktop 集成：自动配置 Claude Desktop

如果已安装，此工具会使用 Gum 提供更好的体验；否则会使用基础终端回退方案。

# Install Gum for best experience (optional)
brew install gum        # macOS
sudo apt install gum    # Debian/Ubuntu
yay -S gum              # Arch Linux

手动配置

Rails MCP 服务遵循 XDG 基础目录规范来存放配置文件：

• 在 macOS 上：$XDG_CONFIG_HOME/rails-mcp，若未设置 XDG_CONFIG_HOME，则使用 ~/.config/rails-mcp
• 在 Windows 上：%APPDATA%\rails-mcp

服务首次运行时会自动创建这些目录和一个空的 projects.yml 文件。

如需手动配置项目：

1. 编辑配置目录中的 projects.yml 文件，将 Rails 项目添加进去：

store: "~/projects/store"
blog: "~/projects/rails-blog"
ecommerce: "/full/path/to/ecommerce-app"

YAML 文件中的每个键都是项目名称（将与 switch_project 工具配合使用），每个值都是项目目录的路径。

用法

启动服务

Rails MCP 服务可在两种模式下运行：

1. STDIO 模式（默认）：通过标准输入/输出通信，可直接与 Claude Desktop 等客户端集成。
2. HTTP 模式：作为 HTTP 服务运行，提供 JSON-RPC 和服务器发送事件（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

在 HTTP 模式下运行时，服务会提供两个端点：

• JSON-RPC 端点：http://localhost:<port>/mcp/messages
• SSE 端点：http://localhost:<port>/mcp/sse

网络访问（HTTP 模式）

出于安全考虑，HTTP 服务器默认只绑定到 localhost。如果需要从本地网络中的其他设备访问服务器（例如，使用多台设备进行测试），可以使用 --bind-all 标志：

# 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

使用 --bind-all 时：

• 服务器绑定到 0.0.0.0，而不是 localhost
• 允许从本地网络 IP 范围（192.168.x.x、10.x.x.x）访问
• 服务器接受来自 .local 域名的连接（例如，my-computer.local）
• 安全功能仍保持启用，以防止未经授权的访问

安全提示：仅在可信网络上使用 --bind-all。服务器内置了用于验证来源和 IP 地址的安全功能，但向网络公开任何服务都会扩大攻击面。

日志选项

默认情况下，服务器会将日志写入 ./log 目录中的文件。可以使用以下选项自定义日志记录：

# Set the log level (debug, info, error)
rails-mcp-server --log-level debug

Claude Desktop 集成

Rails MCP Server 可与 Claude Desktop 搭配使用。有多种设置方式：

选项 1：使用配置工具（推荐）

运行交互式配置工具，并选择“Claude Desktop 集成”：

rails-mcp-config

该工具将：

• 检测当前的 Claude Desktop 配置
• 让你选择 STDIO 或 HTTP 模式
• 自动查找正确的 Ruby 和服务器路径
• 在进行更改前创建备份
• 更新 Claude Desktop 配置

选项 2：使用设置脚本（旧版）

运行设置脚本，它会自动配置 Claude Desktop：

rails-mcp-setup-claude

该脚本将：

• 为你的平台创建相应的配置目录
• 如果 projects.yml 文件不存在，则创建一个空文件
• 更新 Claude Desktop 配置

运行脚本后，重启 Claude Desktop 以应用更改。

选项 3：直接配置

1. 为你的平台创建相应的配置目录：

   • macOS：$XDG_CONFIG_HOME/rails-mcp；如果未设置 XDG_CONFIG_HOME，则使用 ~/.config/rails-mcp
   • Windows：%APPDATA%\rails-mcp

2. 在该目录中创建 projects.yml 文件，并写入你的 Rails 项目。

3. 找到或创建 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

4. 添加或更新 MCP 服务配置：

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

5. 重启 Claude Desktop 以应用更改。

Ruby 版本管理器用户

这里涉及两个不同的 Ruby，服务器对它们的处理方式也不同。

1. 用于运行 MCP 服务的 Ruby

MCP 客户端（例如 Claude Desktop）会使用系统默认的 Ruby 启动服务，而不会初始化版本管理器。服务必须使用安装了其 gem 的 Ruby 运行，否则启动会失败。将客户端的 command 指向该 Ruby 的绝对路径——如果使用版本管理器，其 shim 也可以：

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

将 /home/your_user/.rbenv/shims/ruby 替换为实际的 Ruby 路径（rbenv/mise/asdf shim，或你的 rvm/chruby Ruby）。

提示：rails-mcp-config 工具会自动检测此 Ruby（通过 RbConfig.ruby），并在配置 Claude Desktop 时写入正确的绝对路径。

2. 用于内省各 Rails 项目的 Ruby

启动应用的工具——get_schema、get_routes，以及 analyze_models / analyze_controller_views 中的内省部分——会在项目目录内运行 bin/rails。服务会自动选择项目自己的 Ruby，并且不受版本管理器限制：它会将当前版本管理器的 shim（mise、asdf、rbenv）添加到子进程的 PATH 前面，并在存在 rvm 时加载它，然后使用非登录 shell，避免 macOS 的 path_helper 替换系统 Ruby。Ruby 版本取自项目的 .ruby-version / .tool-versions / .mise.toml，因此不同项目可以使用不同版本的 Ruby，无需额外配置。

无需手动调整 PATH。此前，在使用 mise/asdf 的机器上，这些工具可能会回退到系统 Ruby，导致应用的 Bundler 无法启动。

使用 MCP 代理（高级）

Claude Desktop 和许多其他大模型客户端只支持 STDIO 模式通信，但你可能希望使用服务的 HTTP/SSE 功能。MCP 代理可以弥合这一差距：

1. 以 HTTP 模式启动 Rails MCP Server：

rails-mcp-server --mode http

2. 安装并运行 MCP 代理。有多种不同语言实现的版本可用。MCP 代理可以让只支持 STDIO 通信的客户端通过 HTTP SSE 通信。以下是使用基于 JavaScript 的 MCP 代理的示例：

# Install the Node.js based MCP proxy
npm install -g mcp-remote

# Run the proxy, pointing to your running Rails MCP Server
npx mcp-remote http://localhost:6029/mcp/sse

3. 配置 Claude Desktop（或其他大模型客户端）使用代理，而不是直接连接到服务：

{
  "mcpServers": {
    "railsMcpServer": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:6029/mcp/sse"]
    }
  }
}

通过此设置，只支持 STDIO 的客户端即可通过代理与 Rails MCP Server 通信，在保持客户端兼容性的同时使用 HTTP/SSE 功能。

提示：rails-mcp-config 工具可以自动配置 HTTP 模式并使用 mcp-remote。

GitHub Copilot Agent 集成

Rails MCP Server 开箱即用地支持 GitHub Copilot 编码 Agent。服务启动时会自动检测 Rails 项目；如果通过环境变量配置，也会进行检测。

快速设置

1. 配置 MCP - 在仓库中创建 .github/copilot/mcp.json：

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

2. 设置步骤 - 创建 .github/workflows/copilot-setup-steps.yml：

name: "Copilot Setup Steps"

on: workflow_dispatch

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'
          bundler-cache: true

      - name: Install Rails MCP Server
        run: gem install rails-mcp-server

替代方案：环境变量

你也可以使用 RAILS_MCP_PROJECT_PATH 环境变量：

{
  "mcpServers": {
    "rails": {
      "type": "local",
      "command": "rails-mcp-server",
      "env": {
        "RAILS_MCP_PROJECT_PATH": "."
      },
      "tools": ["switch_project", "search_tools", "execute_tool"]
    }
  }
}

限制

• GitHub Copilot Agent 仅支持 MCP 工具，不支持资源或提示词
• load_guide 分析器可通过 execute_tool 使用，但需要在设置期间下载指南

详细说明请参阅 docs/COPILOT_AGENT.md。

服务的工作方式

Rails MCP Server 使用以下任一模式实现 Model Context Protocol：

• STDIO 模式：从标准输入读取 JSON-RPC 2.0 请求，并将响应写入标准输出。
• HTTP 模式：为 JSON-RPC 2.0 请求和 Server-Sent Events 提供 HTTP 端点。

根据 MCP 规范，每个请求都包含一个序列号，用于将请求与响应匹配。服务会维护项目上下文，并为多个代码库提供 Rails 专属分析功能。

高效利用上下文的架构

服务采用渐进式工具发现架构，以尽量减少上下文用量。它不会一次性公开所有工具，而是提供 3 个引导工具，让大模型能够按需发现并调用内省分析器：

• switch_project - 选择当前 Rails 项目
• search_tools - 按类别或关键字发现可用工具
• execute_tool - 使用参数调用内部分析器

这种设计可以控制初始上下文的大小，同时按需提供完整的分析器集合。

AI Agent 指南

有关使用此服务的 AI Agent（Claude、GPT 等），请参阅全面的 AI Agent 指南，其中涵盖：

• 快速入门工作流
• 常见任务的工具选择指南
• 常见陷阱及规避方法
• 错误处理和回退策略
• 与其他 MCP 服务集成（例如 Neovim MCP）

可用工具

此服务提供 3 个已注册工具，以及可通过 execute_tool 访问的内部分析器。

已注册工具

1. switch_project

说明： 切换当前 Rails 项目。使用其他工具前必须先调用此工具。

参数：

• project_name：（String，必填）项目名称，需与 projects.yml 中定义的名称一致

切换后，你将看到包含常用命令的快速入门指南。

2. search_tools

说明： 按类别或关键词查找可用工具。

参数：

• query：（String，可选）搜索词（例如 'routes'、'model'、'schema'）
• category：（String，可选）按类别筛选：models、database、routing、controllers、files、project、guides
• detail_level：（String，可选）输出详情：'names'、'summary' 或 'full'（默认：'summary'）

3. execute_tool

说明： 按名称调用内部分析器。

参数：

• tool_name：（String，必填）分析器名称（例如 'get_routes'、'analyze_models'）
• params：（Hash，可选）分析器的参数

内部分析器（通过 execute_tool 调用）

project_info

获取全面的项目信息，包括 Rails 版本、目录结构和组织方式。

execute_tool(tool_name: "project_info")

list_files

列出目录中与模式匹配的文件。

execute_tool(tool_name: "list_files", params: { directory: "app/models", pattern: "*.rb" })

get_file

获取指定文件的内容。

execute_tool(tool_name: "get_file", params: { path: "app/models/user.rb" })

get_routes

获取 Rails 路由，可选进行筛选。

execute_tool(tool_name: "get_routes")
execute_tool(tool_name: "get_routes", params: { controller: "users" })
execute_tool(tool_name: "get_routes", params: { verb: "POST" })
execute_tool(tool_name: "get_routes", params: { path_contains: "api" })

analyze_models

分析 Active Record 模型，包括关联、验证，以及可选的 Prism 静态分析。

execute_tool(tool_name: "analyze_models")
execute_tool(tool_name: "analyze_models", params: { model_name: "User" })
execute_tool(tool_name: "analyze_models", params: { model_name: "User", analysis_type: "full" })
execute_tool(tool_name: "analyze_models", params: { detail_level: "names" })

参数：

• model_name：要分析的特定模型
• model_names：要分析的模型数组
• detail_level：'names'、'summary' 或 'full'
• analysis_type：'introspection'、'static' 或 'full'（包括 Prism AST 分析）

get_schema

获取数据库架构信息。

execute_tool(tool_name: "get_schema")
execute_tool(tool_name: "get_schema", params: { table_name: "users" })
execute_tool(tool_name: "get_schema", params: { detail_level: "tables" })

analyze_controller_views

分析控制器与视图之间的关系，可选进行 Prism 静态分析。

execute_tool(tool_name: "analyze_controller_views")
execute_tool(tool_name: "analyze_controller_views", params: { controller_name: "users" })
execute_tool(tool_name: "analyze_controller_views", params: { controller_name: "users", analysis_type: "full" })

analyze_environment_config

分析环境配置中的不一致和安全问题。

execute_tool(tool_name: "analyze_environment_config")

load_guide

加载来自 Rails、Turbo、Stimulus、Kamal 或 Custom 的文档指南。

execute_tool(tool_name: "load_guide", params: { library: "rails" })
execute_tool(tool_name: "load_guide", params: { library: "rails", guide: "getting_started" })
execute_tool(tool_name: "load_guide", params: { library: "turbo" })
execute_tool(tool_name: "load_guide", params: { library: "stimulus" })
execute_tool(tool_name: "load_guide", params: { library: "custom", guide: "tailwind" })

资源和文档

Rails MCP Server 可通过 load_guide 工具和直接访问 MCP 资源的方式，提供全面的文档。你可以访问 Rails、Turbo、Stimulus 和 Kamal 的官方指南，也可以导入自己的自定义文档。

可用资源类别

• Rails 指南：Ruby on Rails 8.0.2 官方文档
• Turbo 指南：Turbo（Hotwire）框架官方文档
• Stimulus 指南：Stimulus JavaScript 框架官方文档
• Kamal 指南：Kamal 部署工具官方文档
• 自定义指南：导入的 Markdown 文件

开始使用资源

管理资源最简单的方式是使用配置工具：

rails-mcp-config

然后从菜单中选择“下载指南”或“导入自定义指南”。

或者，也可以使用旧版命令行工具：

# Download Rails guides
rails-mcp-server-download-resources rails

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

# Import custom markdown files
rails-mcp-server-download-resources --file /path/to/your/docs/

资源访问方式

1. 通过工具访问：在对话中使用 load_guide 工具
2. 直接访问资源：MCP 客户端可使用 rails://guides/{guide_name} 等 URI 模式查询资源

有关下载、管理和使用资源的完整信息，请参阅资源指南。

测试与调试

测试和调试 Rails MCP 服务最简单的方法是使用 MCP Inspector，这是一款专为测试和调试 MCP 服务设计的开发工具。

要将 MCP Inspector 与 Rails MCP 服务配合使用：

# Install and run MCP Inspector
npm -g install @modelcontextprotocol/inspector

npx @modelcontextprotocol/inspector /path/to/rails-mcp-server

这将：

1. 以 HTTP 模式启动 Rails MCP 服务
2. 在浏览器中启动 MCP Inspector UI（默认端口：6274）
3. 设置 MCP 代理服务（默认端口：6277）

在 MCP Inspector UI 中，你可以：

• 查看所有可用工具（你应该能看到 3 个已注册的工具）
• 交互式执行工具调用
• 查看请求和响应详情
• 实时调试问题

Inspector UI 提供了直观的界面，方便你与 MCP 服务交互，从而轻松测试和调试 Rails MCP 服务的实现。

测试工作流

1. 切换项目： 使用 switch_project 并指定项目名称
2. 发现工具： 使用 search_tools 查看可用的分析器
3. 测试分析器： 使用 execute_tool 调用特定分析器（例如 get_routes、get_schema）
4. 读取文件： 使用 execute_tool 调用 get_file，例如 { "path": "Gemfile" }

与大模型客户端集成

此服务旨在与支持 Model Context Protocol 的大模型客户端集成，例如 Claude Desktop 或其他兼容 MCP 的应用程序。

要与 MCP 客户端配合使用：

1. 启动 Rails MCP 服务（默认使用 STDIO 模式）
2. 将兼容 MCP 的客户端连接到服务
3. 客户端即可使用可用工具与 Rails 项目交互

对于使用受管 AI 客户端或控制平面来管理工具访问、审批、审计跟踪和成本报告的团队，请参阅 受管 MCP 客户端。

安全

如有安全方面的问题，请参阅 SECURITY.md。

许可证

此 Rails MCP 服务采用 MIT 许可证发布。这是一种宽松的开源许可证，允许免费使用、修改、分发和私人使用。

版权所有 (c) 2025 Mario Alberto Chávez Cárdenas

特此免费授予任何获得本软件及相关文档文件（“软件”）副本的人不受限制地处理本软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和／或销售本软件副本的权利，以及允许获得本软件的人这样做，但须符合以下条件：

上述版权声明和本许可声明应包含在本软件的所有副本或实质性部分中。

本软件按“原样”提供，不提供任何明示或暗示的担保，包括但不限于适销性、特定用途适用性和非侵权性的担保。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论此类责任是因合同、侵权或其他原因引起，还是与本软件或本软件的使用或其他交易有关。

贡献

欢迎在 GitHub 上提交 Bug 报告和拉取请求：https://github.com/maquina-app/rails-mcp-server。