rubydex 0.2.8 → 0.2.9

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Rubydex
+  module MCPServer
+    class SearchDeclarationsTool < BaseTool
+      tool_name "search_declarations"
+      description 'Search for Ruby classes, modules, methods, or constants by name. Use this INSTEAD OF Grep when you know part of a Ruby identifier name and want to find its definition. Returns fully qualified names, kinds, and file locations. Use the `kind` filter ("Class", "Module", "Method", "Constant") to narrow results. Set `match_mode` to "exact" for precise substring matching or "fuzzy" for LSP-style workspace symbol search (default). Results are paginated: the response includes `total` (the full count of matches). If `total` exceeds the number of returned results, use `offset` to fetch subsequent pages.'
+      input_schema(
+        properties: {
+          query: { type: "string", description: "Search query to match against declaration names" },
+          kind: { type: "string", description: "Filter by declaration kind: Class, Module, Method, Constant, etc." },
+          match_mode: { type: "string", description: 'Matching mode: "fuzzy" (default) for LSP-style workspace symbol search, or "exact" for precise substring matching' },
+          limit: { type: "integer", description: "Maximum number of results to return (default 50, max 100)" },
+          offset: { type: "integer", description: "Number of results to skip for pagination (default 0)" },
+        },
+        required: ["query"],
+      )
+
+      #: (query: String, ?kind: String, ?match_mode: String, ?limit: Integer, ?offset: Integer) -> Tool::Response
+      def call(query:, kind: nil, match_mode: nil, limit: nil, offset: nil)
+        declarations = case match_mode
+        when nil, "fuzzy"
+          @graph.fuzzy_search(query)
+        when "exact"
+          @graph.search(query)
+        else
+          return response(
+            Error.new(
+              "invalid_match_mode",
+              "Invalid match_mode '#{match_mode}'",
+              'Use "fuzzy" or "exact"',
+            ),
+          )
+        end
+
+        if kind
+          declarations = declarations.lazy.select { |declaration| declaration_kind(declaration).casecmp?(kind) }
+        end
+
+        page, total = paginate(declarations, offset, limit, 100)
+        results = page.map do |declaration|
+          {
+            name: declaration.name,
+            kind: declaration_kind(declaration),
+            locations: declaration.definitions.map do |definition|
+              display_location(definition.location)
+            end,
+          }
+        end
+
+        response(results: results, total: total)
+      end
+    end
+  end
+end

data/lib/rubydex/mcp_server.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require "json"
+
+require "rubydex"
+require "rubydex/mcp_server/protocol"
+
+Dir[File.join(__dir__, "mcp_server", "tools", "*_tool.rb")].sort.each { |file| require file }
+
+module Rubydex
+  module MCPServer
+    SERVER_INSTRUCTIONS = <<~TEXT
+      Rubydex provides semantic Ruby code intelligence.
+
+      Use these tools for Ruby source files (.rb, .rbi, .rbs) when you need structural information about declarations, locations, hierarchy, references, or codebase composition.
+
+      Use text search instead for literal strings, comments, log messages, non-Ruby files, or content search rather than structural queries.
+
+      Fully qualified name format: "Foo::Bar" for classes/modules/constants, "Foo::Bar#method_name" for instance methods.
+
+      Pagination: tools that may return a high number of results include `total` for pagination. When `total` exceeds the number of returned items, use `offset` to fetch the next page.
+    TEXT
+
+    class Server
+      WORKER_COUNT = 4
+
+      #: (root_path: String, ?transport: StdioTransport) -> void
+      def initialize(root_path:, transport: nil)
+        @root_path = root_path
+        @transport = transport
+        @graph = Graph.new(workspace_path: @root_path)
+        @graph.load_config
+        @index_finished = false
+        @incoming_queue = Thread::Queue.new
+        @outgoing_queue = Thread::Queue.new
+        @workers = []
+        @outgoing_dispatcher = nil
+      end
+
+      attr_reader :root_path
+
+      #: -> Thread
+      def spawn_indexer
+        Thread.new do
+          @graph.index_workspace
+          @graph.resolve
+          @index_finished = true
+        end
+      end
+
+      #: -> void
+      def main_loop
+        @workers = Array.new(WORKER_COUNT) { new_worker }
+        @outgoing_dispatcher = Thread.new do
+          while (response = @outgoing_queue.pop)
+            @transport.write(response)
+          end
+        end
+
+        @transport.open do |request, parse_error|
+          if parse_error
+            send_message(parse_error)
+          else
+            @incoming_queue << request
+          end
+        end
+      ensure
+        run_shutdown
+        @transport.close
+      end
+
+      #: (Hash | Array | untyped) -> Hash | Array[Hash]?
+      def handle(request)
+        if request.is_a?(Array)
+          return JSONRPC.error_response(nil, JSONRPC::INVALID_REQUEST, "Invalid Request", data: "Request is an empty array") if request.empty?
+
+          responses = request.filter_map { |entry| handle(entry) }
+          return responses if responses.any?
+
+          return
+        end
+
+        unless request.is_a?(Hash)
+          return JSONRPC.error_response(nil, JSONRPC::INVALID_REQUEST, "Invalid Request", data: "Request must be a hash")
+        end
+
+        has_id = request.key?(:id)
+        id = request[:id]
+        method = request[:method]
+        params = request[:params]
+
+        unless request[:jsonrpc] == "2.0"
+          return JSONRPC.error_response(nil, JSONRPC::INVALID_REQUEST, "Invalid Request", data: "JSON-RPC version must be 2.0")
+        end
+
+        unless !has_id || id.is_a?(Integer) || (id.is_a?(String) && id.match?(/\A[a-zA-Z0-9_-]+\z/))
+          return JSONRPC.error_response(nil, JSONRPC::INVALID_REQUEST, "Invalid Request", data: "Request ID must be a string or integer")
+        end
+
+        unless method.is_a?(String) && !method.start_with?("rpc.")
+          return JSONRPC.error_response(nil, JSONRPC::INVALID_REQUEST, "Invalid Request", data: 'Method name must be a string and not start with "rpc."')
+        end
+
+        unless params.nil? || params.is_a?(Hash)
+          return JSONRPC.error_response(id, JSONRPC::INVALID_PARAMS, "Invalid params", data: "Method parameters must be an object or null")
+        end
+
+        result = case method
+        when "initialize"
+          {
+            protocolVersion: "2025-03-26",
+            capabilities: { tools: {} },
+            serverInfo: {
+              name: "rubydex_mcp",
+              version: Rubydex::VERSION,
+            },
+            instructions: SERVER_INSTRUCTIONS,
+          }
+        when "tools/list"
+          { tools: Tool.tools.map(&:to_h) }
+        when "tools/call"
+          call_tool(params || {})
+        when "ping"
+          {}
+        when "notifications/initialized"
+          return
+        else
+          return has_id ? JSONRPC.error_response(id, JSONRPC::METHOD_NOT_FOUND, "Method not found", data: method) : nil
+        end
+
+        has_id ? { jsonrpc: "2.0", id: id, result: result } : nil
+      rescue KeyError => e
+        has_id ? JSONRPC.error_response(id, JSONRPC::INVALID_PARAMS, "Invalid params", data: e.message) : nil
+      rescue StandardError => e
+        has_id ? JSONRPC.error_response(id, JSONRPC::INTERNAL_ERROR, "Internal error", data: e.message) : nil
+      end
+
+      #: -> Graph | Error
+      def graph_or_error
+        return @graph if @index_finished
+
+        Error.new(
+          "indexing",
+          "Rubydex is still indexing the codebase",
+          "The server is starting up. Please retry in a few seconds.",
+        )
+      end
+
+      private
+
+      #: -> void
+      def run_shutdown
+        @incoming_queue.close unless @incoming_queue.closed?
+        @workers.each(&:join)
+        @outgoing_queue.close unless @outgoing_queue.closed?
+        @outgoing_dispatcher&.join
+      end
+
+      #: -> Thread
+      def new_worker
+        Thread.new do
+          while (request = @incoming_queue.pop)
+            send_message(handle(request))
+          end
+        end
+      end
+
+      #: (Hash | Array[Hash]?) -> void
+      def send_message(response)
+        return unless response
+        return if @outgoing_queue.closed?
+
+        @outgoing_queue << response
+      end
+
+      #: (Hash) -> Hash
+      def call_tool(params)
+        tool_name = params.fetch(:name)
+        tool = Tool.tools_by_name.fetch(tool_name, nil)
+        raise KeyError, "Tool not found: #{tool_name}" unless tool
+
+        arguments = params[:arguments] || {}
+        known_arguments = tool.input_schema.fetch(:properties).keys.map(&:to_s)
+        unknown_arguments = arguments.keys.map(&:to_s) - known_arguments
+        unless unknown_arguments.empty?
+          return Tool::Response.new(
+            [{ type: "text", text: "Unknown arguments: #{unknown_arguments.join(", ")}" }],
+            error: true,
+          ).to_h
+        end
+
+        missing_arguments = Array(tool.input_schema[:required]) - arguments.keys.map(&:to_s)
+        unless missing_arguments.empty?
+          return Tool::Response.new(
+            [{ type: "text", text: "Missing required arguments: #{missing_arguments.join(", ")}" }],
+            error: true,
+          ).to_h
+        end
+
+        graph = graph_or_error
+        return Tool::Response.new([{ type: "text", text: JSON.generate(graph) }]).to_h if graph.is_a?(Error)
+
+        response = tool.new(graph).call(**arguments.transform_keys(&:to_sym))
+        response.to_h
+      end
+    end
+
+    class << self
+      #: (?String) -> void
+      def run(path = ".")
+        root = File.realpath(path)
+        server = Server.new(root_path: root, transport: StdioTransport.new)
+        server.spawn_indexer
+
+        server.main_loop
+      end
+    end
+  end
+end

data/lib/rubydex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rubydex
-  VERSION = "0.2.8"
+  VERSION = "0.2.9"
 end

data/rbi/rubydex.rbi

@@ -313,7 +313,7 @@ class Rubydex::Graph
   sig { returns(T::Array[String]) }
   def index_workspace; end
 
-  # Loads configuration, merging its excluded paths into the graph's configuration (the workspace path is never
+  # Loads configuration, merging its exclusion patterns into the graph's configuration (the workspace path is never
   # overridden). With `config_path` (resolved relative to the workspace path), an explicitly named file that does not
   # exist raises `Rubydex::ConfigError`. With no argument, the default `.rubydex` is loaded if present and ignored if
   # missing. Raises `Rubydex::ConfigError` if a file cannot be read or is malformed.
@@ -418,11 +418,11 @@ class Rubydex::Graph
   sig { params(paths: T::Array[String]).void }
   def add_workspace_dependency_paths(paths); end
 
-  sig { params(paths: T::Array[String]).void }
-  def exclude_paths(paths); end
+  sig { params(patterns: T::Array[String]).void }
+  def exclude_patterns(patterns); end
 
   sig { returns(T::Array[String]) }
-  def excluded_paths; end
+  def excluded_patterns; end
 end
 
 class Rubydex::DisplayLocation < Rubydex::Location