Rails MCP Server

Rails MCP服务器

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

什么是MCP？

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

此Rails MCP Server实现了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桌面安装脚本
• rails-mcp-server-download-resources -旧资源下载脚本

配置

使用配置工具（推荐）

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

rails-mcp-config

这提供了一个用户友好的TUI（终端用户界面），用于：

• 管理项目：添加、编辑、删除和验证Rails项目
• 下载指南：下载Rails、Turbo、Stimulus和Kamal文档
• 导入自定义参考线：添加您自己的markdown文档
• Claude桌面集成：自动配置克劳德桌面

该工具使用 口香糖 如果安装了，可以获得增强的体验，但可以使用基本的终端回退。

# 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 或 ~/.config/rails-mcp 如果XDG_CONFIG_HOME未设置
• 在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模式：作为具有JSON-RPC和服务器发送事件（SSE）端点的HTTP服务器运行。

# 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:

/mcp/messages`

• SSE端点： `http://localhost:

/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桌面集成

Rails MCP服务器可以与Claude Desktop一起使用。有多种设置选项：

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

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

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 或 ~/.config/rails-mcp 如果XDG_CONFIG_HOME未设置 - 窗户： %APPDATA%\rails-mcp

1. 创建一个 projects.yml 将Rails项目放在该目录中。

1. 查找或创建Claude Desktop配置文件：

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json

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

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

1. 重新启动Claude Desktop以应用更改。

Ruby版本管理器用户

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

如果你使用的是像rbenv这样的Ruby版本管理器，你可以使用Ruby填充路径来确保使用正确的版本：

{
  "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垫片的实际路径。

小贴士：The rails-mcp-config 该工具会自动检测您的Ruby路径，并在配置Claude Desktop时使用正确的填充路径。

使用MCP代理（高级）

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

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

rails-mcp-server --mode http

1. 安装并运行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

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

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

此设置允许仅STDIO的客户端通过代理与Rails MCP服务器通信，在保持客户端兼容性的同时受益于HTTP/SSE功能。

小贴士：The rails-mcp-config 该工具可以使用mcp-remote自动配置HTTP模式。

GitHub复制代理集成

Rails MCP Server与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"]
    }
  }
}

1. 设置步骤 -创建 .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", "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代码进行自定义查询

这种设计将初始上下文从约2400个令牌减少到约800个令牌，同时保持完整的功能。

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：（字符串，可选）搜索词（例如，“路由”、“模型”、“模式”）
• category：（字符串，可选）按类别筛选：模型、数据库、布线、控制器、文件、项目、指南
• detail_level：（字符串，可选）输出详细信息：“名称”、“摘要”或“完整”（默认值：“摘要”）

3. execute_tool

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

参数：

• tool_name：（字符串，必填）分析器的名称（例如，“get_routes”、“analyze_models”）
• params：（哈希，可选）分析器的参数

4. execute_ruby

说明： 在Rails项目上下文中执行沙盒Ruby代码。

参数：

• code：（String，必填）要执行的Ruby代码
• timeout：（整数，可选）超时时间（秒）（默认值：30，最大值：60）

可用的帮助方法：

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

注： 使用 puts 查看代码的输出。

安全： 沙盒可防止文件写入、系统调用、网络访问和读取敏感文件（.env、凭据等）。

内部分析器（通过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

使用关联、验证和可选的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：“名称”、“摘要”或“完整”
• analysis_type：“内省”、“静态”或“完整”（包括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服务器通过以下两种方式提供对全面文档的访问 load_guide 工具和直接MCP资源访问。您可以访问Rails、Turbo、Stimulus和Kamal的官方指南，也可以导入自己的自定义文档。

可用资源类别

• 轨道指南：Ruby on Rails 8.0.2官方文档
• 涡轮导向装置：官方Turbo（Hotwire）框架文档
• 刺激指南：官方Stimulus JavaScript框架文档
• 卡迈勒指南：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客户端可以使用URI模式查询资源，如 rails://guides/{guide_name}

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

测试和调试

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

要将MCP检查器与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检查器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客户集成

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

要与MCP客户端一起使用：

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

安全

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

许可证

这个Rails MCP服务器是在MIT许可证下发布的，MIT许可证是一个允许自由使用、修改、分发和私人使用的开源许可证。

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

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

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

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

贡献

欢迎在GitHub上提交Bug报告和拉取请求，网址为 .