rubydex 0.2.8 → 0.2.9

data/exe/rdx

@@ -7,7 +7,7 @@ require "optparse"
 
 options = {}
 
-OptionParser.new do |parser|
+option_parser = OptionParser.new do |parser|
   parser.on("--version", "Print the gem's version") do
     require "rubydex/version"
     puts "v#{Rubydex::VERSION}"
@@ -22,10 +22,36 @@ OptionParser.new do |parser|
   parser.on("-i", "--interactive", "Open an interactive session with a populated graph for the current workspace") do
     options[:interactive] = true
   end
-end.parse!
+
+  parser.on("--mcp", "Run the MCP server for AI assistants") do
+    options[:mcp] = true
+  end
+end
+
+begin
+  arguments = option_parser.parse(ARGV)
+rescue OptionParser::ParseError => e
+  warn("error: #{e.message}")
+  warn
+  warn(option_parser)
+  exit(2)
+end
 
 require "rubydex"
 
+if options[:mcp]
+  if arguments.length > 1
+    warn("error: unexpected argument '#{arguments[1]}' found")
+    warn
+    warn(option_parser)
+    exit(2)
+  end
+
+  require "rubydex/mcp_server"
+  Rubydex::MCPServer.run(arguments.fetch(0, Dir.pwd))
+  exit
+end
+
 def __with_timer(message, &block)
   print(message)
   start = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)

data/ext/rubydex/extconf.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "mkmf"
-require "fileutils"
 require "pathname"
 
 unless system("cargo", "--version", out: File::NULL, err: File::NULL)
@@ -82,12 +81,6 @@ else
 end
 
 lib_dir = gem_dir.join("lib").join("rubydex")
-mcp_bin_dir = lib_dir.join("bin")
-FileUtils.mkdir_p(mcp_bin_dir)
-
-mcp_executable = Gem.win_platform? ? "rubydex_mcp.exe" : "rubydex_mcp"
-mcp_src = target_dir.join(mcp_executable)
-mcp_dst = mcp_bin_dir.join(mcp_executable)
 
 copy_dylib_commands = if Gem.win_platform?
   ""
@@ -114,7 +107,6 @@ new_makefile = makefile.gsub("$(OBJS): $(HDRS) $(ruby_headers)", <<~MAKEFILE.cho
   .rust_built: $(RUST_SRCS)
   \t#{cargo_command} || (echo "Compiling Rust failed" && exit 1)
   \t$(COPY) #{bindings_path} #{__dir__}
-  \t$(COPY) #{mcp_src} #{mcp_dst}
   \ttouch $@
 
   compile_rust: .rust_built

data/ext/rubydex/graph.c

@@ -796,38 +796,38 @@ static VALUE rdxr_graph_complete_method_argument(int argc, VALUE *argv, VALUE se
 
 /*
  * call-seq:
- *   exclude_paths(paths) -> nil
+ *   exclude_patterns(patterns) -> nil
  *
- * Excludes the paths from file discovery during indexing.
+ * Excludes files matching the given glob patterns from discovery during indexing.
  */
-static VALUE rdxr_graph_exclude_paths(VALUE self, VALUE paths) {
-    Check_Type(paths, T_ARRAY);
-    rdxi_check_array_of_strings(paths);
+static VALUE rdxr_graph_exclude_patterns(VALUE self, VALUE patterns) {
+    Check_Type(patterns, T_ARRAY);
+    rdxi_check_array_of_strings(patterns);
 
-    size_t length = RARRAY_LEN(paths);
-    char **converted_paths = rdxi_str_array_to_char(paths, length);
+    size_t length = RARRAY_LEN(patterns);
+    char **converted_patterns = rdxi_str_array_to_char(patterns, length);
 
     void *graph;
     TypedData_Get_Struct(self, void*, &graph_type, graph);
 
-    rdx_graph_exclude_paths(graph, (const char **)converted_paths, length);
-    rdxi_free_str_array(converted_paths, length);
+    rdx_graph_exclude_patterns(graph, (const char **)converted_patterns, length);
+    rdxi_free_str_array(converted_patterns, length);
 
     return Qnil;
 }
 
 /*
  * call-seq:
- *   excluded_paths -> Array[String]
+ *   excluded_patterns -> Array[String]
  *
- * Returns the paths currently excluded from file discovery.
+ * Returns the glob patterns currently excluded from file discovery.
  */
-static VALUE rdxr_graph_excluded_paths(VALUE self) {
+static VALUE rdxr_graph_excluded_patterns(VALUE self) {
     void *graph;
     TypedData_Get_Struct(self, void*, &graph_type, graph);
 
     size_t out_count = 0;
-    const char *const *results = rdx_graph_excluded_paths(graph, &out_count);
+    const char *const *results = rdx_graph_excluded_patterns(graph, &out_count);
 
     if (results == NULL) {
         return rb_ary_new();
@@ -965,8 +965,8 @@ void rdxi_initialize_graph(VALUE moduleRubydex) {
     rb_define_method(cGraph, "complete_namespace_access", rdxr_graph_complete_namespace_access, -1);
     rb_define_method(cGraph, "complete_method_call", rdxr_graph_complete_method_call, -1);
     rb_define_method(cGraph, "complete_method_argument", rdxr_graph_complete_method_argument, -1);
-    rb_define_method(cGraph, "exclude_paths", rdxr_graph_exclude_paths, 1);
-    rb_define_method(cGraph, "excluded_paths", rdxr_graph_excluded_paths, 0);
+    rb_define_method(cGraph, "exclude_patterns", rdxr_graph_exclude_patterns, 1);
+    rb_define_method(cGraph, "excluded_patterns", rdxr_graph_excluded_patterns, 0);
     rb_define_method(cGraph, "workspace_path", rdxr_graph_workspace_path, 0);
     rb_define_method(cGraph, "workspace_path=", rdxr_graph_set_workspace_path, 1);
     rb_define_method(cGraph, "load_config", rdxr_graph_load_config, -1);

data/lib/rubydex/mcp_server/protocol.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rubydex
+  module MCPServer
+    module JSONRPC
+      PARSE_ERROR = -32_700
+      INVALID_REQUEST = -32_600
+      METHOD_NOT_FOUND = -32_601
+      INVALID_PARAMS = -32_602
+      INTERNAL_ERROR = -32_603
+
+      class << self
+        #: (untyped, Integer, String, ?data: untyped) -> Hash
+        def error_response(id, code, message, data: nil)
+          {
+            jsonrpc: "2.0",
+            id: id,
+            error: {
+              code: code,
+              message: message,
+              data: data,
+            }.compact,
+          }
+        end
+      end
+    end
+
+    class Error
+      #: (String, ?String, ?String) -> void
+      def initialize(error, message = nil, suggestion = nil)
+        @error = error
+        @message = message
+        @suggestion = suggestion
+      end
+
+      #: (*untyped) -> String
+      def to_json(*args)
+        payload = { error: @error }
+        payload[:message] = @message if @message
+        payload[:suggestion] = @suggestion if @suggestion
+        payload.to_json(*args)
+      end
+    end
+
+    class Tool
+      @tools = []
+
+      class Response
+        #: (Array[Hash], ?bool) -> void
+        def initialize(content, error: false)
+          @content = content
+          @error = error
+        end
+
+        attr_reader :content
+
+        #: -> bool
+        def error?
+          @error
+        end
+
+        #: -> Hash
+        def to_h
+          {
+            content: content,
+            isError: error?,
+          }
+        end
+      end
+
+      class << self
+        attr_reader :tools
+
+        #: (Class) -> void
+        def inherited(tool)
+          Tool.tools << tool unless tool.name&.end_with?("::BaseTool")
+          super
+        end
+
+        #: -> Hash[String, Class]
+        def tools_by_name
+          tools.to_h { |tool| [tool.tool_name, tool] }
+        end
+
+        #: (?String) -> String
+        def tool_name(value = nil)
+          @tool_name = value if value
+          @tool_name || raise(NotImplementedError, "#{name} must define tool_name")
+        end
+
+        #: (?String) -> String
+        def description(value = nil)
+          @description = value if value
+          @description || raise(NotImplementedError, "#{name} must define description")
+        end
+
+        #: (?Hash, ?Array[String]) -> Hash
+        def input_schema(properties: nil, required: nil)
+          if properties
+            @input_schema = {
+              type: "object",
+              properties: properties,
+            }
+            @input_schema[:required] = required if required
+          end
+
+          @input_schema || { type: "object", properties: {} }
+        end
+
+        #: -> Hash
+        def to_h
+          {
+            name: tool_name,
+            description: description,
+            inputSchema: input_schema,
+          }
+        end
+      end
+    end
+
+    class StdioTransport
+      #: -> void
+      def initialize
+        @input = $stdin
+        @output = $stdout
+        @input.binmode
+        @input.sync = true
+        @output.binmode
+        @output.sync = true
+      end
+
+      #: { (Hash | Array?, Hash?) -> void } -> void
+      def open
+        @input.each_line do |line|
+          yield JSON.parse(line, symbolize_names: true)
+        rescue JSON::ParserError
+          yield nil, JSONRPC.error_response(nil, JSONRPC::PARSE_ERROR, "Parse error", data: "Invalid JSON")
+        end
+      end
+
+      #: (Hash | Array[Hash]?) -> void
+      def write(response)
+        return unless response
+
+        @output.puts(JSON.generate(response))
+      end
+
+      #: -> void
+      def close
+        @output.flush
+      end
+    end
+  end
+end

data/lib/rubydex/mcp_server/tools/base_tool.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+require "uri"
+
+module Rubydex
+  module MCPServer
+    class BaseTool < Tool
+      DEFAULT_LIMIT = 50
+
+      #: (Graph) -> void
+      def initialize(graph)
+        super()
+        @graph = graph
+        @root_path = graph.workspace_path
+      end
+
+      #: (Hash | Error) -> Tool::Response
+      def response(payload)
+        Tool::Response.new([{ type: "text", text: JSON.generate(payload) }])
+      end
+
+      #: (Declaration) -> String
+      def declaration_kind(declaration)
+        return "<TODO>" if declaration.is_a?(Rubydex::Todo)
+
+        declaration.class.name.delete_prefix("Rubydex::")
+      end
+
+      #: (String) -> String
+      def format_path(uri)
+        path = file_path_for_uri(uri)
+        return uri unless path
+
+        absolute_path = File.expand_path(path)
+        absolute_root = File.expand_path(@root_path)
+        relative_path = Pathname.new(absolute_path).relative_path_from(Pathname.new(absolute_root)).to_s
+
+        relative_path.start_with?("..") ? absolute_path : relative_path
+      end
+
+      #: (String) -> String?
+      def file_path_for_uri(uri)
+        parsed = URI.parse(uri)
+        return unless parsed.scheme == "file"
+
+        path = URI.decode_uri_component(parsed.path)
+        path.delete_prefix!("/") if Gem.win_platform?
+        path
+      rescue URI::InvalidURIError, ArgumentError
+        nil
+      end
+
+      #: (String) -> Document?
+      def document_for_path(file_path)
+        absolute_target = if Pathname.new(file_path).absolute?
+          file_path
+        else
+          File.join(@root_path, file_path)
+        end
+        canonical_target = File.realpath(absolute_target)
+        @graph.documents.find do |document|
+          path = file_path_for_uri(document.uri)
+          path && File.expand_path(path) == canonical_target
+        end
+      end
+
+      #: (Location) -> Hash
+      def display_location(location)
+        display = location.to_display
+        {
+          path: format_path(display.uri),
+          line: display.start_line,
+        }
+      end
+
+      #: (Enumerable, Integer?, Integer?, Integer) -> [Array, Integer]
+      def paginate(items, offset, limit, max_limit)
+        offset = (offset || 0).to_i
+        offset = 0 unless offset.positive?
+        limit = (limit || DEFAULT_LIMIT).to_i
+        limit = DEFAULT_LIMIT unless limit.positive?
+        limit = [limit, max_limit].min
+
+        page = []
+        index = 0
+        items.each do |item|
+          page << item if index >= offset && page.length < limit
+          index += 1
+        end
+
+        [page, index]
+      end
+
+      #: (String) -> Declaration | Error
+      def lookup_declaration(name)
+        declaration = @graph[name]
+        return declaration if declaration
+
+        Error.new(
+          "not_found",
+          "Declaration '#{name}' not found",
+          "Try search_declarations with a partial name to find the correct FQN",
+        )
+      end
+    end
+  end
+end

data/lib/rubydex/mcp_server/tools/codebase_stats_tool.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Rubydex
+  module MCPServer
+    class CodebaseStatsTool < BaseTool
+      tool_name "codebase_stats"
+      description "Get an overview of the indexed Ruby codebase: total file count, declaration counts, and breakdown by kind (classes, modules, methods, constants). Use this to understand codebase size and composition, or to verify that indexing completed successfully."
+      input_schema(properties: {})
+
+      #: -> Tool::Response
+      def call
+        declaration_count = 0
+        breakdown = Hash.new(0)
+        @graph.declarations.each do |declaration|
+          declaration_count += 1
+          breakdown[declaration_kind(declaration)] += 1
+        end
+
+        response(
+          files: @graph.documents.count,
+          declarations: declaration_count,
+          definitions: @graph.documents.sum { |document| document.definitions.count },
+          constant_references: @graph.constant_references.count,
+          method_references: @graph.method_references.count,
+          breakdown_by_kind: breakdown,
+        )
+      end
+    end
+  end
+end

data/lib/rubydex/mcp_server/tools/find_constant_references_tool.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Rubydex
+  module MCPServer
+    class FindConstantReferencesTool < BaseTool
+      tool_name "find_constant_references"
+      description "Find all resolved references to a Ruby class, module, or constant across the codebase. Returns file paths, line numbers, and columns for each usage. Results are paginated: the response includes `total`. If `total` exceeds the number of returned results, use `offset` to fetch subsequent pages."
+      input_schema(
+        properties: {
+          name: { type: "string", description: "Fully qualified name of the class, module, or constant to find references for" },
+          limit: { type: "integer", description: "Maximum number of references to return (default 50, max 200)" },
+          offset: { type: "integer", description: "Number of references to skip for pagination (default 0)" },
+        },
+        required: ["name"],
+      )
+
+      #: (name: String, ?limit: Integer, ?offset: Integer) -> Tool::Response
+      def call(name:, limit: nil, offset: nil)
+        declaration = lookup_declaration(name)
+
+        case declaration
+        when Error
+          response(declaration)
+        else
+          references = case declaration
+          when Rubydex::Namespace, Rubydex::Constant, Rubydex::ConstantAlias
+            declaration.references
+          else
+            []
+          end
+          page, total = paginate(references, offset, limit, 200)
+          payload = page.map do |reference|
+            display = reference.location.to_display
+            {
+              path: format_path(display.uri),
+              line: display.start_line,
+              column: display.start_column,
+            }
+          end
+
+          response(name: name, references: payload, total: total)
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/mcp_server/tools/get_declaration_tool.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Rubydex
+  module MCPServer
+    class GetDeclarationTool < BaseTool
+      tool_name "get_declaration"
+      description 'Get complete information about a Ruby class, module, method, or constant by its exact fully qualified name. Returns file locations, documentation comments, ancestor chain, and members with locations. FQN format: "Foo::Bar" for classes/modules/constants, "Foo::Bar#method_name" for instance methods, "Foo::Bar::<Bar>" for singleton classes, and "Foo::Bar::<Bar>#method_name" for class methods.'
+      input_schema(
+        properties: {
+          name: { type: "string", description: "Fully qualified name of the declaration (e.g. 'Foo::Bar', 'Foo::Bar#baz')" },
+        },
+        required: ["name"],
+      )
+
+      #: (name: String) -> Tool::Response
+      def call(name:)
+        declaration = lookup_declaration(name)
+
+        case declaration
+        when Error
+          response(declaration)
+        else
+          definitions = declaration.definitions.map do |definition|
+            display_location(definition.location).merge(
+              comments: definition.comments.map do |comment|
+                comment.string.delete_prefix("# ")
+              end,
+            )
+          end
+
+          ancestors = if declaration.is_a?(Rubydex::Namespace)
+            declaration.ancestors.map do |ancestor|
+              {
+                name: ancestor.name,
+                kind: declaration_kind(ancestor),
+              }
+            end
+          else
+            []
+          end
+
+          members = if declaration.is_a?(Rubydex::Namespace)
+            declaration.members.map do |member|
+              payload = {
+                name: member.name,
+                kind: declaration_kind(member),
+              }
+
+              definition = member.definitions.first
+              payload[:location] = display_location(definition.location) if definition
+              payload
+            end
+          else
+            []
+          end
+
+          response(
+            name: declaration.name,
+            kind: declaration_kind(declaration),
+            definitions: definitions,
+            ancestors: ancestors,
+            members: members,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/mcp_server/tools/get_descendants_tool.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Rubydex
+  module MCPServer
+    class GetDescendantsTool < BaseTool
+      tool_name "get_descendants"
+      description "Returns all known descendants for the given namespace including itself and all transitive descendants. Can be used to understand how a module/class is used across the codebase. Results are paginated: the response includes `total`. If `total` exceeds the number of returned results, use `offset` to fetch subsequent pages."
+      input_schema(
+        properties: {
+          name: { type: "string", description: "Fully qualified name of the class or module" },
+          limit: { type: "integer", description: "Maximum number of descendants to return (default 50, max 500)" },
+          offset: { type: "integer", description: "Number of descendants to skip for pagination (default 0)" },
+        },
+        required: ["name"],
+      )
+
+      #: (name: String, ?limit: Integer, ?offset: Integer) -> Tool::Response
+      def call(name:, limit: nil, offset: nil)
+        declaration = lookup_declaration(name)
+
+        case declaration
+        when Error
+          response(declaration)
+        when Rubydex::Namespace
+          page, total = paginate(declaration.descendants, offset, limit, 500)
+          descendants = page.map do |descendant|
+            {
+              name: descendant.name,
+              kind: declaration_kind(descendant),
+            }
+          end
+
+          response(name: declaration.name, descendants: descendants, total: total)
+        else
+          response(
+            Error.new(
+              "invalid_kind",
+              "'#{name}' is not a class or module (it is a #{declaration_kind(declaration)})",
+              "get_descendants only works on classes and modules, not methods or constants",
+            ),
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/mcp_server/tools/get_file_declarations_tool.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Rubydex
+  module MCPServer
+    class GetFileDeclarationsTool < BaseTool
+      tool_name "get_file_declarations"
+      description "List all Ruby classes, modules, methods, and constants defined in a specific file. Returns a structural overview with names, kinds, and line numbers. Use this to understand a file's structure before reading it, or to see what a file contributes to the codebase. Accepts relative or absolute paths."
+      input_schema(
+        properties: {
+          file_path: { type: "string", description: "File path (relative or absolute) to list declarations for" },
+        },
+        required: ["file_path"],
+      )
+
+      #: (file_path: String) -> Tool::Response
+      def call(file_path:)
+        absolute_target = if Pathname.new(file_path).absolute?
+          file_path
+        else
+          File.join(@root_path, file_path)
+        end
+        return file_not_found_response(file_path) unless File.exist?(absolute_target)
+
+        document = document_for_path(file_path)
+        return file_not_found_response(file_path) unless document
+
+        declarations = document.definitions.filter_map do |definition|
+          declaration = definition.declaration
+          next unless declaration
+
+          {
+            name: declaration.name,
+            kind: declaration_kind(declaration),
+            line: definition.location.to_display.start_line,
+          }
+        end
+
+        response(file: format_path(document.uri), declarations: declarations)
+      end
+
+      private
+
+      #: (String) -> Tool::Response
+      def file_not_found_response(file_path)
+        response(
+          Error.new(
+            "not_found",
+            "File '#{file_path}' not found in the index",
+            "Use a relative path like 'app/models/user.rb' or an absolute path matching the indexed project",
+          ),
+        )
+      end
+    end
+  end
+end