cf-mcp 0.19.0 → 0.21.0

data/lib/cf/mcp/templates/script.js

@@ -8,6 +8,8 @@ const TOOLS = TOOL_SCHEMAS_PLACEHOLDER;
 const CATEGORIES = CATEGORIES_PLACEHOLDER;
 const TOPICS = TOPICS_PLACEHOLDER;
 const CHANGELOG = CHANGELOG_PLACEHOLDER;
+const PROTOCOL_VERSION = PROTOCOL_VERSION_PLACEHOLDER;
+const CLIENT_VERSION = CLIENT_VERSION_PLACEHOLDER;
 
 // Helper to render topic options (used in multiple places)
 const renderTopicOptions = () =>
@@ -38,13 +40,24 @@ function useMcpToolCall() {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
-          'Accept': 'application/json, text/event-stream'
+          'Accept': 'application/json, text/event-stream',
+          'MCP-Protocol-Version': PROTOCOL_VERSION,
+          'Mcp-Method': 'tools/call',
+          'Mcp-Name': toolName
         },
         body: JSON.stringify({
           jsonrpc: '2.0',
           id: Date.now(),
           method: 'tools/call',
-          params: { name: toolName, arguments: args }
+          params: {
+            name: toolName,
+            arguments: args,
+            _meta: {
+              'io.modelcontextprotocol/protocolVersion': PROTOCOL_VERSION,
+              'io.modelcontextprotocol/clientCapabilities': {},
+              'io.modelcontextprotocol/clientInfo': { name: 'cf-mcp-dashboard', version: CLIENT_VERSION }
+            }
+          }
         })
       });
 

data/lib/cf/mcp/tool_command.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module CF
+  module MCP
+    # Runs an MCP tool as a command, mapping its input schema onto the command
+    # line: required properties are positional arguments, the rest are flags.
+    class ToolCommand
+      Property = Data.define(:name, :type, :description, :values)
+
+      def initialize(tool)
+        @tool = tool
+        schema = tool.input_schema.to_h
+        required = schema.fetch(:required, []).map(&:to_sym)
+        properties = schema.fetch(:properties).map do |name, spec|
+          Property.new(name: name, type: spec[:type], description: spec[:description].to_s, values: spec[:enum])
+        end
+        @required, @flags = properties.partition { |property| required.include?(property.name) }
+        # A tool that requires nothing still takes its first property as an optional argument.
+        @arguments = @required.empty? ? properties.first(1) : @required
+        @parser = build_parser
+      end
+
+      # Returns the process exit status.
+      def run(args)
+        flags = {} #: Hash[Symbol, untyped]
+        positionals = @parser.parse(args, into: flags)
+        return print_help if flags.key?(:help)
+
+        respond(call_tool(bind(positionals).merge(flags)))
+      end
+
+      private
+
+      def build_parser
+        OptionParser.new do |opts|
+          opts.banner = ["Usage: cf-mcp", @tool.tool_name, *@arguments.map { |argument| usage(argument) }, "[options]"].join(" ")
+          opts.separator ""
+          opts.separator @tool.description.to_s
+          unless @arguments.empty?
+            opts.separator ""
+            opts.separator "Arguments:"
+            @arguments.each { |argument| opts.separator "    #{placeholder(argument).ljust(32)}#{argument.description}" }
+          end
+          opts.separator ""
+          opts.separator "Options:"
+          @flags.each { |flag| define_flag(opts, flag) }
+          opts.on("-h", "--help", "Show this help message")
+        end
+      end
+
+      def define_flag(opts, flag)
+        switch = "--#{flag.name} #{placeholder(flag)}"
+        if (values = flag.values)
+          opts.on(switch, values, "#{flag.description} [#{values.join("|")}]")
+        elsif flag.type == "integer"
+          opts.on(switch, Integer, flag.description)
+        elsif flag.type == "boolean"
+          opts.on("--[no-]#{flag.name}", flag.description)
+        else
+          opts.on(switch, flag.description)
+        end
+      end
+
+      def placeholder(property)
+        property.name.to_s.upcase
+      end
+
+      # How an argument reads in the usage line: optional ones are bracketed.
+      def usage(argument)
+        @required.include?(argument) ? placeholder(argument) : "[#{placeholder(argument)}]"
+      end
+
+      def bind(positionals)
+        if positionals.size < @required.size
+          raise OptionParser::MissingArgument, placeholder(@required.fetch(positionals.size))
+        end
+        if positionals.size > @arguments.size
+          raise OptionParser::NeedlessArgument, positionals.drop(@arguments.size).join(" ")
+        end
+
+        @arguments.first(positionals.size).map(&:name).zip(positionals).to_h
+      end
+
+      def call_tool(arguments)
+        # `MCP::Tool.call` is deliberately undeclared (see sig-stubs/mcp.rbs), so it is sent.
+        @tool.public_send(:call, **arguments) #: ::MCP::Tool::Response
+      end
+
+      def respond(response)
+        text = response.content.filter_map { |item| item[:text] }.join("\n")
+        if response.error?
+          warn text
+          1
+        else
+          puts text
+          0
+        end
+      end
+
+      def print_help
+        puts @parser
+        0
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module CF
+  module MCP
+    module Tools
+      # For a tool whose `category` property takes the index's categories. They are
+      # read when the schema is asked for, not when the class loads, so a tool can
+      # be loaded before the index is filled. The property stays open while the
+      # index is empty, as a JSON Schema enum needs at least one value.
+      module CategoryEnum
+        def input_schema_value
+          categories = Index.instance.categories
+          return super if categories.empty?
+
+          @category_schemas ||= {} #: Hash[Array[String], ::MCP::Tool::InputSchema]
+          @category_schemas[categories] ||= with_categories(super.to_h, categories)
+        end
+
+        private
+
+        def with_categories(schema, categories)
+          properties = schema.fetch(:properties)
+          category = properties.fetch(:category).merge(enum: categories)
+          ::MCP::Tool::InputSchema.new(schema.merge(properties: properties.merge(category: category)))
+        end
+      end
+    end
+  end
+end

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

@@ -9,7 +9,10 @@ module CF
       class FindRelated < ::MCP::Tool
         extend ResponseHelpers
 
+        TITLE = "Find Related"
+
         tool_name "find_related"
+        title TITLE
         description "Find all items related to a given Cute Framework item (bidirectional relationship search)"
 
         input_schema(
@@ -21,6 +24,7 @@ module CF
         )
 
         annotations(
+          title: TITLE,
           read_only_hint: true,
           destructive_hint: false,
           idempotent_hint: true,
@@ -44,12 +48,11 @@ module CF
           }
 
           # Back references: items that reference this item
-          back_refs = []
-          index.items.each_value do |other_item|
+          back_refs = index.items.each_value.filter_map do |other_item|
             next if other_item.name == name
             next unless other_item.related&.include?(name)
 
-            back_refs << "- `#{other_item.name}` (#{other_item.type}) — #{other_item.brief}"
+            "- `#{other_item.name}` (#{other_item.type}) — #{other_item.brief}"
           end
 
           if forward_refs.empty? && back_refs.empty?

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

@@ -9,7 +9,10 @@ module CF
       class GetDetails < ::MCP::Tool
         extend ResponseHelpers
 
+        TITLE = "Get Details"
+
         tool_name "get_details"
+        title TITLE
         description "Get detailed documentation for a specific Cute Framework item by exact name"
 
         input_schema(
@@ -21,6 +24,7 @@ module CF
         )
 
         annotations(
+          title: TITLE,
           read_only_hint: true,
           destructive_hint: false,
           idempotent_hint: true,

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

@@ -9,7 +9,10 @@ module CF
       class GetTopic < ::MCP::Tool
         extend ResponseHelpers
 
+        TITLE = "Get Topic"
+
         tool_name "get_topic"
+        title TITLE
         description "Get the full content of a Cute Framework topic guide document"
 
         input_schema(
@@ -21,6 +24,7 @@ module CF
         )
 
         annotations(
+          title: TITLE,
           read_only_hint: true,
           destructive_hint: false,
           idempotent_hint: true,

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

@@ -1,26 +1,32 @@
 # frozen_string_literal: true
 
 require "mcp"
+require_relative "category_enum"
 require_relative "response_helpers"
 
 module CF
   module MCP
     module Tools
       class ListCategory < ::MCP::Tool
+        extend CategoryEnum
         extend ResponseHelpers
 
+        TITLE = "List Category"
+
         tool_name "list_category"
+        title TITLE
         description "List all items in a specific category, or list all available categories"
 
         input_schema(
           type: "object",
           properties: {
-            category: {type: "string", enum: Index.instance.categories, description: "Category name. Leave empty to list all categories."},
+            category: {type: "string", description: "Category name. Leave empty to list all categories."},
             type: {type: "string", enum: ["function", "struct", "enum"], description: "Optional: filter by item type"}
           }
         )
 
         annotations(
+          title: TITLE,
           read_only_hint: true,
           destructive_hint: false,
           idempotent_hint: true,

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

@@ -9,7 +9,10 @@ module CF
       class ListTopics < ::MCP::Tool
         extend ResponseHelpers
 
+        TITLE = "List Topics"
+
         tool_name "list_topics"
+        title TITLE
         description "List all Cute Framework topic guides, optionally filtered by category or in recommended reading order"
 
         input_schema(
@@ -21,6 +24,7 @@ module CF
         )
 
         annotations(
+          title: TITLE,
           read_only_hint: true,
           destructive_hint: false,
           idempotent_hint: true,

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

@@ -9,7 +9,13 @@ module CF
       class MemberSearch < ::MCP::Tool
         extend ResponseHelpers
 
+        TITLE = "Member Search"
+
+        # A struct together with the members that matched the query.
+        Match = Data.define(:struct, :members)
+
         tool_name "member_search"
+        title TITLE
         description "Search Cute Framework structs by member name or type"
 
         input_schema(
@@ -22,6 +28,7 @@ module CF
         )
 
         annotations(
+          title: TITLE,
           read_only_hint: true,
           destructive_hint: false,
           idempotent_hint: true,
@@ -32,20 +39,11 @@ module CF
           index = Index.instance
 
           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
+          # A limit below 1 still returns the first match.
+          results = index.structs.lazy.filter_map { |struct|
+            matching_members = struct.members.select { |member| member.declaration.match?(pattern) }
+            Match.new(struct, matching_members) unless matching_members.empty?
+          }.first([limit, 1].max)
 
           if results.empty?
             return text_response("No structs found with members matching '#{query}'")
@@ -54,9 +52,9 @@ module CF
           lines = ["# Structs with members matching '#{query}'", ""]
 
           results.each do |result|
-            struct = result[:struct]
+            struct = result.struct
             lines << "- **#{struct.name}** (#{struct.category}) — #{struct.brief}"
-            result[:members].each do |member|
+            result.members.each do |member|
               lines << "  - `#{member.declaration}` — #{member.description}"
             end
             lines << ""

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

@@ -9,7 +9,10 @@ module CF
       class ParameterSearch < ::MCP::Tool
         extend ResponseHelpers
 
+        TITLE = "Parameter Search"
+
         tool_name "parameter_search"
+        title TITLE
         description "Find Cute Framework functions by parameter or return type"
 
         input_schema(
@@ -26,6 +29,7 @@ module CF
         )
 
         annotations(
+          title: TITLE,
           read_only_hint: true,
           destructive_hint: false,
           idempotent_hint: true,
@@ -36,38 +40,27 @@ module CF
           index = Index.instance
 
           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
+          functions = index.functions.select(&:signature)
 
-            # 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
+          # Check return type (text before function name in signature)
+          output_matches = functions.select { |func|
+            next false if direction == "input"
+
+            # Extract return type: everything before the function name
+            next false unless func.signature =~ /^(.+?)\s+#{Regexp.escape(func.name)}\s*\(/
+
+            ::Regexp.last_match(1).to_s.strip.match?(pattern)
+          }.uniq
+
+          # Check input parameters
+          input_matches = functions.select { |func|
+            next false if direction == "output"
+
+            # Check the signature for parameter types
+            next false unless func.signature =~ /\(([^)]*)\)/
 
-          # Remove duplicates between input and output
-          input_matches.uniq!
-          output_matches.uniq!
+            ::Regexp.last_match(1).to_s.match?(pattern)
+          }.uniq
 
           if input_matches.empty? && output_matches.empty?
             return text_response("No functions found using type '#{type}'")

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "mcp"
+require_relative "category_enum"
 require_relative "response_helpers"
 require_relative "search_result_formatter"
 
@@ -8,10 +9,14 @@ module CF
   module MCP
     module Tools
       class SearchTool < ::MCP::Tool
+        extend CategoryEnum
         extend ResponseHelpers
         extend SearchResultFormatter
 
+        TITLE = "Search"
+
         tool_name "search"
+        title TITLE
         description "Search Cute Framework documentation across all types (functions, structs, enums, topics)"
 
         input_schema(
@@ -19,13 +24,14 @@ module CF
           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", enum: Index.instance.categories, description: "Optional: filter by category"},
+            category: {type: "string", description: "Optional: filter by category"},
             limit: {type: "integer", description: "Maximum number of results to return (default: 20)"}
           },
           required: ["query"]
         )
 
         annotations(
+          title: TITLE,
           read_only_hint: true,
           destructive_hint: false,
           idempotent_hint: true,

data/lib/cf/mcp/topic_parser.rb

@@ -22,36 +22,28 @@ module CF
       end
 
       def parse_directory(path)
-        topics = []
         reading_order = parse_reading_order(File.join(path, "index.md"))
 
-        Dir.glob(File.join(path, "*.md")).each do |topic_file|
+        Dir.glob(File.join(path, "*.md")).filter_map do |topic_file|
           next if File.basename(topic_file) == "index.md"
 
           topic = parse_file(topic_file)
-          if topic
-            topic.reading_order = reading_order[topic.name]
-            topics << topic
-          end
-        end
+          next unless topic
 
-        topics
+          topic.reading_order = reading_order[topic.name]
+          topic
+        end
       end
 
       def parse_reading_order(index_path)
         return {} unless File.exist?(index_path)
 
         content = File.read(index_path)
-        order = {}
-        position = 0
 
-        # Match numbered list items with topic links
-        content.scan(/^\d+\.\s+\[([^\]]+)\]\(\.\/(\w+)\.md\)/) do |_title, slug|
-          order[slug] = position
-          position += 1
+        # Match numbered list items with topic links; a repeated slug keeps its last position
+        content.scan(/^\d+\.\s+\[([^\]]+)\]\(\.\/(\w+)\.md\)/).each_with_index.to_h do |(_title, slug), position|
+          [slug, position]
         end
-
-        order
       end
 
       private
@@ -85,81 +77,42 @@ module CF
       end
 
       def extract_brief(content)
-        lines = content.lines
-        in_paragraph = false
-        paragraph_lines = []
-
-        lines.each do |line|
-          next if line.start_with?("#")
-
-          if line.strip.empty?
-            break if in_paragraph
-            next
-          end
-
-          in_paragraph = true
-          paragraph_lines << line.strip
-        end
+        # The first paragraph that isn't a heading
+        paragraph_lines = content.lines
+          .reject { |line| line.start_with?("#") }
+          .drop_while { |line| line.strip.empty? }
+          .take_while { |line| !line.strip.empty? }
+          .map(&:strip)
 
         # Strip markdown links but keep the text
         paragraph_lines.join(" ").gsub(/\[([^\]]+)\]\([^)]+\)/, '\1')
       end
 
       def extract_sections(content)
-        sections = []
-        current_title = nil
-        current_content = []
-
-        content.lines.each do |line|
-          if line =~ SECTION_PATTERN
-            if current_title
-              sections << Models::TopicDoc::Section.new(
-                title: current_title,
-                content: current_content.join
-              )
-            end
-            current_title = ::Regexp.last_match(1).strip
-            current_content = []
-          elsif current_title
-            current_content << line
-          end
+        # A section starts on a "## Title" heading and runs until the next one.
+        # Text before the first heading belongs to no section.
+        content.lines.slice_before { |line| SECTION_PATTERN.match?(line) }.filter_map do |section_lines|
+          heading = section_lines.fetch(0)
+          title = heading[SECTION_PATTERN, 1]
+          next unless title
+
+          Models::TopicDoc::Section.new(title: title.strip, content: section_lines.drop(1).join)
         end
-
-        # Add last section
-        if current_title
-          sections << Models::TopicDoc::Section.new(
-            title: current_title,
-            content: current_content.join
-          )
-        end
-
-        sections
       end
 
       def extract_api_references(content)
-        func_refs = []
-        struct_refs = []
-        enum_refs = []
-
-        content.scan(API_LINK_PATTERN) do |_text, _category, name|
-          if name.start_with?("cf_")
-            func_refs << name
-          elsif name.start_with?("CF_") || name.match?(/^[A-Z]/)
-            # Uppercase names are likely structs or enums
-            # Will be refined when cross-referenced with index
-            struct_refs << name
-          end
-        end
+        names = content.scan(API_LINK_PATTERN).map { |_text, _category, name| name }
+
+        func_refs, other_refs = names.partition { |name| name.start_with?("cf_") }
+        # Uppercase names are likely structs or enums
+        # Will be refined when cross-referenced with index
+        struct_refs = other_refs.select { |name| name.start_with?("CF_") || name.match?(/^[A-Z]/) }
 
-        [func_refs, struct_refs, enum_refs]
+        [func_refs, struct_refs, []]
       end
 
       def extract_topic_references(content)
-        refs = []
-        content.scan(TOPIC_LINK_PATTERN) do |_text, slug|
-          refs << slug
-        end
-        refs
+        content.scan(TOPIC_LINK_PATTERN).map { |_text, slug| slug }
       end
 
       def derive_category(slug)

data/lib/cf/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module CF
   module MCP
-    VERSION = "0.19.0"
+    VERSION = "0.21.0"
   end
 end

data/lib/cf/mcp.rb

@@ -10,7 +10,9 @@ module CF
     autoload :Parser, "cf/mcp/parser"
     autoload :Index, "cf/mcp/index"
     autoload :IndexBuilder, "cf/mcp/index_builder"
+    autoload :IndexCache, "cf/mcp/index_cache"
     autoload :TopicParser, "cf/mcp/topic_parser"
+    autoload :ToolCommand, "cf/mcp/tool_command"
     autoload :Server, "cf/mcp/server"
     autoload :Downloader, "cf/mcp/downloader"
     autoload :GitHubClient, "cf/mcp/github_client"
@@ -37,6 +39,13 @@ module CF
       autoload :MemberSearch, "cf/mcp/tools/member_search"
       autoload :ListTopics, "cf/mcp/tools/list_topics"
       autoload :GetTopic, "cf/mcp/tools/get_topic"
+
+      # A method, not a constant: naming a tool loads it, and SearchTool and
+      # ListCategory read the index's categories when loaded, so callers must
+      # fill the index before asking.
+      def self.all
+        [SearchTool, ListCategory, GetDetails, FindRelated, ParameterSearch, MemberSearch, ListTopics, GetTopic]
+      end
     end
   end
 end