Rails MCP 服务器

一个用于 Rails 项目的模型上下文协议（MCP）服务器的 Ruby 实现。该服务器允许大型语言模型（LLM）通过模型上下文协议与 Rails 项目进行交互，从而提供代码分析、探索和开发辅助等功能。

什么是 MCP？

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

这个 Rails MCP 服务器实现了 MCP 规范，为 AI 模型提供了访问 Rails 项目的能力，以进行代码分析、探索和辅助开发。

特性

• 管理多个 Rails 项目
• 浏览项目文件和结构
• 查看带有筛选选项的 Rails 路由
• 检查模型信息及其关系（借助 Prism 静态分析）
• 获取数据库模式信息
• 分析控制器与视图之间的关系
• 分析环境配置
• 执行沙箱中的 Ruby 代码以进行自定义查询
• 访问全面的 Rails、Turbo、Stimulus 和 Kamal 文档
• 基于上下文高效的架构，支持渐进式工具发现
• 与 LLM 客户端无缝集成

安装

安装 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，该工具将提供更佳体验；否则，它会回退到基本的终端界面。

# 安装 Gum 以获得最佳体验（可选）
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 和 Server-Sent Events（SSE）端点。

# 以默认的 STDIO 模式启动
rails-mcp-server

# 以 HTTP 模式在默认端口（6029）启动
rails-mcp-server --mode http

# 以 HTTP 模式在自定义端口启动
rails-mcp-server --mode http -p 8080

# 以 HTTP 模式绑定到所有接口（以便本地网络访问）
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 标志：

# 允许本地网络中的任何设备访问
rails-mcp-server --mode http --bind-all

# 使用自定义端口
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 目录下的文件中。您可以使用以下选项自定义日志：

# 设置日志级别（debug、info、error）
rails-mcp-server --log-level debug

Claude Desktop 集成

Rails MCP 服务器可以与 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. 在该目录中创建一个包含您的 Rails 项目的 projects.yml 文件。

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 版本管理器用户

Claude Desktop 会使用您系统默认的 Ruby 环境来启动 MCP 服务器，从而绕过版本管理器的初始化（例如 rbenv、RVM）。MCP 服务器需要使用与其安装时相同的 Ruby 版本，因为如果使用不兼容的 Ruby 版本，可能会导致 MCP 服务器启动失败。

如果您正在使用像 rbenv 这样的 Ruby 版本管理器，可以使用 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 shim 路径。

提示：rails-mcp-config 工具会在配置 Claude Desktop 时自动检测您的 Ruby 路径，并使用正确的 shim 路径。

使用 MCP 代理（高级）

Claude Desktop 和许多其他 LLM 客户端仅支持 STDIO 模式通信，但您可能希望利用服务器的 HTTP/SSE 功能。MCP 代理可以弥补这一差距：

1. 以 HTTP 模式启动 Rails MCP 服务器：

rails-mcp-server --mode http

2. 安装并运行一个 MCP 代理。目前有多种不同语言实现的 MCP 代理可供选择。MCP 代理允许仅支持 STDIO 通信的客户端通过 HTTP SSE 进行通信。以下是一个基于 JavaScript 的 MCP 代理示例：

# 安装基于 Node.js 的 MCP 代理
npm install -g mcp-remote

# 运行代理，指向您正在运行的 Rails MCP 服务器
npx mcp-remote http://localhost:6029/mcp/sse

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

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

通过这种设置，仅支持 STDIO 的客户端可以通过代理与 Rails MCP 服务器通信，在保持客户端兼容性的同时，还能享受到 HTTP/SSE 的功能优势。

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

GitHub Copilot Agent 集成

Rails MCP 服务器开箱即用，即可与 GitHub Copilot 编码助手配合使用。当从 Rails 目录启动或通过环境变量进行配置时，服务器会自动检测 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", "execute_ruby"]
    }
  }
}

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

name: "Copilot 设置步骤"

on: workflow_dispatch

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

      - name: 设置 Ruby 环境
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'
          bundler-cache: true

      - name: 安装 Rails MCP 服务器
        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", "execute_ruby"]
    }
  }
}

限制

• GitHub Copilot Agent 仅支持 MCP 工具，而不支持资源或提示。
• load_guide 分析器通过 execute_tool 工作，但需要在设置过程中下载指南。

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

服务器工作原理

Rails MCP 服务器采用模型上下文协议实现，支持以下两种模式：

• STDIO 模式：从标准输入读取 JSON-RPC 2.0 请求，并将响应输出到标准输出。
• HTTP 模式：提供用于处理 JSON-RPC 2.0 请求和服务器发送事件的 HTTP 端点。

每个请求都包含序列号，以便根据 MCP 规范匹配请求和响应。服务器会维护项目上下文，并在多个代码库中提供特定于 Rails 的分析功能。

上下文高效的架构

服务器采用渐进式工具发现架构，以最大限度地减少上下文使用量。它不会一次性暴露所有工具，而是提供 4 个引导工具，使 LLM 能够按需发现并调用其他分析工具：

• switch_project - 选择当前活动的 Rails 项目
• search_tools - 按类别或关键词发现可用工具
• execute_tool - 带参数调用内部分析工具
• execute_ruby - 在沙盒环境中运行自定义 Ruby 代码以执行查询

这种设计可将初始上下文从约 2,400 个 token 减少至约 800 个 token，同时仍能保持完整功能。

AI 代理指南

对于使用本服务器的 AI 代理（Claude、GPT 等），请参阅全面的 AI 代理指南，其中涵盖：

• 快速入门流程
• 常见任务的工具选择指南
• execute_ruby 中可用的帮助方法
• 常见陷阱及避免方法
• 错误处理和回退策略
• 与其他 MCP 服务器（如 Neovim MCP）的集成

可用工具

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

已注册工具

1. switch_project

描述: 切换当前活动的 Rails 项目。在使用其他工具之前必须调用此命令。

参数:

• project_name: (字符串，必填) 在 projects.yml 中定义的项目名称

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

2. search_tools

描述: 按类别或关键词查找可用工具。

参数:

• query: (字符串，可选) 搜索词（例如 'routes', 'model', 'schema'）
• category: (字符串，可选) 按类别筛选：models、database、routing、controllers、files、project、guides
• detail_level: (字符串，可选) 输出详细程度：'names'、'summary' 或 'full'（默认值：'summary'）

3. execute_tool

描述: 通过名称调用内部分析器。

参数:

• tool_name: (字符串，必填) 分析器名称（例如 'get_routes', 'analyze_models'）
• params: (哈希，可选) 分析器的参数

4. execute_ruby

描述: 在 Rails 项目上下文中执行沙盒化的 Ruby 代码。

参数:

• code: (字符串，必填) 要执行的 Ruby 代码
• timeout: (整数，可选) 超时时间，单位为秒（默认值：30，最大值：60）

可用的帮助方法:

• read_file(path) - 安全地读取文件
• file_exists?(path) - 检查文件是否存在
• list_files(pattern) - 使用 glob 匹配文件（例如 'app/models/**/*.rb'）
• project_root - 获取项目根路径

注意: 使用 puts 可以查看代码的输出。

安全性: 沙盒环境会阻止写入文件、系统调用、网络访问以及读取敏感文件（如 .env、credentials 等）。

内部分析器（通过 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 或自定义的文档指南。

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 服务器通过 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

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

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

# 下载 Rails 指南
rails-mcp-server-download-resources rails

# 下载 Turbo 指南
rails-mcp-server-download-resources turbo

# 导入自定义 Markdown 文件
rails-mcp-server-download-resources --file /path/to/your/docs/

资源访问方式

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

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

测试与调试

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

要在 Rails MCP 服务器上使用 MCP Inspector：

# 安装并运行 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 中，您可以：

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

Inspector UI 提供了一个直观的界面来与您的 MCP 服务器交互，使测试和调试您的 Rails MCP 服务器实现变得非常容易。

测试工作流

1. 切换到项目： 使用 switch_project 命令并指定你的项目名称
2. 发现工具： 运行 search_tools 查看可用的分析工具
3. 测试分析工具： 使用 execute_tool 调用特定的分析工具
4. 测试 Ruby 代码执行： 运行 execute_ruby，传入类似 puts read_file('Gemfile') 的代码

与 LLM 客户端的集成

本服务器旨在与支持模型上下文协议（MCP）的 LLM 客户端集成，例如 Claude Desktop 或其他兼容 MCP 的应用。

使用 MCP 客户端的步骤如下：

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

安全性

有关安全性问题，请参阅 SECURITY.md。

许可证

本 Rails MCP 服务器采用 MIT 许可证发布，这是一种宽松的开源许可证，允许自由使用、修改、分发及用于私有用途。

版权所有 © 2025 马里奥·阿尔贝托·查韦斯·卡德纳斯

特此授予任何人免费获取本软件及其相关文档文件（以下简称“软件”）副本的权利，以不受限制的方式处理该软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售该软件副本的权利；并允许向任何获得本软件的人提供本软件以供其使用，但须遵守以下条件：

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

本软件按“原样”提供，不提供任何形式的明示或暗示保证，包括但不限于适销性、特定用途适用性和非侵权性。在任何情况下，作者或版权所有者均不对因本软件或其使用而引起的任何索赔、损害或其他责任负责，无论此类责任是基于合同、侵权行为或其他原因产生的，且在任何情况下，作者或版权所有者均不承担任何责任。

贡献

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

Rails MCP Server 快速上手指南

Rails MCP Server 是一个基于 Ruby 实现的模型上下文协议（MCP）服务器，专为 Rails 项目设计。它允许大语言模型（LLM）通过标准化协议与你的 Rails 代码库交互，提供代码分析、路由查看、模型关系检查及开发辅助等功能。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：macOS、Linux 或 Windows (WSL)。
• Ruby 环境：已安装 Ruby（推荐版本 3.0+）。如果你使用 rbenv 或 RVM，请确保已正确初始化。
• Gem 源加速（推荐）：国内开发者建议将 Gem 源切换至国内镜像以加快安装速度。

  gem sources --add https://gems.ruby-china.com/ --remove https://rubygems.org/
  gem sources -l # 确认列表中包含 ruby-china 源
  

• 可选增强体验：安装 gum 工具以获得更友好的交互式配置界面（非必须，但强烈推荐）。
  • macOS: brew install gum
  • Debian/Ubuntu: sudo apt install gum
  • Arch Linux: yay -S gum

安装步骤

1. 安装核心组件

使用 gem 命令安装服务器：

gem install rails-mcp-server

安装完成后，以下可执行文件将自动添加到你的系统路径中：

• rails-mcp-server：MCP 服务器主程序。
• rails-mcp-config：交互式配置工具（推荐使用）。
• rails-mcp-setup-claude：Claude Desktop 传统设置脚本。

2. 配置项目

推荐使用交互式工具进行配置，它可以帮助你管理项目路径、下载文档并集成 Claude Desktop。

运行配置工具：

rails-mcp-config

在该界面中你可以：

• 添加/编辑项目：指定你的 Rails 项目绝对路径。
• 下载文档：自动获取 Rails、Turbo、Stimulus 和 Kamal 的官方文档供 AI 参考。
• 集成客户端：自动检测并配置 Claude Desktop。

手动配置替代方案： 如果不使用交互工具，可在配置目录（macOS: ~/.config/rails-mcp 或 Windows: %APPDATA%\rails-mcp）下创建 projects.yml 文件：

my_store: "~/projects/store"
my_blog: "~/projects/rails-blog"

基本使用

Rails MCP Server 通常作为后端服务运行，由支持 MCP 协议的 AI 客户端（如 Claude Desktop、GitHub Copilot Agent）调用。

模式一：配合 Claude Desktop 使用（最常用）

1. 运行配置：执行 rails-mcp-config 并按照提示完成 "Claude Desktop integration" 设置。该工具会自动处理 Ruby 路径和配置文件。
2. 重启客户端：完全退出并重新启动 Claude Desktop。
3. 开始对话：在 Claude Desktop 中选择已配置的 Rails 项目，即可询问关于代码结构、路由、数据库架构等问题。

模式二：独立启动服务器（调试或自定义集成）

你可以手动启动服务器以测试连接或配合其他客户端。

启动 STDIO 模式（默认，用于直接管道通信）：

rails-mcp-server

启动 HTTP 模式（用于网络访问或通过代理连接）：

# 默认端口 6029
rails-mcp-server --mode http

# 指定端口并允许局域网访问
rails-mcp-server --mode http -p 8080 --bind-all

模式三：GitHub Copilot Agent 集成

若在 GitHub Copilot Coding Agent 中使用，需在仓库根目录创建 .github/copilot/mcp.json：

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

确保在 CI 或本地环境中已执行 gem install rails-mcp-server。

---

提示：服务器采用“渐进式工具发现”架构，初始上下文极小。AI 会通过 search_tools 和 execute_tool 按需加载分析器，从而高效地分析大型 Rails 项目。