rails-mcp-server 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77086c307fcceff18aac3bb1141c13a4b3de689342b65b276950156de22b09f0
-  data.tar.gz: 7afb0b7e81b51540befce4ef6dacb0aaf731aa3afcbb5135267c1e1311846f79
+  metadata.gz: 8d12279954da579f2d3998c4ffa14a016895fbf71bca6dc13ac5d3ba058a1429
+  data.tar.gz: e1c35ecb2ae0dd6e0dcd862d24c650979777449e5dcece15620d39759c580b9e
 SHA512:
-  metadata.gz: '03796522301b8d8d7c3ab258c67a146847d41ae909534148bc2015f7e11fe0156cbec424218de469f85c2f992958b3831b9b4a51da1799f9235b0c39469d5c4c'
-  data.tar.gz: 9511d7eaa3fdd2a3e05fa42cfd4ab7b102508641ce07831bacb8927311c1b275af4fed19e248754d28db28bcf7c5c82cdcb38e0b4ef9d7335bbee8100372214d
+  metadata.gz: 6a7a701f2f181d219e5e781f7d5ce5b372f7a841b37b6f0d82803ac613b1e00d92af72aba369b70776fda2a82be9084d4263bd0b663b115415d5b436d7c27644
+  data.tar.gz: 3acd59344bdc020e0d2a175835da56e837e5043ae7effdb913862f95b3aa938ec4ec395c812dd440460f8629b9fdfbfb9fe9250f28c781e1775de4d34e1f37ea

data/README.md

@@ -15,6 +15,8 @@ This Rails MCP Server implements the MCP specification to give AI models access
 - View Rails routes
 - Inspect model information
 - Get database schema information
+- Analyze controller-view relationships
+- Analyze environment configurations
 - Follow the Model Context Protocol standard
 
 ## Installation
@@ -110,28 +112,44 @@ Replace "/home/your_user/.rbenv/shims/ruby" with your actual path for the Ruby s
 
 ## Usage
 
-Start the server:
+### Starting the server
+
+The Rails MCP Server can run in two modes:
+
+1. **STDIO mode (default)**: Communicates over standard input/output for direct integration with clients like Claude Desktop.
+2. **HTTP mode**: Runs as an HTTP server with JSON-RPC and Server-Sent Events (SSE) endpoints.
 
 ```bash
+# Start in default STDIO mode
 rails-mcp-server
+
+# Start in HTTP mode on the default port (6029)
+rails-mcp-server --mode http
+
+# Start in HTTP mode on a custom port
+rails-mcp-server --mode http -p 8080
 ```
 
+When running in HTTP mode, the server provides two endpoints:
+
+- JSON-RPC endpoint: `http://localhost:<port>/mcp/messages`
+- SSE endpoint: `http://localhost:<port>/mcp/sse`
+
 ### Logging Options
 
 The server logs to a file in the `./log` directory by default. You can customize logging with these options:
 
 ```bash
-# Set the log level (debug, info, warn, error, fatal)
+# Set the log level (debug, info, error)
 rails-mcp-server --log-level debug
 ```
 
 ## How the Server Works
 
-The Rails MCP Server implements the Model Context Protocol over standard input/output (stdio). It:
+The Rails MCP Server implements the Model Context Protocol using either:
 
-1. Reads JSON-RPC 2.0 requests from standard input
-2. Processes the requests using the appropriate tools
-3. Returns JSON-RPC 2.0 responses to standard output
+- **STDIO mode**: Reads JSON-RPC 2.0 requests from standard input and returns responses to standard output.
+- **HTTP mode**: Provides HTTP endpoints for JSON-RPC 2.0 requests and Server-Sent Events.
 
 Each request includes a sequence number to match requests with responses, as defined in the MCP specification.
 
@@ -141,31 +159,13 @@ The server provides the following tools for interacting with Rails projects:
 
 ### 1. `switch_project`
 
-Switch the active Rails project.
+**Description:** Change the active Rails project to interact with a different codebase. Must be called before using other tools. Available projects are defined in the projects.yml configuration file.
 
 **Parameters:**
 
 - `project_name`: (String, required) Name of the project to switch to, as defined in the projects.yml file
 
-**Example:**
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": "123",
-  "method": "tools/call",
-  "params": {
-    "name": "switch_project",
-    "arguments": {
-      "project_name": "blog"
-    }
-  }
-}
-```
-
-**Description:** Change the active Rails project to interact with a different codebase. Must be called before using other tools. Available projects are defined in the projects.yml configuration file.
-
-Examples:
+#### Examples
 
 ```
 Can you switch to the "store" project so we can explore it?
@@ -181,27 +181,11 @@ Switch to the "ecommerce" project and give me a summary of the codebase.
 
 ### 2. `get_project_info`
 
-Get information about the current Rails project, including version, directory structure, and configuration.
+**Description:** Retrieve comprehensive information about the current Rails project, including Rails version, directory structure, API-only status, and overall project organization. Useful for initial project exploration and understanding the codebase structure.
 
 **Parameters:** None
 
-**Example:**
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": "124",
-  "method": "tools/call",
-  "params": {
-    "name": "get_project_info",
-    "arguments": {}
-  }
-}
-```
-
-**Description:** Retrieve comprehensive information about the current Rails project, including Rails version, directory structure, API-only status, and overall project organization.
-
-Examples:
+#### Examples
 
 ```
 Now that we're in the blog project, can you give me an overview of the project structure and Rails version?
@@ -217,33 +201,14 @@ I'd like to understand the high-level architecture of this project. Can you prov
 
 ### 3. `list_files`
 
-List files in the Rails project, with optional directory path and pattern filtering.
+**Description:** List files in the Rails project matching specific criteria. Use this to explore project directories or locate specific file types. If no parameters are provided, lists files in the project root.
 
 **Parameters:**
 
-- `directory`: (String, optional) Directory path relative to the project root
-- `pattern`: (String, optional) File pattern to match (e.g., "*.rb")
-
-**Example:**
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": "125",
-  "method": "tools/call",
-  "params": {
-    "name": "list_files",
-    "arguments": {
-      "directory": "app/models",
-      "pattern": "*.rb"
-    }
-  }
-}
-```
-
-**Description:** List files in the Rails project matching specific criteria. Use this to explore project directories or locate specific file types.
+- `directory`: (String, optional) Directory path relative to the project root (e.g., 'app/models', 'config')
+- `pattern`: (String, optional) File pattern using glob syntax (e.g., '.rb' for Ruby files, '.erb' for ERB templates)
 
-Examples:
+#### Examples
 
 ```
 Can you list all the model files in this project?
@@ -263,31 +228,13 @@ List all the JavaScript files in the app/javascript directory.
 
 ### 4. `get_file`
 
-Get the content of a file in the Rails project with syntax highlighting.
+**Description:** Retrieve the complete content of a specific file with syntax highlighting. Use this to examine implementation details, configurations, or any text file in the project.
 
 **Parameters:**
 
-- `path`: (String, required) File path relative to the project root
-
-**Example:**
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": "126",
-  "method": "tools/call",
-  "params": {
-    "name": "get_file",
-    "arguments": {
-      "path": "app/models/user.rb"
-    }
-  }
-}
-```
+- `path`: (String, required) File path relative to the project root (e.g., 'app/models/user.rb', 'config/routes.rb')
 
-**Description:** Retrieve the complete content of a specific file with syntax highlighting.
-
-Examples:
+#### Examples
 
 ```
 Can you show me the content of the User model file?
@@ -307,27 +254,11 @@ I'd like to examine the routes file. Can you display the content of config/route
 
 ### 5. `get_routes`
 
-Get the routes defined in the Rails project.
+**Description:** Retrieve all HTTP routes defined in the Rails application with their associated controllers and actions. Equivalent to running 'rails routes' command. This helps understand the API endpoints or page URLs available in the application.
 
 **Parameters:** None
 
-**Example:**
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": "127",
-  "method": "tools/call",
-  "params": {
-    "name": "get_routes",
-    "arguments": {}
-  }
-}
-```
-
-**Description:** Retrieve all HTTP routes defined in the Rails application with their associated controllers and actions.
-
-Examples:
+#### Examples
 
 ```
 Can you show me all the routes defined in this application?
@@ -341,33 +272,15 @@ I need to understand the API endpoints available in this project. Can you list t
 Show me the routing configuration for this Rails app so I can see how the URLs are structured.
 ```
 
-### 6. `get_models`
+### 6. `analyze_models`
 
-Get information about the models in the Rails project, including schema, associations, and definitions.
+**Description:** Retrieve detailed information about Active Record models in the project. When called without parameters, lists all model files. When a specific model is specified, returns its schema, associations (has_many, belongs_to, has_one), and complete source code.
 
 **Parameters:**
 
-- `model_name`: (String, optional) Name of a specific model to get information for
-
-**Example:**
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": "128",
-  "method": "tools/call",
-  "params": {
-    "name": "get_models",
-    "arguments": {
-      "model_name": "User"
-    }
-  }
-}
-```
-
-**Description:** Retrieve detailed information about Active Record models in the project.
+- `model_name`: (String, optional) Class name of a specific model to get detailed information for (e.g., 'User', 'Product'). Use CamelCase, not snake_case.
 
-Examples:
+#### Examples
 
 ```
 Can you list all the models in this Rails project?
@@ -387,31 +300,13 @@ What are all the models in this application, and can you then show me details fo
 
 ### 7. `get_schema`
 
-Get the database schema for the Rails project or for a specific table.
+**Description:** Retrieve database schema information for the Rails application. Without parameters, returns all tables and the complete schema.rb. With a table name, returns detailed column information including data types, constraints, and foreign keys for that specific table.
 
 **Parameters:**
 
-- `table_name`: (String, optional) Name of a specific table to get schema for
+- `table_name`: (String, optional) Database table name to get detailed schema information for (e.g., 'users', 'products'). Use snake_case, plural form.
 
-**Example:**
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": "129",
-  "method": "tools/call",
-  "params": {
-    "name": "get_schema",
-    "arguments": {
-      "table_name": "users"
-    }
-  }
-}
-```
-
-**Description:** Retrieve database schema information for the Rails application.
-
-Examples:
+#### Examples
 
 ```
 Can you show me the complete database schema for this Rails application?
@@ -429,42 +324,69 @@ Show me the columns and their data types in the products table.
 I need to understand the database design. Can you first list all tables and then show me details for the orders table?
 ```
 
-## Integration with LLM Clients
-
-This server is designed to be integrated with LLM clients that support the Model Context Protocol, such as Claude Desktop or other MCP-compatible applications.
+### 8. `analyze_controller_views`
 
-To use with an MCP client:
+**Description:** Analyze the relationships between controllers, their actions, and corresponding views to understand the application's UI flow.
 
-1. Start the Rails MCP Server
-2. Connect your MCP-compatible client to the server
-3. The client will be able to use the available tools to interact with your Rails projects
+**Parameters:**
 
-## Manual Testing
+- `controller_name`: (String, optional) Name of a specific controller to analyze (e.g., 'UsersController' or 'users'). If omitted, all controllers will be analyzed.
 
-You can manually test the server by sending JSON-RPC requests to its standard input:
+#### Examples
 
-```bash
-echo '0 {"jsonrpc":"2.0","id":"test-123","method":"ping"}' | rails-mcp-server
 ```
+Can you analyze the Users controller and its views to help me understand the UI flow?
+```
+
+### 9. `analyze_environment_config`
+
+**Description:** Analyze environment configurations to identify inconsistencies, security issues, and missing variables across environments.
 
-Expected response:
+**Parameters:** None
+
+#### Examples
 
 ```
-0 {"jsonrpc":"2.0","id":"test-123","result":{"version":"1.0.0"}}
+Can you analyze the environment configurations to find any security issues or missing environment variables?
 ```
 
-Or test multiple commands in sequence:
+## Integration with LLM Clients
 
-```bash
-(echo '0 {"jsonrpc":"2.0","id":"test-123","method":"tools/list"}'; sleep 1; echo '1 {"jsonrpc":"2.0","id":"test-456","method":"tools/call","params":{"name":"switch_project","arguments":{"project_name":"blog"}}}') | rails-mcp-server
-```
+This server is designed to be integrated with LLM clients that support the Model Context Protocol, such as Claude Desktop or other MCP-compatible applications.
+To use with an MCP client:
 
-You can also use `jq` to parse the output and format it nicely:
+1. Start the Rails MCP Server (it will use STDIO mode by default)
+1. Connect your MCP-compatible client to the server
+1. The client will be able to use the available tools to interact with your Rails projects
 
-```bash
-echo '0 {"jsonrpc":"2.0","id":"list-tools","method":"tools/list"}' | rails-mcp-server | sed 's/^[0-9]* //' | jq '.result.tools'
+## Testing and Debugging
+
+The 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.
+
+To use MCP Inspector with Rails MCP Server:
+
+```
+# Install and run MCP Inspector with your Rails MCP Server
+npm -g install @modelcontextprotocol/inspector
+
+npx @modelcontextprotocol/inspector /path/to/rails-mcp-server
 ```
 
+This will:
+
+1. Start your Rails MCP Server in HTTP mode
+1. Launch the MCP Inspector UI in your browser (default port: 6274)
+1. Set up an MCP Proxy server (default port: 6277)
+
+In the MCP Inspector UI, you can:
+
+- See all available tools
+- Execute tool calls interactively
+- View request and response details
+- Debug issues in real-time
+
+The Inspector UI provides an intuitive interface to interact with your MCP server, making it easy to test and debug your Rails MCP Server implementation.
+
 ## License
 
 This Rails MCP server is released under the MIT License, a permissive open-source license that allows for free use, modification, distribution, and private use.

data/exe/rails-mcp-server

@@ -1,21 +1,17 @@
 #!/usr/bin/env ruby
 
-require "pathname"
+require "bundler/setup"
 
-# Get script directory and project root
-bin_dir = Pathname.new(__FILE__).dirname
-root_dir = bin_dir.parent
+require "fast_mcp"
+require "rack"
+require "rack/handler/puma"
+require "puma"
+require "puma/configuration"
+require "puma/launcher"
+require_relative "../lib/rails_mcp_server"
 
-# Check if server script exists
-server_script = root_dir.join("lib", "rails_mcp_server.rb")
-unless server_script.exist?
-  puts "Error: rails_mcp_server.rb not found in lib directory (#{root_dir}/lib)"
-  exit 1
-end
-
-# Show version if requested
 if ARGV[0] == "version"
-  puts "Rails MCP Server version 1.0.0"
+  puts "Rails MCP Server version #{RailsMcpServer::VERSION}"
   exit 0
 end
 
@@ -27,14 +23,90 @@ if ARGV[0] == "--help" || ARGV[0] == "-h"
   puts ""
   puts "Options:"
   puts "  --log-level LEVEL      Log level: debug, info, warn, error (default: info)"
+  puts "  --mode MODE            Server mode: http or stdio (default: stdio)"
+  puts "  -p, --port PORT        Port to listen on (default: 6029)"
   puts "  version                Display version information"
   puts "  --help, -h             Display this help message"
   puts ""
   puts "Example:"
-  puts "  #{File.basename($0)} --log-level debug"
+  puts "  #{File.basename($0)} --log-level debug -p 6060"
+  puts "  #{File.basename($0)} --mode stdio"
   exit 0
 end
 
-# Change to root directory and execute server script
-Dir.chdir(root_dir)
-load server_script
+# Default values
+port = 6029
+mode = "stdio"
+
+# Parse command-line arguments
+i = 0
+while i < ARGV.length
+  case ARGV[i]
+  when "--log-level"
+    log_level = ARGV[i + 1].to_sym
+    i += 2
+  when "-p", "--port"
+    port = ARGV[i + 1].to_i
+    i += 2
+  when "--mode"
+    mode = ARGV[i + 1].downcase
+    unless ["http", "stdio"].include?(mode) # rubocop:disable Performance/CollectionLiteralInLoop
+      puts "Error: Invalid mode '#{mode}'. Must be 'http' or 'stdio'."
+      exit 1
+    end
+    i += 2
+  else
+    i += 1
+  end
+end
+
+RailsMcpServer.config do |config|
+  config.log_level = log_level
+end
+
+RailsMcpServer.log(:info, "Starting Rails MCP Server in #{mode} mode...")
+
+# Create tools configuration for both modes
+def setup_mcp_tools(server)
+  server.register_tools(RailsMcpServer::SwitchProject, RailsMcpServer::ProjectInfo,
+    RailsMcpServer::ListFiles, RailsMcpServer::GetFile, RailsMcpServer::GetRoutes, RailsMcpServer::AnalyzeModels,
+    RailsMcpServer::GetSchema, RailsMcpServer::AnalyzeControllerViews, RailsMcpServer::AnalyzeEnvironmentConfig)
+end
+
+case mode
+when "http"
+  puts "Starting Rack application with MCP middleware on http://localhost:#{port}"
+  puts "MCP endpoints:"
+  puts "  - http://localhost:#{port}/mcp/sse (SSE endpoint)"
+  puts "  - http://localhost:#{port}/mcp/messages (JSON-RPC endpoint)"
+  puts "Press Ctrl+C to stop"
+
+  rack_app = ->(env) {
+    [200, {"Content-Type" => "text/plain"}, ["Rails MCP Server #{RailsMcpServer::VERSION}"]]
+  }
+
+  mcp_app = FastMcp.rack_middleware(
+    rack_app,
+    name: "rails-mcp-server", version: RailsMcpServer::VERSION,
+    logger: RailsMcpServer.logger
+  ) { |server| setup_mcp_tools(server) }
+
+  app = Rack::Builder.new { run mcp_app }
+  config = Puma::Configuration.new do |user_config|
+    user_config.bind "tcp://localhost:#{port}"
+    user_config.app app
+  end
+
+  launcher = Puma::Launcher.new(config)
+  launcher.run
+when "stdio"
+  RailsMcpServer.log(:info, "Starting MCP server in STDIO mode...")
+
+  server = FastMcp::Server.new(name: "rails-mcp-server", version: RailsMcpServer::VERSION)
+  setup_mcp_tools(server)
+
+  server.start
+end
+
+RailsMcpServer.log(:info, "Stopping Rails MCP Server...")
+exit

data/exe/rails-mcp-setup-claude

@@ -118,7 +118,8 @@ end
 
 # Update configuration
 config["mcpServers"] ||= {}
-config["mcpServers"]["railsMcpServer"] = {"command" => "ruby", "args" => [server_path]}
+# config["mcpServers"]["railsMcpServer"] = {"command" => "ruby", "args" => [server_path]}
+config["mcpServers"]["railsMcpServer"] = {"command" => server_pathi, "args" => []}
 
 # Write configuration back to file
 File.write(claude_config_file, JSON.pretty_generate(config))

data/lib/rails-mcp-server/config.rb

@@ -0,0 +1,72 @@
+require "logger"
+
+module RailsMcpServer
+  class Config
+    attr_accessor :logger, :log_level, :projects, :current_project, :active_project_path
+
+    def self.setup
+      new.tap do |instance|
+        yield(instance) if block_given?
+      end
+    end
+
+    def initialize
+      @log_level = Logger::INFO
+      @config_dir = get_config_dir
+      @current_project = nil
+      @active_project_path = nil
+
+      configure_logger
+      load_projects
+    end
+
+    private
+
+    def load_projects
+      projects_file = File.join(@config_dir, "projects.yml")
+      @projects = {}
+
+      @logger.add(Logger::INFO, "Loading projects from: #{projects_file}")
+
+      # Create empty projects file if it doesn't exist
+      unless File.exist?(projects_file)
+        @logger.add(:info, "Creating empty projects file: #{projects_file}")
+        FileUtils.mkdir_p(File.dirname(projects_file))
+        File.write(projects_file, "# Rails MCP Projects\n# Format: project_name: /path/to/project\n")
+      end
+
+      @projects = YAML.load_file(projects_file) || {}
+      found_projects_size = @projects.size
+      @logger.add(Logger::INFO, "Loaded #{found_projects_size} projects: #{@projects.keys.join(", ")}")
+
+      if found_projects_size.zero?
+        message = "No projects found.\nPlease add a project to #{projects_file} and try again."
+        puts message
+        @logger.add(Logger::ERROR, message)
+        exit 1
+      end
+    end
+
+    def configure_logger
+      FileUtils.mkdir_p(File.join(@config_dir, "log"))
+      log_file = File.join(@config_dir, "log", "rails_mcp_server.log")
+
+      @logger = Logger.new(log_file)
+      @logger.level = @log_level
+
+      @logger.formatter = proc do |severity, datetime, progname, msg|
+        "[#{datetime.strftime("%Y-%m-%d %H:%M:%S")}] #{severity}: #{msg}\n"
+      end
+    end
+
+    def get_config_dir
+      # Use XDG_CONFIG_HOME if set, otherwise use ~/.config
+      xdg_config_home = ENV["XDG_CONFIG_HOME"]
+      if xdg_config_home && !xdg_config_home.empty?
+        File.join(xdg_config_home, "rails-mcp")
+      else
+        File.join(Dir.home, ".config", "rails-mcp")
+      end
+    end
+  end
+end