{"id":45197296,"url":"https://github.com/goodpie/rails-active-mcp","last_synced_at":"2026-05-15T08:03:46.984Z","repository":{"id":305124491,"uuid":"1008074685","full_name":"GoodPie/rails-active-mcp","owner":"GoodPie","description":"Secure Rails console access for AI agents through Model Context Protocol with safety features and read-only modes","archived":false,"fork":false,"pushed_at":"2026-05-15T06:05:26.000Z","size":320,"stargazers_count":14,"open_issues_count":3,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-15T06:37:25.991Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GoodPie.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-25T01:49:38.000Z","updated_at":"2026-05-15T06:04:46.000Z","dependencies_parsed_at":"2025-07-18T13:37:22.069Z","dependency_job_id":"b0fec0ea-f2b3-463a-a1cd-c70f426d61a0","html_url":"https://github.com/GoodPie/rails-active-mcp","commit_stats":null,"previous_names":["goodpie/rails-active-mcp"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/GoodPie/rails-active-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoodPie%2Frails-active-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoodPie%2Frails-active-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoodPie%2Frails-active-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoodPie%2Frails-active-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GoodPie","download_url":"https://codeload.github.com/GoodPie/rails-active-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoodPie%2Frails-active-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33058965,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-15T02:00:06.351Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-20T13:01:55.280Z","updated_at":"2026-05-15T08:03:46.979Z","avatar_url":"https://github.com/GoodPie.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Gem Version](https://badge.fury.io/rb/rails-active-mcp.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/rails-active-mcp)\n\nNote: This is just a personal project and while it works for the most part, I am still developing it and actively trying to make it a bit more useful for my uses.\n\n# Rails Active MCP\n\nA Ruby gem that provides secure Rails console access through [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for AI agents and development tools. Built using the official MCP Ruby SDK for professional protocol handling and future-proof compatibility.\n\nWorks with any MCP-compatible client, including Claude Desktop, Claude Code, VS Code (GitHub Copilot), Cursor, Windsurf, ChatGPT, Gemini CLI, Amazon Q Developer, JetBrains IDEs, Zed, Warp, Cline, and [many more](https://modelcontextprotocol.io/clients).\n\n\n\n## Quick Start\n\nGet up and running in three steps:\n\n### 1. Install the gem\n\nAdd to your Rails application's `Gemfile`:\n\n```ruby\ngem 'rails-active-mcp'\n```\n\n```bash\nbundle install\n```\n\n### 2. Run the installer\n\n```bash\nrails generate rails_active_mcp:install\n```\n\nThis creates an initializer, server scripts, and prompts you to select which MCP clients you use. It will automatically generate the correct project-level config files (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, etc.) so your MCP client detects the server when you open the project.\n\n### 3. Connect your MCP client\n\nIf you selected your MCP client during installation, you're done — just open the project and the server will be detected automatically.\n\nFor manual configuration or additional clients, the server uses STDIO transport. Below are configuration examples for popular tools.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClaude Desktop\u003c/strong\u003e\u003c/summary\u003e\n\nEdit your config file:\n- **macOS/Linux:** `~/.config/claude-desktop/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"rails-active-mcp\": {\n      \"command\": \"bundle\",\n      \"args\": [\"exec\", \"rails-active-mcp-server\"],\n      \"cwd\": \"/path/to/your/rails/project\"\n    }\n  }\n}\n```\n\nRestart Claude Desktop and the tools will appear automatically.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClaude Code\u003c/strong\u003e\u003c/summary\u003e\n\nFrom your Rails project directory:\n\n```bash\nclaude mcp add rails-active-mcp -- bundle exec rails-active-mcp-server\n```\n\nOr add it to your project's `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"rails-active-mcp\": {\n      \"command\": \"bundle\",\n      \"args\": [\"exec\", \"rails-active-mcp-server\"]\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eVS Code (GitHub Copilot)\u003c/strong\u003e\u003c/summary\u003e\n\nAdd to your workspace `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"rails-active-mcp\": {\n      \"command\": \"bundle\",\n      \"args\": [\"exec\", \"rails-active-mcp-server\"],\n      \"cwd\": \"${workspaceFolder}\"\n    }\n  }\n}\n```\n\nTools are available in Copilot's Agent mode.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCursor\u003c/strong\u003e\u003c/summary\u003e\n\nAdd to your project's `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"rails-active-mcp\": {\n      \"command\": \"bundle\",\n      \"args\": [\"exec\", \"rails-active-mcp-server\"],\n      \"cwd\": \"/path/to/your/rails/project\"\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWindsurf\u003c/strong\u003e\u003c/summary\u003e\n\nAdd to your global Windsurf config at `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"rails-active-mcp\": {\n      \"command\": \"bundle\",\n      \"args\": [\"exec\", \"rails-active-mcp-server\"],\n      \"cwd\": \"/path/to/your/rails/project\"\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eZed\u003c/strong\u003e\u003c/summary\u003e\n\nAdd to your Zed settings (`settings.json`):\n\n```json\n{\n  \"context_servers\": {\n    \"rails-active-mcp\": {\n      \"command\": {\n        \"path\": \"bundle\",\n        \"args\": [\"exec\", \"rails-active-mcp-server\"],\n        \"env\": {}\n      }\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eChatGPT Desktop\u003c/strong\u003e\u003c/summary\u003e\n\nIn ChatGPT Desktop, go to **Settings \u003e Connectors \u003e Advanced \u003e Developer Mode**, then add:\n\n```json\n{\n  \"mcpServers\": {\n    \"rails-active-mcp\": {\n      \"command\": \"bundle\",\n      \"args\": [\"exec\", \"rails-active-mcp-server\"],\n      \"cwd\": \"/path/to/your/rails/project\"\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eOther MCP Clients\u003c/strong\u003e\u003c/summary\u003e\n\nAny MCP client that supports STDIO transport can connect to this server. The key details:\n\n- **Command:** `bundle exec rails-active-mcp-server`\n- **Working directory:** Your Rails project root\n- **Transport:** STDIO (stdin/stdout)\n\nSee the [full list of MCP clients](https://modelcontextprotocol.io/clients) for more options.\n\u003c/details\u003e\n\nOnce connected, four tools will appear automatically: `console_execute`, `model_info`, `safe_query`, and `dry_run`.\n\nTry asking your AI assistant:\n\n- \"Show me all users created in the last week\"\n- \"What's the average order value?\"\n- \"Check the User model schema and associations\"\n- \"Analyze this code for safety: User.delete_all\"\n\n## Features\n\n- 🔒 **Safe Execution**: Advanced safety checks prevent dangerous operations\n- 🚀 **Official MCP SDK**: Built with the official MCP Ruby SDK for robust protocol handling\n- 📊 **Read-Only Queries**: Safe database querying with automatic result limiting\n- 🔍 **Code Analysis**: Dry-run capabilities to analyze code before execution\n- 📝 **Audit Logging**: Complete execution logging for security and debugging\n- ⚙️ **Configurable**: Flexible configuration for different environments\n- 🛡️ **Production Ready**: Strict safety modes for production environments\n- ⚡ **Professional Implementation**: Built-in instrumentation, timing, and error handling\n\n## Configuration\n\nThe installer creates a default configuration at `config/initializers/rails_active_mcp.rb`. The defaults work out of the box, but you can customize behavior:\n\n```ruby\nRailsActiveMcp.configure do |config|\n  # Safety and execution\n  config.safe_mode = true              # Block dangerous operations\n  config.command_timeout = 30          # Seconds before timeout\n  config.max_results = 100             # Limit query results\n  config.allowed_models = []           # Empty = all models allowed\n  config.custom_safety_patterns = []   # Additional patterns to block\n\n  # Logging\n  config.enable_logging = true\n  config.log_level = :info             # :debug, :info, :warn, :error\n  config.log_executions = false        # Log all code executions\n  config.audit_file = nil              # Path to audit log file\n\n  # Environment presets (call instead of setting individually)\n  # config.production_mode!\n  # config.development_mode!\n  # config.test_mode!\nend\n```\n\n## Usage\n\n### MCP Client (Recommended)\n\nOnce connected (see [Quick Start](#quick-start)), your MCP client automatically runs the server for you. The server loads your Rails application, initializes models, and provides secure access to your Rails environment via STDIO transport.\n\n### Direct Usage\n\nYou can also use the gem directly in Ruby:\n\n```ruby\n# Execute code safely\nresult = RailsActiveMcp.execute(\"User.count\")\n\n# Check if code is safe\nRailsActiveMcp.safe?(\"User.delete_all\") # =\u003e false\n```\n\n### Running the Server Manually\n\nIf you need to run the server directly (e.g., for debugging):\n\n```bash\nbundle exec rails-active-mcp-server\n\n# With debug logging\nRAILS_MCP_DEBUG=1 bundle exec rails-active-mcp-server\n```\n\n### Rake Tasks\n\nThe gem provides several rake tasks for diagnostics and testing:\n\n```bash\n# Show status and diagnostics\nrails rails_active_mcp:status\n\n# Validate configuration\nrails rails_active_mcp:validate_config\n\n# Test MCP tools are working\nrails rails_active_mcp:test_tools\n\n# Check if code is safe\nrails rails_active_mcp:check_safety['User.delete_all']\n\n# Execute code with safety checks\nrails rails_active_mcp:execute['User.count']\n\n# Print Claude Desktop configuration\nrails rails_active_mcp:install_claude_config\n\n# Run performance benchmarks\nrails rails_active_mcp:benchmark\n```\n\n## Available MCP Tools\n\nThe Rails Active MCP server provides four powerful tools that appear automatically in any connected MCP client:\n\n### 1. `console_execute`\n\nExecute Ruby code with safety checks and timeout protection:\n\n- **Purpose**: Run Rails console commands safely\n- **Safety**: Built-in dangerous operation detection\n- **Timeout**: Configurable execution timeout\n- **Logging**: All executions are logged for audit\n\n**Example prompt:**\n\u003e \"Execute `User.where(active: true).count`\"\n\n### 2. `model_info`\n\nGet detailed information about Rails models:\n\n- **Schema Information**: Column types, constraints, indexes\n- **Associations**: Has_many, belongs_to, has_one relationships\n- **Validations**: All model validations and rules\n- **Methods**: Available instance and class methods\n\n**Example prompt:**\n\u003e \"Show me the User model structure\"\n\n### 3. `safe_query`\n\nExecute safe, read-only database queries:\n\n- **Read-Only**: Only SELECT operations allowed\n- **Safe Execution**: Automatic query analysis\n- **Result Limiting**: Prevents large data dumps\n- **Model Context**: Works within your model definitions\n\n**Example prompt:**\n\u003e \"Get the 10 most recent orders\"\n\u003e \"Count active users\"\n\nYou can pass an optional `where` hash to filter records before invoking the method. For example, `safe_query(model: \"User\", method: \"count\", where: { active: true })` runs `User.where(active: true).count`. The same applies to `sum`, `average`, `minimum`, `maximum`, `pluck`, and `exists?`.\n\n### 4. `dry_run`\n\nAnalyze Ruby code for safety without executing:\n\n- **Risk Assessment**: Categorizes code by danger level\n- **Safety Analysis**: Identifies potential issues\n- **Recommendations**: Suggests safer alternatives\n- **Zero Execution**: Never runs the actual code\n\n**Example prompt:**\n\u003e \"Analyze this code for safety: `User.delete_all`\"\n\n## Safety Features\n\n### Automatic Detection of Dangerous Operations\n\nThe gem automatically detects and blocks:\n\n- Mass deletions (`delete_all`, `destroy_all`)\n- System commands (`system`, `exec`, backticks)\n- File operations (`File.delete`, `FileUtils`)\n- Raw SQL execution\n- Code evaluation (`eval`, `send`)\n- Process manipulation (`exit`, `fork`)\n\n### Safety Levels\n\n- **Critical**: Never allowed (system commands, file deletion)\n- **High**: Blocked in safe mode (mass deletions, eval)\n- **Medium**: Logged but allowed (raw SQL, update_all)\n- **Low**: Generally safe (environment access, require)\n\n### Read-Only Mode\n\nThe gem can detect read-only operations and provide additional safety:\n\n```ruby\n# These are considered safe read-only operations\nUser.find(1)\nUser.where(active: true).count\nPost.includes(:comments).limit(10)\n```\n\n## Architecture\n\n### Built on Official MCP Ruby SDK\n\nRails Active MCP uses the official MCP Ruby SDK (`mcp` gem) for:\n\n- **Professional Protocol Handling**: Robust JSON-RPC 2.0 implementation\n- **Built-in Instrumentation**: Automatic timing and error reporting\n- **Future-Proof**: Automatic updates as MCP specification evolves\n- **Standards Compliance**: Full MCP protocol compatibility\n\n### Server Implementation\n\nThe server is implemented in `lib/rails_active_mcp/sdk/server.rb` and provides:\n\n- **STDIO Transport**: Compatible with all major MCP clients\n- **Tool Registration**: Automatic discovery of available tools\n- **Error Handling**: Comprehensive error reporting and recovery\n- **Rails Integration**: Deep integration with Rails applications\n\n### Tool Architecture\n\nEach tool is implemented as a separate class in `lib/rails_active_mcp/sdk/tools/`:\n\n- `ConsoleExecuteTool`: Safe code execution\n- `ModelInfoTool`: Model introspection\n- `SafeQueryTool`: Read-only database access\n- `DryRunTool`: Code safety analysis\n\n## Error Handling\n\nThe gem provides specific error types:\n\n- `RailsActiveMcp::SafetyError`: Code failed safety checks\n- `RailsActiveMcp::TimeoutError`: Execution timed out\n- `RailsActiveMcp::ExecutionError`: General execution failure\n\nAll errors are properly reported through the MCP protocol with detailed messages.\n\n## Development and Testing\n\n```bash\n# Run tests\nbundle exec rspec\n\n# Test MCP server protocol compliance\n./bin/test-mcp-output\n```\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n\n## License\n\nThe gem is available as open source under the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoodpie%2Frails-active-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoodpie%2Frails-active-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoodpie%2Frails-active-mcp/lists"}