Mario Alberto Chávez

Blog personal desarrollo de software

Menú
Desarrollo

Rails MCP Server: Enhanced Documentation Access

Rails MCP Server: Enhanced Documentation Access and AI Workflow Integration

Updated Rails MCP Server now provides consistent, up-to-date Rails documentation across multiple LLM clients with enhanced proxy support and Neovim integration.

Table of Contents

The latest updates to Rails MCP Server introduce significant improvements to documentation access, better integration capabilities, and enhanced workflow support that have transformed how I work with Rails projects using AI assistance.

Comprehensive Documentation Resources

The most significant addition in this release is the comprehensive Resources and Documentation system. This addresses a critical need in AI-assisted development: providing LLM clients with consistent, up-to-date documentation that can be shared across multiple AI sessions and different LLM providers.

The Documentation Challenge

When working with AI assistants on Rails projects, I frequently encountered situations where the LLM’s training data was outdated or incomplete regarding specific framework features. This led to suggestions based on deprecated APIs or missing newer functionality. The resource system solves this by:

  • Ensuring accuracy: LLMs receive the exact same official documentation that developers reference
  • Maintaining consistency: Multiple AI sessions can access identical documentation, ensuring consistent guidance
  • Staying current: Documentation can be updated to match specific Rails versions or framework releases
  • Sharing context: The same documentation resources work across different LLM clients and providers

Five Resource Categories Available

The server now provides access to five complete documentation libraries:

1. Rails Guides Documentation

  • Content: Official Ruby on Rails 8.0.2 documentation - all 50+ guides
  • Coverage: Getting started to advanced topics including Active Record, Action Pack, security, and deployment
  • Use case: Comprehensive Rails framework reference

2. Turbo Framework Documentation

  • Content: Complete Hotwire Turbo framework documentation
  • Structure: Handbook and reference sections covering Turbo Drive, Frames, and Streams
  • Use case: Modern Rails frontend development with Hotwire

3. Stimulus JavaScript Framework Documentation

  • Content: Full Stimulus documentation for building interactive components
  • Structure: Handbook tutorials and API reference
  • Use case: JavaScript interactions in Rails applications

4. Kamal Deployment Documentation

  • Content: Comprehensive Kamal deployment tool documentation
  • Coverage: Installation, configuration, commands, and deployment strategies
  • Use case: Modern Rails application deployment

5. Custom Documentation Resources

  • Content: Import and access your own markdown documentation files
  • Flexibility: Project-specific guides, API documentation, team standards
  • Use case: Maintaining consistent project documentation across AI sessions

Setting Up Documentation Resources

Setting up documentation is straightforward with the dedicated download tool:

# Download official framework documentation
rails-mcp-server-download-resources rails
rails-mcp-server-download-resources turbo
rails-mcp-server-download-resources stimulus
rails-mcp-server-download-resources kamal

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

# Force update existing resources
rails-mcp-server-download-resources --force rails

# Verbose output for troubleshooting
rails-mcp-server-download-resources --verbose turbo

Once downloaded, you can access guides naturally in conversation:

Can you load the Rails getting started guide?
Show me the Turbo Frames documentation.
I need help with Stimulus controllers - can you show me that guide?
Load the Kamal deployment guide so I can understand the process.

MCP Proxy Integration for Better Compatibility

Building on the previous release with HTTP SSE support, this update includes comprehensive documentation for using MCP proxies to address Ruby version manager compatibility issues that many developers face with Claude Desktop.

Setting Up MCP Proxy for Enhanced Compatibility

For users who want to leverage the HTTP/SSE capabilities or work around Ruby version manager issues:

Step 1: Start Rails MCP Server in HTTP Mode

rails-mcp-server --mode http

Step 2: Install and Configure MCP Proxy

# 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

Step 3: Configure Claude Desktop for Proxy Usage

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

This setup allows STDIO-only clients to communicate through the proxy while benefiting from HTTP/SSE capabilities and avoiding Ruby version conflicts.

Rails MCP + Neovim MCP Integration Workflow

I’ve significantly improved my development workflow by combining the Rails MCP Server with the Neovim MCP Server. This combination creates a powerful development environment where I can seamlessly work with both my Rails codebase and my active editing context.

The Two-Server Development Approach

Here’s how I use both MCP servers together for enhanced productivity:

Rails MCP Server handles:

  • Project structure analysis and exploration
  • Database schema exploration and relationships
  • Route inspection and API endpoint analysis
  • Model relationship analysis and validations
  • Access to comprehensive Rails ecosystem documentation

Neovim MCP Server provides:

  • Real-time access to currently open buffers
  • Context about active editing sessions
  • Bridge between editor state and AI assistance
  • Live file content without manual specification

Optimized Development Session Workflow

When I start a development session, I begin with context gathering:

Switch to project my_rails_app, don't analyze anything yet.
Show me which files I have open in my "my_rails_app" Neovim instance.

This gives me both project context from Rails MCP and my current editing context from Neovim MCP. Then I can work more efficiently:

Load the User model from Rails and also get the user_controller.rb that I have open in Neovim.
Can you also load the Rails Active Record associations guide for reference?

Benefits of the Dual-Server Approach

This approach allows me to:

  • Work with live context: See exactly what I’m editing without manually specifying files
  • Access comprehensive documentation: Get official guides loaded instantly for reference
  • Maintain project focus: Switch between Rails projects while keeping editor context
  • Avoid manual file management: Let the tools handle finding and loading the right files

Managing Token Usage Effectively

I’ve refined my prompting strategy to manage Claude’s context window more effectively:

Session Start:

Switch to project my_finances, don't analyze the project or any loaded files until you are told to.

Loading Files:

Load the following files from my Neovim buffers, do not analyze or try to load dependencies unless you are told to.

Session Continuation: When reaching conversation limits, I summarize and continue:

Summarize this chat. Describe the goal and add relevant information about what was done. Include the project name and list any files loaded, generated or shared.

Documentation as a Shared Resource

The resource system transforms documentation from a static reference into a dynamic, shared asset. When I load Rails validation documentation in one conversation, another AI session can access the same exact information. This consistency is particularly valuable when:

  • Training team members: Everyone gets the same documentation regardless of which AI tool they use
  • Maintaining project standards: Documentation stays consistent across different development sessions
  • Working with multiple LLM providers: The same Rails 8.0.2 guides work identically with Claude, ChatGPT, or other MCP-compatible clients
  • Ensuring version alignment: Projects can specify exact documentation versions to match their Rails installation

Instead of switching to browser tabs or searching through docs, I can load exactly the guide I need:

I'm working on validations - can you load the Rails validations guide?
Show me the Turbo Streams reference for this real-time update feature.
Load my custom API documentation so we can follow the established patterns.

The system handles both official framework documentation and custom project documentation seamlessly, making it a true companion for Rails development.

Resource Management and Best Practices

Managing resources is straightforward with clear commands and automatic organization:

Resource Organization Best Practices

  • Download once, use everywhere: Resources are stored locally and available across all conversations
  • Automatic updates: Re-download to get the latest documentation versions
  • Custom integration: Import your project-specific documentation alongside official guides
  • Intelligent organization: Resources are categorized and easily discoverable

Resource Storage and Management

Resources are stored in platform-specific locations:

  • macOS: ~/.config/rails-mcp/resources/
  • Windows: %APPDATA%\rails-mcp\resources\

Each resource category maintains a manifest file tracking downloaded guides, versions, and update timestamps.

Performance Optimization Tips

  1. Selective downloads: Only download resources you actively use
  2. Regular updates: Keep documentation current with framework releases
  3. Custom documentation: Organize project-specific guides with descriptive filenames
  4. Version alignment: Match documentation versions to your Rails installation

For complete details on setting up and using resources, I’ve created a comprehensive Resources Guide that covers everything from basic setup to advanced usage patterns.

FAQ

How do I update Rails MCP Server documentation resources?

Re-run the download command for any resource category to get the latest version:

rails-mcp-server-download-resources rails

Can I use Rails MCP Server with other AI clients besides Claude Desktop?

Yes! The MCP proxy setup allows compatibility with any MCP-compatible client. The HTTP/SSE endpoints work with various LLM providers.

What’s the difference between Rails MCP Server and Neovim MCP Server?

  • Rails MCP Server: Analyzes Rails project structure, database, routes, and provides Rails ecosystem documentation
  • Neovim MCP Server: Provides access to currently open files in your editor sessions

How do I troubleshoot Ruby version manager issues with Claude Desktop?

Use the MCP proxy setup to bypass Ruby version conflicts, or create a symbolic link as described in the Ruby Version Manager Users section.

Can I import custom documentation alongside official Rails guides?

Yes! Use the --file option to import your own markdown files:

rails-mcp-server-download-resources --file /path/to/your/docs/

Looking Forward

This enhanced Rails MCP Server has become an integral part of my Rails development workflow. The combination of comprehensive documentation access, improved integration options, and seamless editor integration through the Neovim MCP Server creates a development environment where AI assistance feels natural and productive.

The ability to instantly access official documentation, work with live editing context, and maintain project focus has significantly improved my development velocity and the quality of my AI-assisted coding sessions.

I encourage you to try both servers together and explore the new resource system. The documentation access alone makes this upgrade worthwhile, and the improved integration options ensure it works well regardless of your development setup.

Source code and detailed setup instructions:

The Rails MCP Server continues to evolve based on real-world usage. If you have suggestions or encounter issues, please feel free to open an issue or contribute to the project.