cf-mcp 0.19.0 → 0.21.0

data/lib/cf/mcp/index_cache.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "tempfile"
+
+module CF
+  module MCP
+    # Keeps the parsed index on disk so a command need not reparse every header.
+    #
+    # There is one cache file per source, so projects on different Cute Framework
+    # versions do not evict each other. Each records where it was built from, so
+    # a lookup needs no path resolution (or download) of its own, and rebuilds
+    # when any header or topic file changes. The last source used is remembered
+    # for commands that name none.
+    class IndexCache
+      FORMAT = 1
+      DEFAULT_SOURCE = {root: nil, download: false} #: source
+
+      Payload = Data.define(:format, :gem_version, :headers_path, :topics_path,
+        :fingerprint, :revision, :items)
+
+      def self.default_dir
+        ENV["CF_MCP_CACHE_DIR"] || File.join(ENV["XDG_CACHE_HOME"] || File.expand_path("~/.cache"), "cf-mcp")
+      end
+
+      # The cache file used by the last #index or #refresh, and the checkout it came from.
+      attr_reader :path, :revision
+
+      def initialize(dir: self.class.default_dir)
+        @dir = dir
+      end
+
+      def path_for(source)
+        File.join(@dir, "index-#{Digest::SHA256.hexdigest("#{source[:root]}\n#{source[:download]}")[0, 12]}.bin")
+      end
+
+      # Loads the cached index if it is fresh, otherwise builds and stores it.
+      # `source` names what to build from; nil means the last one used.
+      # The block receives the source to build from and returns an IndexBuilder.
+      def index(source = nil, &builder_for)
+        check_dir!
+        source ||= current_source
+        payload = load_payload(path_for(source))
+        return hydrate(source, payload) if payload && fresh?(payload)
+
+        warn "Index #{payload ? "is stale" : "not found"}, rebuilding..."
+        rebuild(source, &builder_for)
+      end
+
+      # Rebuilds and stores the index, whether or not the cache is fresh.
+      def refresh(source = nil, &builder_for)
+        check_dir!
+        rebuild(source || current_source, &builder_for)
+      end
+
+      private
+
+      # Cache files are read back with Marshal, which can run code, so they are only
+      # trusted in a directory no other user could have put a file in.
+      def check_dir!
+        return unless File.directory?(@dir)
+
+        stat = File.stat(@dir)
+        return if stat.uid == Process.euid && !stat.world_writable?
+
+        raise Error, "Refusing to load the index from #{@dir}: it belongs to another user or is writable by everyone. Set CF_MCP_CACHE_DIR to a directory of your own."
+      end
+
+      # A checkout that has gone away (a cleaned download directory, say) keeps
+      # its cache: only `refresh` should fetch it again.
+      def fresh?(payload)
+        !File.directory?(payload.headers_path) ||
+          fingerprint(payload.headers_path, payload.topics_path) == payload.fingerprint
+      end
+
+      def rebuild(source)
+        builder = yield source
+        unless builder.valid?
+          raise Error, "Headers directory not found: #{builder.headers_path}. Point --root at a Cute Framework checkout, or use --download."
+        end
+
+        index = builder.build
+        write_atomically(path_for(source), Marshal.dump(Payload.new(
+          format: FORMAT,
+          gem_version: VERSION,
+          headers_path: builder.headers_path,
+          topics_path: builder.topics_path,
+          fingerprint: fingerprint(builder.headers_path, builder.topics_path),
+          revision: builder.revision,
+          items: index.items.values
+        )))
+        use(source, builder.revision)
+        index
+      end
+
+      def hydrate(source, payload)
+        index = Index.instance
+        index.reset!
+        payload.items.each { |item| index.add(item) }
+        use(source, payload.revision)
+        index
+      end
+
+      def use(source, revision)
+        @path = path_for(source)
+        @revision = revision
+        write_atomically(current_path, Marshal.dump(source)) unless current_source == source
+      end
+
+      def current_path
+        File.join(@dir, "current")
+      end
+
+      def current_source
+        Marshal.load(File.binread(current_path)) #: source
+      rescue
+        DEFAULT_SOURCE
+      end
+
+      def load_payload(path)
+        payload = Marshal.load(File.binread(path)) #: Payload
+        payload if payload.format == FORMAT && payload.gem_version == VERSION
+      rescue
+        nil
+      end
+
+      # Written beside the file and renamed into place, so a reader never sees half of it.
+      def write_atomically(path, data)
+        FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+        Tempfile.create(["cf-mcp", ".tmp"], File.dirname(path), binmode: true) do |file|
+          file.write(data)
+          file.close
+          File.rename(file.path, path)
+        end
+      end
+
+      def fingerprint(headers_path, topics_path)
+        files = Dir.glob(File.join(headers_path, "**/*.h"))
+        files += Dir.glob(File.join(topics_path, "*.md")) if topics_path
+        stats = files.sort.filter_map do |file|
+          stat = File.stat(file)
+          [file, stat.mtime.to_f, stat.size].join(":")
+        rescue Errno::ENOENT
+          # Gone since it was listed: a header being replaced, as during an update.
+          nil
+        end
+        Digest::SHA256.hexdigest(stats.join("\n"))
+      end
+    end
+  end
+end

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

@@ -11,7 +11,7 @@ module CF
           :example_brief, :related, :source_file, :source_line
 
         def initialize(
-          name: nil,
+          name:,
           type: nil,
           category: nil,
           brief: nil,
@@ -63,7 +63,7 @@ module CF
         def keyword_score(keyword)
           score = 0
           keyword_downcase = keyword.downcase
-          name_downcase = name&.downcase || ""
+          name_downcase = name.downcase
 
           # Exact name match (highest priority)
           if name_downcase == keyword_downcase
@@ -128,9 +128,7 @@ module CF
         end
 
         def to_text(detailed: false, index: nil)
-          lines = []
-          lines.concat(build_header_lines)
-          lines.concat(build_description_lines)
+          lines = build_header_lines + build_description_lines
 
           if detailed
             lines.concat(build_type_specific_lines)
@@ -145,13 +143,9 @@ module CF
         protected
 
         def build_header_lines
-          lines = []
-          lines << "# #{name}"
-          lines << ""
-          lines << "- **Type:** #{type}"
+          lines = ["# #{name}", "", "- **Type:** #{type}"]
           lines << "- **Category:** #{category}" if category
-          if source_file
-            urls = source_urls
+          if (urls = source_urls)
             lines << "- **Source:** [include/#{source_file}](#{urls[:blob]})"
             lines << "- **Raw:** #{urls[:raw]}"
             lines << "- **Implementation:** #{urls[:impl_raw]}"
@@ -161,8 +155,7 @@ module CF
         end
 
         def build_description_lines
-          lines = []
-          lines << "## Description"
+          lines = ["## Description"]
           lines << brief if brief
           lines << ""
           lines

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

@@ -9,10 +9,11 @@ module CF
         Entry = Data.define(:name, :value, :description)
 
         def initialize(
+          name:,
           entries: [],
           **kwargs
         )
-          super(type: :enum, **kwargs)
+          super(name:, type: :enum, **kwargs)
           @entries = entries || []
         end
 
@@ -27,11 +28,7 @@ module CF
         def build_type_specific_lines
           return [] unless entries && !entries.empty?
 
-          lines = []
-          lines << "## Values"
-          lines << ""
-          lines << "| Name | Value | Description |"
-          lines << "| --- | --- | --- |"
+          lines = ["## Values", "", "| Name | Value | Description |", "| --- | --- | --- |"]
           entries.each do |entry|
             lines << "| `#{entry.name}` | #{entry.value} | #{entry.description} |"
           end

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

@@ -9,12 +9,13 @@ module CF
         Parameter = Data.define(:name, :description)
 
         def initialize(
+          name:,
           signature: nil,
           parameters: [],
           return_value: nil,
           **kwargs
         )
-          super(type: :function, **kwargs)
+          super(name:, type: :function, **kwargs)
           @signature = signature
           @parameters = parameters || []
           @return_value = return_value
@@ -35,10 +36,7 @@ module CF
         end
 
         def to_text(detailed: false, index: nil)
-          lines = []
-          lines.concat(build_header_lines)
-          lines.concat(build_signature_lines)
-          lines.concat(build_description_lines)
+          lines = build_header_lines + build_signature_lines + build_description_lines
 
           if detailed
             lines.concat(build_type_specific_lines)
@@ -58,26 +56,21 @@ module CF
         end
 
         def build_type_specific_lines
-          lines = []
+          build_parameters_lines + build_return_value_lines
+        end
 
-          if parameters && !parameters.empty?
-            lines << "## Parameters"
-            lines << ""
-            lines << "| Parameter | Description |"
-            lines << "| --- | --- |"
-            parameters.each do |param|
-              lines << "| `#{param.name}` | #{param.description} |"
-            end
-            lines << ""
-          end
+        def build_parameters_lines
+          return [] unless parameters && !parameters.empty?
 
-          if return_value && !return_value.empty?
-            lines << "## Return Value"
-            lines << return_value
-            lines << ""
-          end
+          ["## Parameters", "", "| Parameter | Description |", "| --- | --- |"] +
+            parameters.map { |param| "| `#{param.name}` | #{param.description} |" } +
+            [""]
+        end
+
+        def build_return_value_lines
+          return [] unless return_value && !return_value.empty?
 
-          lines
+          ["## Return Value", return_value, ""]
         end
       end
     end

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

@@ -9,10 +9,11 @@ module CF
         Member = Data.define(:declaration, :description)
 
         def initialize(
+          name:,
           members: [],
           **kwargs
         )
-          super(type: :struct, **kwargs)
+          super(name:, type: :struct, **kwargs)
           @members = members || []
         end
 
@@ -27,11 +28,7 @@ module CF
         def build_type_specific_lines
           return [] unless members && !members.empty?
 
-          lines = []
-          lines << "## Members"
-          lines << ""
-          lines << "| Member | Description |"
-          lines << "| --- | --- |"
+          lines = ["## Members", "", "| Member | Description |", "| --- | --- |"]
           members.each do |member|
             lines << "| `#{member.declaration}` | #{member.description} |"
           end

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

@@ -10,6 +10,7 @@ module CF
         Section = Data.define(:title, :content)
 
         def initialize(
+          name:,
           content: nil,
           sections: [],
           function_references: [],
@@ -19,7 +20,7 @@ module CF
           reading_order: nil,
           **kwargs
         )
-          super(type: :topic, **kwargs)
+          super(name:, type: :topic, **kwargs)
           @content = content
           @sections = sections || []
           @function_references = function_references || []
@@ -50,10 +51,7 @@ module CF
         end
 
         def to_text(detailed: false, index: nil)
-          lines = []
-          lines << "# #{name}"
-          lines << ""
-          lines << "**Type:** topic"
+          lines = ["# #{name}", "", "**Type:** topic"]
           lines << "**Category:** #{category}" if category
           lines << "**Source:** #{source_file}" if source_file
           lines << ""

data/lib/cf/mcp/parser.rb

@@ -15,13 +15,13 @@ module CF
         content = File.read(path)
         source_file = File.basename(path)
         line_offsets = build_line_offsets(content)
-        items = []
+        items = [] #: Array[Models::DocItem]
 
         # Find all documentation blocks with their positions
         content.scan(%r{(/\*\*.*?\*/)(.*?)(?=/\*\*|\z)}m) do |doc_block, following_content|
           # Get the position of the match to calculate line number
-          match_position = Regexp.last_match.begin(0)
-          source_line = line_for_position(match_position, line_offsets)
+          match = Regexp.last_match || raise("scan yielded without a match")
+          source_line = line_for_position(match.begin(0), line_offsets)
           item = parse_doc_block(doc_block, following_content.strip, source_file, source_line)
           items << item if item
         end
@@ -30,12 +30,10 @@ module CF
       end
 
       def parse_directory(path)
-        items = []
-        Dir.glob(File.join(path, "**/*.h")).each do |header_file|
+        Dir.glob(File.join(path, "**/*.h")).flat_map do |header_file|
           warn "Parsing #{header_file}" if $stderr.isatty
-          items.concat(parse_file(header_file))
+          parse_file(header_file)
         end
-        items
       end
 
       private
@@ -73,34 +71,23 @@ module CF
       end
 
       def extract_tags(doc_block)
-        tags = {}
+        tags = {} #: Hash[Symbol, untyped]
 
         # Remove comment markers and clean up
         lines = doc_block.lines.map do |line|
           line.gsub(%r{^\s*/?\*+\s?}, "").gsub(%r{\s*\*+/\s*$}, "")
         end
 
-        current_tag = nil
-        current_content = []
-
-        lines.each do |line|
-          if line =~ TAG_PATTERN
-            # Save previous tag
-            if current_tag
-              save_tag(tags, current_tag, current_content.join("\n").strip)
-            end
-
-            current_tag = ::Regexp.last_match(1)
-            remaining = line.sub(TAG_PATTERN, "").strip
-            current_content = [remaining]
-          elsif current_tag
-            current_content << line
-          end
-        end
+        # A tag starts on a line containing @tag and runs until the next one.
+        lines.slice_before { |line| TAG_PATTERN.match?(line) }.each do |tag_lines|
+          first_line = tag_lines.fetch(0)
 
-        # Save last tag
-        if current_tag
-          save_tag(tags, current_tag, current_content.join("\n").strip)
+          # Text before the first tag has no tag to belong to
+          tag = first_line[TAG_PATTERN, 1]
+          next unless tag
+
+          remaining = first_line.sub(TAG_PATTERN, "").strip
+          save_tag(tags, tag, [remaining, *tag_lines.drop(1)].join("\n").strip)
         end
 
         tags
@@ -111,8 +98,8 @@ module CF
         when "param"
           tags[:params] ||= []
           # Parse "param_name description" format
-          if content =~ /^(\w+)\s+(.*)$/m
-            tags[:params] << {name: ::Regexp.last_match(1), description: ::Regexp.last_match(2).strip}
+          if (match = /^(\w+)\s+(.*)$/m.match(content))
+            tags[:params] << {name: match[1], description: match[2].strip}
           end
         when "related"
           # Filter out comment artifacts like "/" or "*/"
@@ -184,23 +171,16 @@ module CF
 
       def extract_signature(content)
         # Find the first function declaration (ending with ; or {)
-        lines = content.lines
-        signature_lines = []
-
-        lines.each do |line|
+        signature_lines = content.lines
           # Skip empty lines and comments at the start
-          next if line.strip.empty? && signature_lines.empty?
-          break if line.strip.empty? && !signature_lines.empty?
-
-          # Stop at struct/enum definitions
-          break if /^typedef\s+(struct|enum)/.match?(line)
-          break if /^#define/.match?(line)
+          .drop_while { |line| line.strip.empty? }
+          # Stop at the first empty line, and at struct/enum definitions
+          .take_while { |line| !line.strip.empty? && !/^typedef\s+(struct|enum)/.match?(line) && !/^#define/.match?(line) }
+          # ...and just after the line that ends the declaration
+          .slice_after { |line| line.include?(";") || line.include?("{") }
+          .first
 
-          signature_lines << line
-          break if line.include?(";") || line.include?("{")
-        end
-
-        return nil if signature_lines.empty?
+        return nil if signature_lines.nil? || signature_lines.empty?
 
         signature = signature_lines.join.strip
         # Clean up macros and normalize whitespace
@@ -211,33 +191,25 @@ module CF
       end
 
       def extract_members(content)
-        members = []
-
         # Find /* @member ... */ comments and the following declaration
         # Use [^/]+? to ensure we capture content (non-slash chars) before the next comment
-        content.scan(%r{/\*\s*@member\s+(.*?)\s*\*/\s*([^/]+?)(?=/\*|//\s*@end|$)}m) do |description, declaration|
+        content.scan(%r{/\*\s*@member\s+(.*?)\s*\*/\s*([^/]+?)(?=/\*|//\s*@end|$)}m).filter_map do |description, declaration|
           decl = declaration.strip.lines.first&.strip
           next unless decl && !decl.empty?
 
           # Clean up the declaration (remove trailing semicolon for display)
           decl = decl.gsub(/;$/, "").strip
-          members << Models::StructDoc::Member.new(decl, description.strip)
+          Models::StructDoc::Member.new(decl, description.strip)
         end
-
-        members
       end
 
       def extract_enum_entries(content)
-        entries = []
-
         # Find the #define block with CF_ENUM macros
         # Pattern: /* @entry description */ followed by CF_ENUM(NAME, VALUE)
-        content.scan(%r{/\*\s*@entry\s+(.*?)\s*\*/\s*\\?\s*CF_ENUM\s*\(\s*(\w+)\s*,\s*([^)]*)\)}m) do |description, name, value|
+        content.scan(%r{/\*\s*@entry\s+(.*?)\s*\*/\s*\\?\s*CF_ENUM\s*\(\s*(\w+)\s*,\s*([^)]*)\)}m).map do |description, name, value|
           # CF_ENUM(K, V) expands to CF_##K = V, so add CF_ prefix
-          entries << Models::EnumDoc::Entry.new("CF_#{name.strip}", value.strip, description.strip)
+          Models::EnumDoc::Entry.new("CF_#{name.strip}", value.strip, description.strip)
         end
-
-        entries
       end
     end
   end

data/lib/cf/mcp/server.rb

@@ -12,7 +12,7 @@ module CF
       CORS_HEADERS = {
         "access-control-allow-origin" => "*",
         "access-control-allow-methods" => "GET, POST, DELETE, OPTIONS",
-        "access-control-allow-headers" => "Content-Type, Accept, Mcp-Session-Id",
+        "access-control-allow-headers" => "Content-Type, Accept, MCP-Protocol-Version, Mcp-Method, Mcp-Name, Mcp-Session-Id",
         "access-control-expose-headers" => "Mcp-Session-Id"
       }.freeze
 
@@ -37,33 +37,37 @@ module CF
         new(index, revision: builder.revision).rack_app
       end
 
-      PROTOCOL_VERSION = "2025-03-26"
+      # Modern clients carry their version on every request (no handshake); legacy
+      # clients negotiate through `initialize`. Both track the SDK rather than pinning.
+      MODERN_PROTOCOL_VERSION = ::MCP::Configuration::LATEST_MODERN_PROTOCOL_VERSION
+      LEGACY_PROTOCOL_VERSION = ::MCP::Configuration::LATEST_HANDSHAKE_PROTOCOL_VERSION
+      DESCRIPTION = "Search and browse Cute Framework API documentation: functions, structs, enums, and topic guides."
       WEBSITE_URL = ENV.fetch("FLY_APP_NAME", nil) ? "https://#{ENV["FLY_APP_NAME"]}.fly.dev" : "https://cf-mcp.fly.dev"
       PUBLIC_DIR = File.join(__dir__, "public")
+      ALLOWED_HOSTS_ENV = "CF_MCP_ALLOWED_HOSTS"
 
-      def initialize(index, revision: nil)
+      # Comma-separated list of extra Host header values the HTTP transport accepts
+      # (the MCP SDK only allows loopback hosts by default).
+      def self.allowed_hosts_from_env(env = ENV)
+        env.fetch(ALLOWED_HOSTS_ENV, "").split(",").map(&:strip).reject(&:empty?)
+      end
+
+      def initialize(index, revision: nil, allowed_hosts: self.class.allowed_hosts_from_env)
         @index = index
         @revision = revision
+        @allowed_hosts = allowed_hosts
 
-        configuration = ::MCP::Configuration.new(protocol_version: PROTOCOL_VERSION)
         @server = ::MCP::Server.new(
           name: "cf-mcp",
-          configuration:,
+          title: "Cute Framework MCP",
+          description: DESCRIPTION,
           version: CF::MCP::VERSION,
+          website_url: WEBSITE_URL,
           icons: [
             ::MCP::Icon.new(src: "#{WEBSITE_URL}/favicon.svg", mime_type: "image/svg+xml", sizes: ["any"]),
             ::MCP::Icon.new(src: "#{WEBSITE_URL}/favicon-96x96.png", mime_type: "image/png", sizes: ["96x96"])
           ],
-          tools: [
-            Tools::SearchTool,
-            Tools::ListCategory,
-            Tools::GetDetails,
-            Tools::FindRelated,
-            Tools::ParameterSearch,
-            Tools::MemberSearch,
-            Tools::ListTopics,
-            Tools::GetTopic
-          ],
+          tools: Tools.all,
           resources: build_topic_resources(index)
         )
         @server.server_context = {index: index}
@@ -82,7 +86,7 @@ module CF
       def rack_app
         require "rack"
 
-        http_transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(@server, stateless: true)
+        http_transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(@server, stateless: true, allowed_hosts: @allowed_hosts)
         @server.transport = http_transport
 
         landing_page = build_landing_page
@@ -97,7 +101,7 @@ module CF
 
           # Handle CORS preflight
           if request.options?
-            return [204, cors_headers, []]
+            next [204, cors_headers, []] #: [Integer, Hash[String, String], Array[String]]
           end
 
           # Route based on path
@@ -136,12 +140,12 @@ module CF
           end
 
           # Add CORS headers to response
-          [status, headers.merge(cors_headers), body]
+          [status, headers.merge(cors_headers), body] #: ::Rack::response
         }
 
-        Rack::Builder.new do
-          use Rack::CommonLogger
-          run app
+        Rack::Builder.new do |builder|
+          builder.use Rack::CommonLogger
+          builder.run app
         end
       end
 
@@ -165,7 +169,7 @@ module CF
         topic_name = uri.sub("cf://topics/", "")
         topic = index.find(topic_name)
 
-        return [] unless topic&.type == :topic
+        return [] unless topic.is_a?(Models::TopicDoc)
 
         [{
           uri: uri,
@@ -193,7 +197,8 @@ module CF
         ->(index, tool_classes) {
           context = TemplateContext.new(
             version: CF::MCP::VERSION,
-            protocol_version: PROTOCOL_VERSION,
+            modern_protocol_version: MODERN_PROTOCOL_VERSION,
+            legacy_protocol_version: LEGACY_PROTOCOL_VERSION,
             revision: @revision,
             revision_url: @revision && format(CUTE_FRAMEWORK_COMMIT_URL_TEMPLATE, revision: @revision),
             stats: index.stats,
@@ -219,11 +224,12 @@ module CF
       class TemplateContext
         TEMPLATES_DIR = File.join(__dir__, "templates")
 
-        attr_reader :version, :protocol_version, :revision, :revision_url, :stats, :categories, :topics, :tools, :tool_schemas_json
+        attr_reader :version, :modern_protocol_version, :legacy_protocol_version, :revision, :revision_url, :stats, :categories, :topics, :tools, :tool_schemas_json
 
-        def initialize(version:, protocol_version:, revision:, revision_url:, stats:, categories:, topics:, tools:, tool_schemas_json:)
+        def initialize(version:, modern_protocol_version:, legacy_protocol_version:, revision:, revision_url:, stats:, categories:, topics:, tools:, tool_schemas_json:)
           @version = version
-          @protocol_version = protocol_version
+          @modern_protocol_version = modern_protocol_version
+          @legacy_protocol_version = legacy_protocol_version
           @revision = revision
           @revision_url = revision_url
           @stats = stats
@@ -256,7 +262,10 @@ module CF
 
         def js_content
           js = File.read(File.join(TEMPLATES_DIR, "script.js"))
-          js.sub("TOOL_SCHEMAS_PLACEHOLDER", @tool_schemas_json)
+          # Substitute the scalar placeholders first so injected content can't collide with them
+          js.sub("PROTOCOL_VERSION_PLACEHOLDER", @modern_protocol_version.to_json)
+            .sub("CLIENT_VERSION_PLACEHOLDER", @version.to_json)
+            .sub("TOOL_SCHEMAS_PLACEHOLDER", @tool_schemas_json)
             .sub("CATEGORIES_PLACEHOLDER", categories_json)
             .sub("TOPICS_PLACEHOLDER", topics_json)
             .sub("CHANGELOG_PLACEHOLDER", changelog_json)

data/lib/cf/mcp/templates/index.erb

@@ -53,7 +53,7 @@
     </tr>
     <tr>
       <th>Protocol Version</th>
-      <td><%= protocol_version %></td>
+      <td><%= modern_protocol_version %> <small>(legacy handshake up to <%= legacy_protocol_version %>)</small></td>
     </tr>
     <% if revision %>
     <tr>