cf-mcp 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa1835b909429755f2b06a50b6db8d973c68445f879413974b7b28863b6bce06
-  data.tar.gz: 6a110d101e27e125763506715bed2a92b973e9cecd709bd17a69c7088fb5e55f
+  metadata.gz: 74d1434cafd05f9f937dffdf7ae0f332ddb30816b9584bd20a5cf7b0a964914a
+  data.tar.gz: c513c509f8cc74e414312be4caf351ecb36b12c95ac23a98f43e4fa68721f29d
 SHA512:
-  metadata.gz: e450154e426288754d99ee28a63e4b3fa99d2394600ab8519df3f0d584844b2428f64a1c62d106053f3f3826ace1d4e4beeadd6d9f45e0100b2d7bcc3717db69
-  data.tar.gz: 7fd889d1f4ae36abed48cb84048efa8debf22a4c97d198c2d12745ad095589a3ab02feeb5c2c1d4d3221f33a38069c363214f3142b7c56bcbf0c30e04d790f54
+  metadata.gz: 9f037629edf72ea2a7a9b221d51a7108376e8136c7fa4f749fb10088c96a134b6ab1d62e77297da5167189ce940c22f5519d6303112a2c0d76b5b8b16ddf543c
+  data.tar.gz: 465e434412b383fa0f99d2210e86131cf320bb59f2dccd2d8781960b000a7a7f1a77155951ced1d191c5f5923527453f33f7c31d67d105a1e2de308c2ebeef52

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.21.0] - 2026-09-21
+
+### Added
+
+- Every tool is now a command (`cf-mcp search sprite --type function`, `cf-mcp get_details CF_Sprite`, and so on) with arguments and `--help` generated from the tool's input schema
+- `cf-mcp index` caches the parsed index in `~/.cache/cf-mcp` (`CF_MCP_CACHE_DIR` and `XDG_CACHE_HOME` are honoured), one cache per `--root` so projects on different Cute Framework versions do not evict each other; tool commands read it and rebuild it when a header or topic changes. A cache directory that belongs to another user or that everyone can write to is refused, since cache files are read back with `Marshal`
+- RBS signatures for the whole library, checked in CI with Steep (strict, and every method must have a signature) and by running the test suite under RBS's runtime type checker; run them with `rake rbs`. They are development-only and not packaged in the gem.
+
+### Changed
+
+- `CLI#run` returns the exit status instead of exiting, and an unknown command or option now fails with a message (previously an unknown command printed the usage and exited 0)
+- `search` and `list_category` list the index's categories when their schema is asked for instead of when the class loads, so tools can be loaded before the index is filled; the `category` property has no `enum` while the index is empty
+- `name:` is now a required keyword on `DocItem` and its subclasses (`FunctionDoc`, `StructDoc`, `EnumDoc`, `TopicDoc`); previously a nameless item could be built and indexed
+- `Index#by_type` now returns an `Index::ByType` (`functions`, `structs`, `enums`, `topics`) instead of a Hash keyed by type symbol, and `Index#add` files items by class rather than by their `type`
+- Small internal refactors so the code type checks; no behavior change for valid input
+
+### Removed
+
+- Dropped the unused `listen` runtime dependency
+
 ## [0.20.0] - 2026-09-19
 
 ### Added
@@ -14,6 +34,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `CF_MCP_ALLOWED_HOSTS` environment variable (comma-separated) to allow extra `Host` header values on the HTTP endpoint; set to `cf-mcp.fly.dev` in `fly.toml`
 - Support MCP protocol version 2026-07-28: stateless requests carrying their version in `_meta`, and the `server/discover` method
 - Allow the `MCP-Protocol-Version`, `Mcp-Method` and `Mcp-Name` headers in CORS preflight responses
+- Server `description` in `serverInfo`
 
 ### Changed
 
@@ -21,6 +42,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated `mcp` from 0.25.0 to 1.5.1
 - Updated `puma` from 7.2.1 to 8.0.2 (the gemspec constraint is now `~> 8.0`) and `rubyzip` from 3.6.0 to 3.7.0
 - Removed the `2025-03-26` protocol pin; clients using the `initialize` handshake now negotiate up to 2025-11-25
+- Restored the server `title`, `website_url` and tool titles removed in 0.17.2 for that pin; the SDK still omits the server fields for clients that negotiate an older version
 - The web UI now calls tools through the stateless 2026-07-28 protocol
 - The web UI shows both the modern and the legacy handshake protocol versions
 - Bump Ruby to 4.0.7 in `.ruby-version`, the Dockerfile, and the CI matrix
@@ -332,7 +354,8 @@ This version was prepared but never released. Changes rolled into 0.17.2.
   - `cf_list_category` - List items by category
   - `cf_get_details` - Get full documentation by name
 
-[Unreleased]: https://github.com/pusewicz/cf-mcp/compare/v0.20.0...HEAD
+[Unreleased]: https://github.com/pusewicz/cf-mcp/compare/v0.21.0...HEAD
+[0.21.0]: https://github.com/pusewicz/cf-mcp/compare/v0.20.0...v0.21.0
 [0.20.0]: https://github.com/pusewicz/cf-mcp/compare/v0.19.0...v0.20.0
 [0.19.0]: https://github.com/pusewicz/cf-mcp/compare/v0.18.0...v0.19.0
 [0.17.2]: https://github.com/pusewicz/cf-mcp/compare/v0.17.0...v0.17.2

data/Manifest.txt

@@ -12,6 +12,7 @@ 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/index_cache.rb
 lib/cf/mcp/models/doc_item.rb
 lib/cf/mcp/models/enum_doc.rb
 lib/cf/mcp/models/function_doc.rb
@@ -29,6 +30,8 @@ lib/cf/mcp/server.rb
 lib/cf/mcp/templates/index.erb
 lib/cf/mcp/templates/script.js
 lib/cf/mcp/templates/style.css
+lib/cf/mcp/tool_command.rb
+lib/cf/mcp/tools/category_enum.rb
 lib/cf/mcp/tools/find_related.rb
 lib/cf/mcp/tools/get_details.rb
 lib/cf/mcp/tools/get_topic.rb
@@ -41,4 +44,3 @@ lib/cf/mcp/tools/search_result_formatter.rb
 lib/cf/mcp/tools/search_tool.rb
 lib/cf/mcp/topic_parser.rb
 lib/cf/mcp/version.rb
-sig/cf/mcp.rbs

data/README.md

@@ -35,6 +35,21 @@ cf-mcp stdio --root /path/to/cute_framework_project  # STDIO mode
 cf-mcp http --root /path/to/cute_framework_project   # HTTP mode with web UI
 ```
 
+## Command line
+
+Every tool is also a command, so no MCP client is needed. Index the docs once, then look things up:
+
+```bash
+cf-mcp index --root /path/to/cute_framework   # re-run after updating Cute Framework
+cf-mcp search sprite --type function --limit 5
+cf-mcp get_details CF_Sprite
+cf-mcp list_category sprite
+```
+
+The commands are `search`, `get_details`, `find_related`, `parameter_search`, `member_search`, `list_category`, `list_topics` and `get_topic`. Run `cf-mcp <command> --help` for a command's arguments.
+
+The index is cached in `~/.cache/cf-mcp` (or `$XDG_CACHE_HOME/cf-mcp`, or `$CF_MCP_CACHE_DIR`) and rebuilt automatically when a header changes. Each `--root` keeps its own cache, so projects on different Cute Framework versions can take turns without reindexing: pass `--root` (or set `CF_HEADERS_PATH`) to say which one a command should use. Without either, a command uses the last one it was given. Cache files are read back with `Marshal`, so a cache directory that belongs to another user or that everyone can write to is refused.
+
 ## Inspecting with MCP Inspector
 
 You can use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to debug and test the server.

data/Rakefile

@@ -9,7 +9,7 @@ require "standard/rake"
 
 desc "Generate Manifest.txt from git ls-files"
 task :manifest do
-  ignore_patterns = %w[bin/ Gemfile .gitignore test/ .github/ .standard.yml cf-mcp.gemspec .ruby-version CLAUDE.md AGENTS.md fly.toml Procfile Dockerfile .dockerignore .claude/ .mcp.json .serena/]
+  ignore_patterns = %w[bin/ Gemfile .gitignore test/ .github/ .standard.yml cf-mcp.gemspec .ruby-version CLAUDE.md AGENTS.md fly.toml Procfile Dockerfile .dockerignore .claude/ .mcp.json .serena/ sig/ sig-stubs/ Steepfile rbs_collection.yaml rbs_collection.lock.yaml]
 
   files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
     ls.readlines("\x0", chomp: true)
@@ -23,11 +23,35 @@ task :manifest do
   puts "Generated Manifest.txt with #{files.size} files"
 end
 
-desc "Validate RBS type signatures"
-task :rbs do
-  sh "rbs", "-I", "sig", "validate"
+namespace :rbs do
+  desc "Validate RBS type signatures"
+  task :validate do
+    sh "rbs", "--collection", "rbs_collection.yaml", "-I", "sig", "-I", "sig-stubs", "validate"
+  end
+
+  desc "Type check lib/ against the RBS signatures with Steep"
+  task :steep do
+    sh "steep", "check"
+  end
+
+  desc "Run the test suite under the RBS runtime type checker"
+  task :test do
+    env = {
+      "RBS_TEST_TARGET" => "CF::MCP::*",
+      "RBS_TEST_OPT" => "-I sig -I sig-stubs --collection rbs_collection.yaml",
+      "RBS_TEST_DOUBLE_SUITE" => "minitest",
+      "RBS_TEST_LOGLEVEL" => "warn",
+      # Append rather than replace: under `bundle exec`, RUBYOPT already carries
+      # -rbundler/setup, and dropping it would make the child resolve system gems.
+      "RUBYOPT" => "#{ENV["RUBYOPT"]} -rrbs/test/setup".strip
+    }
+    sh env, "bundle", "exec", "rake", "test"
+  end
 end
 
+desc "Validate signatures, type check with Steep, and run the tests under the runtime type checker"
+task rbs: %w[rbs:validate rbs:steep rbs:test]
+
 task default: %i[test standard rbs manifest]
 
 desc "Deploy to Fly.io (runs tests and linting first)"

data/exe/cf-mcp

@@ -3,4 +3,4 @@
 
 require "cf/mcp"
 
-CF::MCP::CLI.new(ARGV).run
+exit CF::MCP::CLI.new(ARGV).run

data/lib/cf/mcp/cli.rb

@@ -5,92 +5,117 @@ require "optparse"
 module CF
   module MCP
     class CLI
+      USAGE = "Usage: cf-mcp [options] <command> [options]"
+
+      COMMANDS = {
+        "stdio" => "Run in STDIO mode (for CLI integration)",
+        "http" => "Run as HTTP server with web interface",
+        "index" => "Index the documentation into a cache for fast lookups"
+      }.freeze
+
       def initialize(args)
         @args = args
-        @options = parse_args
+        @options = {
+          port: nil,
+          host: "0.0.0.0",
+          root: nil,
+          download: false,
+          help: false,
+          version: false
+        } #: options
+        @option_parser = build_option_parser
       end
 
+      # Returns the process exit status.
       def run
-        case @options[:command]
-        when :stdio
-          run_server(:stdio)
-        when :http
-          run_http_server
-        when :help
-          puts @option_parser
-        else
-          warn "Unknown command. Use --help for usage information."
-          exit 1
+        @option_parser.order!(@args)
+        command = @args.shift&.tr("-", "_")
+        tool = find_tool(command)
+        # A tool's flags are checked against the index, so the options that choose it come out first.
+        tool ? take_source_options : @option_parser.parse!(@args)
+
+        return print_version if @options[:version]
+        return print_usage if @options[:help] || [nil, "help"].include?(command)
+        return run_tool(tool) if tool
+        return fail_with("Unexpected arguments: #{@args.join(" ")}") unless @args.empty?
+
+        case command
+        when "stdio" then run_stdio
+        when "http" then run_http
+        when "index" then run_index
+        else fail_with("Unknown command '#{command}'. Use --help for usage information.")
         end
+      rescue OptionParser::ParseError, Error => e
+        fail_with(e.message)
       end
 
       private
 
-      def parse_args
-        options = {
-          command: nil,
-          port: nil,
-          host: "0.0.0.0",
-          root: nil,
-          download: false
-        }
-
-        @option_parser = OptionParser.new do |opts|
-          opts.banner = "Usage: cf-mcp <command> [options]"
-          opts.separator ""
-          opts.separator "Commands:"
-          opts.separator "  stdio    Run in STDIO mode (for CLI integration)"
-          opts.separator "  http     Run as HTTP server with web interface"
+      def build_option_parser
+        OptionParser.new do |opts|
+          opts.banner = USAGE
           opts.separator ""
           opts.separator "Options:"
 
-          opts.on("-r", "--root PATH", "Path to Cute Framework headers directory") do |path|
-            options[:root] = path
+          opts.on("-r", "--root PATH", "Path to a Cute Framework checkout, or its include directory") do |path|
+            @options[:root] = path
           end
 
           opts.on("-p", "--port PORT", Integer, "Port for HTTP server (default: 9292)") do |port|
-            options[:port] = port
+            @options[:port] = port
           end
 
           opts.on("-H", "--host HOST", "Host to bind to (default: 0.0.0.0)") do |host|
-            options[:host] = host
+            @options[:host] = host
           end
 
           opts.on("-d", "--download", "Download Cute Framework headers from GitHub") do
-            options[:download] = true
+            @options[:download] = true
           end
 
           opts.on("-h", "--help", "Show this help message") do
-            options[:command] = :help
+            @options[:help] = true
           end
 
           opts.on("-v", "--version", "Show version") do
-            puts "cf-mcp #{CF::MCP::VERSION}"
-            exit 0
+            @options[:version] = true
           end
         end
+      end
 
-        @option_parser.parse!(@args)
+      def print_version
+        puts "cf-mcp #{VERSION}"
+        0
+      end
 
-        # Parse command from remaining args
-        if options[:command].nil? && !@args.empty?
-          command = @args.shift.to_sym
-          options[:command] = command if [:stdio, :http].include?(command)
-        end
+      # The commands go in the banner because the tools are only loaded when asked for.
+      def print_usage
+        @option_parser.banner = [
+          USAGE, "",
+          "Commands:", *command_lines(COMMANDS), "",
+          "Documentation commands (hyphens work too, as in get-details; see `cf-mcp <command> --help`):",
+          *command_lines(tool_descriptions)
+        ].join("\n")
+        puts @option_parser
+        0
+      end
 
-        options[:command] ||= :help
-        options
+      def command_lines(descriptions)
+        descriptions.map { |name, description| "  #{name.ljust(18)}#{description}" }
       end
 
-      def run_server(mode)
-        builder = IndexBuilder.new(root: @options[:root], download: @options[:download])
+      def tool_descriptions
+        Tools.all.to_h { |tool| [tool.tool_name.to_s, tool.description.to_s] }
+      end
 
-        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
+      def fail_with(message)
+        warn "Error: #{message}"
+        1
+      end
+
+      def run_stdio
+        builder = IndexBuilder.new(root: @options[:root], download: @options[:download])
+        return fail_with(missing_headers_message(builder)) unless builder.valid?
 
         warn "Parsing headers from: #{builder.headers_path}"
         index = builder.build do |event, path, count|
@@ -99,11 +124,11 @@ module CF
         warn "Indexed #{index.stats[:total]} items (#{index.stats[:functions]} functions, #{index.stats[:structs]} structs, #{index.stats[:enums]} enums)"
         warn "Cute Framework revision: #{builder.revision}" if builder.revision
 
-        server = Server.new(index, revision: builder.revision)
-        server.run_stdio
+        Server.new(index, revision: builder.revision).run_stdio
+        0
       end
 
-      def run_http_server
+      def run_http
         require "rackup"
 
         port = @options[:port] || 9292
@@ -118,6 +143,56 @@ module CF
         warn "Web interface available at http://localhost:#{port}/"
         warn "MCP endpoint available at http://localhost:#{port}/http"
         Rackup::Server.start(app: app, Host: host, Port: port, Logger: $stderr)
+        0
+      end
+
+      def run_index
+        cache = IndexCache.new
+        stats = cache.refresh(index_source) { |source| IndexBuilder.new(**source) }.stats
+
+        puts "Indexed #{stats[:total]} items (#{stats[:functions]} functions, #{stats[:structs]} structs, #{stats[:enums]} enums, #{stats[:topics]} topics)"
+        puts "Cute Framework revision: #{cache.revision}" if cache.revision
+        puts "Cached at #{cache.path}"
+        0
+      end
+
+      # Takes --root and --download out of the arguments wherever they stand, leaving the rest for the tool.
+      def take_source_options
+        rest = [] #: Array[String]
+        while (arg = @args.shift)
+          case arg
+          when "-r", "--root" then @options[:root] = @args.shift || raise(OptionParser::MissingArgument, arg)
+          when /\A--root=(.*)\z/ then @options[:root] = $1
+          when "-d", "--download" then @options[:download] = true
+          else rest << arg
+          end
+        end
+        @args.replace(rest)
+      end
+
+      # The tool named by the command, if it names one. Asking loads the tools, which the
+      # other commands have no need of.
+      def find_tool(command)
+        return if command.nil? || COMMANDS.key?(command)
+
+        Tools.all.find { |tool| tool.tool_name == command }
+      end
+
+      # Help describes the tool from its schema alone, so it goes without the index.
+      def run_tool(tool)
+        IndexCache.new.index(index_source) { |source| IndexBuilder.new(**source) } unless @args.intersect?(%w[-h --help])
+        ToolCommand.new(tool).run(@args)
+      end
+
+      # What the user asked to index, by flag or CF_HEADERS_PATH; nil leaves the choice to the
+      # cache. The root is expanded so every spelling of it names the same index.
+      def index_source
+        root = @options[:root] || ENV["CF_HEADERS_PATH"]
+        {root: root && File.expand_path(root), download: @options[:download]} if root || @options[:download]
+      end
+
+      def missing_headers_message(builder)
+        "Headers directory not found: #{builder.headers_path}. Use --root to specify the path to Cute Framework headers, or --download to fetch them from GitHub."
       end
     end
   end

data/lib/cf/mcp/downloader.rb

@@ -63,15 +63,19 @@ module CF
 
       def download_zip(destination, url = CUTE_FRAMEWORK_ZIP_URL)
         uri = URI.parse(url)
+        host = uri.host || raise(DownloadError, "No host in #{url}")
 
-        Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
+        Net::HTTP.start(host, uri.port, use_ssl: true) do |http|
           request = Net::HTTP::Get.new(uri)
+          # @type var response: Net::HTTPResponse
           response = http.request(request)
 
           # Handle redirects (GitHub redirects to codeload.github.com)
           if response.is_a?(Net::HTTPRedirection)
-            redirect_uri = URI.parse(response["location"])
-            Net::HTTP.start(redirect_uri.host, redirect_uri.port, use_ssl: true) do |redirect_http|
+            location = response["location"] || raise(DownloadError, "Redirect from #{url} has no Location header")
+            redirect_uri = URI.parse(location)
+            redirect_host = redirect_uri.host || raise(DownloadError, "No host in redirect to #{location}")
+            Net::HTTP.start(redirect_host, redirect_uri.port, use_ssl: true) do |redirect_http|
               redirect_request = Net::HTTP::Get.new(redirect_uri)
               response = redirect_http.request(redirect_request)
             end
@@ -92,12 +96,12 @@ module CF
         Zip::File.open(zip_path) do |zip_file|
           # The zip contains a top-level directory like "cute_framework-master/"
           # We want to extract "include/" and "docs/topics/" subdirectories
-          top_level_prefix = nil
+          top_level_prefix = nil #: String?
 
           zip_file.each do |entry|
             # 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]
+              top_level_prefix = entry.name[%r{^(cute_framework-[^/]+/)}, 1]
               break
             end
           end

data/lib/cf/mcp/github_client.rb

@@ -25,7 +25,8 @@ module CF
         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|
+        hostname = uri.hostname || raise(ArgumentError, "No host in #{uri}")
+        response = Net::HTTP.start(hostname, uri.port, use_ssl: true) do |http|
           http.request(request)
         end
 

data/lib/cf/mcp/index.rb

@@ -7,6 +7,8 @@ module CF
     class Index
       include Singleton
 
+      ByType = Data.define(:functions, :structs, :enums, :topics)
+
       attr_reader :items, :by_type, :by_category, :topic_references
 
       def initialize
@@ -15,27 +17,28 @@ module CF
 
       def reset!
         @items = {}
-        @by_type = {
-          function: [],
-          struct: [],
-          enum: [],
-          topic: []
-        }
+        @by_type = ByType.new(functions: [], structs: [], enums: [], topics: [])
         @by_category = {}
         @topic_references = {}
       end
 
       def add(item)
         @items[item.name] = item
-        @by_type[item.type] << item if @by_type.key?(item.type)
+
+        case item
+        when Models::FunctionDoc then @by_type.functions << item
+        when Models::StructDoc then @by_type.structs << item
+        when Models::EnumDoc then @by_type.enums << item
+        when Models::TopicDoc
+          @by_type.topics << item
+          # Build reverse reference index for topics
+          build_topic_reverse_index(item)
+        end
 
         if item.category
           @by_category[item.category] ||= []
           @by_category[item.category] << item
         end
-
-        # Build reverse reference index for topics
-        build_topic_reverse_index(item) if item.type == :topic
       end
 
       def find(name)
@@ -73,19 +76,19 @@ module CF
       end
 
       def functions
-        @by_type[:function]
+        @by_type.functions
       end
 
       def structs
-        @by_type[:struct]
+        @by_type.structs
       end
 
       def enums
-        @by_type[:enum]
+        @by_type.enums
       end
 
       def topics
-        @by_type[:topic]
+        @by_type.topics
       end
 
       def topics_ordered
@@ -111,10 +114,10 @@ module CF
       def stats
         {
           total: @items.size,
-          functions: @by_type[:function].size,
-          structs: @by_type[:struct].size,
-          enums: @by_type[:enum].size,
-          topics: @by_type[:topic].size,
+          functions: @by_type.functions.size,
+          structs: @by_type.structs.size,
+          enums: @by_type.enums.size,
+          topics: @by_type.topics.size,
           categories: @by_category.size
         }
       end

data/lib/cf/mcp/index_builder.rb

@@ -23,14 +23,13 @@ module CF
         end
 
         # Parse topics if available
-        topics_path = find_topics_path(headers_path)
-        if topics_path && File.directory?(topics_path)
+        if (path = topics_path)
           topic_parser = TopicParser.new
-          topic_parser.parse_directory(topics_path).each do |topic|
+          topic_parser.parse_directory(path).each do |topic|
             refine_topic_references(topic, index)
             index.add(topic)
           end
-          yield(:topics_indexed, topics_path, index.stats[:topics]) if block_given?
+          yield(:topics_indexed, path, index.stats[:topics]) if block_given?
         end
 
         index
@@ -40,6 +39,11 @@ module CF
         File.directory?(headers_path)
       end
 
+      # The topic guides directory, when the checkout has one.
+      def topics_path
+        @topics_path ||= find_topics_path(headers_path)
+      end
+
       private
 
       def resolve_headers_path(root:, download:)