cf-mcp 0.10.1 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4766c9f8bb80d8be199403996163b2e21b7898ea2a8f14e0426d75bbf620364c
-  data.tar.gz: bd23236c47957a598c6b69c3f7d3d738d40701ceb2dba97b3afc84a94421ccb7
+  metadata.gz: 30c68992a64d36c8265af4bdcd018dd116c7d2e59479ab1fd83213896028b86d
+  data.tar.gz: 4a4e5b715cdca959296e1043bf3173a2c4c314a40ab5c1cb76154dd20b823557
 SHA512:
-  metadata.gz: 1ea224066e2bb647782d8acc1c5c63855b11eafa4b31c6f649e77b74675443d8c4495b029ba6b0b21c4c85b34cf392f562d80c61d1a2d76d53429d6d94ff3732
-  data.tar.gz: 6158b7385eac465183b837e058042f2d648ab108d5a3b9deacadc7bdbe1e013d3bfec1eca58ecd2df1e2c8628b431a2c168d207035ba2bcd39657c6ae63c7992
+  metadata.gz: 1704a19c8b49fb37258b247e5689a15f7ed67a2cce9ff226ee5ac0c4689dbc45b547150d426cc91e15e09a2f36405752f58a98e5b14596e5282dc7b9784c4e15
+  data.tar.gz: d1c5c7f81871cddb2f0a1bb81b98272b7d3d07a8d7d40bfafd08c338ef2e6b8073d296407ae2dd74575b7ec2738864c1c5bd941408f9f681e373002af363a70d

data/CHANGELOG.md

@@ -5,19 +5,41 @@ 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).
 
+## [0.12.1] - 2026-01-14
+
+### Changed
+
+- Refactored tool classes to use shared `ResponseHelpers` module, removing duplicate code
+- Extracted `IndexBuilder` class to consolidate index building logic from CLI and HTTPServer
+- Extracted `SearchResultFormatter` module for consistent search result formatting
+- Simplified model `to_text()` methods using template method pattern in `DocItem` base class
+
+## [0.12.0] - 2026-01-14
+
+### Changed
+
+- Renamed `CombinedServer` to `HTTPServer` for clarity
+- Updated config.ru to use the new `HTTPServer` class
+
+### Removed
+
+- SSE transport endpoint (HTTP streamable transport is now the only HTTP option)
+
 ## [0.10.1] - 2026-01-14
 
 ### Added
 
 - `--host` CLI option for binding address (defaults to `0.0.0.0`)
+- `CombinedServer.build_rack_app` class method for shared boot logic
 
 ### Changed
 
-- Unified boot process: Procfile now uses `cf-mcp combined --download` instead of rackup
+- Unified boot process: config.ru and CLI now share the same initialization logic
+- Simplified config.ru to a single line using `CombinedServer.build_rack_app`
 
 ### Removed
 
-- `config.ru` (no longer needed, CLI handles all server modes)
+- `Procfile` (Fly.io uses config.ru directly)
 
 ## [0.10.0] - 2026-01-14
 
@@ -126,6 +148,8 @@ 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.12.1]: https://github.com/pusewicz/cf-mcp/compare/v0.12.0...v0.12.1
+[0.12.0]: https://github.com/pusewicz/cf-mcp/compare/v0.10.1...v0.12.0
 [0.10.1]: https://github.com/pusewicz/cf-mcp/compare/v0.10.0...v0.10.1
 [0.10.0]: https://github.com/pusewicz/cf-mcp/compare/v0.9.3...v0.10.0
 [0.9.3]: https://github.com/pusewicz/cf-mcp/compare/v0.9.2...v0.9.3

data/Manifest.txt

@@ -3,11 +3,13 @@ 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/index_builder.rb
 lib/cf/mcp/models/doc_item.rb
 lib/cf/mcp/models/enum_doc.rb
 lib/cf/mcp/models/function_doc.rb
@@ -25,8 +27,10 @@ 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/response_helpers.rb
 lib/cf/mcp/tools/search_enums.rb
 lib/cf/mcp/tools/search_functions.rb
+lib/cf/mcp/tools/search_result_formatter.rb
 lib/cf/mcp/tools/search_structs.rb
 lib/cf/mcp/tools/search_tool.rb
 lib/cf/mcp/topic_parser.rb

data/README.md

@@ -2,11 +2,10 @@
 
 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:
+The MCP server supports two 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.
+- **HTTP Mode**: Operates as an HTTP server with a web interface at the root and MCP endpoint at `/http`.
 
 ## Features
 
@@ -33,8 +32,7 @@ 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)
+cf-mcp http --root /path/to/cute_framework_project   # HTTP mode with web UI
 ```
 
 ## Development

data/config.ru

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "lib/cf/mcp"
+
+# Build and run the HTTP server with automatic header downloading
+run CF::MCP::HTTPServer.build_rack_app(download: true)

data/lib/cf/mcp/cli.rb

@@ -1,17 +1,12 @@
 # frozen_string_literal: true
 
 require "optparse"
-require_relative "parser"
-require_relative "topic_parser"
-require_relative "index"
+require_relative "index_builder"
 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
@@ -22,11 +17,7 @@ module CF
         when :stdio
           run_server(:stdio)
         when :http
-          run_server(:http)
-        when :sse
-          run_server(:sse)
-        when :combined
-          run_combined_server
+          run_http_server
         when :help
           puts @option_parser
         else
@@ -51,9 +42,7 @@ module CF
           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 "  http     Run as HTTP server with web interface"
           opts.separator ""
           opts.separator "Options:"
 
@@ -61,7 +50,7 @@ module CF
             options[:root] = path
           end
 
-          opts.on("-p", "--port PORT", Integer, "Port for HTTP/SSE server (default: 9292 for HTTP, 9393 for SSE)") do |port|
+          opts.on("-p", "--port PORT", Integer, "Port for HTTP server (default: 9292)") do |port|
             options[:port] = port
           end
 
@@ -88,7 +77,7 @@ module CF
         # 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)
+          options[:command] = command if [:stdio, :http].include?(command)
         end
 
         options[:command] ||= :help
@@ -96,122 +85,41 @@ module CF
       end
 
       def run_server(mode)
-        headers_path = resolve_headers_path
+        builder = IndexBuilder.new(root: @options[:root], download: @options[:download])
 
-        unless File.directory?(headers_path)
-          warn "Error: Headers directory not found: #{headers_path}"
+        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
 
-        warn "Parsing headers from: #{headers_path}"
-        index = build_index(headers_path)
+        warn "Parsing headers from: #{builder.headers_path}"
+        index = builder.build do |event, path, count|
+          warn "Indexed #{count} topics from: #{path}" if event == :topics_indexed
+        end
         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
+        server.run_stdio
       end
 
-      def run_combined_server
-        require "rack"
+      def run_http_server
         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
         host = @options[:host]
-        server = CombinedServer.new(index)
-        app = server.rack_app
 
-        warn "Starting combined server on #{host}:#{port}..."
+        app = HTTPServer.build_rack_app(
+          root: @options[:root],
+          download: @options[:download]
+        )
+
+        warn "Starting HTTP server on #{host}:#{port}..."
         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)
       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/index_builder.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "parser"
+require_relative "topic_parser"
+require_relative "index"
+require_relative "downloader"
+
+module CF
+  module MCP
+    class IndexBuilder
+      DEFAULT_HEADERS_PATH = File.expand_path("~/Work/GitHub/pusewicz/cute_framework/include")
+
+      attr_reader :headers_path
+
+      def initialize(root: nil, download: false)
+        @headers_path = resolve_headers_path(root: root, download: download)
+      end
+
+      def build
+        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
+          yield(:topics_indexed, topics_path, index.stats[:topics]) if block_given?
+        end
+
+        index
+      end
+
+      def valid?
+        File.directory?(headers_path)
+      end
+
+      private
+
+      def resolve_headers_path(root:, download:)
+        return root if root
+        return ENV["CF_HEADERS_PATH"] if ENV["CF_HEADERS_PATH"]
+
+        if 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 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/models/doc_item.rb

@@ -128,6 +128,23 @@ module CF
         end
 
         def to_text(detailed: false, index: nil)
+          lines = []
+          lines.concat(build_header_lines)
+          lines.concat(build_description_lines)
+
+          if detailed
+            lines.concat(build_type_specific_lines)
+            lines.concat(build_remarks_lines)
+            lines.concat(build_example_lines)
+            lines.concat(build_related_lines(index))
+          end
+
+          lines.join("\n")
+        end
+
+        protected
+
+        def build_header_lines
           lines = []
           lines << "# #{name}"
           lines << ""
@@ -140,36 +157,44 @@ module CF
             lines << "- **Implementation:** #{urls[:impl_raw]}"
           end
           lines << ""
+          lines
+        end
+
+        def build_description_lines
+          lines = []
           lines << "## Description"
           lines << brief if brief
           lines << ""
+          lines
+        end
 
-          if detailed
-            if remarks && !remarks.empty?
-              lines << "## Remarks"
-              lines << remarks
-              lines << ""
-            end
+        def build_type_specific_lines
+          [] # Override in subclasses
+        end
 
-            if example && !example.empty?
-              lines << "## Example"
-              lines << example_brief if example_brief
-              lines << "```c"
-              lines << example
-              lines << "```"
-              lines << ""
-            end
+        def build_remarks_lines
+          return [] unless remarks && !remarks.empty?
+          ["## Remarks", remarks, ""]
+        end
 
-            if related && !related.empty?
-              lines << "## Related"
-              lines << format_related_items(index)
-              lines << ""
-            end
-          end
+        def build_example_lines
+          return [] unless example && !example.empty?
+          lines = ["## Example"]
+          lines << example_brief if example_brief
+          lines << "```c"
+          lines << example
+          lines << "```"
+          lines << ""
+          lines
+        end
 
-          lines.join("\n")
+        def build_related_lines(index)
+          return [] unless related && !related.empty?
+          ["## Related", format_related_items(index), ""]
         end
 
+        public
+
         def format_related_items(index)
           return related.join(", ") unless index
 

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

@@ -24,58 +24,21 @@ module CF
           ).compact
         end
 
-        def to_text(detailed: false, index: nil)
+        protected
+
+        def build_type_specific_lines
+          return [] unless entries && !entries.empty?
+
           lines = []
-          lines << "# #{name}"
+          lines << "## Values"
           lines << ""
-          lines << "- **Type:** enum"
-          lines << "- **Category:** #{category}" if category
-          if source_file
-            urls = source_urls
-            lines << "- **Source:** [include/#{source_file}](#{urls[:blob]})"
-            lines << "- **Raw:** #{urls[:raw]}"
-            lines << "- **Implementation:** #{urls[:impl_raw]}"
+          lines << "| Name | Value | Description |"
+          lines << "| --- | --- | --- |"
+          entries.each do |entry|
+            lines << "| `#{entry.name}` | #{entry.value} | #{entry.description} |"
           end
           lines << ""
-          lines << "## Description"
-          lines << brief if brief
-          lines << ""
-
-          if detailed
-            if entries && !entries.empty?
-              lines << "## Values"
-              lines << ""
-              lines << "| Name | Value | Description |"
-              lines << "| --- | --- | --- |"
-              entries.each do |entry|
-                lines << "| `#{entry.name}` | #{entry.value} | #{entry.description} |"
-              end
-              lines << ""
-            end
-
-            if remarks && !remarks.empty?
-              lines << "## Remarks"
-              lines << remarks
-              lines << ""
-            end
-
-            if example && !example.empty?
-              lines << "## Example"
-              lines << example_brief if example_brief
-              lines << "```c"
-              lines << example
-              lines << "```"
-              lines << ""
-            end
-
-            if related && !related.empty?
-              lines << "## Related"
-              lines << format_related_items(index)
-              lines << ""
-            end
-          end
-
-          lines.join("\n")
+          lines
         end
       end
     end

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

@@ -38,71 +38,48 @@ module CF
 
         def to_text(detailed: false, index: nil)
           lines = []
-          lines << "# #{name}"
-          lines << ""
-          lines << "- **Type:** function"
-          lines << "- **Category:** #{category}" if category
-          if source_file
-            urls = source_urls
-            lines << "- **Source:** [include/#{source_file}](#{urls[:blob]})"
-            lines << "- **Raw:** #{urls[:raw]}"
-            lines << "- **Implementation:** #{urls[:impl_raw]}"
-          end
-          lines << ""
+          lines.concat(build_header_lines)
+          lines.concat(build_signature_lines)
+          lines.concat(build_description_lines)
 
-          if signature
-            lines << "## Signature"
-            lines << "```c"
-            lines << signature
-            lines << "```"
-            lines << ""
+          if detailed
+            lines.concat(build_type_specific_lines)
+            lines.concat(build_remarks_lines)
+            lines.concat(build_example_lines)
+            lines.concat(build_related_lines(index))
           end
 
-          lines << "## Description"
-          lines << brief if brief
-          lines << ""
+          lines.join("\n")
+        end
 
-          if detailed
-            if parameters && !parameters.empty?
-              lines << "## Parameters"
-              lines << ""
-              lines << "| Parameter | Description |"
-              lines << "| --- | --- |"
-              parameters.each do |param|
-                lines << "| `#{param.name}` | #{param.description} |"
-              end
-              lines << ""
-            end
+        protected
 
-            if return_value && !return_value.empty?
-              lines << "## Return Value"
-              lines << return_value
-              lines << ""
-            end
+        def build_signature_lines
+          return [] unless signature
+          ["## Signature", "```c", signature, "```", ""]
+        end
 
-            if remarks && !remarks.empty?
-              lines << "## Remarks"
-              lines << remarks
-              lines << ""
-            end
+        def build_type_specific_lines
+          lines = []
 
-            if example && !example.empty?
-              lines << "## Example"
-              lines << example_brief if example_brief
-              lines << "```c"
-              lines << example
-              lines << "```"
-              lines << ""
+          if parameters && !parameters.empty?
+            lines << "## Parameters"
+            lines << ""
+            lines << "| Parameter | Description |"
+            lines << "| --- | --- |"
+            parameters.each do |param|
+              lines << "| `#{param.name}` | #{param.description} |"
             end
+            lines << ""
+          end
 
-            if related && !related.empty?
-              lines << "## Related"
-              lines << format_related_items(index)
-              lines << ""
-            end
+          if return_value && !return_value.empty?
+            lines << "## Return Value"
+            lines << return_value
+            lines << ""
           end
 
-          lines.join("\n")
+          lines
         end
       end
     end