cf-mcp 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa40d95e95c2179eeaa55f22e374232510ee6857aec12ca73ab5c438d9808f16
-  data.tar.gz: 1047aa59ffc741fb792778037a9e958ee3af42fec332a0653882a351277ef10f
+  metadata.gz: 0f3d843ae9e0087f798cad60be61d347da0db7c1f26e5bee5050eccda2a38b29
+  data.tar.gz: 98735400ef25d3a51d6d984a0daf12141c1c96b6843922069d71bb24a4183bdc
 SHA512:
-  metadata.gz: dac224a9ccf242b04a8d8a801b148f71bf1e9326bf8550560045b2e34ef8501e60f44a7bfd0ea14b06d762c0ddde9b82e50e4896dd2dd7a2489ee823658f9fa3
-  data.tar.gz: 8ebd60174ed5d853121255db222fb34ee4baa7c033d2ebfdd0fc246d9f5cdfe5cf824a18926e49591c34b052154fdd78623e5b25675bcf4b09521f6107260796
+  metadata.gz: fb5143e02aca5453221893bdabd3cb945912cfa83c7693f34d0cba99ea1cbde14a93d4238d3dfb92ab1e39026f5b98ab416de2a40eb68f262745f028e6aecf68
+  data.tar.gz: 918e16127b4a29c8e0d33fe162b5d1788d14c28f3e1c55774d97204ad1805a38c1407f6d10b07072fe9b55c1998436f833fb957ee4f3739434887e94eea84f07

data/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.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: config.ru and CLI now share the same initialization logic
+- Simplified config.ru to a single line using `CombinedServer.build_rack_app`
+
+### Removed
+
+- `Procfile` (Fly.io uses config.ru directly)
+
 ## [0.10.0] - 2026-01-14
 
 ### Added
@@ -112,6 +139,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.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
 [0.9.2]: https://github.com/pusewicz/cf-mcp/compare/v0.9.1...v0.9.2

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

@@ -2,25 +2,5 @@
 
 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
+# 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

@@ -22,11 +22,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
@@ -41,6 +37,7 @@ module CF
         options = {
           command: nil,
           port: nil,
+          host: "0.0.0.0",
           root: nil,
           download: false
         }
@@ -50,9 +47,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:"
 
@@ -60,10 +55,14 @@ 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
 
+          opts.on("-H", "--host HOST", "Host to bind to (default: 0.0.0.0)") do |host|
+            options[:host] = host
+          end
+
           opts.on("-d", "--download", "Download Cute Framework headers from GitHub") do
             options[:download] = true
           end
@@ -83,7 +82,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
@@ -105,43 +104,24 @@ module CF
         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
-        server = CombinedServer.new(index)
-        app = server.rack_app
+        host = @options[:host]
+
+        app = HTTPServer.build_rack_app(
+          root: @options[:root],
+          download: @options[:download]
+        )
 
-        warn "Starting combined server on port #{port}..."
+        warn "Starting HTTP server on #{host}:#{port}..."
         warn "Web interface available at http://localhost:#{port}/"
-        Rackup::Server.start(app: app, Port: port, Logger: $stderr)
+        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

data/lib/cf/mcp/server.rb

@@ -84,59 +84,93 @@ module CF
         transport = ::MCP::Server::Transports::StdioTransport.new(@server)
         transport.open
       end
+    end
 
-      def run_http(port: 9292)
-        require "rackup"
+    # HTTP server with web interface at root and MCP endpoint at /http
+    class HTTPServer
+      # Build a rack app with automatic header downloading and indexing
+      # This is the shared entry point for both config.ru and CLI
+      def self.build_rack_app(root: nil, download: false)
+        require_relative "parser"
+        require_relative "topic_parser"
+        require_relative "index"
+        require_relative "downloader"
 
-        app = http_app
-        warn "Starting HTTP server on port #{port}..."
-        warn "Index contains #{@index.size} items"
-        Rackup::Server.start(app: app, Port: port, Logger: $stderr)
-      end
+        headers_path = resolve_headers_path(root: root, download: download)
 
-      def http_app
-        require "rack"
+        unless File.directory?(headers_path)
+          raise "Headers directory not found: #{headers_path}. Use root: or download: true"
+        end
 
-        transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(@server, stateless: true)
-        @server.transport = transport
+        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)"
 
-        build_rack_app(transport)
+        new(index).rack_app
       end
 
-      def run_sse(port: 9393)
-        require "rack"
-        require "rackup"
+      def self.resolve_headers_path(root:, download:)
+        return root if root
+        return ENV["CF_HEADERS_PATH"] if ENV["CF_HEADERS_PATH"]
 
-        transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(@server)
-        @server.transport = transport
+        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
 
-        app = build_rack_app(transport)
-        warn "Starting SSE server on port #{port}..."
-        warn "Index contains #{@index.size} items"
-        Rackup::Server.start(app: app, Port: port, Logger: $stderr)
+        File.expand_path("~/Work/GitHub/pusewicz/cute_framework/include")
       end
 
-      private
+      def self.build_index(headers_path)
+        parser = Parser.new
+        index = Index.new
 
-      def build_rack_app(transport)
-        Rack::Builder.new do
-          use Rack::CommonLogger
-          run ->(env) { transport.handle_request(Rack::Request.new(env)) }
+        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 sse_app
-        require "rack"
+      def self.find_topics_path(headers_path)
+        base = File.dirname(headers_path)
+        topics_path = File.join(base, "docs", "topics")
+        return topics_path if File.directory?(topics_path)
 
-        transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(@server)
-        @server.transport = transport
+        topics_path = File.join(base, "topics")
+        return topics_path if File.directory?(topics_path)
 
-        build_rack_app(transport)
+        nil
       end
-    end
 
-    # Combined server that exposes both SSE and HTTP transports under different paths
-    class CombinedServer
+      def self.refine_topic_references(topic, index)
+        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
+
+      private_class_method :resolve_headers_path, :build_index, :find_topics_path, :refine_topic_references
+
       def initialize(index)
         @index = index
       end
@@ -144,22 +178,16 @@ 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, Last-Event-ID",
+        "access-control-allow-headers" => "Content-Type, Accept, Mcp-Session-Id",
         "access-control-expose-headers" => "Mcp-Session-Id"
       }.freeze
 
       def rack_app
         require "rack"
 
-        # Create separate server instances for each transport
-        sse_server = create_mcp_server
-        http_server = create_mcp_server
-
-        sse_transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(sse_server)
-        sse_server.transport = sse_transport
-
-        http_transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(http_server, stateless: true)
-        http_server.transport = http_transport
+        mcp_server = create_mcp_server
+        http_transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(mcp_server, stateless: true)
+        mcp_server.transport = http_transport
 
         landing_page = build_landing_page
         index = @index
@@ -180,17 +208,16 @@ module CF
           when %r{^/\.well-known/}
             # OAuth discovery - return 404 to indicate no OAuth required
             [404, {"content-type" => "application/json"}, ['{"error":"Not found"}']]
-          when %r{^/sse(/|$)}
-            sse_transport.handle_request(request)
           when %r{^/http(/|$)}
             http_transport.handle_request(request)
           else
-            # Default route - show landing page for browsers, SSE for MCP clients
+            # Default route - show landing page for browsers
             accept = request.get_header("HTTP_ACCEPT") || ""
             if request.get? && accept.include?("text/html")
               [200, {"content-type" => "text/html; charset=utf-8"}, [landing_page.call(index, tools)]]
             else
-              sse_transport.handle_request(request)
+              # For non-browser clients at root, redirect to /http
+              [301, {"location" => "/http", "content-type" => "text/plain"}, ["Redirecting to /http"]]
             end
           end
 

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

@@ -37,13 +37,9 @@
   </div>
 
   <h2>Endpoints</h2>
-  <div class="endpoint">
-    <div class="endpoint-path">/ or /sse</div>
-    <div class="endpoint-desc">Streamable HTTP (stateful) - for Claude Desktop and Claude Code</div>
-  </div>
   <div class="endpoint">
     <div class="endpoint-path">/http</div>
-    <div class="endpoint-desc">Streamable HTTP (stateless) - for simple integrations</div>
+    <div class="endpoint-desc">MCP HTTP endpoint - for Claude Desktop and Claude Code</div>
   </div>
 
   <h2>Claude Desktop Setup</h2>
@@ -53,7 +49,7 @@
     <li>Go to <strong>Settings &rarr; Connectors</strong></li>
     <li>Add this URL as a remote MCP server:</li>
   </ol>
-  <pre><code>https://cf-mcp.fly.dev/</code></pre>
+  <pre><code>https://cf-mcp.fly.dev/http</code></pre>
 
   <h2>Claude Code CLI Setup</h2>
   <pre><code>claude mcp add --transport http cf-mcp https://cf-mcp.fly.dev/http</code></pre>

data/lib/cf/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module CF
   module MCP
-    VERSION = "0.10.0"
+    VERSION = "0.12.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cf-mcp
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Piotr Usewicz