rails-mcp-server 1.2.3 → 1.4.0

data/lib/rails-mcp-server/tools/search_tools.rb

@@ -0,0 +1,186 @@
+module RailsMcpServer
+  class SearchTools < BaseTool
+    tool_name "search_tools"
+
+    description <<~DESC
+      Search available Rails MCP tools by keyword or category. Use this to discover tools 
+      before invoking them with execute_tool.
+
+      Workflow:
+      1. Call search_tools to find relevant tools
+      2. Call execute_tool(tool_name: "tool_name", params: {...}) to run them
+
+      Categories: models, database, routing, controllers, files, project, guides
+    DESC
+
+    arguments do
+      optional(:query).filled(:string).description(
+        "Search term to find matching tools (e.g., 'model', 'routes', 'schema', 'controller')"
+      )
+      optional(:category).filled(:string).description(
+        "Filter by category: models, database, routing, controllers, files, project, guides"
+      )
+      optional(:detail_level).filled(:string).description(
+        "Level of detail: 'names' (tool names only), 'summary' (names + one-line description), 'full' (complete definition with parameters). Default: 'summary'"
+      )
+    end
+
+    TOOL_CATALOG = {
+      "project_info" => {
+        category: "project",
+        keywords: %w[project info structure directory tree rails version],
+        summary: "Get Rails version, directory structure, and project overview",
+        parameters: [
+          {name: "max_depth", type: "integer", required: false, description: "Directory tree depth (default: 2, max: 5)"},
+          {name: "include_files", type: "boolean", required: false, description: "Include files in tree (default: true)"},
+          {name: "detail_level", type: "string", required: false, description: "'minimal', 'summary', or 'full' (default: 'full')"}
+        ]
+      },
+      "list_files" => {
+        category: "files",
+        keywords: %w[files list directory glob find search],
+        summary: "List files matching a pattern in a directory",
+        parameters: [
+          {name: "directory", type: "string", required: false, description: "Directory path relative to project root"},
+          {name: "pattern", type: "string", required: false, description: "Glob pattern (default: '*.rb')"}
+        ]
+      },
+      "get_file" => {
+        category: "files",
+        keywords: %w[file read content source code view],
+        summary: "Read the contents of a specific file",
+        parameters: [
+          {name: "path", type: "string", required: true, description: "File path relative to project root"}
+        ]
+      },
+      "get_routes" => {
+        category: "routing",
+        keywords: %w[routes endpoints urls api paths http verbs controller actions introspection],
+        summary: "List HTTP routes via Rails introspection with filtering by controller, verb, or path",
+        parameters: [
+          {name: "controller", type: "string", required: false, description: "Filter by controller name"},
+          {name: "verb", type: "string", required: false, description: "Filter by HTTP verb (GET, POST, PUT, PATCH, DELETE)"},
+          {name: "path_contains", type: "string", required: false, description: "Filter routes containing path segment"},
+          {name: "named_only", type: "boolean", required: false, description: "Only return named routes (default: false)"},
+          {name: "detail_level", type: "string", required: false, description: "'names', 'summary', or 'full' (default: 'full')"}
+        ]
+      },
+      "analyze_models" => {
+        category: "models",
+        keywords: %w[model active_record orm association schema database belongs_to has_many validations callbacks scopes prism introspection],
+        summary: "Analyze ActiveRecord models using Rails introspection and/or Prism static analysis",
+        parameters: [
+          {name: "model_name", type: "string", required: false, description: "Single model name (CamelCase)"},
+          {name: "model_names", type: "array", required: false, description: "Array of model names for batch analysis"},
+          {name: "detail_level", type: "string", required: false, description: "'names', 'associations', or 'full' (default: 'full')"},
+          {name: "analysis_type", type: "string", required: false, description: "'introspection' (runtime), 'static' (Prism AST), or 'full' (both). Default: 'introspection'"}
+        ]
+      },
+      "get_schema" => {
+        category: "database",
+        keywords: %w[schema database table column migration sql foreign_key index],
+        summary: "Get database schema - all tables or specific table details",
+        parameters: [
+          {name: "table_name", type: "string", required: false, description: "Specific table (snake_case, plural)"},
+          {name: "table_names", type: "array", required: false, description: "Array of table names for batch retrieval"},
+          {name: "detail_level", type: "string", required: false, description: "'tables', 'summary', or 'full' (default: 'full')"}
+        ]
+      },
+      "analyze_controller_views" => {
+        category: "controllers",
+        keywords: %w[controller view action template partial stimulus erb html callbacks filters before_action strong_params prism introspection],
+        summary: "Analyze controllers using Rails introspection and/or Prism static analysis (callbacks, filters, strong params, renders)",
+        parameters: [
+          {name: "controller_name", type: "string", required: false, description: "Specific controller to analyze"},
+          {name: "detail_level", type: "string", required: false, description: "'names', 'summary', or 'full' (default: 'full')"},
+          {name: "analysis_type", type: "string", required: false, description: "'introspection' (runtime), 'static' (Prism AST), or 'full' (both). Default: 'introspection'"}
+        ]
+      },
+      "analyze_environment_config" => {
+        category: "project",
+        keywords: %w[environment config configuration development production test settings],
+        summary: "Compare environment configurations and find inconsistencies",
+        parameters: []
+      },
+      "load_guide" => {
+        category: "guides",
+        keywords: %w[guide documentation rails turbo stimulus kamal docs help],
+        summary: "Load Rails, Turbo, Stimulus, or Kamal documentation guides",
+        parameters: [
+          {name: "guides", type: "string", required: true, description: "Library: 'rails', 'turbo', 'stimulus', 'kamal', 'custom'"},
+          {name: "guide", type: "string", required: false, description: "Specific guide name to load"}
+        ]
+      }
+    }.freeze
+
+    CATEGORIES = %w[models database routing controllers files project guides].freeze
+
+    def call(query: nil, category: nil, detail_level: "summary")
+      detail_level = "summary" unless %w[names summary full].include?(detail_level)
+
+      # Filter tools
+      filtered_tools = TOOL_CATALOG.dup
+
+      if category && CATEGORIES.include?(category.downcase)
+        filtered_tools = filtered_tools.select { |_, info| info[:category] == category.downcase }
+      end
+
+      if query && !query.strip.empty?
+        query_terms = query.downcase.split(/\s+/)
+        filtered_tools = filtered_tools.select do |name, info|
+          searchable = [name, info[:category], info[:summary], *info[:keywords]].join(" ").downcase
+          query_terms.all? { |term| searchable.include?(term) }
+        end
+      end
+
+      if filtered_tools.empty?
+        return "No tools found matching your criteria. Available categories: #{CATEGORIES.join(", ")}"
+      end
+
+      format_results(filtered_tools, detail_level)
+    end
+
+    private
+
+    def format_results(tools, detail_level)
+      case detail_level
+      when "names"
+        output = ["Available tools (invoke via execute_tool):\n"]
+        output << tools.keys.sort.join("\n")
+        output.join
+
+      when "summary"
+        output = ["Available tools (invoke via execute_tool):\n"]
+        tools.sort_by { |name, _| name }.each do |name, info|
+          output << "  #{name} [#{info[:category]}]"
+          output << "    #{info[:summary]}"
+          output << ""
+        end
+        output << "Example: execute_tool(tool_name: \"analyze_models\", params: { model_name: \"User\", analysis_type: \"full\" })"
+        output.join("\n")
+
+      when "full"
+        output = ["Available tools (invoke via execute_tool):\n"]
+        tools.sort_by { |name, _| name }.each do |name, info|
+          output << "  #{name}"
+          output << "    Category: #{info[:category]}"
+          output << "    #{info[:summary]}"
+          output << "    Keywords: #{info[:keywords].join(", ")}"
+
+          if info[:parameters].any?
+            output << "    Parameters:"
+            info[:parameters].each do |param|
+              req = param[:required] ? "required" : "optional"
+              output << "      - #{param[:name]} (#{param[:type]}, #{req}): #{param[:description]}"
+            end
+          else
+            output << "    Parameters: none"
+          end
+          output << ""
+        end
+        output << "Usage: execute_tool(tool_name: \"<name>\", params: { ... })"
+        output.join("\n")
+      end
+    end
+  end
+end

data/lib/rails-mcp-server/tools/switch_project.rb

@@ -8,13 +8,28 @@ module RailsMcpServer
       required(:project_name).filled(:string).description("Name of the project as defined in the projects.yml file (case-sensitive)")
     end
 
+    QUICK_START = <<~GUIDE
+
+      Quick Start:
+      • Get project overview:  execute_tool("project_info")
+      • Read a file:           execute_ruby("puts read_file('config/routes.rb')")
+      • Find files:            execute_ruby("puts Dir.glob('app/models/*.rb').join('\\n')")
+      • Analyze models:        execute_tool("analyze_models", { model_name: "User" })
+      • Get routes:            execute_tool("get_routes")
+      • Get schema:            execute_tool("get_schema", { table_name: "users" })
+      • Search available tools: search_tools()
+
+      Helpers in execute_ruby: read_file(path), file_exists?(path), list_files(pattern), project_root
+      Note: Always use `puts` in execute_ruby to see output.
+    GUIDE
+
     def call(project_name:)
       if projects.key?(project_name)
         self.current_project = project_name
         self.active_project_path = File.expand_path(projects[project_name])
         log(:info, "Switched to project: #{project_name} at path: #{active_project_path}")
 
-        "Switched to project: #{project_name} at path: #{active_project_path}"
+        "Switched to project: #{project_name} at path: #{active_project_path}\n#{QUICK_START}"
       else
         log(:warn, "Project not found: #{project_name}")
 

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

@@ -1,3 +1,3 @@
 module RailsMcpServer
-  VERSION = "1.2.3"
+  VERSION = "1.4.0"
 end

data/lib/rails_mcp_server.rb

@@ -4,29 +4,35 @@ require "forwardable"
 require "open3"
 require_relative "rails-mcp-server/version"
 require_relative "rails-mcp-server/config"
-require_relative "rails-mcp-server/extensions/resource_templating"
-require_relative "rails-mcp-server/extensions/server_templating"
 require_relative "rails-mcp-server/utilities/run_process"
+
+# MCP Tools (registered with FastMCP)
 require_relative "rails-mcp-server/tools/base_tool"
-require_relative "rails-mcp-server/tools/project_info"
-require_relative "rails-mcp-server/tools/list_files"
-require_relative "rails-mcp-server/tools/get_file"
-require_relative "rails-mcp-server/tools/get_routes"
-require_relative "rails-mcp-server/tools/analyze_models"
-require_relative "rails-mcp-server/tools/get_schema"
-require_relative "rails-mcp-server/tools/analyze_controller_views"
-require_relative "rails-mcp-server/tools/analyze_environment_config"
 require_relative "rails-mcp-server/tools/switch_project"
-require_relative "rails-mcp-server/tools/load_guide"
+require_relative "rails-mcp-server/tools/search_tools"
+require_relative "rails-mcp-server/tools/execute_tool"
+require_relative "rails-mcp-server/tools/execute_ruby"
+
+# Analyzers (internal, invoked via execute_tool)
+require_relative "rails-mcp-server/analyzers/base_analyzer"
+require_relative "rails-mcp-server/analyzers/project_info"
+require_relative "rails-mcp-server/analyzers/list_files"
+require_relative "rails-mcp-server/analyzers/get_file"
+require_relative "rails-mcp-server/analyzers/get_routes"
+require_relative "rails-mcp-server/analyzers/get_schema"
+require_relative "rails-mcp-server/analyzers/analyze_models"
+require_relative "rails-mcp-server/analyzers/analyze_controller_views"
+require_relative "rails-mcp-server/analyzers/analyze_environment_config"
+require_relative "rails-mcp-server/analyzers/load_guide"
+
+# Resources
 require_relative "rails-mcp-server/resources/base_resource"
-
 require_relative "rails-mcp-server/resources/guide_content_formatter"
 require_relative "rails-mcp-server/resources/guide_error_handler"
 require_relative "rails-mcp-server/resources/guide_file_finder"
 require_relative "rails-mcp-server/resources/guide_loader_template"
 require_relative "rails-mcp-server/resources/guide_manifest_operations"
 require_relative "rails-mcp-server/resources/guide_framework_contract"
-
 require_relative "rails-mcp-server/resources/rails_guides_resource"
 require_relative "rails-mcp-server/resources/rails_guides_resources"
 require_relative "rails-mcp-server/resources/stimulus_guides_resource"
@@ -59,45 +65,5 @@ module RailsMcpServer
 
       @config.logger.add(log_level, message)
     end
-
-    # NOTE: This needs to be removed once FastMcp provides official support for URI templating
-    # Setup method to initialize FastMcp::Resource extensions
-    # Call this after the gem is loaded to enable URI templating
-    def setup_resource_extensions!
-      Extensions::ResourceExtensionSetup.setup!
-    end
-
-    # Check if resource extensions are loaded
-    def resource_extensions_loaded?
-      Extensions::ResourceExtensionSetup.setup_complete?
-    end
-
-    # Setup method to initialize FastMcp::Server extensions
-    # This is called automatically by resource extension setup
-    def setup_server_extensions!
-      Extensions::ServerExtensionSetup.setup!
-    end
-
-    # Check if server extensions are loaded
-    def server_extensions_loaded?
-      Extensions::ServerExtensionSetup.setup_complete?
-    end
-
-    # Setup all extensions at once
-    def setup_extensions!
-      setup_resource_extensions!
-      # Server extensions are setup automatically by resource extensions
-    end
-
-    # Check if all extensions are loaded
-    def extensions_loaded?
-      resource_extensions_loaded? && server_extensions_loaded?
-    end
   end
-
-  class Error < StandardError; end
-
-  # Auto-setup extensions when the module is loaded
-  # This ensures extensions are available immediately
-  setup_resource_extensions!
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-mcp-server
 version: !ruby/object:Gem::Version
-  version: 1.2.3
+  version: 1.4.0
 platform: ruby
 authors:
 - Mario Alberto Chávez Cárdenas
@@ -29,42 +29,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.4.0
+        version: 1.6.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.4.0
+        version: 1.6.0
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.1.12
+        version: 3.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.1.12
+        version: 3.2.0
 - !ruby/object:Gem::Dependency
   name: puma
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.6.0
+        version: 7.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.6.0
+        version: 7.1.0
 - !ruby/object:Gem::Dependency
   name: logger
   requirement: !ruby/object:Gem::Requirement
@@ -93,10 +93,53 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
 description: A Ruby implementation of Model Context Protocol server for Rails projects
 email:
 - mario.chavez@gmail.com
 executables:
+- rails-mcp-config
 - rails-mcp-server
 - rails-mcp-server-download-resources
 - rails-mcp-setup-claude
@@ -107,13 +150,23 @@ files:
 - LICENSE.txt
 - README.md
 - config/resources.yml
+- 'docs/AGENT.md '
 - docs/RESOURCES.md
+- exe/rails-mcp-config
 - exe/rails-mcp-server
 - exe/rails-mcp-server-download-resources
 - exe/rails-mcp-setup-claude
+- lib/rails-mcp-server/analyzers/analyze_controller_views.rb
+- lib/rails-mcp-server/analyzers/analyze_environment_config.rb
+- lib/rails-mcp-server/analyzers/analyze_models.rb
+- lib/rails-mcp-server/analyzers/base_analyzer.rb
+- lib/rails-mcp-server/analyzers/get_file.rb
+- lib/rails-mcp-server/analyzers/get_routes.rb
+- lib/rails-mcp-server/analyzers/get_schema.rb
+- lib/rails-mcp-server/analyzers/list_files.rb
+- lib/rails-mcp-server/analyzers/load_guide.rb
+- lib/rails-mcp-server/analyzers/project_info.rb
 - lib/rails-mcp-server/config.rb
-- lib/rails-mcp-server/extensions/resource_templating.rb
-- lib/rails-mcp-server/extensions/server_templating.rb
 - lib/rails-mcp-server/helpers/resource_base.rb
 - lib/rails-mcp-server/helpers/resource_downloader.rb
 - lib/rails-mcp-server/helpers/resource_importer.rb
@@ -134,17 +187,11 @@ files:
 - lib/rails-mcp-server/resources/stimulus_guides_resources.rb
 - lib/rails-mcp-server/resources/turbo_guides_resource.rb
 - lib/rails-mcp-server/resources/turbo_guides_resources.rb
-- lib/rails-mcp-server/tools/analyze_controller_views.rb
-- lib/rails-mcp-server/tools/analyze_environment_config.rb
-- lib/rails-mcp-server/tools/analyze_models.rb
 - lib/rails-mcp-server/tools/base_tool.rb
-- lib/rails-mcp-server/tools/get_file.rb
+- lib/rails-mcp-server/tools/execute_ruby.rb
+- lib/rails-mcp-server/tools/execute_tool.rb
 - lib/rails-mcp-server/tools/get_model.rb
-- lib/rails-mcp-server/tools/get_routes.rb
-- lib/rails-mcp-server/tools/get_schema.rb
-- lib/rails-mcp-server/tools/list_files.rb
-- lib/rails-mcp-server/tools/load_guide.rb
-- lib/rails-mcp-server/tools/project_info.rb
+- lib/rails-mcp-server/tools/search_tools.rb
 - lib/rails-mcp-server/tools/switch_project.rb
 - lib/rails-mcp-server/utilities/run_process.rb
 - lib/rails-mcp-server/version.rb

data/lib/rails-mcp-server/extensions/resource_templating.rb

@@ -1,182 +0,0 @@
-module RailsMcpServer
-  module Extensions
-    # Extension module to add URI templating capabilities to FastMcp::Resource
-    # Uses module prepending for clean method override behavior
-    module ResourceTemplating
-      # Class methods to be prepended to the singleton class
-      module ClassMethods
-        attr_reader :template_params
-
-        def variabilized_uri(params = {})
-          addressable_template.partial_expand(params).pattern
-        end
-
-        def addressable_template
-          @addressable_template ||= Addressable::Template.new(uri)
-        end
-
-        def template_variables
-          addressable_template.variables
-        end
-
-        def templated?
-          template_variables.any?
-        end
-
-        def non_templated?
-          !templated?
-        end
-
-        def match(uri)
-          addressable_template.match(uri)
-        end
-
-        def initialize_from_uri(uri)
-          new(params_from_uri(uri))
-        end
-
-        def params_from_uri(uri)
-          match(uri).mapping.transform_keys(&:to_sym)
-        end
-
-        def instance(uri = self.uri)
-          @instances ||= {}
-          @instances[uri] ||= begin
-            resource_class = Class.new(self)
-            params = params_from_uri(uri)
-            resource_class.instance_variable_set(:@params, params)
-
-            resource_class.define_singleton_method(:instance) do
-              @instance ||= begin
-                instance = new
-                instance.instance_variable_set(:@params, params)
-                instance
-              end
-            end
-
-            resource_class.instance
-          end
-        end
-
-        def params
-          @params || {}
-        end
-
-        def name
-          return resource_name if resource_name
-          super
-        end
-
-        def metadata
-          if templated?
-            {
-              uriTemplate: uri,
-              name: resource_name,
-              description: description,
-              mimeType: mime_type
-            }.compact
-          else
-            super
-          end
-        end
-      end
-
-      # Instance methods to be prepended
-      module InstanceMethods
-        def initialize
-          @params = self.class.params
-          super if defined?(super)
-        end
-
-        def params
-          @params || self.class.params
-        end
-
-        def name
-          self.class.resource_name
-        end
-      end
-
-      # Called when this module is prepended to a class
-      def self.prepended(base)
-        base.singleton_class.prepend(ClassMethods)
-        base.prepend(InstanceMethods)
-      end
-    end
-
-    # Main setup class for resource extensions
-    class ResourceExtensionSetup
-      class << self
-        def setup!
-          return if @setup_complete
-
-          ensure_dependencies_loaded!
-          apply_extensions!
-
-          @setup_complete = true
-          RailsMcpServer.log(:info, "FastMcp::Resource extensions loaded successfully")
-        rescue => e
-          RailsMcpServer.log(:error, "Failed to setup resource extensions: #{e.message}")
-          raise
-        end
-
-        def reset!
-          @setup_complete = false
-        end
-
-        def setup_complete?
-          @setup_complete || false
-        end
-
-        private
-
-        def ensure_dependencies_loaded!
-          # Check that FastMcp::Resource exists
-          unless defined?(FastMcp::Resource)
-            begin
-              require "fast-mcp"
-            rescue LoadError => e
-              raise LoadError, "fast-mcp gem is required but not available. Ensure it's in your Gemfile: #{e.message}"
-            end
-          end
-
-          # Verify the expected interface exists
-          unless FastMcp::Resource.respond_to?(:uri)
-            raise "FastMcp::Resource doesn't have expected interface. Check fast-mcp gem version."
-          end
-
-          # Load addressable template dependency
-          begin
-            require "addressable/template"
-          rescue LoadError => e
-            raise LoadError, "addressable gem is required for URI templating: #{e.message}"
-          end
-
-          # Optional: Version checking
-          if defined?(FastMcp::VERSION)
-            version = Gem::Version.new(FastMcp::VERSION)
-            minimum_version = Gem::Version.new("1.4.0")
-
-            if version < minimum_version
-              RailsMcpServer.log(:warn, "FastMcp version #{FastMcp::VERSION} detected. Extensions tested with #{minimum_version}+")
-            end
-          end
-        end
-
-        def apply_extensions!
-          # Apply extensions to FastMcp::Resource
-          FastMcp::Resource.prepend(ResourceTemplating)
-
-          # Also ensure our BaseResource gets the extensions
-          if defined?(RailsMcpServer::BaseResource)
-            # BaseResource already inherits from FastMcp::Resource, so it gets extensions automatically
-            RailsMcpServer.log(:debug, "BaseResource will inherit templating extensions")
-          end
-
-          # Setup server extensions as well
-          RailsMcpServer::Extensions::ServerExtensionSetup.setup!
-        end
-      end
-    end
-  end
-end