cf-mcp 0.16.2 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8616f673c57b67cd09602a2b49611c030fc058d63f1701dd2cec2cff2c04d4ad
-  data.tar.gz: abc2b55c27a9f4ace220d5fd9d013cb5944c02d8bd6f43106be141ac05aaa208
+  metadata.gz: d62d42b607e127916235fb3bbd2a2dace73fc1aefc9216dc1d9f92acfa6c423a
+  data.tar.gz: 12a75fda9901e78aee0fc6f7c3ed448ce52f6130d868f036aa674464efea640c
 SHA512:
-  metadata.gz: 7587ed21fd3fe5e3f81a7fd574cc32afc3da7c69b7c9869241508ad8a3f477ec813297f1d893b0dba5c3c9ccc4411773adacce35eeb8e15a936328f613d55186
-  data.tar.gz: 02e5f832b1c52dc25ec415d362585e7f104a526a24e7454af38192f48d60abc209c7f91175b60dd5759b0dc1670508fdf16ad61fa7db4aebe25edf7f406d984a
+  metadata.gz: 63eabad61e8ea796f628e8f6248ac3e147b8486ac7495ab897dbd596d13044bd6495032dabede788a25a9426fcb9b855e5ced42a541b47aaeb269e161d958887
+  data.tar.gz: a262522cae34cbcb9b2f9c54252709b86fa44efbf2f32f8426937784cc35d5aaf048c9267ca4e9ee53bf1b3543f5df0e4d8ca76580a881cc94b0d4ab44f355a5

data/CHANGELOG.md

@@ -5,6 +5,22 @@ 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).
 
+## [Unreleased]
+
+## [0.17.0] - 2026-02-09
+
+### Added
+
+- SHA-based caching for downloaded Cute Framework headers - checks GitHub API for latest commit SHA before downloading to avoid redundant fetches
+- GitHub API client with optional GITHUB_TOKEN support for higher rate limits (5000/hr vs 60/hr unauthenticated)
+- Metadata tracking (.cf-mcp-sha file) stores downloaded version SHA for cache validation
+
+### Changed
+
+- Downloader uses commit-specific archive URLs (e.g., /archive/abc1234.zip) instead of always downloading master branch
+- Download process now checks for updates by comparing stored SHA with latest GitHub commit
+- Refactored all internal `require_relative` statements to use `autoload` for lazy loading, improving load time and memory usage
+
 ## [0.16.2] - 2026-01-31
 
 ### Fixed
@@ -261,6 +277,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.17.0]: https://github.com/pusewicz/cf-mcp/compare/v0.16.2...v0.17.0
 [0.16.2]: https://github.com/pusewicz/cf-mcp/compare/v0.16.1...v0.16.2
 [0.16.1]: https://github.com/pusewicz/cf-mcp/compare/v0.16.0...v0.16.1
 [0.16.0]: https://github.com/pusewicz/cf-mcp/compare/v0.15.5...v0.16.0

data/Manifest.txt

@@ -8,6 +8,7 @@ exe/cf-mcp
 lib/cf/mcp.rb
 lib/cf/mcp/cli.rb
 lib/cf/mcp/downloader.rb
+lib/cf/mcp/github_client.rb
 lib/cf/mcp/index.rb
 lib/cf/mcp/index_builder.rb
 lib/cf/mcp/models/doc_item.rb

data/lib/cf/mcp/cli.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 require "optparse"
-require_relative "index_builder"
-require_relative "server"
 
 module CF
   module MCP

data/lib/cf/mcp/downloader.rb

@@ -4,12 +4,13 @@ require "net/http"
 require "uri"
 require "fileutils"
 require "zip"
-require_relative "version"
 
 module CF
   module MCP
     class Downloader
       CUTE_FRAMEWORK_ZIP_URL = "https://github.com/RandyGaul/cute_framework/archive/refs/heads/master.zip"
+      GITHUB_ARCHIVE_URL_TEMPLATE = "https://github.com/RandyGaul/cute_framework/archive/%{ref}.zip"
+      SHA_METADATA_FILE = ".cf-mcp-sha"
       DEFAULT_DOWNLOAD_DIR = File.join(Dir.tmpdir, "cf-mcp-#{VERSION}")
 
       class DownloadError < StandardError; end
@@ -24,23 +25,41 @@ module CF
         zip_path = File.join(@download_dir, "cute_framework.zip")
         base_path = File.join(@download_dir, "cute_framework")
         include_path = File.join(base_path, "include")
-        File.join(base_path, "docs", "topics")
+        sha_file = File.join(@download_dir, SHA_METADATA_FILE)
 
-        # Return existing path if already downloaded
-        if File.directory?(include_path) && !Dir.empty?(include_path)
-          return include_path
+        # Check if cache is valid
+        stored_sha = read_sha_metadata(sha_file)
+        latest_sha = fetch_latest_sha
+
+        if stored_sha && latest_sha && stored_sha == latest_sha
+          if File.directory?(include_path) && !Dir.empty?(include_path)
+            warn "Using cached Cute Framework headers (SHA: #{stored_sha})"
+            return include_path
+          end
+        end
+
+        # Determine download URL
+        if latest_sha
+          download_url = format(GITHUB_ARCHIVE_URL_TEMPLATE, ref: latest_sha)
+          warn "Downloading Cute Framework at SHA #{latest_sha}..."
+        else
+          download_url = CUTE_FRAMEWORK_ZIP_URL
+          warn "Downloading Cute Framework from master branch..."
         end
 
-        download_zip(zip_path)
+        download_zip(zip_path, download_url)
         extract_directories(zip_path, base_path)
 
+        # Store metadata for future cache checks
+        write_sha_metadata(sha_file, latest_sha) if latest_sha
+
         include_path
       end
 
       private
 
-      def download_zip(destination)
-        uri = URI.parse(CUTE_FRAMEWORK_ZIP_URL)
+      def download_zip(destination, url = CUTE_FRAMEWORK_ZIP_URL)
+        uri = URI.parse(url)
 
         Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
           request = Net::HTTP::Get.new(uri)
@@ -73,9 +92,9 @@ module CF
           top_level_prefix = nil
 
           zip_file.each do |entry|
-            # Find the top-level directory prefix (e.g., "cute_framework-master/")
-            if top_level_prefix.nil? && entry.name.match?(%r{^[^/]+/include/})
-              top_level_prefix = entry.name.match(%r{^([^/]+/)})[1]
+            # Find the top-level directory prefix (e.g., "cute_framework-master/" or "cute_framework-abc1234/")
+            if top_level_prefix.nil? && entry.name.match?(%r{^cute_framework-[^/]+/include/})
+              top_level_prefix = entry.name.match(%r{^(cute_framework-[^/]+/)})[1]
               break
             end
           end
@@ -107,6 +126,29 @@ module CF
           end
         end
       end
+
+      def fetch_latest_sha
+        client = GitHubClient.new
+        client.latest_commit_sha
+      rescue => e
+        warn "GitHub API error: #{e.message}"
+        nil
+      end
+
+      def read_sha_metadata(file)
+        return nil unless File.exist?(file)
+        File.read(file).strip
+      rescue => e
+        warn "Error reading SHA metadata: #{e.message}"
+        nil
+      end
+
+      def write_sha_metadata(file, sha)
+        return unless sha
+        File.write(file, sha)
+      rescue => e
+        warn "Error writing SHA metadata: #{e.message}"
+      end
     end
   end
 end

data/lib/cf/mcp/github_client.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module CF
+  module MCP
+    class GitHubClient
+      GITHUB_API_BASE = "https://api.github.com"
+      REPO_OWNER = "RandyGaul"
+      REPO_NAME = "cute_framework"
+      DEFAULT_BRANCH = "master"
+
+      def initialize(token: ENV["GITHUB_TOKEN"])
+        @token = token
+      end
+
+      # Returns latest commit SHA (short 7-char format) or nil on failure
+      def latest_commit_sha
+        uri = URI.parse("#{GITHUB_API_BASE}/repos/#{REPO_OWNER}/#{REPO_NAME}/commits/#{DEFAULT_BRANCH}")
+
+        request = Net::HTTP::Get.new(uri)
+        request["Accept"] = "application/vnd.github+json"
+        request["Authorization"] = "Bearer #{@token}" if @token
+        request["User-Agent"] = "cf-mcp/#{CF::MCP::VERSION}"
+
+        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+          http.request(request)
+        end
+
+        return nil unless response.is_a?(Net::HTTPSuccess)
+
+        data = JSON.parse(response.body)
+        data.dig("sha")&.slice(0, 7) # Return short SHA
+      rescue
+        # Return nil on any error (network, JSON parse, etc.)
+        nil
+      end
+    end
+  end
+end

data/lib/cf/mcp/index_builder.rb

@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "parser"
-require_relative "topic_parser"
-require_relative "index"
-require_relative "downloader"
-
 module CF
   module MCP
     class IndexBuilder

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "doc_item"
-
 module CF
   module MCP
     module Models

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "doc_item"
-
 module CF
   module MCP
     module Models

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "doc_item"
-
 module CF
   module MCP
     module Models

data/lib/cf/mcp/parser.rb

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "models/function_doc"
-require_relative "models/struct_doc"
-require_relative "models/enum_doc"
-
 module CF
   module MCP
     class Parser

data/lib/cf/mcp/topic_parser.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "models/topic_doc"
-
 module CF
   module MCP
     class TopicParser

data/lib/cf/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module CF
   module MCP
-    VERSION = "0.16.2"
+    VERSION = "0.17.0"
   end
 end

data/lib/cf/mcp.rb

@@ -2,25 +2,32 @@
 
 require "pathname"
 require_relative "mcp/version"
-require_relative "mcp/models/doc_item"
-require_relative "mcp/models/function_doc"
-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"
 
 module CF
   module MCP
     class Error < StandardError; end
 
+    autoload :Parser, "cf/mcp/parser"
+    autoload :Index, "cf/mcp/index"
+    autoload :IndexBuilder, "cf/mcp/index_builder"
+    autoload :TopicParser, "cf/mcp/topic_parser"
+    autoload :Server, "cf/mcp/server"
+    autoload :Downloader, "cf/mcp/downloader"
+    autoload :GitHubClient, "cf/mcp/github_client"
+    autoload :CLI, "cf/mcp/cli"
+
     def self.root
       @root ||= Pathname.new(File.expand_path("../..", __dir__))
     end
 
+    module Models
+      autoload :DocItem, "cf/mcp/models/doc_item"
+      autoload :FunctionDoc, "cf/mcp/models/function_doc"
+      autoload :StructDoc, "cf/mcp/models/struct_doc"
+      autoload :EnumDoc, "cf/mcp/models/enum_doc"
+      autoload :TopicDoc, "cf/mcp/models/topic_doc"
+    end
+
     module Tools
       autoload :SearchTool, "cf/mcp/tools/search_tool"
       autoload :ListCategory, "cf/mcp/tools/list_category"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cf-mcp
 version: !ruby/object:Gem::Version
-  version: 0.16.2
+  version: 0.17.0
 platform: ruby
 authors:
 - Piotr Usewicz
@@ -98,6 +98,7 @@ files:
 - lib/cf/mcp.rb
 - lib/cf/mcp/cli.rb
 - lib/cf/mcp/downloader.rb
+- lib/cf/mcp/github_client.rb
 - lib/cf/mcp/index.rb
 - lib/cf/mcp/index_builder.rb
 - lib/cf/mcp/models/doc_item.rb
@@ -152,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: MCP server providing documentation tools for Cute Framework
 test_files: []