cf-mcp 0.9.2

data/lib/cf/mcp/parser.rb

@@ -0,0 +1,246 @@
+# 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
+      DOC_BLOCK_PATTERN = %r{/\*\*.*?\*/}m
+      TAG_PATTERN = /@(\w+)\s*/
+      MEMBER_COMMENT_PATTERN = %r{/\*\s*@member\s+(.*?)\s*\*/}m
+      ENTRY_COMMENT_PATTERN = %r{/\*\s*@entry\s+(.*?)\s*\*/}m
+      CF_ENUM_PATTERN = /CF_ENUM\s*\(\s*(\w+)\s*,\s*([^)]*)\)/
+      SIGNATURE_CLEANUP = /\b(CF_API|CF_CALL|CF_INLINE)\b\s*/
+      END_MARKER_PATTERN = %r{//\s*@end|/\*\s*@end\s*\*/}
+
+      def parse_file(path)
+        content = File.read(path)
+        source_file = File.basename(path)
+        line_offsets = build_line_offsets(content)
+        items = []
+
+        # Find all documentation blocks with their positions
+        content.scan(%r{(/\*\*.*?\*/)(.*?)(?=/\*\*|\z)}m) do |doc_block, following_content|
+          # Get the position of the match to calculate line number
+          match_position = Regexp.last_match.begin(0)
+          source_line = line_for_position(match_position, line_offsets)
+          item = parse_doc_block(doc_block, following_content.strip, source_file, source_line)
+          items << item if item
+        end
+
+        items
+      end
+
+      def parse_directory(path)
+        items = []
+        Dir.glob(File.join(path, "**/*.h")).each do |header_file|
+          items.concat(parse_file(header_file))
+        end
+        items
+      end
+
+      private
+
+      # Build an array of byte positions where each line starts
+      def build_line_offsets(content)
+        offsets = [0]
+        content.each_char.with_index do |char, index|
+          offsets << index + 1 if char == "\n"
+        end
+        offsets
+      end
+
+      # Convert a byte position to a 1-based line number
+      def line_for_position(position, line_offsets)
+        # Binary search to find the line containing this position
+        line_offsets.bsearch_index { |offset| offset > position } || line_offsets.size
+      end
+
+      def parse_doc_block(doc_block, following_content, source_file, source_line = nil)
+        tags = extract_tags(doc_block)
+        return nil if tags.empty?
+
+        type = determine_type(tags)
+        return nil unless type
+
+        case type
+        when :function
+          parse_function(tags, following_content, source_file, source_line)
+        when :struct
+          parse_struct(tags, following_content, source_file, source_line)
+        when :enum
+          parse_enum(tags, following_content, source_file, source_line)
+        end
+      end
+
+      def extract_tags(doc_block)
+        tags = {}
+
+        # Remove comment markers and clean up
+        lines = doc_block.lines.map do |line|
+          line.gsub(%r{^\s*/?\*+\s?}, "").gsub(%r{\s*\*+/\s*$}, "")
+        end
+
+        current_tag = nil
+        current_content = []
+
+        lines.each do |line|
+          if line =~ TAG_PATTERN
+            # Save previous tag
+            if current_tag
+              save_tag(tags, current_tag, current_content.join("\n").strip)
+            end
+
+            current_tag = ::Regexp.last_match(1)
+            remaining = line.sub(TAG_PATTERN, "").strip
+            current_content = [remaining]
+          elsif current_tag
+            current_content << line
+          end
+        end
+
+        # Save last tag
+        if current_tag
+          save_tag(tags, current_tag, current_content.join("\n").strip)
+        end
+
+        tags
+      end
+
+      def save_tag(tags, tag, content)
+        case tag
+        when "param"
+          tags[:params] ||= []
+          # Parse "param_name description" format
+          if content =~ /^(\w+)\s+(.*)$/m
+            tags[:params] << {name: ::Regexp.last_match(1), description: ::Regexp.last_match(2).strip}
+          end
+        when "related"
+          # Filter out comment artifacts like "/" or "*/"
+          tags[:related] = content.split(/\s+/).reject { |s| s.empty? || s.match?(%r{^[/*]+$}) }
+        else
+          tags[tag.to_sym] = content
+        end
+      end
+
+      def determine_type(tags)
+        return :function if tags[:function]
+        return :struct if tags[:struct]
+        return :enum if tags[:enum]
+        nil
+      end
+
+      def parse_function(tags, following_content, source_file, source_line = nil)
+        # Extract signature from following content
+        signature = extract_signature(following_content)
+
+        Models::FunctionDoc.new(
+          name: tags[:function],
+          category: tags[:category],
+          brief: tags[:brief],
+          remarks: tags[:remarks],
+          example: tags[:example],
+          related: tags[:related] || [],
+          source_file: source_file,
+          source_line: source_line,
+          signature: signature,
+          parameters: (tags[:params] || []).map { |p| Models::FunctionDoc::Parameter.new(p[:name], p[:description]) },
+          return_value: tags[:return]
+        )
+      end
+
+      def parse_struct(tags, following_content, source_file, source_line = nil)
+        # Extract members from the struct body
+        members = extract_members(following_content)
+
+        Models::StructDoc.new(
+          name: tags[:struct],
+          category: tags[:category],
+          brief: tags[:brief],
+          remarks: tags[:remarks],
+          example: tags[:example],
+          related: tags[:related] || [],
+          source_file: source_file,
+          source_line: source_line,
+          members: members
+        )
+      end
+
+      def parse_enum(tags, following_content, source_file, source_line = nil)
+        # Extract enum entries from the #define macro
+        entries = extract_enum_entries(following_content)
+
+        Models::EnumDoc.new(
+          name: tags[:enum],
+          category: tags[:category],
+          brief: tags[:brief],
+          remarks: tags[:remarks],
+          example: tags[:example],
+          related: tags[:related] || [],
+          source_file: source_file,
+          source_line: source_line,
+          entries: entries
+        )
+      end
+
+      def extract_signature(content)
+        # Find the first function declaration (ending with ; or {)
+        lines = content.lines
+        signature_lines = []
+
+        lines.each do |line|
+          # Skip empty lines and comments at the start
+          next if line.strip.empty? && signature_lines.empty?
+          break if line.strip.empty? && !signature_lines.empty?
+
+          # Stop at struct/enum definitions
+          break if /^typedef\s+(struct|enum)/.match?(line)
+          break if /^#define/.match?(line)
+
+          signature_lines << line
+          break if line.include?(";") || line.include?("{")
+        end
+
+        return nil if signature_lines.empty?
+
+        signature = signature_lines.join.strip
+        # Clean up macros and normalize whitespace
+        signature = signature.gsub(SIGNATURE_CLEANUP, "")
+        signature = signature.gsub(/\s*\{.*$/m, "").strip
+        signature = signature.gsub(/;$/, "").strip
+        signature.empty? ? nil : signature
+      end
+
+      def extract_members(content)
+        members = []
+
+        # Find /* @member ... */ comments and the following declaration
+        # Use [^/]+? to ensure we capture content (non-slash chars) before the next comment
+        content.scan(%r{/\*\s*@member\s+(.*?)\s*\*/\s*([^/]+?)(?=/\*|//\s*@end|$)}m) do |description, declaration|
+          decl = declaration.strip.lines.first&.strip
+          next unless decl && !decl.empty?
+
+          # Clean up the declaration (remove trailing semicolon for display)
+          decl = decl.gsub(/;$/, "").strip
+          members << Models::StructDoc::Member.new(decl, description.strip)
+        end
+
+        members
+      end
+
+      def extract_enum_entries(content)
+        entries = []
+
+        # Find the #define block with CF_ENUM macros
+        # Pattern: /* @entry description */ followed by CF_ENUM(NAME, VALUE)
+        content.scan(%r{/\*\s*@entry\s+(.*?)\s*\*/\s*\\?\s*CF_ENUM\s*\(\s*(\w+)\s*,\s*([^)]*)\)}m) do |description, name, value|
+          entries << Models::EnumDoc::Entry.new(name.strip, value.strip, description.strip)
+        end
+
+        entries
+      end
+    end
+  end
+end

data/lib/cf/mcp/server.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require "mcp"
+require_relative "tools/search_tool"
+require_relative "tools/search_functions"
+require_relative "tools/search_structs"
+require_relative "tools/search_enums"
+require_relative "tools/list_category"
+require_relative "tools/get_details"
+require_relative "tools/find_related"
+require_relative "tools/parameter_search"
+require_relative "tools/member_search"
+require_relative "tools/list_topics"
+require_relative "tools/get_topic"
+
+module CF
+  module MCP
+    class Server
+      attr_reader :server, :index
+
+      TOOLS = [
+        Tools::SearchTool,
+        Tools::SearchFunctions,
+        Tools::SearchStructs,
+        Tools::SearchEnums,
+        Tools::ListCategory,
+        Tools::GetDetails,
+        Tools::FindRelated,
+        Tools::ParameterSearch,
+        Tools::MemberSearch,
+        Tools::ListTopics,
+        Tools::GetTopic
+      ].freeze
+
+      def initialize(index)
+        @index = index
+        @server = ::MCP::Server.new(
+          name: "cf-mcp",
+          version: CF::MCP::VERSION,
+          tools: TOOLS,
+          resources: build_topic_resources(index)
+        )
+        @server.server_context = {index: index}
+
+        # Register handler for reading resource content
+        @server.resources_read_handler do |params|
+          handle_resource_read(params, index)
+        end
+      end
+
+      private
+
+      def build_topic_resources(index)
+        index.topics.map do |topic|
+          ::MCP::Resource.new(
+            uri: "cf://topics/#{topic.name}",
+            name: topic.name,
+            title: topic.name.tr("_", " ").split.map(&:capitalize).join(" "),
+            description: topic.brief,
+            mime_type: "text/markdown"
+          )
+        end
+      end
+
+      def handle_resource_read(params, index)
+        uri = params[:uri]
+        return [] unless uri&.start_with?("cf://topics/")
+
+        topic_name = uri.sub("cf://topics/", "")
+        topic = index.find(topic_name)
+
+        return [] unless topic&.type == :topic
+
+        [{
+          uri: uri,
+          mimeType: "text/markdown",
+          text: topic.content
+        }]
+      end
+
+      public
+
+      def run_stdio
+        transport = ::MCP::Server::Transports::StdioTransport.new(@server)
+        transport.open
+      end
+
+      def run_http(port: 9292)
+        require "rackup"
+
+        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
+
+      def http_app
+        require "rack"
+
+        transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(@server, stateless: true)
+        @server.transport = transport
+
+        build_rack_app(transport)
+      end
+
+      def run_sse(port: 9393)
+        require "rack"
+        require "rackup"
+
+        transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(@server)
+        @server.transport = transport
+
+        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)
+      end
+
+      private
+
+      def build_rack_app(transport)
+        Rack::Builder.new do
+          use Rack::CommonLogger
+          run ->(env) { transport.handle_request(Rack::Request.new(env)) }
+        end
+      end
+
+      def sse_app
+        require "rack"
+
+        transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(@server)
+        @server.transport = transport
+
+        build_rack_app(transport)
+      end
+    end
+
+    # Combined server that exposes both SSE and HTTP transports under different paths
+    class CombinedServer
+      def initialize(index)
+        @index = index
+      end
+
+      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-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
+
+        landing_page = build_landing_page
+        index = @index
+        tools = Server::TOOLS
+        cors_headers = CORS_HEADERS
+
+        app = ->(env) {
+          request = Rack::Request.new(env)
+          path = request.path_info
+
+          # Handle CORS preflight
+          if request.options?
+            return [204, cors_headers, []]
+          end
+
+          # Route based on path
+          status, headers, body = case path
+          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
+            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)
+            end
+          end
+
+          # Add CORS headers to response
+          [status, headers.merge(cors_headers), body]
+        }
+
+        Rack::Builder.new do
+          use Rack::CommonLogger
+          run app
+        end
+      end
+
+      private
+
+      def escape_html(text)
+        text.to_s
+          .gsub("&", "&")
+          .gsub("<", "&lt;")
+          .gsub(">", "&gt;")
+          .gsub('"', "&quot;")
+          .gsub("'", "&#39;")
+      end
+
+      def create_mcp_server
+        server = ::MCP::Server.new(
+          name: "cf-mcp",
+          version: CF::MCP::VERSION,
+          tools: Server::TOOLS
+        )
+        server.server_context = {index: @index}
+        server
+      end
+
+      def build_landing_page
+        require "erb"
+        require "json"
+
+        template_path = File.join(__dir__, "templates", "index.erb")
+        template = ERB.new(File.read(template_path))
+
+        ->(index, tool_classes) {
+          context = TemplateContext.new(
+            version: CF::MCP::VERSION,
+            stats: index.stats,
+            categories: index.categories.sort,
+            topics: index.topics_ordered.map { |t| {name: t.name, brief: t.brief} },
+            tools: tool_classes.map { |tool|
+              name = tool.respond_to?(:tool_name) ? tool.tool_name : tool.name
+              desc = tool.respond_to?(:description) ? tool.description : ""
+              {name: name, description: desc}
+            },
+            tool_schemas_json: tool_classes.map { |tool|
+              name = tool.respond_to?(:tool_name) ? tool.tool_name : tool.name
+              desc = tool.respond_to?(:description) ? tool.description : ""
+              schema = tool.input_schema.to_h
+              {name: name, description: desc, inputSchema: schema}
+            }.to_json
+          )
+          template.result(context.get_binding)
+        }
+      end
+
+      # Helper class to provide a clean binding for ERB templates
+      class TemplateContext
+        TEMPLATES_DIR = File.join(__dir__, "templates")
+
+        attr_reader :version, :stats, :categories, :topics, :tools, :tool_schemas_json
+
+        def initialize(version:, stats:, categories:, topics:, tools:, tool_schemas_json:)
+          @version = version
+          @stats = stats
+          @categories = categories
+          @topics = topics
+          @tools = tools
+          @tool_schemas_json = tool_schemas_json
+        end
+
+        def categories_json
+          @categories.to_json
+        end
+
+        def topics_json
+          @topics.to_json
+        end
+
+        def css_content
+          File.read(File.join(TEMPLATES_DIR, "style.css"))
+        end
+
+        def changelog_content
+          changelog_path = CF::MCP.root.join("CHANGELOG.md")
+          changelog_path.exist? ? changelog_path.read : ""
+        end
+
+        def changelog_json
+          changelog_content.to_json
+        end
+
+        def js_content
+          js = File.read(File.join(TEMPLATES_DIR, "script.js"))
+          js.sub("TOOL_SCHEMAS_PLACEHOLDER", @tool_schemas_json)
+            .sub("CATEGORIES_PLACEHOLDER", categories_json)
+            .sub("TOPICS_PLACEHOLDER", topics_json)
+            .sub("CHANGELOG_PLACEHOLDER", changelog_json)
+        end
+
+        def h(text)
+          text.to_s
+            .gsub("&", "&amp;")
+            .gsub("<", "&lt;")
+            .gsub(">", "&gt;")
+            .gsub('"', "&quot;")
+            .gsub("'", "&#39;")
+        end
+
+        def get_binding
+          binding
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>CF::MCP - Cute Framework MCP Server</title>
+  <style>
+<%= css_content %>
+  </style>
+  <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+</head>
+<body>
+  <h1>CF::MCP <small style="font-size: 0.5em; color: #8b949e;">v<%= version %></small></h1>
+  <p>MCP (Model Context Protocol) server for the <a href="https://github.com/RandyGaul/cute_framework">Cute Framework</a>, a C/C++ 2D game framework.</p>
+
+  <div class="stats">
+    <div class="stat">
+      <div class="stat-value"><%= stats[:total] %></div>
+      <div class="stat-label">Total Items</div>
+    </div>
+    <div class="stat">
+      <div class="stat-value"><%= stats[:functions] %></div>
+      <div class="stat-label">Functions</div>
+    </div>
+    <div class="stat">
+      <div class="stat-value"><%= stats[:structs] %></div>
+      <div class="stat-label">Structs</div>
+    </div>
+    <div class="stat">
+      <div class="stat-value"><%= stats[:enums] %></div>
+      <div class="stat-label">Enums</div>
+    </div>
+    <div class="stat">
+      <div class="stat-value"><%= stats[:topics] %></div>
+      <div class="stat-label">Topics</div>
+    </div>
+  </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>
+
+  <h2>Claude Desktop Setup</h2>
+  <p>Remote MCP servers require a <strong>Pro, Max, Team, or Enterprise</strong> plan.</p>
+  <ol>
+    <li>Open Claude Desktop</li>
+    <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>
+
+  <h2>Claude Code CLI Setup</h2>
+  <pre><code>claude mcp add --transport http cf-mcp https://cf-mcp.fly.dev/http</code></pre>
+
+  <h2>Available Tools</h2>
+  <div class="tools">
+    <% tools.each do |tool| %>
+    <div class="tool">
+      <div class="tool-name"><%= h(tool[:name]) %></div>
+      <div class="tool-desc"><%= h(tool[:description]) %></div>
+    </div>
+    <% end %>
+  </div>
+
+  <h2>Tool Explorer</h2>
+  <div id="tool-explorer-root"></div>
+
+  <h2>Topics Explorer</h2>
+  <p>Browse tutorial guides and documentation topics for Cute Framework.</p>
+  <div id="topics-explorer-root"></div>
+
+  <h2>Links</h2>
+  <ul>
+    <li><a href="https://github.com/pusewicz/cf-mcp">CF::MCP on GitHub</a></li>
+    <li><a href="https://github.com/RandyGaul/cute_framework">Cute Framework</a></li>
+    <li><a href="https://modelcontextprotocol.io">Model Context Protocol</a></li>
+  </ul>
+
+  <details class="changelog">
+    <summary><h2 style="display: inline; cursor: pointer;">Changelog</h2></summary>
+    <div id="changelog-content"></div>
+  </details>
+
+  <script type="module">
+<%= js_content %>
+  </script>
+</body>
+</html>