[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-maquina-app--rails-mcp-server":3,"tool-maquina-app--rails-mcp-server":61},[4,17,27,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":16},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",159267,2,"2026-04-17T11:29:14",[13,14,15],"开发框架","Agent","语言模型","ready",{"id":18,"name":19,"github_repo":20,"description_zh":21,"stars":22,"difficulty_score":23,"last_commit_at":24,"category_tags":25,"status":16},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[14,26],"插件",{"id":28,"name":29,"github_repo":30,"description_zh":31,"stars":32,"difficulty_score":10,"last_commit_at":33,"category_tags":34,"status":16},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[26,14,35,13],"图像",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":10,"last_commit_at":42,"category_tags":43,"status":16},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[26,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":50,"last_commit_at":51,"category_tags":52,"status":16},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,3,"2026-04-06T11:19:32",[15,35,14,13],{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":10,"last_commit_at":59,"category_tags":60,"status":16},8553,"spec-kit","github\u002Fspec-kit","Spec Kit 是一款专为提升软件开发效率而设计的开源工具包，旨在帮助团队快速落地“规格驱动开发”（Spec-Driven Development）模式。传统开发中，需求文档往往与代码实现脱节，导致沟通成本高且结果不可控；而 Spec Kit 通过将规格说明书转化为可执行的指令，让 AI 直接依据明确的业务场景生成高质量代码，从而减少从零开始的随意编码，确保产出结果的可预测性。\n\n该工具特别适合希望利用 AI 辅助编程的开发者、技术负责人及初创团队。无论是启动全新项目还是在现有工程中引入规范化流程，用户只需通过简单的命令行操作，即可初始化项目并集成主流的 AI 编程助手。其核心技术亮点在于“规格即代码”的理念，支持社区扩展与预设模板，允许用户根据特定技术栈定制开发流程。此外，Spec Kit 强调官方维护的安全性，提供稳定的版本管理，帮助开发者在享受 AI 红利的同时，依然牢牢掌握架构设计的主动权，真正实现从“凭感觉写代码”到“按规格建系统”的转变。",88749,"2026-04-17T09:48:14",[15,35,14,13],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":77,"owner_location":77,"owner_email":77,"owner_twitter":77,"owner_website":78,"owner_url":79,"languages":80,"stars":85,"forks":86,"last_commit_at":87,"license":88,"difficulty_score":10,"env_os":89,"env_gpu":90,"env_ram":90,"env_deps":91,"category_tags":98,"github_topics":77,"view_count":10,"oss_zip_url":77,"oss_zip_packed_at":77,"status":16,"created_at":99,"updated_at":100,"faqs":101,"releases":131},8598,"maquina-app\u002Frails-mcp-server","rails-mcp-server","A Ruby gem implementation of a Model Context Protocol (MCP) server for Rails projects. This server allows LLMs (Large Language Models) to interact with Rails projects through the Model Context Protocol.","rails-mcp-server 是一款专为 Ruby on Rails 项目打造的 AI 连接工具，它基于模型上下文协议（MCP）构建，充当大语言模型与 Rails 代码库之间的桥梁。在开发过程中，AI 往往难以准确理解复杂的项目结构、路由关系或数据库架构，导致生成的代码不够精准。rails-mcp-server 有效解决了这一痛点，让 AI 能够“看懂”你的项目，从而提供更具针对性的代码分析、探索辅助和开发建议。\n\n这款工具主要面向 Rails 开发者，无论是维护遗留系统还是构建新应用，都能从中受益。其技术亮点在于深度集成了 Prism 静态分析技术，可智能解析模型关系与控制器视图逻辑；同时支持沙箱执行自定义 Ruby 查询，并能直接访问 Rails、Turbo、Stimulus 等官方文档。用户只需通过简单的命令行配置，即可让 AI 助手具备浏览文件、查看路由、检查数据库架构甚至分析环境配置的能力。配合友好的交互式配置工具，rails-mcp-server 能无缝接入 Claude Desktop 等主流 AI 客户端，显著提升开发效率与代码质量，是 Rails 生态中实用的智能","rails-mcp-server 是一款专为 Ruby on Rails 项目打造的 AI 连接工具，它基于模型上下文协议（MCP）构建，充当大语言模型与 Rails 代码库之间的桥梁。在开发过程中，AI 往往难以准确理解复杂的项目结构、路由关系或数据库架构，导致生成的代码不够精准。rails-mcp-server 有效解决了这一痛点，让 AI 能够“看懂”你的项目，从而提供更具针对性的代码分析、探索辅助和开发建议。\n\n这款工具主要面向 Rails 开发者，无论是维护遗留系统还是构建新应用，都能从中受益。其技术亮点在于深度集成了 Prism 静态分析技术，可智能解析模型关系与控制器视图逻辑；同时支持沙箱执行自定义 Ruby 查询，并能直接访问 Rails、Turbo、Stimulus 等官方文档。用户只需通过简单的命令行配置，即可让 AI 助手具备浏览文件、查看路由、检查数据库架构甚至分析环境配置的能力。配合友好的交互式配置工具，rails-mcp-server 能无缝接入 Claude Desktop 等主流 AI 客户端，显著提升开发效率与代码质量，是 Rails 生态中实用的智能化开发伴侣。","# Rails MCP Server\n\nA Ruby implementation of a Model Context Protocol (MCP) server for Rails projects. This server allows LLMs (Large Language Models) to interact with Rails projects through the Model Context Protocol, providing capabilities for code analysis, exploration, and development assistance.\n\n## What is MCP?\n\nThe Model Context Protocol (MCP) is a standardized way for AI models to interact with their environment. It defines a structured method for models to request and use tools, access resources, and maintain context during interactions.\n\nThis Rails MCP Server implements the MCP specification to give AI models access to Rails projects for code analysis, exploration, and assistance.\n\n## Features\n\n- Manage multiple Rails projects\n- Browse project files and structures\n- View Rails routes with filtering options\n- Inspect model information and relationships (with Prism static analysis)\n- Get database schema information\n- Analyze controller-view relationships\n- Analyze environment configurations\n- Execute sandboxed Ruby code for custom queries\n- Access comprehensive Rails, Turbo, Stimulus, and Kamal documentation\n- Context-efficient architecture with progressive tool discovery\n- Seamless integration with LLM clients\n\n## Installation\n\nInstall the gem:\n\n```bash\ngem install rails-mcp-server\n```\n\nAfter installation, the following executables will be available in your PATH:\n\n- `rails-mcp-server` - The MCP server itself\n- `rails-mcp-config` - Interactive configuration tool (recommended)\n- `rails-mcp-setup-claude` - Legacy Claude Desktop setup script\n- `rails-mcp-server-download-resources` - Legacy resource download script\n\n## Configuration\n\n### Using the Configuration Tool (Recommended)\n\nThe easiest way to configure the Rails MCP Server is using the interactive configuration tool:\n\n```bash\nrails-mcp-config\n```\n\nThis provides a user-friendly TUI (Terminal User Interface) for:\n\n- **Managing Projects**: Add, edit, remove, and validate Rails projects\n- **Downloading Guides**: Download Rails, Turbo, Stimulus, and Kamal documentation\n- **Importing Custom Guides**: Add your own markdown documentation\n- **Claude Desktop Integration**: Automatically configure Claude Desktop\n\nThe tool uses [Gum](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Fgum) for an enhanced experience if installed, but works with a basic terminal fallback.\n\n```bash\n# Install Gum for best experience (optional)\nbrew install gum        # macOS\nsudo apt install gum    # Debian\u002FUbuntu\nyay -S gum              # Arch Linux\n```\n\n### Manual Configuration\n\nThe Rails MCP Server follows the XDG Base Directory Specification for configuration files:\n\n- On macOS: `$XDG_CONFIG_HOME\u002Frails-mcp` or `~\u002F.config\u002Frails-mcp` if XDG_CONFIG_HOME is not set\n- On Windows: `%APPDATA%\\rails-mcp`\n\nThe server will automatically create these directories and an empty `projects.yml` file the first time it runs.\n\nTo configure your projects manually:\n\n1. Edit the `projects.yml` file in your config directory to include your Rails projects:\n\n```yaml\nstore: \"~\u002Fprojects\u002Fstore\"\nblog: \"~\u002Fprojects\u002Frails-blog\"\necommerce: \"\u002Ffull\u002Fpath\u002Fto\u002Fecommerce-app\"\n```\n\nEach key in the YAML file is a project name (which will be used with the `switch_project` tool), and each value is the path to the project directory.\n\n## Usage\n\n### Starting the server\n\nThe Rails MCP Server can run in two modes:\n\n1. **STDIO mode (default)**: Communicates over standard input\u002Foutput for direct integration with clients like Claude Desktop.\n2. **HTTP mode**: Runs as an HTTP server with JSON-RPC and Server-Sent Events (SSE) endpoints.\n\n```bash\n# Start in default STDIO mode\nrails-mcp-server\n\n# Start in HTTP mode on the default port (6029)\nrails-mcp-server --mode http\n\n# Start in HTTP mode on a custom port\nrails-mcp-server --mode http -p 8080\n\n# Start in HTTP mode binding to all interfaces (for local network access)\nrails-mcp-server --mode http --bind-all\n```\n\nWhen running in HTTP mode, the server provides two endpoints:\n\n- JSON-RPC endpoint: `http:\u002F\u002Flocalhost:\u003Cport>\u002Fmcp\u002Fmessages`\n- SSE endpoint: `http:\u002F\u002Flocalhost:\u003Cport>\u002Fmcp\u002Fsse`\n\n### Network Access (HTTP Mode)\n\nBy default, the HTTP server only binds to localhost for security. If you need to access the server from other machines on your local network (e.g., for testing with multiple devices), you can use the `--bind-all` flag:\n\n```bash\n# Allow access from any machine on your local network\nrails-mcp-server --mode http --bind-all\n\n# With a custom port\nrails-mcp-server --mode http --bind-all -p 8080\n```\n\nWhen using `--bind-all`:\n\n- The server binds to `0.0.0.0` instead of `localhost`\n- Access is allowed from local network IP ranges (192.168.x.x, 10.x.x.x)\n- The server accepts connections from `.local` domain names (e.g., `my-computer.local`)\n- Security features remain active to prevent unauthorized access\n\n**Security Note**: Only use `--bind-all` on trusted networks. The server includes built-in security features to validate origins and IP addresses, but exposing any service to your network increases the attack surface.\n\n### Logging Options\n\nThe server logs to a file in the `.\u002Flog` directory by default. You can customize logging with these options:\n\n```bash\n# Set the log level (debug, info, error)\nrails-mcp-server --log-level debug\n```\n\n## Claude Desktop Integration\n\nThe Rails MCP Server can be used with Claude Desktop. There are multiple options to set this up:\n\n### Option 1: Use the configuration tool (recommended)\n\nRun the interactive configuration tool and select \"Claude Desktop integration\":\n\n```bash\nrails-mcp-config\n```\n\nThe tool will:\n\n- Detect your current Claude Desktop configuration\n- Let you choose between STDIO or HTTP mode\n- Automatically find the correct Ruby and server paths\n- Create a backup before making changes\n- Update the Claude Desktop configuration\n\n### Option 2: Use the setup script (legacy)\n\nRun the setup script which will automatically configure Claude Desktop:\n\n```bash\nrails-mcp-setup-claude\n```\n\nThe script will:\n\n- Create the appropriate config directory for your platform\n- Create an empty `projects.yml` file if it doesn't exist\n- Update the Claude Desktop configuration\n\nAfter running the script, restart Claude Desktop to apply the changes.\n\n### Option 3: Direct Configuration\n\n1. Create the appropriate config directory for your platform:\n   - macOS: `$XDG_CONFIG_HOME\u002Frails-mcp` or `~\u002F.config\u002Frails-mcp` if XDG_CONFIG_HOME is not set\n   - Windows: `%APPDATA%\\rails-mcp`\n\n2. Create a `projects.yml` file in that directory with your Rails projects.\n\n3. Find or create the Claude Desktop configuration file:\n   - macOS: `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n   - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n4. Add or update the MCP server configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"railsMcpServer\": {\n      \"command\": \"ruby\",\n      \"args\": [\"\u002Ffull\u002Fpath\u002Fto\u002Frails-mcp-server\u002Fexe\u002Frails-mcp-server\"] \n    }\n  }\n}\n```\n\n5. Restart Claude Desktop to apply the changes.\n\n### Ruby Version Manager Users\n\nClaude Desktop launches the MCP server using your system's default Ruby environment, bypassing version manager initialization (e.g., rbenv, RVM). The MCP server needs to use the same Ruby version where it was installed, as MCP server startup failures can occur when using an incompatible Ruby version.\n\nIf you are using a Ruby version manager such as rbenv, you can use the Ruby shim path to ensure the correct version is used:\n\n```json\n{\n  \"mcpServers\": {\n    \"railsMcpServer\": {\n      \"command\": \"\u002Fhome\u002Fyour_user\u002F.rbenv\u002Fshims\u002Fruby\",\n      \"args\": [\"\u002Ffull\u002Fpath\u002Fto\u002Frails-mcp-server\u002Fexe\u002Frails-mcp-server\"] \n    }\n  }\n}\n```\n\nReplace \"\u002Fhome\u002Fyour_user\u002F.rbenv\u002Fshims\u002Fruby\" with your actual path for the Ruby shim.\n\n**Tip**: The `rails-mcp-config` tool automatically detects your Ruby path and uses the correct shim path when configuring Claude Desktop.\n\n### Using an MCP Proxy (Advanced)\n\nClaude Desktop and many other LLM clients only support STDIO mode communication, but you might want to use the HTTP\u002FSSE capabilities of the server. An MCP proxy can bridge this gap:\n\n1. Start the Rails MCP Server in HTTP mode:\n\n```bash\nrails-mcp-server --mode http\n```\n\n2. Install and run an MCP proxy. There are several implementations available in different languages. An MCP proxy allows a client that only supports STDIO communication to communicate via HTTP SSE. Here's an example using a JavaScript-based MCP proxy:\n\n```bash\n# Install the Node.js based MCP proxy\nnpm install -g mcp-remote\n\n# Run the proxy, pointing to your running Rails MCP Server\nnpx mcp-remote http:\u002F\u002Flocalhost:6029\u002Fmcp\u002Fsse\n```\n\n3. Configure Claude Desktop (or other LLM client) to use the proxy instead of connecting directly to the server:\n\n```json\n{\n  \"mcpServers\": {\n    \"railsMcpServer\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-remote\", \"http:\u002F\u002Flocalhost:6029\u002Fmcp\u002Fsse\"]\n    }\n  }\n}\n```\n\nThis setup allows STDIO-only clients to communicate with the Rails MCP Server through the proxy, benefiting from the HTTP\u002FSSE capabilities while maintaining client compatibility.\n\n**Tip**: The `rails-mcp-config` tool can configure HTTP mode with mcp-remote automatically.\n\n## GitHub Copilot Agent Integration\n\nRails MCP Server works with GitHub Copilot coding agent out of the box. The server auto-detects Rails projects when started from a Rails directory or when configured with environment variables.\n\n### Quick Setup\n\n1. **Configure MCP** - Create `.github\u002Fcopilot\u002Fmcp.json` in your repository:\n\n```json\n{\n  \"mcpServers\": {\n    \"rails\": {\n      \"type\": \"local\",\n      \"command\": \"rails-mcp-server\",\n      \"args\": [\"--single-project\"],\n      \"tools\": [\"switch_project\", \"search_tools\", \"execute_tool\", \"execute_ruby\"]\n    }\n  }\n}\n```\n\n2. **Setup Steps** - Create `.github\u002Fworkflows\u002Fcopilot-setup-steps.yml`:\n\n```yaml\nname: \"Copilot Setup Steps\"\n\non: workflow_dispatch\n\njobs:\n  copilot-setup-steps:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n    steps:\n      - name: Checkout\n        uses: actions\u002Fcheckout@v4\n\n      - name: Set up Ruby\n        uses: ruby\u002Fsetup-ruby@v1\n        with:\n          ruby-version: '3.3'\n          bundler-cache: true\n\n      - name: Install Rails MCP Server\n        run: gem install rails-mcp-server\n```\n\n### Alternative: Environment Variable\n\nYou can also use the `RAILS_MCP_PROJECT_PATH` environment variable:\n\n```json\n{\n  \"mcpServers\": {\n    \"rails\": {\n      \"type\": \"local\",\n      \"command\": \"rails-mcp-server\",\n      \"env\": {\n        \"RAILS_MCP_PROJECT_PATH\": \".\"\n      },\n      \"tools\": [\"switch_project\", \"search_tools\", \"execute_tool\", \"execute_ruby\"]\n    }\n  }\n}\n```\n\n### Limitations\n\n- GitHub Copilot Agent only supports MCP **tools**, not resources or prompts\n- The `load_guide` analyzer works via `execute_tool`, but requires guides to be downloaded during setup\n\nFor detailed instructions, see [docs\u002FCOPILOT_AGENT.md](docs\u002FCOPILOT_AGENT.md).\n\n## How the Server Works\n\nThe Rails MCP Server implements the Model Context Protocol using either:\n\n- **STDIO mode**: Reads JSON-RPC 2.0 requests from standard input and returns responses to standard output.\n- **HTTP mode**: Provides HTTP endpoints for JSON-RPC 2.0 requests and Server-Sent Events.\n\nEach request includes a sequence number to match requests with responses, as defined in the MCP specification. The server maintains project context and provides Rails-specific analysis capabilities across multiple codebases.\n\n### Context-Efficient Architecture\n\nThe server uses a progressive tool discovery architecture to minimize context usage. Instead of exposing all tools upfront, it provides 4 bootstrap tools that allow LLMs to discover and invoke additional analyzers on-demand:\n\n- **`switch_project`** - Select the active Rails project\n- **`search_tools`** - Discover available tools by category or keyword\n- **`execute_tool`** - Invoke internal analyzers with parameters\n- **`execute_ruby`** - Run sandboxed Ruby code for custom queries\n\nThis design reduces initial context from ~2,400 tokens to ~800 tokens while maintaining full functionality.\n\n## AI Agent Guide\n\nFor AI agents (Claude, GPT, etc.) using this server, see the comprehensive **[AI Agent Guide](docs\u002FAGENT.md)** which covers:\n\n- Quick start workflow\n- Tool selection guide for common tasks\n- Helper methods available in `execute_ruby`\n- Common pitfalls and how to avoid them\n- Error handling and fallback strategies\n- Integration with other MCP servers (e.g., Neovim MCP)\n\n## Available Tools\n\nThe server provides 4 registered tools plus internal analyzers accessible via `execute_tool`.\n\n### Registered Tools\n\n#### 1. `switch_project`\n\n**Description:** Change the active Rails project. Must be called before using other tools.\n\n**Parameters:**\n\n- `project_name`: (String, required) Name of the project as defined in projects.yml\n\nAfter switching, you'll see a Quick Start guide with common commands.\n\n#### 2. `search_tools`\n\n**Description:** Discover available tools by category or keyword.\n\n**Parameters:**\n\n- `query`: (String, optional) Search term (e.g., 'routes', 'model', 'schema')\n- `category`: (String, optional) Filter by category: models, database, routing, controllers, files, project, guides\n- `detail_level`: (String, optional) Output detail: 'names', 'summary', or 'full' (default: 'summary')\n\n#### 3. `execute_tool`\n\n**Description:** Invoke internal analyzers by name.\n\n**Parameters:**\n\n- `tool_name`: (String, required) Name of the analyzer (e.g., 'get_routes', 'analyze_models')\n- `params`: (Hash, optional) Parameters for the analyzer\n\n#### 4. `execute_ruby`\n\n**Description:** Execute sandboxed Ruby code in the Rails project context.\n\n**Parameters:**\n\n- `code`: (String, required) Ruby code to execute\n- `timeout`: (Integer, optional) Timeout in seconds (default: 30, max: 60)\n\n**Available helper methods:**\n\n- `read_file(path)` - Read a file safely\n- `file_exists?(path)` - Check if a file exists\n- `list_files(pattern)` - Glob files (e.g., `'app\u002Fmodels\u002F**\u002F*.rb'`)\n- `project_root` - Get the project root path\n\n**Note:** Use `puts` to see output from your code.\n\n**Security:** The sandbox prevents file writes, system calls, network access, and reading sensitive files (.env, credentials, etc.).\n\n### Internal Analyzers (via execute_tool)\n\n#### `project_info`\n\nRetrieve comprehensive project information including Rails version, directory structure, and organization.\n\n```\nexecute_tool(tool_name: \"project_info\")\n```\n\n#### `list_files`\n\nList files matching a pattern in a directory.\n\n```\nexecute_tool(tool_name: \"list_files\", params: { directory: \"app\u002Fmodels\", pattern: \"*.rb\" })\n```\n\n#### `get_file`\n\nRetrieve the content of a specific file.\n\n```\nexecute_tool(tool_name: \"get_file\", params: { path: \"app\u002Fmodels\u002Fuser.rb\" })\n```\n\n#### `get_routes`\n\nRetrieve Rails routes with optional filtering.\n\n```\nexecute_tool(tool_name: \"get_routes\")\nexecute_tool(tool_name: \"get_routes\", params: { controller: \"users\" })\nexecute_tool(tool_name: \"get_routes\", params: { verb: \"POST\" })\nexecute_tool(tool_name: \"get_routes\", params: { path_contains: \"api\" })\n```\n\n#### `analyze_models`\n\nAnalyze Active Record models with associations, validations, and optional Prism static analysis.\n\n```\nexecute_tool(tool_name: \"analyze_models\")\nexecute_tool(tool_name: \"analyze_models\", params: { model_name: \"User\" })\nexecute_tool(tool_name: \"analyze_models\", params: { model_name: \"User\", analysis_type: \"full\" })\nexecute_tool(tool_name: \"analyze_models\", params: { detail_level: \"names\" })\n```\n\n**Parameters:**\n\n- `model_name`: Specific model to analyze\n- `model_names`: Array of models to analyze\n- `detail_level`: 'names', 'summary', or 'full'\n- `analysis_type`: 'introspection', 'static', or 'full' (includes Prism AST analysis)\n\n#### `get_schema`\n\nRetrieve database schema information.\n\n```\nexecute_tool(tool_name: \"get_schema\")\nexecute_tool(tool_name: \"get_schema\", params: { table_name: \"users\" })\nexecute_tool(tool_name: \"get_schema\", params: { detail_level: \"tables\" })\n```\n\n#### `analyze_controller_views`\n\nAnalyze controller-view relationships with optional Prism static analysis.\n\n```\nexecute_tool(tool_name: \"analyze_controller_views\")\nexecute_tool(tool_name: \"analyze_controller_views\", params: { controller_name: \"users\" })\nexecute_tool(tool_name: \"analyze_controller_views\", params: { controller_name: \"users\", analysis_type: \"full\" })\n```\n\n#### `analyze_environment_config`\n\nAnalyze environment configurations for inconsistencies and security issues.\n\n```\nexecute_tool(tool_name: \"analyze_environment_config\")\n```\n\n#### `load_guide`\n\nLoad documentation guides from Rails, Turbo, Stimulus, Kamal, or Custom.\n\n```\nexecute_tool(tool_name: \"load_guide\", params: { library: \"rails\" })\nexecute_tool(tool_name: \"load_guide\", params: { library: \"rails\", guide: \"getting_started\" })\nexecute_tool(tool_name: \"load_guide\", params: { library: \"turbo\" })\nexecute_tool(tool_name: \"load_guide\", params: { library: \"stimulus\" })\nexecute_tool(tool_name: \"load_guide\", params: { library: \"custom\", guide: \"tailwind\" })\n```\n\n## Resources and Documentation\n\nThe Rails MCP Server provides access to comprehensive documentation through both the `load_guide` tool and direct MCP resource access. You can access official guides for Rails, Turbo, Stimulus, and Kamal, as well as import your own custom documentation.\n\n### Available Resource Categories\n\n- **Rails Guides**: Official Ruby on Rails 8.0.2 documentation\n- **Turbo Guides**: Official Turbo (Hotwire) framework documentation  \n- **Stimulus Guides**: Official Stimulus JavaScript framework documentation\n- **Kamal Guides**: Official Kamal deployment tool documentation\n- **Custom Guides**: Your imported markdown files\n\n### Getting Started with Resources\n\nThe easiest way to manage resources is using the configuration tool:\n\n```bash\nrails-mcp-config\n```\n\nThen select \"Download guides\" or \"Import custom guides\" from the menu.\n\nAlternatively, you can use the legacy command-line tools:\n\n```bash\n# Download Rails guides\nrails-mcp-server-download-resources rails\n\n# Download Turbo guides\nrails-mcp-server-download-resources turbo\n\n# Import custom markdown files\nrails-mcp-server-download-resources --file \u002Fpath\u002Fto\u002Fyour\u002Fdocs\u002F\n```\n\n### Resource Access Methods\n\n1. **Tool-based access**: Use the `load_guide` tool in conversations\n2. **Direct resource access**: MCP clients can query resources using URI patterns like `rails:\u002F\u002Fguides\u002F{guide_name}`\n\nFor complete information about downloading, managing, and using resources, see the [Resources Guide](docs\u002FRESOURCES.md).\n\n## Testing and Debugging\n\nThe easiest way to test and debug the Rails MCP Server is by using the MCP Inspector, a developer tool designed specifically for testing and debugging MCP servers.\n\nTo use MCP Inspector with Rails MCP Server:\n\n```bash\n# Install and run MCP Inspector\nnpm -g install @modelcontextprotocol\u002Finspector\n\nnpx @modelcontextprotocol\u002Finspector \u002Fpath\u002Fto\u002Frails-mcp-server\n```\n\nThis will:\n\n1. Start your Rails MCP Server in HTTP mode\n2. Launch the MCP Inspector UI in your browser (default port: 6274)\n3. Set up an MCP Proxy server (default port: 6277)\n\nIn the MCP Inspector UI, you can:\n\n- See all available tools (you should see 4 registered tools)\n- Execute tool calls interactively\n- View request and response details\n- Debug issues in real-time\n\nThe Inspector UI provides an intuitive interface to interact with your MCP server, making it easy to test and debug your Rails MCP Server implementation.\n\n### Testing Workflow\n\n1. **Switch to a project:** `switch_project` with your project name\n2. **Discover tools:** `search_tools` to see available analyzers\n3. **Test analyzers:** `execute_tool` to invoke specific analyzers\n4. **Test Ruby execution:** `execute_ruby` with code like `puts read_file('Gemfile')`\n\n## Integration with LLM Clients\n\nThis server is designed to be integrated with LLM clients that support the Model Context Protocol, such as Claude Desktop or other MCP-compatible applications.\n\nTo use with an MCP client:\n\n1. Start the Rails MCP Server (it will use STDIO mode by default)\n2. Connect your MCP-compatible client to the server\n3. The client will be able to use the available tools to interact with your Rails projects\n\n## Security\n\nFor security concerns, please see [SECURITY.md](SECURITY.md).\n\n## License\n\nThis Rails MCP server is released under the MIT License, a permissive open-source license that allows for free use, modification, distribution, and private use.\n\nCopyright (c) 2025 Mario Alberto Chávez Cárdenas\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and\u002For sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at \u003Chttps:\u002F\u002Fgithub.com\u002Fmaquina-app\u002Frails-mcp-server>.\n","# Rails MCP 服务器\n\n一个用于 Rails 项目的模型上下文协议（MCP）服务器的 Ruby 实现。该服务器允许大型语言模型（LLM）通过模型上下文协议与 Rails 项目进行交互，从而提供代码分析、探索和开发辅助等功能。\n\n## 什么是 MCP？\n\n模型上下文协议（MCP）是一种标准化的 AI 模型与其环境交互的方式。它定义了一种结构化的机制，使模型能够在交互过程中请求和使用工具、访问资源，并保持上下文信息。\n\n这个 Rails MCP 服务器实现了 MCP 规范，为 AI 模型提供了访问 Rails 项目的能力，以进行代码分析、探索和辅助开发。\n\n## 特性\n\n- 管理多个 Rails 项目\n- 浏览项目文件和结构\n- 查看带有筛选选项的 Rails 路由\n- 检查模型信息及其关系（借助 Prism 静态分析）\n- 获取数据库模式信息\n- 分析控制器与视图之间的关系\n- 分析环境配置\n- 执行沙箱中的 Ruby 代码以进行自定义查询\n- 访问全面的 Rails、Turbo、Stimulus 和 Kamal 文档\n- 基于上下文高效的架构，支持渐进式工具发现\n- 与 LLM 客户端无缝集成\n\n## 安装\n\n安装 gem：\n\n```bash\ngem install rails-mcp-server\n```\n\n安装完成后，以下可执行文件将出现在您的 PATH 中：\n\n- `rails-mcp-server` - MCP 服务器本身\n- `rails-mcp-config` - 交互式配置工具（推荐）\n- `rails-mcp-setup-claude` - 旧版 Claude Desktop 设置脚本\n- `rails-mcp-server-download-resources` - 旧版资源下载脚本\n\n## 配置\n\n### 使用配置工具（推荐）\n\n配置 Rails MCP 服务器最简单的方式是使用交互式配置工具：\n\n```bash\nrails-mcp-config\n```\n\n该工具提供了一个用户友好的 TUI（终端用户界面），用于：\n\n- **管理项目**：添加、编辑、删除并验证 Rails 项目\n- **下载指南**：下载 Rails、Turbo、Stimulus 和 Kamal 的文档\n- **导入自定义指南**：添加您自己的 Markdown 文档\n- **Claude Desktop 集成**：自动配置 Claude Desktop\n\n如果已安装 [Gum](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Fgum)，该工具将提供更佳体验；否则，它会回退到基本的终端界面。\n\n```bash\n# 安装 Gum 以获得最佳体验（可选）\nbrew install gum        # macOS\nsudo apt install gum    # Debian\u002FUbuntu\nyay -S gum              # Arch Linux\n```\n\n### 手动配置\n\nRails MCP 服务器遵循 XDG 基础目录规范来存储配置文件：\n\n- 在 macOS 上：`$XDG_CONFIG_HOME\u002Frails-mcp` 或者如果未设置 `XDG_CONFIG_HOME`，则为 `~\u002F.config\u002Frails-mcp`\n- 在 Windows 上：`%APPDATA%\\rails-mcp`\n\n服务器首次运行时，会自动创建这些目录以及一个空的 `projects.yml` 文件。\n\n要手动配置您的项目：\n\n1. 编辑配置目录中的 `projects.yml` 文件，加入您的 Rails 项目：\n\n```yaml\nstore: \"~\u002Fprojects\u002Fstore\"\nblog: \"~\u002Fprojects\u002Frails-blog\"\necommerce: \"\u002Ffull\u002Fpath\u002Fto\u002Fecommerce-app\"\n```\n\nYAML 文件中的每个键都是项目名称（将在 `switch_project` 工具中使用），每个值则是项目目录的路径。\n\n## 使用\n\n### 启动服务器\n\nRails MCP 服务器有两种运行模式：\n\n1. **STDIO 模式（默认）**：通过标准输入输出进行通信，以便与 Claude Desktop 等客户端直接集成。\n2. **HTTP 模式**：作为 HTTP 服务器运行，提供 JSON-RPC 和 Server-Sent Events（SSE）端点。\n\n```bash\n# 以默认的 STDIO 模式启动\nrails-mcp-server\n\n# 以 HTTP 模式在默认端口（6029）启动\nrails-mcp-server --mode http\n\n# 以 HTTP 模式在自定义端口启动\nrails-mcp-server --mode http -p 8080\n\n# 以 HTTP 模式绑定到所有接口（以便本地网络访问）\nrails-mcp-server --mode http --bind-all\n```\n\n在 HTTP 模式下，服务器提供两个端点：\n\n- JSON-RPC 端点：`http:\u002F\u002Flocalhost:\u003Cport>\u002Fmcp\u002Fmessages`\n- SSE 端点：`http:\u002F\u002Flocalhost:\u003Cport>\u002Fmcp\u002Fsse`\n\n### 网络访问（HTTP 模式）\n\n默认情况下，HTTP 服务器仅绑定到 localhost，以确保安全性。如果您需要从本地网络中的其他设备访问服务器（例如进行多设备测试），可以使用 `--bind-all` 标志：\n\n```bash\n# 允许本地网络中的任何设备访问\nrails-mcp-server --mode http --bind-all\n\n# 使用自定义端口\nrails-mcp-server --mode http --bind-all -p 8080\n```\n\n当使用 `--bind-all` 时：\n\n- 服务器会绑定到 `0.0.0.0` 而不是 `localhost`\n- 允许来自本地网络 IP 范围（192.168.x.x、10.x.x.x）的访问\n- 服务器接受来自 `.local` 域名的连接（例如 `my-computer.local`）\n- 安全功能仍然有效，以防止未经授权的访问\n\n**安全提示**：请仅在受信任的网络上使用 `--bind-all`。虽然服务器内置了验证来源和 IP 地址的安全功能，但将任何服务暴露到您的网络都会增加攻击面。\n\n### 日志选项\n\n服务器默认将日志记录到 `.\u002Flog` 目录下的文件中。您可以使用以下选项自定义日志：\n\n```bash\n# 设置日志级别（debug、info、error）\nrails-mcp-server --log-level debug\n```\n\n## Claude Desktop 集成\n\nRails MCP 服务器可以与 Claude Desktop 配合使用。有多种方式可以进行设置：\n\n### 方法 1：使用配置工具（推荐）\n\n运行交互式配置工具，并选择“Claude Desktop 集成”：\n\n```bash\nrails-mcp-config\n```\n\n该工具会：\n\n- 检测您当前的 Claude Desktop 配置\n- 让您选择 STDIO 或 HTTP 模式\n- 自动找到正确的 Ruby 和服务器路径\n- 在进行更改之前创建备份\n- 更新 Claude Desktop 的配置\n\n### 方法 2：使用设置脚本（旧版）\n\n运行设置脚本，它会自动配置 Claude Desktop：\n\n```bash\nrails-mcp-setup-claude\n```\n\n该脚本会：\n\n- 为您的平台创建适当的配置目录\n- 如果不存在，则创建一个空的 `projects.yml` 文件\n- 更新 Claude Desktop 的配置\n\n运行脚本后，请重启 Claude Desktop 以使更改生效。\n\n### 方法 3：直接配置\n\n1. 为您的平台创建适当的配置目录：\n   - macOS：`$XDG_CONFIG_HOME\u002Frails-mcp` 或者如果未设置 `XDG_CONFIG_HOME`，则为 `~\u002F.config\u002Frails-mcp`\n   - Windows：`%APPDATA%\\rails-mcp`\n\n2. 在该目录中创建一个包含您的 Rails 项目的 `projects.yml` 文件。\n\n3. 找到或创建 Claude Desktop 的配置文件：\n   - macOS：`~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n   - Windows：`%APPDATA%\\Claude\\claude_desktop_config.json`\n\n4. 添加或更新 MCP 服务器配置：\n\n```json\n{\n  \"mcpServers\": {\n    \"railsMcpServer\": {\n      \"command\": \"ruby\",\n      \"args\": [\"\u002Ffull\u002Fpath\u002Fto\u002Frails-mcp-server\u002Fexe\u002Frails-mcp-server\"] \n    }\n  }\n}\n```\n\n5. 重启 Claude Desktop 以应用更改。\n\n### Ruby 版本管理器用户\n\nClaude Desktop 会使用您系统默认的 Ruby 环境来启动 MCP 服务器，从而绕过版本管理器的初始化（例如 rbenv、RVM）。MCP 服务器需要使用与其安装时相同的 Ruby 版本，因为如果使用不兼容的 Ruby 版本，可能会导致 MCP 服务器启动失败。\n\n如果您正在使用像 rbenv 这样的 Ruby 版本管理器，可以使用 Ruby shim 路径来确保使用正确的版本：\n\n```json\n{\n  \"mcpServers\": {\n    \"railsMcpServer\": {\n      \"command\": \"\u002Fhome\u002Fyour_user\u002F.rbenv\u002Fshims\u002Fruby\",\n      \"args\": [\"\u002Ffull\u002Fpath\u002Fto\u002Frails-mcp-server\u002Fexe\u002Frails-mcp-server\"] \n    }\n  }\n}\n```\n\n请将 `\u002Fhome\u002Fyour_user\u002F.rbenv\u002Fshims\u002Fruby` 替换为您实际的 Ruby shim 路径。\n\n**提示**：`rails-mcp-config` 工具会在配置 Claude Desktop 时自动检测您的 Ruby 路径，并使用正确的 shim 路径。\n\n### 使用 MCP 代理（高级）\n\nClaude Desktop 和许多其他 LLM 客户端仅支持 STDIO 模式通信，但您可能希望利用服务器的 HTTP\u002FSSE 功能。MCP 代理可以弥补这一差距：\n\n1. 以 HTTP 模式启动 Rails MCP 服务器：\n\n```bash\nrails-mcp-server --mode http\n```\n\n2. 安装并运行一个 MCP 代理。目前有多种不同语言实现的 MCP 代理可供选择。MCP 代理允许仅支持 STDIO 通信的客户端通过 HTTP SSE 进行通信。以下是一个基于 JavaScript 的 MCP 代理示例：\n\n```bash\n# 安装基于 Node.js 的 MCP 代理\nnpm install -g mcp-remote\n\n# 运行代理，指向您正在运行的 Rails MCP 服务器\nnpx mcp-remote http:\u002F\u002Flocalhost:6029\u002Fmcp\u002Fsse\n```\n\n3. 配置 Claude Desktop（或其他 LLM 客户端）以使用代理，而不是直接连接到服务器：\n\n```json\n{\n  \"mcpServers\": {\n    \"railsMcpServer\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-remote\", \"http:\u002F\u002Flocalhost:6029\u002Fmcp\u002Fsse\"]\n    }\n  }\n}\n```\n\n通过这种设置，仅支持 STDIO 的客户端可以通过代理与 Rails MCP 服务器通信，在保持客户端兼容性的同时，还能享受到 HTTP\u002FSSE 的功能优势。\n\n**提示**：`rails-mcp-config` 工具可以自动配置 HTTP 模式和 mcp-remote。\n\n## GitHub Copilot Agent 集成\n\nRails MCP 服务器开箱即用，即可与 GitHub Copilot 编码助手配合使用。当从 Rails 目录启动或通过环境变量进行配置时，服务器会自动检测 Rails 项目。\n\n### 快速设置\n\n1. **配置 MCP** - 在您的仓库中创建 `.github\u002Fcopilot\u002Fmcp.json` 文件：\n\n```json\n{\n  \"mcpServers\": {\n    \"rails\": {\n      \"type\": \"local\",\n      \"command\": \"rails-mcp-server\",\n      \"args\": [\"--single-project\"],\n      \"tools\": [\"switch_project\", \"search_tools\", \"execute_tool\", \"execute_ruby\"]\n    }\n  }\n}\n```\n\n2. **设置步骤** - 创建 `.github\u002Fworkflows\u002Fcopilot-setup-steps.yml` 文件：\n\n```yaml\nname: \"Copilot 设置步骤\"\n\non: workflow_dispatch\n\njobs:\n  copilot-setup-steps:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n    steps:\n      - name: 检出代码\n        uses: actions\u002Fcheckout@v4\n\n      - name: 设置 Ruby 环境\n        uses: ruby\u002Fsetup-ruby@v1\n        with:\n          ruby-version: '3.3'\n          bundler-cache: true\n\n      - name: 安装 Rails MCP 服务器\n        run: gem install rails-mcp-server\n```\n\n### 另一种方法：环境变量\n\n您也可以使用 `RAILS_MCP_PROJECT_PATH` 环境变量：\n\n```json\n{\n  \"mcpServers\": {\n    \"rails\": {\n      \"type\": \"local\",\n      \"command\": \"rails-mcp-server\",\n      \"env\": {\n        \"RAILS_MCP_PROJECT_PATH\": \".\"\n      },\n      \"tools\": [\"switch_project\", \"search_tools\", \"execute_tool\", \"execute_ruby\"]\n    }\n  }\n}\n```\n\n### 限制\n\n- GitHub Copilot Agent 仅支持 MCP **工具**，而不支持资源或提示。\n- `load_guide` 分析器通过 `execute_tool` 工作，但需要在设置过程中下载指南。\n\n有关详细说明，请参阅 [docs\u002FCOPILOT_AGENT.md](docs\u002FCOPILOT_AGENT.md)。\n\n## 服务器工作原理\n\nRails MCP 服务器采用模型上下文协议实现，支持以下两种模式：\n\n- **STDIO 模式**：从标准输入读取 JSON-RPC 2.0 请求，并将响应输出到标准输出。\n- **HTTP 模式**：提供用于处理 JSON-RPC 2.0 请求和服务器发送事件的 HTTP 端点。\n\n每个请求都包含序列号，以便根据 MCP 规范匹配请求和响应。服务器会维护项目上下文，并在多个代码库中提供特定于 Rails 的分析功能。\n\n### 上下文高效的架构\n\n服务器采用渐进式工具发现架构，以最大限度地减少上下文使用量。它不会一次性暴露所有工具，而是提供 4 个引导工具，使 LLM 能够按需发现并调用其他分析工具：\n\n- **`switch_project`** - 选择当前活动的 Rails 项目\n- **`search_tools`** - 按类别或关键词发现可用工具\n- **`execute_tool`** - 带参数调用内部分析工具\n- **`execute_ruby`** - 在沙盒环境中运行自定义 Ruby 代码以执行查询\n\n这种设计可将初始上下文从约 2,400 个 token 减少至约 800 个 token，同时仍能保持完整功能。\n\n## AI 代理指南\n\n对于使用本服务器的 AI 代理（Claude、GPT 等），请参阅全面的 **[AI 代理指南](docs\u002FAGENT.md)**，其中涵盖：\n\n- 快速入门流程\n- 常见任务的工具选择指南\n- `execute_ruby` 中可用的帮助方法\n- 常见陷阱及避免方法\n- 错误处理和回退策略\n- 与其他 MCP 服务器（如 Neovim MCP）的集成\n\n## 可用工具\n\n服务器提供了 4 个注册工具以及可通过 `execute_tool` 访问的内部分析工具。\n\n### 已注册工具\n\n#### 1. `switch_project`\n\n**描述:** 切换当前活动的 Rails 项目。在使用其他工具之前必须调用此命令。\n\n**参数:**\n\n- `project_name`: (字符串，必填) 在 projects.yml 中定义的项目名称\n\n切换后，您将看到包含常用命令的快速入门指南。\n\n#### 2. `search_tools`\n\n**描述:** 按类别或关键词查找可用工具。\n\n**参数:**\n\n- `query`: (字符串，可选) 搜索词（例如 'routes', 'model', 'schema'）\n- `category`: (字符串，可选) 按类别筛选：models、database、routing、controllers、files、project、guides\n- `detail_level`: (字符串，可选) 输出详细程度：'names'、'summary' 或 'full'（默认值：'summary'）\n\n#### 3. `execute_tool`\n\n**描述:** 通过名称调用内部分析器。\n\n**参数:**\n\n- `tool_name`: (字符串，必填) 分析器名称（例如 'get_routes', 'analyze_models'）\n- `params`: (哈希，可选) 分析器的参数\n\n#### 4. `execute_ruby`\n\n**描述:** 在 Rails 项目上下文中执行沙盒化的 Ruby 代码。\n\n**参数:**\n\n- `code`: (字符串，必填) 要执行的 Ruby 代码\n- `timeout`: (整数，可选) 超时时间，单位为秒（默认值：30，最大值：60）\n\n**可用的帮助方法:**\n\n- `read_file(path)` - 安全地读取文件\n- `file_exists?(path)` - 检查文件是否存在\n- `list_files(pattern)` - 使用 glob 匹配文件（例如 `'app\u002Fmodels\u002F**\u002F*.rb'`）\n- `project_root` - 获取项目根路径\n\n**注意:** 使用 `puts` 可以查看代码的输出。\n\n**安全性:** 沙盒环境会阻止写入文件、系统调用、网络访问以及读取敏感文件（如 .env、credentials 等）。\n\n### 内部分析器（通过 execute_tool 调用）\n\n#### `project_info`\n\n获取项目的全面信息，包括 Rails 版本、目录结构和组织情况。\n\n```\nexecute_tool(tool_name: \"project_info\")\n```\n\n#### `list_files`\n\n列出目录中匹配特定模式的文件。\n\n```\nexecute_tool(tool_name: \"list_files\", params: { directory: \"app\u002Fmodels\", pattern: \"*.rb\" })\n```\n\n#### `get_file`\n\n获取指定文件的内容。\n\n```\nexecute_tool(tool_name: \"get_file\", params: { path: \"app\u002Fmodels\u002Fuser.rb\" })\n```\n\n#### `get_routes`\n\n获取 Rails 路由，支持可选过滤。\n\n```\nexecute_tool(tool_name: \"get_routes\")\nexecute_tool(tool_name: \"get_routes\", params: { controller: \"users\" })\nexecute_tool(tool_name: \"get_routes\", params: { verb: \"POST\" })\nexecute_tool(tool_name: \"get_routes\", params: { path_contains: \"api\" })\n```\n\n#### `analyze_models`\n\n分析 Active Record 模型及其关联、验证规则，并可选进行 Prism 静态分析。\n\n```\nexecute_tool(tool_name: \"analyze_models\")\nexecute_tool(tool_name: \"analyze_models\", params: { model_name: \"User\" })\nexecute_tool(tool_name: \"analyze_models\", params: { model_name: \"User\", analysis_type: \"full\" })\nexecute_tool(tool_name: \"analyze_models\", params: { detail_level: \"names\" })\n```\n\n**参数:**\n\n- `model_name`: 要分析的具体模型\n- `model_names`: 要分析的模型列表\n- `detail_level`: 'names'、'summary' 或 'full'\n- `analysis_type`: 'introspection'、'static' 或 'full'（包含 Prism AST 分析）\n\n#### `get_schema`\n\n获取数据库模式信息。\n\n```\nexecute_tool(tool_name: \"get_schema\")\nexecute_tool(tool_name: \"get_schema\", params: { table_name: \"users\" })\nexecute_tool(tool_name: \"get_schema\", params: { detail_level: \"tables\" })\n```\n\n#### `analyze_controller_views`\n\n分析控制器与视图之间的关系，可选进行 Prism 静态分析。\n\n```\nexecute_tool(tool_name: \"analyze_controller_views\")\nexecute_tool(tool_name: \"analyze_controller_views\", params: { controller_name: \"users\" })\nexecute_tool(tool_name: \"analyze_controller_views\", params: { controller_name: \"users\", analysis_type: \"full\" })\n```\n\n#### `analyze_environment_config`\n\n分析环境配置中的不一致性和安全问题。\n\n```\nexecute_tool(tool_name: \"analyze_environment_config\")\n```\n\n#### `load_guide`\n\n加载来自 Rails、Turbo、Stimulus、Kamal 或自定义的文档指南。\n\n```\nexecute_tool(tool_name: \"load_guide\", params: { library: \"rails\" })\nexecute_tool(tool_name: \"load_guide\", params: { library: \"rails\", guide: \"getting_started\" })\nexecute_tool(tool_name: \"load_guide\", params: { library: \"turbo\" })\nexecute_tool(tool_name: \"load_guide\", params: { library: \"stimulus\" })\nexecute_tool(tool_name: \"load_guide\", params: { library: \"custom\", guide: \"tailwind\" })\n```\n\n## 资源与文档\n\nRails MCP 服务器通过 `load_guide` 工具以及直接的 MCP 资源访问功能，提供了对全面文档的访问权限。您可以访问 Rails、Turbo、Stimulus 和 Kamal 的官方指南，也可以导入您自己的自定义文档。\n\n### 可用资源类别\n\n- **Rails 指南**: 官方 Ruby on Rails 8.0.2 文档\n- **Turbo 指南**: 官方 Turbo（Hotwire）框架文档\n- **Stimulus 指南**: 官方 Stimulus JavaScript 框架文档\n- **Kamal 指南**: 官方 Kamal 部署工具文档\n- **自定义指南**: 您导入的 Markdown 文件\n\n### 开始使用资源\n\n管理资源最简单的方式是使用配置工具：\n\n```bash\nrails-mcp-config\n```\n\n然后从菜单中选择“下载指南”或“导入自定义指南”。\n\n或者，您也可以使用旧版命令行工具：\n\n```bash\n# 下载 Rails 指南\nrails-mcp-server-download-resources rails\n\n# 下载 Turbo 指南\nrails-mcp-server-download-resources turbo\n\n# 导入自定义 Markdown 文件\nrails-mcp-server-download-resources --file \u002Fpath\u002Fto\u002Fyour\u002Fdocs\u002F\n```\n\n### 资源访问方式\n\n1. **工具访问**: 在对话中使用 `load_guide` 工具\n2. **直接资源访问**: MCP 客户端可以使用 URI 模式查询资源，例如 `rails:\u002F\u002Fguides\u002F{guide_name}`\n\n有关下载、管理和使用资源的完整信息，请参阅 [资源指南](docs\u002FRESOURCES.md)。\n\n## 测试与调试\n\n测试和调试 Rails MCP 服务器最简单的方法是使用 MCP Inspector，这是一款专为测试和调试 MCP 服务器而设计的开发者工具。\n\n要在 Rails MCP 服务器上使用 MCP Inspector：\n\n```bash\n# 安装并运行 MCP Inspector\nnpm -g install @modelcontextprotocol\u002Finspector\n\nnpx @modelcontextprotocol\u002Finspector \u002Fpath\u002Fto\u002Frails-mcp-server\n```\n\n这将：\n\n1. 以 HTTP 模式启动您的 Rails MCP 服务器\n2. 在浏览器中打开 MCP Inspector UI（默认端口：6274）\n3. 设置一个 MCP 代理服务器（默认端口：6277）\n\n在 MCP Inspector UI 中，您可以：\n\n- 查看所有可用工具（您应该能看到 4 个已注册工具）\n- 交互式地执行工具调用\n- 查看请求和响应详情\n- 实时调试问题\n\nInspector UI 提供了一个直观的界面来与您的 MCP 服务器交互，使测试和调试您的 Rails MCP 服务器实现变得非常容易。\n\n### 测试工作流\n\n1. **切换到项目：** 使用 `switch_project` 命令并指定你的项目名称\n2. **发现工具：** 运行 `search_tools` 查看可用的分析工具\n3. **测试分析工具：** 使用 `execute_tool` 调用特定的分析工具\n4. **测试 Ruby 代码执行：** 运行 `execute_ruby`，传入类似 `puts read_file('Gemfile')` 的代码\n\n## 与 LLM 客户端的集成\n\n本服务器旨在与支持模型上下文协议（MCP）的 LLM 客户端集成，例如 Claude Desktop 或其他兼容 MCP 的应用。\n\n使用 MCP 客户端的步骤如下：\n\n1. 启动 Rails MCP 服务器（默认使用 STDIO 模式）\n2. 将兼容 MCP 的客户端连接到服务器\n3. 客户端即可使用提供的工具与你的 Rails 项目进行交互\n\n## 安全性\n\n有关安全性问题，请参阅 [SECURITY.md](SECURITY.md)。\n\n## 许可证\n\n本 Rails MCP 服务器采用 MIT 许可证发布，这是一种宽松的开源许可证，允许自由使用、修改、分发及用于私有用途。\n\n版权所有 © 2025 马里奥·阿尔贝托·查韦斯·卡德纳斯\n\n特此授予任何人免费获取本软件及其相关文档文件（以下简称“软件”）副本的权利，以不受限制的方式处理该软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和\u002F或销售该软件副本的权利；并允许向任何获得本软件的人提供本软件以供其使用，但须遵守以下条件：\n\n上述版权声明及本许可声明应包含在本软件的所有副本或实质性部分中。\n\n本软件按“原样”提供，不提供任何形式的明示或暗示保证，包括但不限于适销性、特定用途适用性和非侵权性。在任何情况下，作者或版权所有者均不对因本软件或其使用而引起的任何索赔、损害或其他责任负责，无论此类责任是基于合同、侵权行为或其他原因产生的，且在任何情况下，作者或版权所有者均不承担任何责任。\n\n## 贡献\n\n欢迎在 GitHub 上提交错误报告和拉取请求：\u003Chttps:\u002F\u002Fgithub.com\u002Fmaquina-app\u002Frails-mcp-server>。","# Rails MCP Server 快速上手指南\n\nRails MCP Server 是一个基于 Ruby 实现的模型上下文协议（MCP）服务器，专为 Rails 项目设计。它允许大语言模型（LLM）通过标准化协议与你的 Rails 代码库交互，提供代码分析、路由查看、模型关系检查及开发辅助等功能。\n\n## 环境准备\n\n在开始之前，请确保你的开发环境满足以下要求：\n\n*   **操作系统**：macOS、Linux 或 Windows (WSL)。\n*   **Ruby 环境**：已安装 Ruby（推荐版本 3.0+）。如果你使用 `rbenv` 或 `RVM`，请确保已正确初始化。\n*   **Gem 源加速（推荐）**：国内开发者建议将 Gem 源切换至国内镜像以加快安装速度。\n    ```bash\n    gem sources --add https:\u002F\u002Fgems.ruby-china.com\u002F --remove https:\u002F\u002Frubygems.org\u002F\n    gem sources -l # 确认列表中包含 ruby-china 源\n    ```\n*   **可选增强体验**：安装 `gum` 工具以获得更友好的交互式配置界面（非必须，但强烈推荐）。\n    *   macOS: `brew install gum`\n    *   Debian\u002FUbuntu: `sudo apt install gum`\n    *   Arch Linux: `yay -S gum`\n\n## 安装步骤\n\n### 1. 安装核心组件\n使用 gem 命令安装服务器：\n\n```bash\ngem install rails-mcp-server\n```\n\n安装完成后，以下可执行文件将自动添加到你的系统路径中：\n*   `rails-mcp-server`：MCP 服务器主程序。\n*   `rails-mcp-config`：交互式配置工具（推荐使用）。\n*   `rails-mcp-setup-claude`：Claude Desktop 传统设置脚本。\n\n### 2. 配置项目\n推荐使用交互式工具进行配置，它可以帮助你管理项目路径、下载文档并集成 Claude Desktop。\n\n运行配置工具：\n```bash\nrails-mcp-config\n```\n\n在该界面中你可以：\n*   **添加\u002F编辑项目**：指定你的 Rails 项目绝对路径。\n*   **下载文档**：自动获取 Rails、Turbo、Stimulus 和 Kamal 的官方文档供 AI 参考。\n*   **集成客户端**：自动检测并配置 Claude Desktop。\n\n> **手动配置替代方案**：\n> 如果不使用交互工具，可在配置目录（macOS: `~\u002F.config\u002Frails-mcp` 或 Windows: `%APPDATA%\\rails-mcp`）下创建 `projects.yml` 文件：\n> ```yaml\n> my_store: \"~\u002Fprojects\u002Fstore\"\n> my_blog: \"~\u002Fprojects\u002Frails-blog\"\n> ```\n\n## 基本使用\n\nRails MCP Server 通常作为后端服务运行，由支持 MCP 协议的 AI 客户端（如 Claude Desktop、GitHub Copilot Agent）调用。\n\n### 模式一：配合 Claude Desktop 使用（最常用）\n\n1.  **运行配置**：执行 `rails-mcp-config` 并按照提示完成 \"Claude Desktop integration\" 设置。该工具会自动处理 Ruby 路径和配置文件。\n2.  **重启客户端**：完全退出并重新启动 Claude Desktop。\n3.  **开始对话**：在 Claude Desktop 中选择已配置的 Rails 项目，即可询问关于代码结构、路由、数据库架构等问题。\n\n### 模式二：独立启动服务器（调试或自定义集成）\n\n你可以手动启动服务器以测试连接或配合其他客户端。\n\n**启动 STDIO 模式（默认，用于直接管道通信）：**\n```bash\nrails-mcp-server\n```\n\n**启动 HTTP 模式（用于网络访问或通过代理连接）：**\n```bash\n# 默认端口 6029\nrails-mcp-server --mode http\n\n# 指定端口并允许局域网访问\nrails-mcp-server --mode http -p 8080 --bind-all\n```\n\n### 模式三：GitHub Copilot Agent 集成\n\n若在 GitHub Copilot Coding Agent 中使用，需在仓库根目录创建 `.github\u002Fcopilot\u002Fmcp.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"rails\": {\n      \"type\": \"local\",\n      \"command\": \"rails-mcp-server\",\n      \"args\": [\"--single-project\"],\n      \"tools\": [\"switch_project\", \"search_tools\", \"execute_tool\", \"execute_ruby\"]\n    }\n  }\n}\n```\n\n确保在 CI 或本地环境中已执行 `gem install rails-mcp-server`。\n\n---\n**提示**：服务器采用“渐进式工具发现”架构，初始上下文极小。AI 会通过 `search_tools` 和 `execute_tool` 按需加载分析器，从而高效地分析大型 Rails 项目。","资深后端工程师小李正接手一个遗留的电商 Rails 项目，需要在两天内理清复杂的订单模块逻辑并修复一个隐蔽的数据关联 Bug。\n\n### 没有 rails-mcp-server 时\n- **盲目翻阅代码**：为了搞清 `Order` 模型与其他表的关联，不得不手动打开十几个文件逐行搜索 `has_many` 或 `belongs_to`，效率极低且容易遗漏。\n- **路由定位困难**：面对数百条路由配置，只能靠全局关键词搜索猜测某个 API 对应的控制器动作，经常找错文件或版本。\n- **文档查阅割裂**：遇到不熟悉的 Turbo 或 Stimulus 写法时，需频繁切换浏览器查阅官方文档，打断编程心流。\n- **环境理解成本高**：难以快速确认不同环境下的配置差异，导致本地复现生产环境问题时反复试错。\n- **静态分析缺失**：缺乏自动化的代码结构洞察，完全依赖个人经验推断控制器与视图的绑定关系，极易产生误判。\n\n### 使用 rails-mcp-server 后\n- **一键洞察模型**：直接让 AI 调用工具 inspect 模型信息，瞬间生成包含所有外键关联和 Prism 静态分析结果的完整图谱。\n- **精准路由过滤**：通过自然语言指令筛选特定资源的路由，秒级定位到具体的 Controller Action 及其参数定义。\n- **上下文无缝集成**：AI 直接在对话中访问内置的 Rails、Turbo 及 Kamal 官方文档，无需跳出终端即可获取权威解释。\n- **配置智能解析**：自动分析环境配置文件，快速指出开发环境与生产环境的差异点，大幅缩短问题复现路径。\n- **全链路关系推导**：利用工具自动分析控制器与视图的对应关系，准确识别代码调用链，让重构和修 Bug 有的放矢。\n\nrails-mcp-server 通过将 Rails 项目结构转化为 AI 可理解的标准化上下文，把原本数小时的代码考古工作压缩到了分钟级。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmaquina-app_rails-mcp-server_f3bc51af.png","maquina-app","maquina.app","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fmaquina-app_cd37c27b.png","",null,"https:\u002F\u002Fmaquina.app","https:\u002F\u002Fgithub.com\u002Fmaquina-app",[81],{"name":82,"color":83,"percentage":84},"Ruby","#701516",100,537,33,"2026-04-14T22:02:11","MIT","Linux, macOS, Windows","未说明",{"notes":92,"python":93,"dependencies":94},"该工具是基于 Ruby 实现的 MCP 服务器，非 Python 项目。安装需使用 `gem install rails-mcp-server`。若使用 rbenv 或 RVM 等版本管理器，在配置 Claude Desktop 时需指定正确的 Ruby shim 路径以避免启动失败。支持 STDIO 和 HTTP 两种运行模式，HTTP 模式默认仅绑定 localhost，如需局域网访问需添加 `--bind-all` 参数。","不适用 (基于 Ruby)",[95,96,97],"Ruby (版本需与安装环境一致)","Gum (可选，用于增强配置体验)","mcp-remote (可选，用于 HTTP 模式代理)",[15,26],"2026-03-27T02:49:30.150509","2026-04-18T02:22:11.670819",[102,107,112,117,122,127],{"id":103,"question_zh":104,"answer_zh":105,"source_url":106},38527,"在 macOS 上安装时遇到 \"comparison of Symbol with 1 failed (ArgumentError)\" 错误怎么办？","这是一个已知问题，通常由旧版本引起。维护者已发布新版本修复了该问题。请尝试更新 gem 到最新版本：\n`gem install rails-mcp-server`\n如果问题依旧，请检查是否有相关的 Pull Request（如 PR #8）已合并修复。","https:\u002F\u002Fgithub.com\u002Fmaquina-app\u002Frails-mcp-server\u002Fissues\u002F7",{"id":108,"question_zh":109,"answer_zh":110,"source_url":111},38528,"使用 Cline 扩展或 Cody 时出现 \"cannot load such file -- mcp (LoadError)\" 错误如何解决？","这通常是因为 Ruby 环境路径未正确加载。解决方案有两种：\n1. **临时修复**：在代码中直接使用 `mcp` gem 的绝对路径，例如：`require '\u002FUsers\u002F你的用户名\u002F.rvm\u002Fgems\u002Fruby-3.2.0\u002Fgems\u002Fmcp-rb-0.3.2\u002Flib\u002Fmcp.rb'`。\n2. **推荐修复**：创建一个 Ruby 包装脚本（ruby-wrapper），用于初始化 rbenv 或 RVM 环境。脚本内容如下：\n```ruby\n#!\u002Fusr\u002Fbin\u002Fenv ruby\nrequire 'shellwords'\ninit_commands = []\nif File.exist?(File.expand_path(\"~\u002F.rbenv\"))\n  init_commands \u003C\u003C 'eval \"$(rbenv init -)\"'\nelsif File.exist?(File.expand_path(\"~\u002F.rvm\"))\n  init_commands \u003C\u003C 'source ~\u002F.rvm\u002Fscripts\u002Frvm'\nend\n# ... (后续逻辑用于捕获环境变量并执行命令)\n```\n赋予执行权限 `chmod +x \u002Fpath\u002Fto\u002Fruby-wrapper`，然后在 `claude_desktop_config.json` 中将 command 指向该脚本的全路径。此外，确保安装了 `shellwords` gem (`gem install shellwords`)。","https:\u002F\u002Fgithub.com\u002Fmaquina-app\u002Frails-mcp-server\u002Fissues\u002F1",{"id":113,"question_zh":114,"answer_zh":115,"source_url":116},38529,"在大型代码库中使用 `get_project_info` 工具时提示 \"Your conversation is too long\" 怎么办？","这是因为一次性加载整个项目导致上下文过长。建议采取以下措施：\n1. **升级版本**：升级到支持 HTTP SSE 的新版本服务器，这有助于更有效地管理数据流。\n2. **配置忽略规则**：确保工具自动忽略 `.git`、`node_modules` 和 vendor 目录，避免读取不必要的文件。\n3. **参考最佳实践**：查阅相关博客文章了解如何配置 Claude 以避免其“创造性”地一次性加载所有项目内容。","https:\u002F\u002Fgithub.com\u002Fmaquina-app\u002Frails-mcp-server\u002Fissues\u002F2",{"id":118,"question_zh":119,"answer_zh":120,"source_url":121},38530,"如何在 GitHub Copilot Agent 中配置 rails-mcp-server（特别是在没有持久化用户目录的环境中）？","GitHub Copilot Agent 运行在无持久化用户目录的环境中，依赖 `projects.yml` 会失效。解决方案是使用 `--single-project` 标志（需在 v1.5.0 或更高版本中）：\n1. 该标志会跳过 `projects.yml` 检查。\n2. 直接使用当前目录作为项目。\n3. 启动时自动切换项目。\n\nMCP 配置示例 (`settings.json` 或 repo settings)：\n```json\n{\n  \"mcpServers\": {\n    \"rails\": {\n      \"type\": \"local\",\n      \"command\": \"rails-mcp-server\",\n      \"args\": [\"--single-project\"],\n      \"tools\": [\"switch_project\", \"search_tools\", \"execute_tool\", \"execute_ruby\"]\n    }\n  }\n}\n```\n注意：Copilot Agent 仅支持 MCP **tools**，不支持 resources，因此无法通过资源机制获取文档指南。","https:\u002F\u002Fgithub.com\u002Fmaquina-app\u002Frails-mcp-server\u002Fissues\u002F18",{"id":123,"question_zh":124,"answer_zh":125,"source_url":126},38531,"运行 MCP 服务器时出现 JSON ParseError 是什么原因？","这通常是因为服务器可执行文件中使用了 `puts` 输出调试信息，破坏了标准的 JSON-RPC 通信格式。维护者已确认此问题并将 `puts` 调用改为日志记录语句。请升级到最新版本的 `rails-mcp-server` 以获取修复。","https:\u002F\u002Fgithub.com\u002Fmaquina-app\u002Frails-mcp-server\u002Fissues\u002F12",{"id":128,"question_zh":129,"answer_zh":130,"source_url":116},38532,"如何在 Cursor 编辑器中安装和配置 rails-mcp-server？","虽然具体步骤可能随版本更新，但通用配置流程如下：\n1. 确保已安装 Ruby 和 `rails-mcp-server` gem。\n2. 在 Cursor 的设置中找到 MCP Servers 配置部分。\n3. 添加新的服务器配置，指定命令为 `rails-mcp-server`。\n4. 如果是大型项目，建议参考 HTTP SSE 的配置方式以避免上下文过长问题。\n5. 如果遇到路径问题，可能需要像配置 Claude Desktop 一样使用包装脚本来确保 Ruby 环境正确加载。",[132,137,142,147,152,157,162,167],{"id":133,"version":134,"summary_zh":135,"released_at":136},312093,"v1.5.1","放宽 gemspec 中的次要版本锁定（logger、puma、rack），以允许兼容的补丁更新。使用最新的依赖项更新 Gemfile.lock。","2026-03-05T02:44:55",{"id":138,"version":139,"summary_zh":140,"released_at":141},312094,"v1.4.1","修复了通过 rbenv shim 运行时的静默失败问题。","2025-12-11T16:42:51",{"id":143,"version":144,"summary_zh":145,"released_at":146},312095,"v1.4.0","本次重大发布通过全新的渐进式工具发现架构，将初始上下文消耗降低了67%，该架构基于[Anthropic的MCP最佳实践](https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Fbuilding-effective-agents)。\n\n## 亮点\n\n### 上下文高效架构\n- 已注册的MCP工具从12个减少到4个引导工具\n- 9个内部分析器通过`search_tools`按需发现，并通过`execute_tool`调用\n- 在与AI助手协作时显著降低令牌使用量\n\n### 沙箱化的Ruby执行\n新的`execute_ruby`工具允许在Rails环境中安全地执行代码，具备以下特性：\n- 文件、网络和系统调用限制\n- 敏感文件保护（如`.env`、凭据以及被`.gitignore`忽略的文件）\n- 辅助方法：`read_file`、`file_exists?`、`list_files`、`project_root`\n\n### 交互式配置工具\n全新的`rails-mcp-config` TUI用于：\n- 带验证的项目管理\n- 带进度指示器的指南下载\n- Claude Desktop自动配置（STDIO\u002FHTTP模式）\n- 使用Gum增强的UI，并提供终端回退方案\n\n### Rails内省功能（替代正则表达式解析）\n- 使用真实的Rails API（`reflect_on_all_associations`、`validators`、`action_methods`）\n- 更准确的模型和控制器分析\n- 基于Prism的静态分析，用于回调、作用域和混入模块\n\n### 输出优化\n- 新增`detail_level`参数：仅名称 | 简要摘要 | 完整详细信息\n- 可按控制器、HTTP动词或路径筛选路由\n- 支持对模型和数据库模式的批量操作\n\n## 完整变更日志\n完整详情请参阅[CHANGELOG.md](https:\u002F\u002Fgithub.com\u002Fmaquina-app\u002Frails-mcp-server\u002Fblob\u002Fmain\u002FCHANGELOG.md)。","2025-12-11T00:06:22",{"id":148,"version":149,"summary_zh":150,"released_at":151},312096,"v1.2.3","此版本修复了 `rails-mcp-setup-claude` 在只读文件系统（如 NixOS）上，或当用户不是可执行文件的所有者时无法正常运行的问题。\n\n感谢 @emptyflask 的贡献！","2025-12-10T20:56:30",{"id":153,"version":154,"summary_zh":155,"released_at":156},312097,"v1.2.1","此版本修复了一个通过 STDIO 连接时生成无效 JSON 的 bug。","2025-06-09T23:39:51",{"id":158,"version":159,"summary_zh":160,"released_at":161},312098,"v1.2.0","### 新增功能\n\n- **全面的资源与文档系统**：完整访问 Rails 生态系统的文档\n  - `load_guide` 工具用于访问官方框架文档\n  - 支持 Rails、Turbo、Stimulus 和 Kamal 的文档\n  - 自定义 Markdown 文件导入功能\n  - 通过 `rails-mcp-server-download-resources` 命令自动下载资源\n  - 资源存储在符合 XDG 规范的目录中，并附带清单文件进行跟踪\n- **五大资源类别**：\n  - **Rails 指南**：Ruby on Rails 8.0.2 官方文档（50 多篇指南）\n  - **Turbo 指南**：Hotwire Turbo 框架的完整文档\n  - **Stimulus 指南**：Stimulus JavaScript 框架的全部文档\n  - **Kamal 指南**：Kamal 部署工具的全面文档\n  - **自定义指南**：导入并管理您自己的 Markdown 文档\n- **直接资源访问**：MCP 客户端可使用 URI 模板查询资源\n  - `rails:\u002F\u002Fguides\u002F{guide_name}` 用于 Rails 文档\n  - `turbo:\u002F\u002Fguides\u002F{guide_name}` 用于 Turbo 指南\n  - `stimulus:\u002F\u002Fguides\u002F{guide_name}` 用于 Stimulus 文档\n  - `kamal:\u002F\u002Fguides\u002F{guide_name}` 用于 Kamal 指南\n  - `custom:\u002F\u002Fguides\u002F{guide_name}` 用于自定义导入\n- **高级资源管理**：\n  - 强制下载选项 (`--force`) 用于更新资源\n  - 详细日志记录 (`--verbose`) 用于故障排除\n  - 批量导入支持，适用于目录结构\n  - 自定义导入时的文件名规范化\n  - 版本跟踪与更新管理\n\n### 优化改进\n\n- **增强的文档说明**：所有工具现均包含详尽的自然语言示例\n- **资源集成**：与现有 MCP 工具生态无缝集成\n- **文件组织**：项目结构更佳，符合 XDG 基础目录规范\n- **错误处理**：在各项资源操作中，验证与错误信息得到进一步改善\n\n### 技术细节\n\n- 支持 URI 模板化，实现直接资源访问\n- 增强了清单文件管理，便于资源跟踪\n- 与 FastMCP 集成，提供强大的资源处理能力\n- 简化了指南的配置与管理流程","2025-06-03T17:04:20",{"id":163,"version":164,"summary_zh":165,"released_at":166},312099,"v1.1.4","- 修复了导致 Puma 服务器无法以 HTTP 模式启动的问题\r\n- 修复了调用 Rails 命令时出现的问题","2025-05-02T20:10:26",{"id":168,"version":169,"summary_zh":170,"released_at":171},312100,"v1.1.2","在此次变更之前，该 Gem 并未指定依赖项的版本。因此，每次安装都可能引入不同版本的依赖（较旧或较新），这可能导致服务器出现不可预测或不稳定的行为。","2025-04-27T19:09:04"]