rails-mcp服务器

Name: rails-mcp服务器
Author: maquina-app

作者：maquina-app411 星标更新：2025-07-22

安装使用来源：spider==github.com

项目介绍

Rails MCP Server

Rails项目的Model Context Protocol (MCP)服务器的Ruby实现。该服务器允许大型语言模型（LLMs）通过Model Context Protocol与Rails项目进行交互，提供代码分析、探索和开发辅助的能力。

什么是MCP？

Model Context Protocol (MCP) 是一种标准化的方式，用于AI模型与其环境之间的交互。它定义了一种结构化的方法，使模型能够请求并使用工具，访问资源，并在交互过程中维护上下文。

这个Rails MCP Server实现了MCP规范，使AI模型能够访问Rails项目以进行代码分析、探索和辅助。

功能

管理多个Rails项目
浏览项目文件和结构
查看Rails路由
检查模型信息和关系
获取数据库模式信息
分析控制器视图关系
分析环境配置
访问全面的Rails、Turbo、Stimulus和Kamal文档
遵循Model Context Protocol标准
无缝集成到LLM客户端

安装

安装gem：

gem install rails-mcp-server

安装后，rails-mcp-server 和 rails-mcp-setup-claude 执行文件将在你的PATH中可用。

配置

Rails MCP Server遵循XDG Base Directory Specification来配置文件：

在macOS上：$XDG_CONFIG_HOME/rails-mcp 或者如果未设置XDG_CONFIG_HOME，则为 ~/.config/rails-mcp
在Windows上：%APPDATA%\rails-mcp

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

要配置你的项目：

编辑配置目录中的 projects.yml 文件，包括你的Rails项目：

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

YAML文件中的每个键都是一个项目名称（这将在使用 switch_project 工具时用到），每个值是项目的路径。

使用

启动服务器

Rails MCP Server可以运行在两种模式下：

STDIO模式（默认）：通过标准输入/输出与客户端如Claude Desktop直接集成。
HTTP模式：作为具有JSON-RPC和服务器发送事件（SSE）端点的HTTP服务器运行。

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

# 在默认端口（6029）上启动HTTP模式
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 Server可以与Claude Desktop一起使用。有两种设置方法：

方法1：使用设置脚本（推荐）

运行设置脚本，该脚本将自动配置Claude Desktop并设置适当的XDG兼容目录结构：

rails-mcp-setup-claude

该脚本将：

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

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

方法2：直接配置

创建适合你平台的配置目录：
- macOS：$XDG_CONFIG_HOME/rails-mcp 或者如果未设置XDG_CONFIG_HOME，则为 ~/.config/rails-mcp
- Windows：%APPDATA%\rails-mcp
在该目录中创建一个包含你的Rails项目的 projects.yml 文件。
找到或创建Claude Desktop配置文件：
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：%APPDATA%\Claude\claude_desktop_config.json
添加或更新MCP服务器配置：

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

重启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路径。

使用MCP代理（高级）

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

在HTTP模式下启动Rails MCP Server：

rails-mcp-server --mode http

安装并运行一个MCP代理。有许多不同语言的实现可供选择。MCP代理允许仅支持STDIO通信的客户端通过HTTP SSE进行通信。这里是一个使用基于JavaScript的MCP代理的例子：

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

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

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

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

这种设置允许仅支持STDIO的客户端通过代理与Rails MCP Server通信，从而受益于HTTP/SSE功能同时保持客户端兼容性。

服务器如何工作

Rails MCP Server使用以下方式实现Model Context Protocol：

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

每个请求都包含一个序列号，以便将请求与响应匹配，正如MCP规范所定义的那样。服务器维护项目上下文，并提供跨多个代码库的Rails特定分析能力。

可用工具

服务器提供了以下工具来与Rails项目进行交互：

1. `switch_project`

描述：切换到另一个代码库的活动Rails项目。必须在使用其他工具之前调用。可用项目在 projects.yml 配置文件中定义。

参数：

project_name：（字符串，必需）在 projects.yml 文件中定义的项目名称（区分大小写）

示例

你能切换到“store”项目，让我们探索一下吗？

我想分析我的“blog”应用程序。请先切换到那个项目。

切换到“ecommerce”项目，并给我一个代码库的概述。

2. `project_info`

描述：检索关于当前Rails项目的综合信息，包括Rails版本、目录结构、API-only状态以及整体项目组织。对于初始项目探索和理解代码库结构非常有用。

参数：无

示例

现在我们在博客项目中，你能给我一个项目结构和Rails版本的概述吗？

告诉我这个Rails应用程序的情况。它运行什么版本，它是如何组织的？

我想了解这个项目的高层架构。你能提供项目信息吗？

3. `list_files`

描述：列出符合特定条件的Rails项目文件。使用此功能来探索项目目录或定位特定类型的文件。如果没有提供参数，则列出项目根目录中的文件。

参数：

directory：（字符串，可选）相对于项目根的目录路径（例如，'app/models'，'config'）。留空则列出根目录中的文件。
pattern：（字符串，可选）使用glob语法的文件模式（例如，'.rb' 用于Ruby文件，'.erb' 用于ERB模板，'*_controller.rb' 用于控制器）

示例

你能列出这个项目中的所有模型文件吗？

显示app/controllers目录中的所有控制器文件。

我需要查看users部分的所有视图模板。你能列出app/views/users中的文件吗？

列出app/javascript目录中的所有JavaScript文件。

4. `get_file`

描述：获取特定文件的完整内容，并带有语法高亮。使用此功能来检查实现细节、配置或项目中的任何文本文件。

参数：

path：（字符串，必需）相对于项目根的文件路径（例如，'app/models/user.rb'，'config/routes.rb'）。如果不确定确切路径，请先使用 list_files。

示例

你能展示User模型文件的内容吗？

我需要查看app/controllers/products_controller.rb的内容。你能检索那个文件吗？

请展示application.rb文件，让我检查配置设置。

我想查看路由文件。你能显示config/routes.rb的内容吗？

5. `get_routes`

描述：检索Rails应用程序中定义的所有HTTP路由及其关联的控制器和动作。相当于运行 'rails routes' 命令。这有助于理解应用程序中的API端点或页面URL。

参数：无

示例

你能展示这个应用程序中定义的所有路由吗？

我需要了解这个项目中可用的API端点。你能列出这些路由吗？

展示这个Rails应用程序的路由配置，这样我可以看看URL是如何构建的。

6. `analyze_models`

描述：检索项目中Active Record模型的详细信息。如果没有提供参数，则列出所有模型文件。如果指定了特定模型，则返回其模式、关联（has_many, belongs_to, has_one）和完整的源代码。

参数：

model_name：（字符串，可选）特定模型的类名，以获取详细信息（例如，'User'，'Product'）。使用CamelCase，而不是snake_case。如果省略，则返回所有模型的列表。

示例

你能列出这个Rails项目中的所有模型吗？

我想详细了解User模型。你能展示它的模式、关联和代码吗？

展示Product模型的定义，包括与其他模型的关系。

这个应用程序中的所有模型是什么，然后你能具体展示Order模型的详情吗？

7. `get_schema`

描述：检索Rails应用程序的数据库模式信息。如果没有提供参数，则返回所有表和完整的schema.rb。如果提供了表名，则返回该特定表的详细列信息，包括数据类型、约束和外键。

参数：

table_name：（字符串，可选）要获取详细模式信息的数据库表名（例如，'users'，'products'）。使用snake_case，复数形式。如果省略，则返回完整的数据库模式。

示例

你能展示这个Rails应用程序的完整数据库模式吗？

我想看看users表的结构。你能检索那个模式信息吗？

展示products表中的列及其数据类型。

我需要理解数据库设计。你能首先列出所有表，然后展示orders表的详情吗？

8. `analyze_controller_views`

描述：分析控制器、它们的动作和相应的视图之间的关系，以理解应用程序的UI流程。

参数：

controller_name：（字符串，可选）要分析的具体控制器名称（例如，'UsersController' 或 'users'）。如果省略，则分析所有控制器。

示例

你能分析Users控制器及其视图，帮助我理解UI流程吗？

展示ProductsController如何连接到其视图以及有哪些可用的动作。

我想了解整个应用程序的控制器-视图结构。

9. `analyze_environment_config`

描述：分析环境配置以识别不一致、安全问题和缺失变量。

参数：无

示例

你能分析环境配置以查找任何安全问题或缺失的环境变量吗？

检查配置文件，找出开发和生产环境之间的任何不一致之处。

10. `load_guide`

描述：从Rails、Turbo、Stimulus、Kamal或自定义加载文档指南。使用此功能在对话中获取指南内容。

参数：

guides：（字符串，必需）要搜索的指南库：'rails'，'turbo'，'stimulus'，'kamal' 或 'custom'
guide：（字符串，可选）要加载的具体指南名称。如果没有提供，则返回可用指南列表。

示例

你能加载Rails入门指南吗？

显示可用的Turbo指南，然后加载关于Turbo Frames的那个。

我在处理Stimulus的问题。你能加载hello_stimulus指南吗？

加载Kamal安装指南，这样我可以了解部署选项。

资源和文档

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指南
rails-mcp-server-download-resources rails

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

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

资源访问方法

基于工具的访问：在对话中使用 load_guide 工具
直接资源访问：MCP客户端可以通过URI模式如 rails://guides/{guide_name} 查询资源

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

测试和调试

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

要使用MCP Inspector与Rails MCP Server：

# 安装并运行MCP Inspector，与你的Rails MCP Server一起
npm -g install @modelcontextprotocol/inspector

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

这将：

在HTTP模式下启动你的Rails MCP Server
在浏览器中启动MCP Inspector UI（默认端口：6274）
设置一个MCP Proxy服务器（默认端口：6277）

在MCP Inspector UI中，你可以：

查看所有可用工具
交互式执行工具调用
查看请求和响应详情
实时调试问题

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

与LLM客户端集成

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

要与MCP客户端一起使用：

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

许可证

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

特此授予任何人获得此软件及附带文档文件副本（以下简称“软件”）的人，在不受限制的情况下处理软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本的权利，以及允许收到软件的人这样做，但需遵守以下条件：

软件按“原样”提供，不附带任何形式的保证，无论是明示

rails-mcp服务器

项目介绍

Rails MCP Server

什么是MCP？

功能

安装

配置

使用

启动服务器

网络访问（HTTP模式）

日志选项

Claude Desktop集成

方法1：使用设置脚本（推荐）

方法2：直接配置

使用Ruby版本管理器的用户

使用MCP代理（高级）

服务器如何工作

可用工具

1. switch_project

示例

2. project_info

示例

3. list_files

示例

4. get_file

示例

5. get_routes

示例

6. analyze_models

示例

7. get_schema

示例

8. analyze_controller_views

示例

9. analyze_environment_config

示例

10. load_guide

示例

资源和文档

可用资源类别

开始使用资源

资源访问方法

测试和调试

与LLM客户端集成

许可证

1. `switch_project`

2. `project_info`

3. `list_files`

4. `get_file`

5. `get_routes`

6. `analyze_models`

7. `get_schema`

8. `analyze_controller_views`

9. `analyze_environment_config`

10. `load_guide`