rails-introspect-mcp

laquereric/rails-introspect-mcp

3.3

If you are the rightful owner of rails-introspect-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Rails Introspec MCP is a Ruby gem that integrates Model Context Protocol (MCP) server capabilities into Rails applications, providing comprehensive introspection methods for AI assistants.

Tools
3
Resources
0
Prompts
0

Rails Introspec MCP

Gem Version Coverage Status

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.

Features

  • 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

Installation

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

Quick Start

1. Generate Configuration

$ rails generate rails_introspec_mcp:install

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

2. Configure the Gem

# 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

3. Start the MCP Server

Option A: Standalone Server
$ rails-introspec-mcp-server --rails-app /path/to/your/rails/app
Option B: Integrated with Rails Server
$ rails server  # MCP server runs alongside Rails

MCP Tools

The gem provides comprehensive introspection tools:

Model 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

Route Tools

  • 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

Database Tools

  • 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

Additional Tools

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

Usage with AI Assistants

Claude Desktop

  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"
      }
    }
  }
}
  1. Restart Claude Desktop
  2. Start chatting with Claude about your Rails application!

VSCode with MCP Extension

  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"
    }
  ]
}

Cursor

  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"]

WindSurf

  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

Configuration Options

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

Security Considerations

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

Development

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

Testing

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

Contributing

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

License

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

Changelog

See for version history and changes.

Support