cf-mcp 0.9.2

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module CF
+  module MCP
+    module Tools
+      class ListCategory < ::MCP::Tool
+        tool_name "cf_list_category"
+        description "List all items in a specific category, or list all available categories"
+
+        input_schema(
+          type: "object",
+          properties: {
+            category: {type: "string", description: "Category name (e.g., 'app', 'sprite', 'graphics'). Leave empty to list all categories."},
+            type: {type: "string", enum: ["function", "struct", "enum"], description: "Optional: filter by item type"}
+          }
+        )
+
+        def self.call(category: nil, type: nil, server_context: {})
+          index = server_context[:index]
+          return error_response("Index not available") unless index
+
+          if category.nil? || category.empty?
+            # List all categories with counts by type
+            categories = index.categories
+            if categories.empty?
+              text_response("No categories found")
+            else
+              formatted = categories.map do |cat|
+                items = index.items_in_category(cat)
+                counts = items.group_by(&:type).transform_values(&:size)
+                type_breakdown = [:function, :struct, :enum]
+                  .filter_map { |t| "#{counts[t]} #{t}s" if counts[t]&.positive? }
+                  .join(", ")
+                "- **#{cat}** — #{items.size} items (#{type_breakdown})"
+              end.join("\n")
+              text_response("Available categories:\n\n#{formatted}\n\n**Tip:** Use `cf_list_category` with a category name to see all items in that category.")
+            end
+          else
+            # List items in the specified category
+            items = index.items_in_category(category)
+
+            if type
+              type_sym = type.to_sym
+              items = items.select { |item| item.type == type_sym }
+            end
+
+            if items.empty?
+              text_response("No items found in category '#{category}'#{" of type #{type}" if type}")
+            else
+              formatted = items.map(&:to_summary).join("\n")
+
+              # Suggest related topics
+              related_topics = index.topics.select { |t| t.category == category }
+              topic_suggestion = if related_topics.any?
+                "\n\n**Related Topics:**\n" + related_topics.map { |t| "- **#{t.name}** — #{t.brief}" }.join("\n")
+              else
+                ""
+              end
+
+              text_response("Items in '#{category}':\n\n#{formatted}#{topic_suggestion}\n\n**Tip:** Use `cf_get_details` with an exact name to get full documentation.")
+            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
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module CF
+  module MCP
+    module Tools
+      class ListTopics < ::MCP::Tool
+        tool_name "cf_list_topics"
+        description "List all Cute Framework topic guides, optionally filtered by category or in recommended reading order"
+
+        input_schema(
+          type: "object",
+          properties: {
+            category: {type: "string", description: "Optional: filter topics by category (e.g., 'audio', 'draw', 'graphics')"},
+            ordered: {type: "boolean", description: "If true, return topics in recommended reading order (default: false)"}
+          }
+        )
+
+        def self.call(category: nil, ordered: false, server_context: {})
+          index = server_context[:index]
+          return error_response("Index not available") unless index
+
+          topics = ordered ? index.topics_ordered : index.topics
+
+          if category
+            topics = topics.select { |t| t.category == category }
+          end
+
+          if topics.empty?
+            return text_response("No topics found#{" in category '#{category}'" if category}\n\n#{CATEGORY_TIP}")
+          end
+
+          lines = ["# Cute Framework Topics", ""]
+
+          if ordered
+            lines << "_Listed in recommended reading order_"
+            lines << ""
+          end
+
+          topics.each_with_index do |topic, i|
+            prefix = (ordered && topic.reading_order) ? "#{i + 1}. " : "- "
+            lines << "#{prefix}**#{topic.name}** — #{topic.brief}"
+          end
+
+          lines << ""
+          lines << "**Tip:** Use `cf_get_topic` with a topic name to read the full content."
+
+          text_response(lines.join("\n"))
+        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
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module CF
+  module MCP
+    module Tools
+      class MemberSearch < ::MCP::Tool
+        tool_name "cf_member_search"
+        description "Search Cute Framework structs by member name or type"
+
+        input_schema(
+          type: "object",
+          properties: {
+            query: {type: "string", description: "Search query (matches member name or type in declaration)"},
+            limit: {type: "integer", description: "Maximum number of results to return (default: 20)"}
+          },
+          required: ["query"]
+        )
+
+        def self.call(query:, limit: 20, server_context: {})
+          index = server_context[:index]
+          return error_response("Index not available") unless index
+
+          pattern = Regexp.new(Regexp.escape(query), Regexp::IGNORECASE)
+          results = []
+
+          index.structs.each do |struct|
+            next unless struct.members&.any?
+
+            matching_members = struct.members.select { |member|
+              member.declaration&.match?(pattern)
+            }
+
+            next if matching_members.empty?
+
+            results << {struct: struct, members: matching_members}
+            break if results.size >= limit
+          end
+
+          if results.empty?
+            return text_response("No structs found with members matching '#{query}'")
+          end
+
+          lines = ["# Structs with members matching '#{query}'", ""]
+
+          results.each do |result|
+            struct = result[:struct]
+            lines << "- **#{struct.name}** (#{struct.category}) — #{struct.brief}"
+            result[:members].each do |member|
+              lines << "  - `#{member.declaration}` — #{member.description}"
+            end
+            lines << ""
+          end
+
+          if results.size >= limit
+            lines << "_Results limited to #{limit}. Narrow your search for more specific results._"
+            lines << ""
+          end
+
+          lines << "**Tip:** Use `cf_get_details` with a struct name for full documentation."
+
+          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
+end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module CF
+  module MCP
+    module Tools
+      class ParameterSearch < ::MCP::Tool
+        tool_name "cf_parameter_search"
+        description "Find Cute Framework functions by parameter or return type"
+
+        input_schema(
+          type: "object",
+          properties: {
+            type: {type: "string", description: "Type name to search for (e.g., 'CF_Sprite', 'const char*', 'int')"},
+            direction: {
+              type: "string",
+              enum: ["input", "output", "both"],
+              description: "Search direction: 'input' for parameters, 'output' for return types, 'both' for either (default: both)"
+            }
+          },
+          required: ["type"]
+        )
+
+        def self.call(type:, direction: "both", server_context: {})
+          index = server_context[:index]
+          return error_response("Index not available") unless index
+
+          pattern = Regexp.new(Regexp.escape(type), Regexp::IGNORECASE)
+          input_matches = []
+          output_matches = []
+
+          index.functions.each do |func|
+            next unless func.signature
+
+            # Check return type (text before function name in signature)
+            if direction != "input"
+              # Extract return type: everything before the function name
+              if func.signature =~ /^(.+?)\s+#{Regexp.escape(func.name)}\s*\(/
+                return_type = ::Regexp.last_match(1).strip
+                if return_type.match?(pattern)
+                  output_matches << func
+                end
+              end
+            end
+
+            # Check input parameters
+            if direction != "output"
+              # Check the signature for parameter types
+              if func.signature =~ /\(([^)]*)\)/
+                params_str = ::Regexp.last_match(1)
+                if params_str.match?(pattern)
+                  input_matches << func unless input_matches.include?(func)
+                end
+              end
+            end
+          end
+
+          # Remove duplicates between input and output
+          input_matches.uniq!
+          output_matches.uniq!
+
+          if input_matches.empty? && output_matches.empty?
+            return text_response("No functions found using type '#{type}'")
+          end
+
+          lines = ["# Functions using '#{type}'", ""]
+
+          unless input_matches.empty?
+            lines << "## Takes as input (#{input_matches.size})"
+            input_matches.each do |func|
+              lines << "- **#{func.name}** — #{func.brief}"
+              lines << "  `#{func.signature}`" if func.signature
+            end
+            lines << ""
+          end
+
+          unless output_matches.empty?
+            lines << "## Returns (#{output_matches.size})"
+            output_matches.each do |func|
+              lines << "- **#{func.name}** — #{func.brief}"
+              lines << "  `#{func.signature}`" if func.signature
+            end
+            lines << ""
+          end
+
+          lines << "**Tip:** Use `cf_get_details` with a function name for full documentation."
+
+          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
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module CF
+  module MCP
+    module Tools
+      class SearchEnums < ::MCP::Tool
+        tool_name "cf_search_enums"
+        description "Search Cute Framework enums"
+
+        input_schema(
+          type: "object",
+          properties: {
+            query: {type: "string", description: "Search query"},
+            category: {type: "string", description: "Optional: filter by category"},
+            limit: {type: "integer", description: "Maximum results (default: 20)"}
+          },
+          required: ["query"]
+        )
+
+        DETAILS_TIP = "**Tip:** Use `cf_get_details` with an exact name to get full documentation including values and examples."
+
+        def self.call(query:, category: nil, limit: 20, server_context: {})
+          index = server_context[:index]
+          return error_response("Index not available") unless index
+
+          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)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module CF
+  module MCP
+    module Tools
+      class SearchFunctions < ::MCP::Tool
+        tool_name "cf_search_functions"
+        description "Search Cute Framework functions"
+
+        input_schema(
+          type: "object",
+          properties: {
+            query: {type: "string", description: "Search query"},
+            category: {type: "string", description: "Optional: filter by category"},
+            limit: {type: "integer", description: "Maximum results (default: 20)"}
+          },
+          required: ["query"]
+        )
+
+        DETAILS_TIP = "**Tip:** Use `cf_get_details` with an exact name to get full documentation including signature, parameters, and examples."
+
+        def self.call(query:, category: nil, limit: 20, server_context: {})
+          index = server_context[:index]
+          return error_response("Index not available") unless index
+
+          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)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module CF
+  module MCP
+    module Tools
+      class SearchStructs < ::MCP::Tool
+        tool_name "cf_search_structs"
+        description "Search Cute Framework structs"
+
+        input_schema(
+          type: "object",
+          properties: {
+            query: {type: "string", description: "Search query"},
+            category: {type: "string", description: "Optional: filter by category"},
+            limit: {type: "integer", description: "Maximum results (default: 20)"}
+          },
+          required: ["query"]
+        )
+
+        DETAILS_TIP = "**Tip:** Use `cf_get_details` with an exact name to get full documentation including members and examples."
+
+        def self.call(query:, category: nil, limit: 20, server_context: {})
+          index = server_context[:index]
+          return error_response("Index not available") unless index
+
+          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)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module CF
+  module MCP
+    module Tools
+      class SearchTool < ::MCP::Tool
+        tool_name "cf_search"
+        description "Search Cute Framework documentation across all types (functions, structs, enums, topics)"
+
+        input_schema(
+          type: "object",
+          properties: {
+            query: {type: "string", description: "Search query (searches in name, description, and remarks)"},
+            type: {type: "string", enum: ["function", "struct", "enum", "topic"], description: "Optional: filter by item type"},
+            category: {type: "string", description: "Optional: filter by category (e.g., 'app', 'sprite', 'graphics')"},
+            limit: {type: "integer", description: "Maximum number of results to return (default: 20)"}
+          },
+          required: ["query"]
+        )
+
+        DETAILS_TIP = "**Tip:** Use `cf_get_details` for API items or `cf_get_topic` for topic guides to get full documentation."
+
+        def self.call(query:, type: nil, category: nil, limit: 20, server_context: {})
+          index = server_context[:index]
+          return error_response("Index not available") unless index
+
+          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)
+        end
+      end
+    end
+  end
+end