cf-mcp 0.9.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4fdaf411a4f3224a85c8399b9bd6964688ad3a6e8ce68ab61abbd76c32833c8e
+  data.tar.gz: b23b96e53d98c56b9fc3364ec76a3a67c50df807b152d8b0e43f1f07db626d2e
+SHA512:
+  metadata.gz: 23b5cfa8ed27a9f71d8c031cefabad9b12c83ae5e109f9306b2456fcc0979c305287bcfde0e0dd2581009f84683b78b0e16630a52e8c665aba15c0dc26639453
+  data.tar.gz: 1e1785c0bac762cf2b77dfa4bf26faa4e9093124ccf2be74972cc34552e315ca20dbe9a530136b8b34f485d6b1ae727bd617028e5ef3bdad3feb6684787d1fb6

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Piotr Usewicz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,34 @@
+LICENSE.txt
+Manifest.txt
+README.md
+Rakefile
+config.ru
+exe/cf-mcp
+lib/cf/mcp.rb
+lib/cf/mcp/cli.rb
+lib/cf/mcp/downloader.rb
+lib/cf/mcp/index.rb
+lib/cf/mcp/models/doc_item.rb
+lib/cf/mcp/models/enum_doc.rb
+lib/cf/mcp/models/function_doc.rb
+lib/cf/mcp/models/struct_doc.rb
+lib/cf/mcp/models/topic_doc.rb
+lib/cf/mcp/parser.rb
+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/tools/find_related.rb
+lib/cf/mcp/tools/get_details.rb
+lib/cf/mcp/tools/get_topic.rb
+lib/cf/mcp/tools/list_category.rb
+lib/cf/mcp/tools/list_topics.rb
+lib/cf/mcp/tools/member_search.rb
+lib/cf/mcp/tools/parameter_search.rb
+lib/cf/mcp/tools/search_enums.rb
+lib/cf/mcp/tools/search_functions.rb
+lib/cf/mcp/tools/search_structs.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

@@ -0,0 +1,52 @@
+# CF::MCP
+
+CF::MCP is an MCP server providing documentation tools for the [Cute Framework](https://github.com/RandyGaul/cute_framework), a C/C++ 2D game framework.
+
+The MCP server supports three modes of operation:
+
+- **STDIO Mode**: Communicates via standard input and output streams, suitable for integration with CLI tools and desktop applications.
+- **HTTP Mode**: Operates as a stateless HTTP server, suitable for simple request/response interactions and multi-node deployments.
+- **SSE Mode**: Operates as a stateful HTTP server with Server-Sent Events support, enabling real-time notifications and streaming responses.
+
+## Features
+
+- **Documentation Generation**: Automatically generates documentation for Cute Framework projects by indexing the the header files and extracting the documentation from the comments.
+- **Search Functionality**: Provides a search feature to quickly find structs, classes, functions, and other elements within the documentation.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add cf-mcp
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install cf-mcp
+```
+
+## Usage
+
+To start the MCP server, run the following command in your terminal:
+
+```bash
+cf-mcp stdio --root /path/to/cute_framework_project  # STDIO mode
+cf-mcp http --root /path/to/cute_framework_project   # HTTP mode (stateless)
+cf-mcp sse --root /path/to/cute_framework_project    # SSE mode (stateful, real-time)
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/pusewicz/cf-mcp.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+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 fly.toml Procfile Dockerfile .dockerignore .claude/]
+
+  files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
+    ls.readlines("\x0", chomp: true)
+  end.reject { |f| f.start_with?(*ignore_patterns) }.sort
+
+  # Add Manifest.txt itself so it's included in the gem
+  files << "Manifest.txt" unless files.include?("Manifest.txt")
+  files.sort!
+
+  File.write("Manifest.txt", files.join("\n") + "\n")
+  puts "Generated Manifest.txt with #{files.size} files"
+end
+
+task default: %i[test standard manifest]
+
+desc "Deploy to Fly.io (runs tests and linting first)"
+task deploy: %i[test standard] do
+  sh "fly deploy"
+end
+
+desc "Create a git tag for the current version"
+task :tag do
+  require_relative "lib/cf/mcp/version"
+  version = CF::MCP::VERSION
+  tag = "v#{version}"
+
+  if system("git", "rev-parse", tag, out: File::NULL, err: File::NULL)
+    puts "Tag #{tag} already exists"
+  else
+    sh "git", "tag", "-a", tag, "-m", "Release #{version}"
+    puts "Created tag #{tag}"
+  end
+end
+
+desc "Create and push git tag for current version"
+task "release:tag" => %i[test standard tag] do
+  require_relative "lib/cf/mcp/version"
+  tag = "v#{CF::MCP::VERSION}"
+  sh "git", "push", "origin", tag
+  puts "Pushed #{tag} to origin"
+end

data/config.ru

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "lib/cf/mcp"
+
+# Download headers from GitHub if not already present
+warn "Initializing CF::MCP server..."
+downloader = CF::MCP::Downloader.new
+headers_path = downloader.download_and_extract
+warn "Using headers from: #{headers_path}"
+
+# Build the index
+warn "Parsing headers..."
+parser = CF::MCP::Parser.new
+index = CF::MCP::Index.new
+
+parser.parse_directory(headers_path).each do |item|
+  index.add(item)
+end
+
+warn "Indexed #{index.stats[:total]} items (#{index.stats[:functions]} functions, #{index.stats[:structs]} structs, #{index.stats[:enums]} enums)"
+
+# Create and run the combined server with both SSE and HTTP transports
+# - / and /sse - SSE transport (stateful, for Claude Desktop)
+# - /http - HTTP transport (stateless, for simple integrations)
+server = CF::MCP::CombinedServer.new(index)
+run server.rack_app

data/exe/cf-mcp

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "cf/mcp"
+
+CF::MCP::CLI.new(ARGV).run

data/lib/cf/mcp/cli.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "parser"
+require_relative "topic_parser"
+require_relative "index"
+require_relative "server"
+require_relative "downloader"
+
+module CF
+  module MCP
+    class CLI
+      DEFAULT_HEADERS_PATH = File.expand_path("~/Work/GitHub/pusewicz/cute_framework/include")
+
+      def initialize(args)
+        @args = args
+        @options = parse_args
+      end
+
+      def run
+        case @options[:command]
+        when :stdio
+          run_server(:stdio)
+        when :http
+          run_server(:http)
+        when :sse
+          run_server(:sse)
+        when :combined
+          run_combined_server
+        when :help
+          puts @option_parser
+        else
+          warn "Unknown command. Use --help for usage information."
+          exit 1
+        end
+      end
+
+      private
+
+      def parse_args
+        options = {
+          command: nil,
+          port: nil,
+          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 (stateless)"
+          opts.separator "  sse      Run as SSE server (stateful with real-time updates)"
+          opts.separator "  combined Run as combined server (SSE + HTTP with web interface)"
+          opts.separator ""
+          opts.separator "Options:"
+
+          opts.on("-r", "--root PATH", "Path to Cute Framework headers directory") do |path|
+            options[:root] = path
+          end
+
+          opts.on("-p", "--port PORT", Integer, "Port for HTTP/SSE server (default: 9292 for HTTP, 9393 for SSE)") do |port|
+            options[:port] = port
+          end
+
+          opts.on("-d", "--download", "Download Cute Framework headers from GitHub") do
+            options[:download] = true
+          end
+
+          opts.on("-h", "--help", "Show this help message") do
+            options[:command] = :help
+          end
+
+          opts.on("-v", "--version", "Show version") do
+            puts "cf-mcp #{CF::MCP::VERSION}"
+            exit 0
+          end
+        end
+
+        @option_parser.parse!(@args)
+
+        # Parse command from remaining args
+        if options[:command].nil? && !@args.empty?
+          command = @args.shift.to_sym
+          options[:command] = command if [:stdio, :http, :sse, :combined].include?(command)
+        end
+
+        options[:command] ||= :help
+        options
+      end
+
+      def run_server(mode)
+        headers_path = resolve_headers_path
+
+        unless File.directory?(headers_path)
+          warn "Error: Headers directory not found: #{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
+
+        warn "Parsing headers from: #{headers_path}"
+        index = build_index(headers_path)
+        warn "Indexed #{index.stats[:total]} items (#{index.stats[:functions]} functions, #{index.stats[:structs]} structs, #{index.stats[:enums]} enums)"
+
+        server = Server.new(index)
+
+        case mode
+        when :stdio
+          server.run_stdio
+        when :http
+          port = @options[:port] || 9292
+          server.run_http(port: port)
+        when :sse
+          port = @options[:port] || 9393
+          server.run_sse(port: port)
+        end
+      end
+
+      def run_combined_server
+        require "rack"
+        require "rackup"
+
+        headers_path = resolve_headers_path
+
+        unless File.directory?(headers_path)
+          warn "Error: Headers directory not found: #{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
+
+        warn "Parsing headers from: #{headers_path}"
+        index = build_index(headers_path)
+        warn "Indexed #{index.stats[:total]} items (#{index.stats[:functions]} functions, #{index.stats[:structs]} structs, #{index.stats[:enums]} enums)"
+
+        port = @options[:port] || 9292
+        server = CombinedServer.new(index)
+        app = server.rack_app
+
+        warn "Starting combined server on port #{port}..."
+        warn "Web interface available at http://localhost:#{port}/"
+        Rackup::Server.start(app: app, Port: port, Logger: $stderr)
+      end
+
+      def resolve_headers_path
+        return @options[:root] if @options[:root]
+        return ENV["CF_HEADERS_PATH"] if ENV["CF_HEADERS_PATH"]
+
+        if @options[:download]
+          warn "Downloading Cute Framework headers from GitHub..."
+          downloader = Downloader.new
+          path = downloader.download_and_extract
+          warn "Downloaded headers to: #{path}"
+          return path
+        end
+
+        DEFAULT_HEADERS_PATH
+      end
+
+      def build_index(headers_path)
+        parser = Parser.new
+        index = Index.new
+
+        parser.parse_directory(headers_path).each do |item|
+          index.add(item)
+        end
+
+        # Parse topics if available
+        topics_path = find_topics_path(headers_path)
+        if topics_path && File.directory?(topics_path)
+          topic_parser = TopicParser.new
+          topic_parser.parse_directory(topics_path).each do |topic|
+            refine_topic_references(topic, index)
+            index.add(topic)
+          end
+          warn "Indexed #{index.stats[:topics]} topics from: #{topics_path}"
+        end
+
+        index
+      end
+
+      def find_topics_path(headers_path)
+        # If headers_path is .../cute_framework/include, topics is at .../cute_framework/docs/topics
+        base = File.dirname(headers_path)
+        topics_path = File.join(base, "docs", "topics")
+        return topics_path if File.directory?(topics_path)
+
+        # Alternative: topics directly under headers parent
+        topics_path = File.join(base, "topics")
+        return topics_path if File.directory?(topics_path)
+
+        nil
+      end
+
+      def refine_topic_references(topic, index)
+        # Move items from struct_references to enum_references if they're actually enums
+        topic.struct_references.dup.each do |ref|
+          item = index.find(ref)
+          next unless item
+
+          if item.type == :enum
+            topic.struct_references.delete(ref)
+            topic.enum_references << ref unless topic.enum_references.include?(ref)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cf/mcp/downloader.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+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"
+      DEFAULT_DOWNLOAD_DIR = File.join(Dir.tmpdir, "cf-mcp-#{VERSION}")
+
+      class DownloadError < StandardError; end
+
+      def initialize(download_dir: DEFAULT_DOWNLOAD_DIR)
+        @download_dir = download_dir
+      end
+
+      def download_and_extract
+        FileUtils.mkdir_p(@download_dir)
+
+        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")
+
+        # Return existing path if already downloaded
+        if File.directory?(include_path) && !Dir.empty?(include_path)
+          return include_path
+        end
+
+        download_zip(zip_path)
+        extract_directories(zip_path, base_path)
+
+        include_path
+      end
+
+      private
+
+      def download_zip(destination)
+        uri = URI.parse(CUTE_FRAMEWORK_ZIP_URL)
+
+        Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
+          request = Net::HTTP::Get.new(uri)
+          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|
+              redirect_request = Net::HTTP::Get.new(redirect_uri)
+              response = redirect_http.request(redirect_request)
+            end
+          end
+
+          unless response.is_a?(Net::HTTPSuccess)
+            raise DownloadError, "Failed to download Cute Framework: #{response.code} #{response.message}"
+          end
+
+          File.binwrite(destination, response.body)
+        end
+      end
+
+      def extract_directories(zip_path, base_path)
+        FileUtils.rm_rf(base_path)
+        FileUtils.mkdir_p(base_path)
+
+        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
+
+          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]
+              break
+            end
+          end
+
+          raise DownloadError, "Could not find include directory in zip" unless top_level_prefix
+
+          # Directories to extract
+          extract_prefixes = [
+            "#{top_level_prefix}include/",
+            "#{top_level_prefix}docs/topics/"
+          ]
+
+          zip_file.each do |entry|
+            extract_prefix = extract_prefixes.find { |p| entry.name.start_with?(p) }
+            next unless extract_prefix
+
+            # Calculate the relative path from the top-level directory
+            relative_path = entry.name.sub(top_level_prefix, "")
+            next if relative_path.empty?
+
+            target_path = File.join(base_path, relative_path)
+
+            if entry.directory?
+              FileUtils.mkdir_p(target_path)
+            else
+              FileUtils.mkdir_p(File.dirname(target_path))
+              entry.extract(target_path)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cf/mcp/index.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module CF
+  module MCP
+    class Index
+      attr_reader :items, :by_type, :by_category, :topic_references
+
+      def initialize
+        @items = {}
+        @by_type = {
+          function: [],
+          struct: [],
+          enum: [],
+          topic: []
+        }
+        @by_category = {}
+        @topic_references = {}
+      end
+
+      def add(item)
+        @items[item.name] = item
+        @by_type[item.type] << item if @by_type.key?(item.type)
+
+        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)
+        @items[name]
+      end
+
+      def brief_for(name)
+        item = find(name)
+        return nil unless item
+        {name: item.name, type: item.type, brief: item.brief}
+      end
+
+      def search(query, type: nil, category: nil, limit: 20)
+        results = all_items
+
+        # Filter by type
+        if type
+          type_sym = type.to_sym
+          results = results.select { |item| item.type == type_sym }
+        end
+
+        # Filter by category
+        if category
+          results = results.select { |item| item.category == category }
+        end
+
+        # Filter by query and sort by relevance
+        if query && !query.empty?
+          results = results
+            .select { |item| item.matches?(query) }
+            .sort_by { |item| -item.relevance_score(query) }
+        end
+
+        results.take(limit)
+      end
+
+      def functions
+        @by_type[:function]
+      end
+
+      def structs
+        @by_type[:struct]
+      end
+
+      def enums
+        @by_type[:enum]
+      end
+
+      def topics
+        @by_type[:topic]
+      end
+
+      def topics_ordered
+        topics.sort_by { |t| t.reading_order || Float::INFINITY }
+      end
+
+      def topics_for(api_name)
+        (@topic_references[api_name] || []).map { |name| find(name) }.compact
+      end
+
+      def categories
+        @by_category.keys.sort
+      end
+
+      def items_in_category(category)
+        @by_category[category] || []
+      end
+
+      def size
+        @items.size
+      end
+
+      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,
+          categories: @by_category.size
+        }
+      end
+
+      private
+
+      def all_items
+        @items.values
+      end
+
+      def build_topic_reverse_index(topic)
+        topic.all_api_references.each do |ref_name|
+          @topic_references[ref_name] ||= []
+          @topic_references[ref_name] << topic.name unless @topic_references[ref_name].include?(topic.name)
+        end
+      end
+    end
+  end
+end