A Ruby gem that adds Model Context Protocol (MCP) server capabilities to Rails applications, exposing comprehensive Rails introspection methods through a standardized MCP interface. This enables AI assistants to understand and interact with Rails application structure, models, routes, database schema, and configuration.

• Complete Rails Introspection: Models, routes, controllers, database schema, gems, and configuration
• MCP Protocol Compliance: Full support for MCP 2025-06-18 specification
• Multiple Transport Options: stdio and HTTP transports
• Security First: Configurable access controls, data filtering, and audit logging
• Development Friendly: Easy integration with existing Rails applications
• AI Assistant Ready: Works with Claude Desktop, VSCode, Cursor, WindSurf, and other MCP clients

Add this line to your Rails application's Gemfile:

gem 'rails-introspec-mcp', group: [:development, :test]

And then execute:

$ bundle install

Or install it yourself as:

$ gem install rails-introspec-mcp

$ rails generate rails_introspec_mcp:install

This creates config/initializers/rails_introspec_mcp.rb with default configuration.

# config/initializers/rails_introspec_mcp.rb
RailsIntrospecMcp.configure do |config|
  # Enable/disable MCP server
  config.enabled = Rails.env.development?
  
  # Server configuration
  config.transport = :stdio  # or :http
  config.port = 3001         # for HTTP transport
  
  # Security settings
  config.allowed_environments = [:development, :test]
  config.filter_secrets = true
  config.mask_credentials = true
  
  # Feature toggles
  config.enable_models = true
  config.enable_routes = true
  config.enable_database = true
end

$ rails-introspec-mcp-server --rails-app /path/to/your/rails/app

$ rails server  # MCP server runs alongside Rails

The gem provides comprehensive introspection tools:

• list_models - List all ActiveRecord models
• describe_model - Get detailed model information
• model_associations - Get model associations and relationships
• model_attributes - Get model attributes and types
• model_validations - Get model validations
• model_callbacks - Get model callbacks

• list_routes - List all application routes
• find_route - Find routes by pattern or name
• route_details - Get detailed route information
• controller_routes - Get routes for specific controller
• named_routes - Get named routes and helpers

• list_tables - List database tables
• table_schema - Get table schema and columns
• table_indexes - Get table indexes
• migration_status - Get migration status
• database_config - Get database configuration
• foreign_keys - Get foreign key relationships

• Application structure and configuration
• Gem dependencies and versions
• Controller actions and filters
• And more...

1. Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "rails-introspec": {
      "command": "rails-introspec-mcp-server",
      "args": ["--rails-app", "/path/to/your/rails/app"],
      "env": {
        "RAILS_ENV": "development"
      }
    }
  }
}

2. Restart Claude Desktop
3. Start chatting with Claude about your Rails application!

1. Install the MCP extension for VSCode
2. Add server configuration to VSCode settings:

{
  "mcp.servers": [
    {
      "name": "rails-introspec",
      "command": "rails-introspec-mcp-server",
      "args": ["--rails-app", "/path/to/your/rails/app"],
      "transport": "stdio"
    }
  ]
}

1. Open Cursor settings
2. Navigate to MCP Servers section
3. Add new server:
   • Name: rails-introspec
   • Command: rails-introspec-mcp-server
   • Args: ["--rails-app", "/path/to/your/rails/app"]

1. Open WindSurf preferences
2. Go to Extensions → MCP
3. Add server configuration:

servers:
  rails-introspec:
    command: rails-introspec-mcp-server
    args:
      - --rails-app
      - /path/to/your/rails/app
    transport: stdio

RailsIntrospecMcp.configure do |config|
  # Basic settings
  config.enabled = true
  config.transport = :stdio  # :stdio or :http
  config.port = 3001
  
  # Security
  config.allowed_environments = [:development, :test]
  config.require_authentication = false
  config.auth_token = ENV['MCP_AUTH_TOKEN']
  config.allowed_ips = ['127.0.0.1', '::1']
  
  # Features
  config.enable_models = true
  config.enable_routes = true
  config.enable_controllers = true
  config.enable_database = true
  config.enable_gems = true
  config.enable_configuration = true
  config.enable_application = true
  
  # Data filtering
  config.filter_secrets = true
  config.mask_credentials = true
  config.anonymize_user_data = false
  
  # Performance
  config.max_results_per_query = 1000
  config.timeout_seconds = 30
  
  # Logging
  config.audit_logging = true
  config.log_level = :info
end

This gem provides powerful introspection capabilities that could expose sensitive information. Please consider:

• Environment Restrictions: Only enable in development/test environments
• Access Control: Use authentication tokens and IP restrictions
• Data Filtering: Enable secret filtering and credential masking
• Audit Logging: Monitor tool usage and access patterns
• Network Security: Use stdio transport or secure HTTP endpoints

After checking out the repo, run:

$ bin/setup
$ bundle install
$ bundle exec rspec
$ bundle exec cucumber

To install this gem onto your local machine:

$ bundle exec rake install

To release a new version:

$ bundle exec rake release

The gem includes comprehensive test coverage:

# Run RSpec tests
$ bundle exec rspec

# Run Cucumber features
$ bundle exec cucumber

# Run all tests with coverage
$ bundle exec rake test:all

Bug reports and pull requests are welcome on GitHub at https://github.com/rails-introspec-mcp/rails-introspec-mcp.

1. Fork the repository
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

The gem is available as open source under the terms of the MIT License.

See CHANGELOG.md for version history and changes.

• GitHub Issues: https://github.com/rails-introspec-mcp/rails-introspec-mcp/issues
• Documentation: https://github.com/rails-introspec-mcp/rails-introspec-mcp/wiki
• Discussions: https://github.com/rails-introspec-mcp/rails-introspec-mcp/discussions