cf-mcp 0.12.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f3d843ae9e0087f798cad60be61d347da0db7c1f26e5bee5050eccda2a38b29
-  data.tar.gz: 98735400ef25d3a51d6d984a0daf12141c1c96b6843922069d71bb24a4183bdc
+  metadata.gz: 30c68992a64d36c8265af4bdcd018dd116c7d2e59479ab1fd83213896028b86d
+  data.tar.gz: 4a4e5b715cdca959296e1043bf3173a2c4c314a40ab5c1cb76154dd20b823557
 SHA512:
-  metadata.gz: fb5143e02aca5453221893bdabd3cb945912cfa83c7693f34d0cba99ea1cbde14a93d4238d3dfb92ab1e39026f5b98ab416de2a40eb68f262745f028e6aecf68
-  data.tar.gz: 918e16127b4a29c8e0d33fe162b5d1788d14c28f3e1c55774d97204ad1805a38c1407f6d10b07072fe9b55c1998436f833fb957ee4f3739434887e94eea84f07
+  metadata.gz: 1704a19c8b49fb37258b247e5689a15f7ed67a2cce9ff226ee5ac0c4689dbc45b547150d426cc91e15e09a2f36405752f58a98e5b14596e5282dc7b9784c4e15
+  data.tar.gz: d1c5c7f81871cddb2f0a1bb81b98272b7d3d07a8d7d40bfafd08c338ef2e6b8073d296407ae2dd74575b7ec2738864c1c5bd941408f9f681e373002af363a70d

data/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.12.1] - 2026-01-14
+
+### Changed
+
+- Refactored tool classes to use shared `ResponseHelpers` module, removing duplicate code
+- Extracted `IndexBuilder` class to consolidate index building logic from CLI and HTTPServer
+- Extracted `SearchResultFormatter` module for consistent search result formatting
+- Simplified model `to_text()` methods using template method pattern in `DocItem` base class
+
 ## [0.12.0] - 2026-01-14
 
 ### Changed
@@ -139,6 +148,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `cf_list_category` - List items by category
   - `cf_get_details` - Get full documentation by name
 
+[0.12.1]: https://github.com/pusewicz/cf-mcp/compare/v0.12.0...v0.12.1
 [0.12.0]: https://github.com/pusewicz/cf-mcp/compare/v0.10.1...v0.12.0
 [0.10.1]: https://github.com/pusewicz/cf-mcp/compare/v0.10.0...v0.10.1
 [0.10.0]: https://github.com/pusewicz/cf-mcp/compare/v0.9.3...v0.10.0

data/Manifest.txt

@@ -9,6 +9,7 @@ lib/cf/mcp.rb
 lib/cf/mcp/cli.rb
 lib/cf/mcp/downloader.rb
 lib/cf/mcp/index.rb
+lib/cf/mcp/index_builder.rb
 lib/cf/mcp/models/doc_item.rb
 lib/cf/mcp/models/enum_doc.rb
 lib/cf/mcp/models/function_doc.rb
@@ -26,8 +27,10 @@ lib/cf/mcp/tools/list_category.rb
 lib/cf/mcp/tools/list_topics.rb
 lib/cf/mcp/tools/member_search.rb
 lib/cf/mcp/tools/parameter_search.rb
+lib/cf/mcp/tools/response_helpers.rb
 lib/cf/mcp/tools/search_enums.rb
 lib/cf/mcp/tools/search_functions.rb
+lib/cf/mcp/tools/search_result_formatter.rb
 lib/cf/mcp/tools/search_structs.rb
 lib/cf/mcp/tools/search_tool.rb
 lib/cf/mcp/topic_parser.rb

data/lib/cf/mcp/cli.rb

@@ -1,17 +1,12 @@
 # frozen_string_literal: true
 
 require "optparse"
-require_relative "parser"
-require_relative "topic_parser"
-require_relative "index"
+require_relative "index_builder"
 require_relative "server"
-require_relative "downloader"
 
 module CF
   module MCP
     class CLI
-      DEFAULT_HEADERS_PATH = File.expand_path("~/Work/GitHub/pusewicz/cute_framework/include")
-
       def initialize(args)
         @args = args
         @options = parse_args
@@ -90,17 +85,19 @@ module CF
       end
 
       def run_server(mode)
-        headers_path = resolve_headers_path
+        builder = IndexBuilder.new(root: @options[:root], download: @options[:download])
 
-        unless File.directory?(headers_path)
-          warn "Error: Headers directory not found: #{headers_path}"
+        unless builder.valid?
+          warn "Error: Headers directory not found: #{builder.headers_path}"
           warn "Use --root to specify the path to Cute Framework headers"
           warn "Or use --download to fetch headers from GitHub"
           exit 1
         end
 
-        warn "Parsing headers from: #{headers_path}"
-        index = build_index(headers_path)
+        warn "Parsing headers from: #{builder.headers_path}"
+        index = builder.build do |event, path, count|
+          warn "Indexed #{count} topics from: #{path}" if event == :topics_indexed
+        end
         warn "Indexed #{index.stats[:total]} items (#{index.stats[:functions]} functions, #{index.stats[:structs]} structs, #{index.stats[:enums]} enums)"
 
         server = Server.new(index)
@@ -123,69 +120,6 @@ module CF
         warn "MCP endpoint available at http://localhost:#{port}/http"
         Rackup::Server.start(app: app, Host: host, Port: port, Logger: $stderr)
       end
-
-      def resolve_headers_path
-        return @options[:root] if @options[:root]
-        return ENV["CF_HEADERS_PATH"] if ENV["CF_HEADERS_PATH"]
-
-        if @options[:download]
-          warn "Downloading Cute Framework headers from GitHub..."
-          downloader = Downloader.new
-          path = downloader.download_and_extract
-          warn "Downloaded headers to: #{path}"
-          return path
-        end
-
-        DEFAULT_HEADERS_PATH
-      end
-
-      def build_index(headers_path)
-        parser = Parser.new
-        index = Index.new
-
-        parser.parse_directory(headers_path).each do |item|
-          index.add(item)
-        end
-
-        # Parse topics if available
-        topics_path = find_topics_path(headers_path)
-        if topics_path && File.directory?(topics_path)
-          topic_parser = TopicParser.new
-          topic_parser.parse_directory(topics_path).each do |topic|
-            refine_topic_references(topic, index)
-            index.add(topic)
-          end
-          warn "Indexed #{index.stats[:topics]} topics from: #{topics_path}"
-        end
-
-        index
-      end
-
-      def find_topics_path(headers_path)
-        # If headers_path is .../cute_framework/include, topics is at .../cute_framework/docs/topics
-        base = File.dirname(headers_path)
-        topics_path = File.join(base, "docs", "topics")
-        return topics_path if File.directory?(topics_path)
-
-        # Alternative: topics directly under headers parent
-        topics_path = File.join(base, "topics")
-        return topics_path if File.directory?(topics_path)
-
-        nil
-      end
-
-      def refine_topic_references(topic, index)
-        # Move items from struct_references to enum_references if they're actually enums
-        topic.struct_references.dup.each do |ref|
-          item = index.find(ref)
-          next unless item
-
-          if item.type == :enum
-            topic.struct_references.delete(ref)
-            topic.enum_references << ref unless topic.enum_references.include?(ref)
-          end
-        end
-      end
     end
   end
 end

data/lib/cf/mcp/index_builder.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "parser"
+require_relative "topic_parser"
+require_relative "index"
+require_relative "downloader"
+
+module CF
+  module MCP
+    class IndexBuilder
+      DEFAULT_HEADERS_PATH = File.expand_path("~/Work/GitHub/pusewicz/cute_framework/include")
+
+      attr_reader :headers_path
+
+      def initialize(root: nil, download: false)
+        @headers_path = resolve_headers_path(root: root, download: download)
+      end
+
+      def build
+        parser = Parser.new
+        index = Index.new
+
+        parser.parse_directory(headers_path).each do |item|
+          index.add(item)
+        end
+
+        # Parse topics if available
+        topics_path = find_topics_path(headers_path)
+        if topics_path && File.directory?(topics_path)
+          topic_parser = TopicParser.new
+          topic_parser.parse_directory(topics_path).each do |topic|
+            refine_topic_references(topic, index)
+            index.add(topic)
+          end
+          yield(:topics_indexed, topics_path, index.stats[:topics]) if block_given?
+        end
+
+        index
+      end
+
+      def valid?
+        File.directory?(headers_path)
+      end
+
+      private
+
+      def resolve_headers_path(root:, download:)
+        return root if root
+        return ENV["CF_HEADERS_PATH"] if ENV["CF_HEADERS_PATH"]
+
+        if download
+          warn "Downloading Cute Framework headers from GitHub..."
+          downloader = Downloader.new
+          path = downloader.download_and_extract
+          warn "Downloaded headers to: #{path}"
+          return path
+        end
+
+        DEFAULT_HEADERS_PATH
+      end
+
+      def find_topics_path(headers_path)
+        # If headers_path is .../cute_framework/include, topics is at .../cute_framework/docs/topics
+        base = File.dirname(headers_path)
+        topics_path = File.join(base, "docs", "topics")
+        return topics_path if File.directory?(topics_path)
+
+        # Alternative: topics directly under headers parent
+        topics_path = File.join(base, "topics")
+        return topics_path if File.directory?(topics_path)
+
+        nil
+      end
+
+      def refine_topic_references(topic, index)
+        # Move items from struct_references to enum_references if they're actually enums
+        topic.struct_references.dup.each do |ref|
+          item = index.find(ref)
+          next unless item
+
+          if item.type == :enum
+            topic.struct_references.delete(ref)
+            topic.enum_references << ref unless topic.enum_references.include?(ref)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cf/mcp/models/doc_item.rb

@@ -128,6 +128,23 @@ module CF
         end
 
         def to_text(detailed: false, index: nil)
+          lines = []
+          lines.concat(build_header_lines)
+          lines.concat(build_description_lines)
+
+          if detailed
+            lines.concat(build_type_specific_lines)
+            lines.concat(build_remarks_lines)
+            lines.concat(build_example_lines)
+            lines.concat(build_related_lines(index))
+          end
+
+          lines.join("\n")
+        end
+
+        protected
+
+        def build_header_lines
           lines = []
           lines << "# #{name}"
           lines << ""
@@ -140,36 +157,44 @@ module CF
             lines << "- **Implementation:** #{urls[:impl_raw]}"
           end
           lines << ""
+          lines
+        end
+
+        def build_description_lines
+          lines = []
           lines << "## Description"
           lines << brief if brief
           lines << ""
+          lines
+        end
 
-          if detailed
-            if remarks && !remarks.empty?
-              lines << "## Remarks"
-              lines << remarks
-              lines << ""
-            end
+        def build_type_specific_lines
+          [] # Override in subclasses
+        end
 
-            if example && !example.empty?
-              lines << "## Example"
-              lines << example_brief if example_brief
-              lines << "```c"
-              lines << example
-              lines << "```"
-              lines << ""
-            end
+        def build_remarks_lines
+          return [] unless remarks && !remarks.empty?
+          ["## Remarks", remarks, ""]
+        end
 
-            if related && !related.empty?
-              lines << "## Related"
-              lines << format_related_items(index)
-              lines << ""
-            end
-          end
+        def build_example_lines
+          return [] unless example && !example.empty?
+          lines = ["## Example"]
+          lines << example_brief if example_brief
+          lines << "```c"
+          lines << example
+          lines << "```"
+          lines << ""
+          lines
+        end
 
-          lines.join("\n")
+        def build_related_lines(index)
+          return [] unless related && !related.empty?
+          ["## Related", format_related_items(index), ""]
         end
 
+        public
+
         def format_related_items(index)
           return related.join(", ") unless index
 

data/lib/cf/mcp/models/enum_doc.rb

@@ -24,58 +24,21 @@ module CF
           ).compact
         end
 
-        def to_text(detailed: false, index: nil)
+        protected
+
+        def build_type_specific_lines
+          return [] unless entries && !entries.empty?
+
           lines = []
-          lines << "# #{name}"
+          lines << "## Values"
           lines << ""
-          lines << "- **Type:** enum"
-          lines << "- **Category:** #{category}" if category
-          if source_file
-            urls = source_urls
-            lines << "- **Source:** [include/#{source_file}](#{urls[:blob]})"
-            lines << "- **Raw:** #{urls[:raw]}"
-            lines << "- **Implementation:** #{urls[:impl_raw]}"
+          lines << "| Name | Value | Description |"
+          lines << "| --- | --- | --- |"
+          entries.each do |entry|
+            lines << "| `#{entry.name}` | #{entry.value} | #{entry.description} |"
           end
           lines << ""
-          lines << "## Description"
-          lines << brief if brief
-          lines << ""
-
-          if detailed
-            if entries && !entries.empty?
-              lines << "## Values"
-              lines << ""
-              lines << "| Name | Value | Description |"
-              lines << "| --- | --- | --- |"
-              entries.each do |entry|
-                lines << "| `#{entry.name}` | #{entry.value} | #{entry.description} |"
-              end
-              lines << ""
-            end
-
-            if remarks && !remarks.empty?
-              lines << "## Remarks"
-              lines << remarks
-              lines << ""
-            end
-
-            if example && !example.empty?
-              lines << "## Example"
-              lines << example_brief if example_brief
-              lines << "```c"
-              lines << example
-              lines << "```"
-              lines << ""
-            end
-
-            if related && !related.empty?
-              lines << "## Related"
-              lines << format_related_items(index)
-              lines << ""
-            end
-          end
-
-          lines.join("\n")
+          lines
         end
       end
     end

data/lib/cf/mcp/models/function_doc.rb

@@ -38,71 +38,48 @@ module CF
 
         def to_text(detailed: false, index: nil)
           lines = []
-          lines << "# #{name}"
-          lines << ""
-          lines << "- **Type:** function"
-          lines << "- **Category:** #{category}" if category
-          if source_file
-            urls = source_urls
-            lines << "- **Source:** [include/#{source_file}](#{urls[:blob]})"
-            lines << "- **Raw:** #{urls[:raw]}"
-            lines << "- **Implementation:** #{urls[:impl_raw]}"
-          end
-          lines << ""
+          lines.concat(build_header_lines)
+          lines.concat(build_signature_lines)
+          lines.concat(build_description_lines)
 
-          if signature
-            lines << "## Signature"
-            lines << "```c"
-            lines << signature
-            lines << "```"
-            lines << ""
+          if detailed
+            lines.concat(build_type_specific_lines)
+            lines.concat(build_remarks_lines)
+            lines.concat(build_example_lines)
+            lines.concat(build_related_lines(index))
           end
 
-          lines << "## Description"
-          lines << brief if brief
-          lines << ""
+          lines.join("\n")
+        end
 
-          if detailed
-            if parameters && !parameters.empty?
-              lines << "## Parameters"
-              lines << ""
-              lines << "| Parameter | Description |"
-              lines << "| --- | --- |"
-              parameters.each do |param|
-                lines << "| `#{param.name}` | #{param.description} |"
-              end
-              lines << ""
-            end
+        protected
 
-            if return_value && !return_value.empty?
-              lines << "## Return Value"
-              lines << return_value
-              lines << ""
-            end
+        def build_signature_lines
+          return [] unless signature
+          ["## Signature", "```c", signature, "```", ""]
+        end
 
-            if remarks && !remarks.empty?
-              lines << "## Remarks"
-              lines << remarks
-              lines << ""
-            end
+        def build_type_specific_lines
+          lines = []
 
-            if example && !example.empty?
-              lines << "## Example"
-              lines << example_brief if example_brief
-              lines << "```c"
-              lines << example
-              lines << "```"
-              lines << ""
+          if parameters && !parameters.empty?
+            lines << "## Parameters"
+            lines << ""
+            lines << "| Parameter | Description |"
+            lines << "| --- | --- |"
+            parameters.each do |param|
+              lines << "| `#{param.name}` | #{param.description} |"
             end
+            lines << ""
+          end
 
-            if related && !related.empty?
-              lines << "## Related"
-              lines << format_related_items(index)
-              lines << ""
-            end
+          if return_value && !return_value.empty?
+            lines << "## Return Value"
+            lines << return_value
+            lines << ""
           end
 
-          lines.join("\n")
+          lines
         end
       end
     end

data/lib/cf/mcp/models/struct_doc.rb

@@ -24,58 +24,21 @@ module CF
           ).compact
         end
 
-        def to_text(detailed: false, index: nil)
+        protected
+
+        def build_type_specific_lines
+          return [] unless members && !members.empty?
+
           lines = []
-          lines << "# #{name}"
+          lines << "## Members"
           lines << ""
-          lines << "- **Type:** struct"
-          lines << "- **Category:** #{category}" if category
-          if source_file
-            urls = source_urls
-            lines << "- **Source:** [include/#{source_file}](#{urls[:blob]})"
-            lines << "- **Raw:** #{urls[:raw]}"
-            lines << "- **Implementation:** #{urls[:impl_raw]}"
+          lines << "| Member | Description |"
+          lines << "| --- | --- |"
+          members.each do |member|
+            lines << "| `#{member.declaration}` | #{member.description} |"
           end
           lines << ""
-          lines << "## Description"
-          lines << brief if brief
-          lines << ""
-
-          if detailed
-            if members && !members.empty?
-              lines << "## Members"
-              lines << ""
-              lines << "| Member | Description |"
-              lines << "| --- | --- |"
-              members.each do |member|
-                lines << "| `#{member.declaration}` | #{member.description} |"
-              end
-              lines << ""
-            end
-
-            if remarks && !remarks.empty?
-              lines << "## Remarks"
-              lines << remarks
-              lines << ""
-            end
-
-            if example && !example.empty?
-              lines << "## Example"
-              lines << example_brief if example_brief
-              lines << "```c"
-              lines << example
-              lines << "```"
-              lines << ""
-            end
-
-            if related && !related.empty?
-              lines << "## Related"
-              lines << format_related_items(index)
-              lines << ""
-            end
-          end
-
-          lines.join("\n")
+          lines
         end
       end
     end

data/lib/cf/mcp/server.rb

@@ -91,86 +91,23 @@ module CF
       # Build a rack app with automatic header downloading and indexing
       # This is the shared entry point for both config.ru and CLI
       def self.build_rack_app(root: nil, download: false)
-        require_relative "parser"
-        require_relative "topic_parser"
-        require_relative "index"
-        require_relative "downloader"
+        require_relative "index_builder"
 
-        headers_path = resolve_headers_path(root: root, download: download)
+        builder = IndexBuilder.new(root: root, download: download)
 
-        unless File.directory?(headers_path)
-          raise "Headers directory not found: #{headers_path}. Use root: or download: true"
+        unless builder.valid?
+          raise "Headers directory not found: #{builder.headers_path}. Use root: or download: true"
         end
 
-        warn "Parsing headers from: #{headers_path}"
-        index = build_index(headers_path)
+        warn "Parsing headers from: #{builder.headers_path}"
+        index = builder.build do |event, path, count|
+          warn "Indexed #{count} topics from: #{path}" if event == :topics_indexed
+        end
         warn "Indexed #{index.stats[:total]} items (#{index.stats[:functions]} functions, #{index.stats[:structs]} structs, #{index.stats[:enums]} enums)"
 
         new(index).rack_app
       end
 
-      def self.resolve_headers_path(root:, download:)
-        return root if root
-        return ENV["CF_HEADERS_PATH"] if ENV["CF_HEADERS_PATH"]
-
-        if download
-          warn "Downloading Cute Framework headers from GitHub..."
-          downloader = Downloader.new
-          path = downloader.download_and_extract
-          warn "Downloaded headers to: #{path}"
-          return path
-        end
-
-        File.expand_path("~/Work/GitHub/pusewicz/cute_framework/include")
-      end
-
-      def self.build_index(headers_path)
-        parser = Parser.new
-        index = Index.new
-
-        parser.parse_directory(headers_path).each do |item|
-          index.add(item)
-        end
-
-        # Parse topics if available
-        topics_path = find_topics_path(headers_path)
-        if topics_path && File.directory?(topics_path)
-          topic_parser = TopicParser.new
-          topic_parser.parse_directory(topics_path).each do |topic|
-            refine_topic_references(topic, index)
-            index.add(topic)
-          end
-          warn "Indexed #{index.stats[:topics]} topics from: #{topics_path}"
-        end
-
-        index
-      end
-
-      def self.find_topics_path(headers_path)
-        base = File.dirname(headers_path)
-        topics_path = File.join(base, "docs", "topics")
-        return topics_path if File.directory?(topics_path)
-
-        topics_path = File.join(base, "topics")
-        return topics_path if File.directory?(topics_path)
-
-        nil
-      end
-
-      def self.refine_topic_references(topic, index)
-        topic.struct_references.dup.each do |ref|
-          item = index.find(ref)
-          next unless item
-
-          if item.type == :enum
-            topic.struct_references.delete(ref)
-            topic.enum_references << ref unless topic.enum_references.include?(ref)
-          end
-        end
-      end
-
-      private_class_method :resolve_headers_path, :build_index, :find_topics_path, :refine_topic_references
-
       def initialize(index)
         @index = index
       end

data/lib/cf/mcp/tools/find_related.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 require "mcp"
+require_relative "response_helpers"
 
 module CF
   module MCP
     module Tools
       class FindRelated < ::MCP::Tool
+        extend ResponseHelpers
+
         tool_name "cf_find_related"
         description "Find all items related to a given Cute Framework item (bidirectional relationship search)"
 
@@ -63,14 +66,6 @@ module CF
 
           text_response(lines.join("\n"))
         end
-
-        def self.text_response(text)
-          ::MCP::Tool::Response.new([{type: "text", text: text}])
-        end
-
-        def self.error_response(message)
-          ::MCP::Tool::Response.new([{type: "text", text: "Error: #{message}"}], error: true)
-        end
       end
     end
   end

data/lib/cf/mcp/tools/get_details.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 require "mcp"
+require_relative "response_helpers"
 
 module CF
   module MCP
     module Tools
       class GetDetails < ::MCP::Tool
+        extend ResponseHelpers
+
         tool_name "cf_get_details"
         description "Get detailed documentation for a specific Cute Framework item by exact name"
 
@@ -50,14 +53,6 @@ module CF
             text_response(output)
           end
         end
-
-        def self.text_response(text)
-          ::MCP::Tool::Response.new([{type: "text", text: text}])
-        end
-
-        def self.error_response(message)
-          ::MCP::Tool::Response.new([{type: "text", text: "Error: #{message}"}], error: true)
-        end
       end
     end
   end

data/lib/cf/mcp/tools/get_topic.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 require "mcp"
+require_relative "response_helpers"
 
 module CF
   module MCP
     module Tools
       class GetTopic < ::MCP::Tool
+        extend ResponseHelpers
+
         tool_name "cf_get_topic"
         description "Get the full content of a Cute Framework topic guide document"
 
@@ -39,14 +42,6 @@ module CF
             text_response(topic.to_text(detailed: true, index: index))
           end
         end
-
-        def self.text_response(text)
-          ::MCP::Tool::Response.new([{type: "text", text: text}])
-        end
-
-        def self.error_response(message)
-          ::MCP::Tool::Response.new([{type: "text", text: "Error: #{message}"}], error: true)
-        end
       end
     end
   end

data/lib/cf/mcp/tools/list_category.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 require "mcp"
+require_relative "response_helpers"
 
 module CF
   module MCP
     module Tools
       class ListCategory < ::MCP::Tool
+        extend ResponseHelpers
+
         tool_name "cf_list_category"
         description "List all items in a specific category, or list all available categories"
 
@@ -63,14 +66,6 @@ module CF
             end
           end
         end
-
-        def self.text_response(text)
-          ::MCP::Tool::Response.new([{type: "text", text: text}])
-        end
-
-        def self.error_response(message)
-          ::MCP::Tool::Response.new([{type: "text", text: "Error: #{message}"}], error: true)
-        end
       end
     end
   end

data/lib/cf/mcp/tools/list_topics.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 require "mcp"
+require_relative "response_helpers"
 
 module CF
   module MCP
     module Tools
       class ListTopics < ::MCP::Tool
+        extend ResponseHelpers
+
         tool_name "cf_list_topics"
         description "List all Cute Framework topic guides, optionally filtered by category or in recommended reading order"
 
@@ -50,14 +53,6 @@ module CF
         end
 
         CATEGORY_TIP = "Use `cf_list_topics` without a category to see all available topics."
-
-        def self.text_response(text)
-          ::MCP::Tool::Response.new([{type: "text", text: text}])
-        end
-
-        def self.error_response(message)
-          ::MCP::Tool::Response.new([{type: "text", text: "Error: #{message}"}], error: true)
-        end
       end
     end
   end

data/lib/cf/mcp/tools/member_search.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 require "mcp"
+require_relative "response_helpers"
 
 module CF
   module MCP
     module Tools
       class MemberSearch < ::MCP::Tool
+        extend ResponseHelpers
+
         tool_name "cf_member_search"
         description "Search Cute Framework structs by member name or type"
 
@@ -62,14 +65,6 @@ module CF
 
           text_response(lines.join("\n"))
         end
-
-        def self.text_response(text)
-          ::MCP::Tool::Response.new([{type: "text", text: text}])
-        end
-
-        def self.error_response(message)
-          ::MCP::Tool::Response.new([{type: "text", text: "Error: #{message}"}], error: true)
-        end
       end
     end
   end

data/lib/cf/mcp/tools/parameter_search.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 require "mcp"
+require_relative "response_helpers"
 
 module CF
   module MCP
     module Tools
       class ParameterSearch < ::MCP::Tool
+        extend ResponseHelpers
+
         tool_name "cf_parameter_search"
         description "Find Cute Framework functions by parameter or return type"
 
@@ -88,14 +91,6 @@ module CF
 
           text_response(lines.join("\n"))
         end
-
-        def self.text_response(text)
-          ::MCP::Tool::Response.new([{type: "text", text: text}])
-        end
-
-        def self.error_response(message)
-          ::MCP::Tool::Response.new([{type: "text", text: "Error: #{message}"}], error: true)
-        end
       end
     end
   end

data/lib/cf/mcp/tools/response_helpers.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module CF
+  module MCP
+    module Tools
+      module ResponseHelpers
+        def text_response(text)
+          ::MCP::Tool::Response.new([{type: "text", text: text}])
+        end
+
+        def error_response(message)
+          ::MCP::Tool::Response.new([{type: "text", text: "Error: #{message}"}], error: true)
+        end
+      end
+    end
+  end
+end

data/lib/cf/mcp/tools/search_enums.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
 require "mcp"
+require_relative "response_helpers"
+require_relative "search_result_formatter"
 
 module CF
   module MCP
     module Tools
       class SearchEnums < ::MCP::Tool
+        extend ResponseHelpers
+        extend SearchResultFormatter
+
         tool_name "cf_search_enums"
         description "Search Cute Framework enums"
 
@@ -27,29 +32,15 @@ module CF
 
           results = index.search(query, type: :enum, category: category, limit: limit)
 
-          if results.empty?
-            text_response("No enums found for '#{query}'")
-          else
-            formatted = results.map(&:to_summary).join("\n")
-            header = if results.size >= limit
-              "Found #{results.size} enum(s) (limit reached, more may exist):"
-            else
-              "Found #{results.size} enum(s):"
-            end
-
-            footer = "\n\n#{DETAILS_TIP}"
-            footer += "\nTo find more results, narrow your search with a `category` filter." if results.size >= limit
-
-            text_response("#{header}\n\n#{formatted}#{footer}")
-          end
-        end
-
-        def self.text_response(text)
-          ::MCP::Tool::Response.new([{type: "text", text: text}])
-        end
-
-        def self.error_response(message)
-          ::MCP::Tool::Response.new([{type: "text", text: "Error: #{message}"}], error: true)
+          text = format_search_results(
+            results,
+            query: query,
+            type_label: "enum(s)",
+            limit: limit,
+            details_tip: DETAILS_TIP,
+            filter_suggestion: "To find more results, narrow your search with a `category` filter."
+          )
+          text_response(text)
         end
       end
     end

data/lib/cf/mcp/tools/search_functions.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
 require "mcp"
+require_relative "response_helpers"
+require_relative "search_result_formatter"
 
 module CF
   module MCP
     module Tools
       class SearchFunctions < ::MCP::Tool
+        extend ResponseHelpers
+        extend SearchResultFormatter
+
         tool_name "cf_search_functions"
         description "Search Cute Framework functions"
 
@@ -27,29 +32,15 @@ module CF
 
           results = index.search(query, type: :function, category: category, limit: limit)
 
-          if results.empty?
-            text_response("No functions found for '#{query}'")
-          else
-            formatted = results.map(&:to_summary).join("\n")
-            header = if results.size >= limit
-              "Found #{results.size} function(s) (limit reached, more may exist):"
-            else
-              "Found #{results.size} function(s):"
-            end
-
-            footer = "\n\n#{DETAILS_TIP}"
-            footer += "\nTo find more results, narrow your search with a `category` filter." if results.size >= limit
-
-            text_response("#{header}\n\n#{formatted}#{footer}")
-          end
-        end
-
-        def self.text_response(text)
-          ::MCP::Tool::Response.new([{type: "text", text: text}])
-        end
-
-        def self.error_response(message)
-          ::MCP::Tool::Response.new([{type: "text", text: "Error: #{message}"}], error: true)
+          text = format_search_results(
+            results,
+            query: query,
+            type_label: "function(s)",
+            limit: limit,
+            details_tip: DETAILS_TIP,
+            filter_suggestion: "To find more results, narrow your search with a `category` filter."
+          )
+          text_response(text)
         end
       end
     end

data/lib/cf/mcp/tools/search_result_formatter.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CF
+  module MCP
+    module Tools
+      module SearchResultFormatter
+        def format_search_results(results, query:, type_label:, limit:, details_tip:, filter_suggestion: nil)
+          if results.empty?
+            # Use plural form for "no results" message (e.g., "No functions found")
+            plural_label = type_label.sub(/\(s\)$/, "s")
+            return "No #{plural_label} found for '#{query}'"
+          end
+
+          formatted = results.map(&:to_summary).join("\n")
+
+          header = if results.size >= limit
+            "Found #{results.size} #{type_label} (limit reached, more may exist):"
+          else
+            "Found #{results.size} #{type_label}:"
+          end
+
+          footer = "\n\n#{details_tip}"
+          footer += "\n#{filter_suggestion}" if results.size >= limit && filter_suggestion
+
+          "#{header}\n\n#{formatted}#{footer}"
+        end
+      end
+    end
+  end
+end

data/lib/cf/mcp/tools/search_structs.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
 require "mcp"
+require_relative "response_helpers"
+require_relative "search_result_formatter"
 
 module CF
   module MCP
     module Tools
       class SearchStructs < ::MCP::Tool
+        extend ResponseHelpers
+        extend SearchResultFormatter
+
         tool_name "cf_search_structs"
         description "Search Cute Framework structs"
 
@@ -27,29 +32,15 @@ module CF
 
           results = index.search(query, type: :struct, category: category, limit: limit)
 
-          if results.empty?
-            text_response("No structs found for '#{query}'")
-          else
-            formatted = results.map(&:to_summary).join("\n")
-            header = if results.size >= limit
-              "Found #{results.size} struct(s) (limit reached, more may exist):"
-            else
-              "Found #{results.size} struct(s):"
-            end
-
-            footer = "\n\n#{DETAILS_TIP}"
-            footer += "\nTo find more results, narrow your search with a `category` filter." if results.size >= limit
-
-            text_response("#{header}\n\n#{formatted}#{footer}")
-          end
-        end
-
-        def self.text_response(text)
-          ::MCP::Tool::Response.new([{type: "text", text: text}])
-        end
-
-        def self.error_response(message)
-          ::MCP::Tool::Response.new([{type: "text", text: "Error: #{message}"}], error: true)
+          text = format_search_results(
+            results,
+            query: query,
+            type_label: "struct(s)",
+            limit: limit,
+            details_tip: DETAILS_TIP,
+            filter_suggestion: "To find more results, narrow your search with a `category` filter."
+          )
+          text_response(text)
         end
       end
     end

data/lib/cf/mcp/tools/search_tool.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
 require "mcp"
+require_relative "response_helpers"
+require_relative "search_result_formatter"
 
 module CF
   module MCP
     module Tools
       class SearchTool < ::MCP::Tool
+        extend ResponseHelpers
+        extend SearchResultFormatter
+
         tool_name "cf_search"
         description "Search Cute Framework documentation across all types (functions, structs, enums, topics)"
 
@@ -28,29 +33,15 @@ module CF
 
           results = index.search(query, type: type, category: category, limit: limit)
 
-          if results.empty?
-            text_response("No results found for '#{query}'")
-          else
-            formatted = results.map(&:to_summary).join("\n")
-            header = if results.size >= limit
-              "Found #{results.size} result(s) (limit reached, more may exist):"
-            else
-              "Found #{results.size} result(s):"
-            end
-
-            footer = "\n\n#{DETAILS_TIP}"
-            footer += "\nTo find more results, narrow your search with `type` or `category` filters." if results.size >= limit
-
-            text_response("#{header}\n\n#{formatted}#{footer}")
-          end
-        end
-
-        def self.text_response(text)
-          ::MCP::Tool::Response.new([{type: "text", text: text}])
-        end
-
-        def self.error_response(message)
-          ::MCP::Tool::Response.new([{type: "text", text: "Error: #{message}"}], error: true)
+          text = format_search_results(
+            results,
+            query: query,
+            type_label: "result(s)",
+            limit: limit,
+            details_tip: DETAILS_TIP,
+            filter_suggestion: "To find more results, narrow your search with `type` or `category` filters."
+          )
+          text_response(text)
         end
       end
     end

data/lib/cf/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module CF
   module MCP
-    VERSION = "0.12.0"
+    VERSION = "0.12.1"
   end
 end

data/lib/cf/mcp.rb

@@ -8,6 +8,7 @@ require_relative "mcp/models/struct_doc"
 require_relative "mcp/models/enum_doc"
 require_relative "mcp/parser"
 require_relative "mcp/index"
+require_relative "mcp/index_builder"
 require_relative "mcp/server"
 require_relative "mcp/downloader"
 require_relative "mcp/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cf-mcp
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.12.1
 platform: ruby
 authors:
 - Piotr Usewicz
@@ -99,6 +99,7 @@ files:
 - lib/cf/mcp/cli.rb
 - lib/cf/mcp/downloader.rb
 - lib/cf/mcp/index.rb
+- lib/cf/mcp/index_builder.rb
 - lib/cf/mcp/models/doc_item.rb
 - lib/cf/mcp/models/enum_doc.rb
 - lib/cf/mcp/models/function_doc.rb
@@ -116,8 +117,10 @@ files:
 - lib/cf/mcp/tools/list_topics.rb
 - lib/cf/mcp/tools/member_search.rb
 - lib/cf/mcp/tools/parameter_search.rb
+- lib/cf/mcp/tools/response_helpers.rb
 - lib/cf/mcp/tools/search_enums.rb
 - lib/cf/mcp/tools/search_functions.rb
+- lib/cf/mcp/tools/search_result_formatter.rb
 - lib/cf/mcp/tools/search_structs.rb
 - lib/cf/mcp/tools/search_tool.rb
 - lib/cf/mcp/topic_parser.rb