mathpix 0.1.0

data/lib/mathpix/mcp/resources/formats_list_resource.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Mathpix
+  module MCP
+    module Resources
+      # Formats List Resource Handler
+      #
+      # Returns available output formats for Mathpix OCR
+      # URI: mathpix://formats/list
+      #
+      # The geodesic path: resource handler + static data
+      module FormatsListResource
+        # Fetch formats list
+        #
+        # @param client [Mathpix::Client] optional client (not used, kept for consistency)
+        # @return [Hash] resource content
+        def self.fetch(client = nil)
+          formats = {
+            image_formats: [
+              {
+                name: "latex_styled",
+                description: "LaTeX with styling commands",
+                use_case: "Typesetting, display"
+              },
+              {
+                name: "text",
+                description: "Plain text representation",
+                use_case: "Simple text extraction"
+              },
+              {
+                name: "latex_list",
+                description: "Array of LaTeX expressions",
+                use_case: "Multiple equations"
+              },
+              {
+                name: "mathml",
+                description: "MathML markup language",
+                use_case: "Web display, accessibility"
+              },
+              {
+                name: "asciimath",
+                description: "AsciiMath notation",
+                use_case: "Simple math notation"
+              },
+              {
+                name: "text_display",
+                description: "Display-style text",
+                use_case: "Large equation display"
+              },
+              {
+                name: "latex_simplified",
+                description: "Simplified LaTeX",
+                use_case: "Basic LaTeX output"
+              },
+              {
+                name: "data",
+                description: "Full response with metadata",
+                use_case: "Complete API response"
+              },
+              {
+                name: "html",
+                description: "HTML markup",
+                use_case: "Web integration"
+              }
+            ],
+            document_formats: [
+              {
+                name: "markdown",
+                description: "Markdown document format",
+                use_case: "Note-taking, documentation"
+              },
+              {
+                name: "latex",
+                description: "LaTeX document format",
+                use_case: "Academic papers, typesetting"
+              },
+              {
+                name: "html",
+                description: "HTML document format",
+                use_case: "Web publishing"
+              },
+              {
+                name: "docx",
+                description: "Microsoft Word document",
+                use_case: "Word processing"
+              },
+              {
+                name: "tex.zip",
+                description: "LaTeX with figures (zipped)",
+                use_case: "Complete LaTeX projects"
+              }
+            ]
+          }
+
+          {
+            uri: "mathpix://formats/list",
+            mime_type: "application/json",
+            content: JSON.pretty_generate({
+              success: true,
+              image_formats_count: formats[:image_formats].length,
+              document_formats_count: formats[:document_formats].length,
+              formats: formats,
+              usage: {
+                image_capture: "Use with Mathpix.snap() or ConvertImageTool",
+                document_conversion: "Use with Mathpix.document() or ConvertDocumentTool"
+              }
+            })
+          }
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/resources/hierarchical_router.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+module Mathpix
+  module MCP
+    module Resources
+      # Hierarchical URI router with parameter extraction
+      class HierarchicalRouter
+        attr_reader :client, :routes
+
+        MIN_LIMIT = 1
+        MAX_LIMIT = 100
+
+        def initialize(client)
+          @client = client
+          @routes = {}
+        end
+
+        def register_route(pattern:, handler:, methods:, description: nil, params: nil)
+          @routes[pattern] = {
+            handler: handler,
+            methods: Array(methods),
+            description: description,
+            params: params
+          }
+        end
+
+        def match_route(path, method)
+          @routes.each do |pattern, route|
+            next unless route[:methods].include?(method)
+
+            params = extract_params(pattern, path)
+            next if params.nil?
+
+            return {
+              handler: route[:handler],
+              params: params,
+              route: route
+            }
+          end
+
+          nil
+        end
+
+        def route_request(path, method, query_params)
+          match = match_route(path, method)
+          raise RouteNotFoundError, "No route matches #{method.upcase} #{path}" if match.nil?
+
+          # Merge URI params with query params
+          all_params = match[:params].merge(query_params)
+
+          # Validate parameters
+          validate_params(all_params)
+
+          # Call handler method
+          send(match[:handler], all_params)
+        end
+
+        def parse_query_params(query_string)
+          return {} if query_string.nil? || query_string.empty?
+
+          params = {}
+
+          query_string.split('&').each do |param|
+            key, value = param.split('=', 2)
+            key = key.to_sym
+            value = CGI.unescape(value) if value
+
+            # Type coercion
+            params[key] = coerce_value(value)
+          end
+
+          params
+        end
+
+        def pagination_links(path:, limit:, offset:, total:, query_params:)
+          links = {}
+
+          # Self link
+          links[:self] = build_link(path, limit, offset, query_params)
+
+          # First link
+          links[:first] = build_link(path, limit, 0, query_params)
+
+          # Previous link (if not on first page)
+          if offset > 0
+            prev_offset = [offset - limit, 0].max
+            links[:prev] = build_link(path, limit, prev_offset, query_params)
+          end
+
+          # Next link (if not on last page)
+          if offset + limit < total
+            next_offset = offset + limit
+            links[:next] = build_link(path, limit, next_offset, query_params)
+          end
+
+          # Last link
+          last_offset = ((total - 1) / limit) * limit
+          links[:last] = build_link(path, limit, last_offset, query_params)
+
+          links
+        end
+
+        def select_fields(data, fields_param)
+          return data if fields_param.nil?
+
+          fields = fields_param.split(',').map(&:strip).map(&:to_sym)
+          data.select { |k, _| fields.include?(k) }
+        end
+
+        def relationship_links(resource)
+          links = {
+            self: "/snip/#{resource[:id]}"
+          }
+
+          links[:batch] = "/batch/#{resource[:batch_id]}" if resource[:batch_id]
+
+          links
+        end
+
+        def uri_templates
+          @routes.map do |pattern, route|
+            {
+              template: pattern.gsub(/:(\w+)/, '{\1}'),
+              description: route[:description],
+              methods: route[:methods],
+              params: route[:params]
+            }
+          end
+        end
+
+        private
+
+        def extract_params(pattern, path)
+          pattern_parts = pattern.split('/')
+          path_parts = path.split('/')
+
+          return nil unless pattern_parts.length == path_parts.length
+
+          params = {}
+
+          pattern_parts.each_with_index do |part, index|
+            if part.start_with?(':')
+              param_name = part[1..].to_sym
+              param_value = path_parts[index]
+
+              # Validate ID format (alphanumeric, underscores, hyphens)
+              return nil unless param_value =~ /^[a-zA-Z0-9_-]+$/
+
+              params[param_name] = param_value
+            else
+              return nil unless part == path_parts[index]
+            end
+          end
+
+          params
+        end
+
+        def coerce_value(value)
+          return nil if value.nil?
+
+          # Integer
+          return value.to_i if value =~ /^\d+$/
+
+          # Boolean
+          return true if value == 'true'
+          return false if value == 'false'
+
+          # Array (comma-separated)
+          if value.include?(',')
+            return value.split(',').map(&:strip)
+          end
+
+          # String
+          value
+        end
+
+        def validate_params(params)
+          # Validate limit
+          if params[:limit]
+            unless params[:limit].is_a?(Integer)
+              raise InvalidParameterError, 'limit must be a number'
+            end
+
+            unless params[:limit].between?(MIN_LIMIT, MAX_LIMIT)
+              raise InvalidParameterError, "limit must be between #{MIN_LIMIT} and #{MAX_LIMIT}"
+            end
+          end
+
+          # Validate offset
+          if params[:offset]
+            unless params[:offset].is_a?(Integer)
+              raise InvalidParameterError, 'offset must be a number'
+            end
+          end
+
+          # Validate ID format (if present)
+          if params[:id]
+            unless params[:id] =~ /^[a-zA-Z0-9_-]+$/
+              raise InvalidParameterError, 'id must be alphanumeric'
+            end
+          end
+        end
+
+        def build_link(path, limit, offset, query_params)
+          params = query_params.dup
+          params[:limit] = limit
+          params[:offset] = offset
+
+          query_string = params.map { |k, v| "#{k}=#{v}" }.join('&')
+          "#{path}?#{query_string}"
+        end
+
+        # Placeholder handler methods
+        # These would be implemented based on actual resource handlers
+
+        def get_snip(params)
+          # Delegate to actual resource handler
+          { id: params[:id], placeholder: true }
+        end
+
+        def get_snip_metadata(params)
+          { id: params[:id], metadata: true }
+        end
+
+        def get_line(params)
+          { id: params[:id], line_number: params[:line_number] }
+        end
+
+        def list_snips(params)
+          []
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/resources/latest_snip_resource.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Mathpix
+  module MCP
+    module Resources
+      # Latest Snip Resource Handler
+      #
+      # Returns the most recent capture result
+      # URI: mathpix://snip/recent/latest
+      #
+      # The geodesic path: resource handler + client delegation
+      module LatestSnipResource
+        # Fetch latest snip data
+        #
+        # @param client [Mathpix::Client] Mathpix API client
+        # @return [Hash] resource content
+        def self.fetch(client)
+          recent = client.recent(limit: 1)
+
+          if recent.empty?
+            {
+              uri: "mathpix://snip/recent/latest",
+              mime_type: "application/json",
+              content: JSON.pretty_generate({
+                success: false,
+                message: "No recent captures found"
+              })
+            }
+          else
+            result = recent.first
+            {
+              uri: "mathpix://snip/recent/latest",
+              mime_type: "application/json",
+              content: JSON.pretty_generate({
+                success: true,
+                id: result.request_id,
+                created_at: result.timestamp,
+                latex: result.latex,
+                text: result.text,
+                confidence: result.confidence,
+                is_printed: result.printed?,
+                is_handwritten: result.handwritten?,
+                position: result.position
+              })
+            }
+          end
+        rescue Mathpix::Error => e
+          {
+            uri: "mathpix://snip/recent/latest",
+            mime_type: "application/json",
+            content: JSON.pretty_generate({
+              success: false,
+              error: e.message
+            })
+          }
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/resources/recent_snips_resource.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Mathpix
+  module MCP
+    module Resources
+      # Recent Snips Resource Handler
+      #
+      # Returns recent capture results with pagination
+      # URI: mathpix://snip/recent?limit=N
+      #
+      # The geodesic path: resource handler + client delegation
+      module RecentSnipsResource
+        # Fetch recent snips data
+        #
+        # @param client [Mathpix::Client] Mathpix API client
+        # @param limit [Integer] number of results (default: 10, max: 100)
+        # @return [Hash] resource content
+        def self.fetch(client, limit: 10)
+          config = client.config
+
+          # Use configuration bounds instead of magic numbers
+          limit = config.sanitize_limit(limit)
+
+          # Log the request
+          config.log(:info, 'Fetching recent snips', { limit: limit })
+
+          recent = client.recent(limit: limit)
+
+          results = recent.map do |result|
+            {
+              id: result.request_id,
+              created_at: result.timestamp,
+              latex_preview: truncate(result.latex, 100),
+              text_preview: truncate(result.text, 100),
+              confidence: result.confidence,
+              is_printed: result.printed?,
+              is_handwritten: result.handwritten?
+            }
+          end
+
+          {
+            uri: "mathpix://snip/recent?limit=#{limit}",
+            mime_type: "application/json",
+            content: JSON.pretty_generate({
+              success: true,
+              limit: limit,
+              count: results.length,
+              results: results
+            })
+          }
+        rescue Mathpix::Error => e
+          {
+            uri: "mathpix://snip/recent?limit=#{limit}",
+            mime_type: "application/json",
+            content: JSON.pretty_generate({
+              success: false,
+              error: e.message
+            })
+          }
+        end
+
+        # Truncate text for preview
+        #
+        # @param text [String, nil] text to truncate
+        # @param max_length [Integer] maximum length
+        # @return [String, nil] truncated text
+        def self.truncate(text, max_length)
+          return nil unless text
+          return text if text.length <= max_length
+          "#{text[0...max_length]}..."
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/resources/snip_stats_resource.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Mathpix
+  module MCP
+    module Resources
+      # Snip Stats Resource Handler
+      #
+      # Returns overall capture statistics
+      # URI: mathpix://snip/stats
+      #
+      # The geodesic path: resource handler + client delegation
+      module SnipStatsResource
+        # Fetch snip statistics
+        #
+        # @param client [Mathpix::Client] Mathpix API client
+        # @return [Hash] resource content
+        def self.fetch(client)
+          config = client.config
+
+          # Log the request
+          config.log(:info, 'Fetching snip statistics', { limit: config.max_limit })
+
+          # Get recent captures to compute stats
+          recent = client.recent(limit: config.max_limit)
+
+          # Compute statistics
+          stats = compute_stats(recent)
+
+          {
+            uri: "mathpix://snip/stats",
+            mime_type: "application/json",
+            content: JSON.pretty_generate({
+              success: true,
+              period: "last_100_captures",
+              stats: stats
+            })
+          }
+        rescue Mathpix::Error => e
+          {
+            uri: "mathpix://snip/stats",
+            mime_type: "application/json",
+            content: JSON.pretty_generate({
+              success: false,
+              error: e.message
+            })
+          }
+        end
+
+        # Compute statistics from results
+        #
+        # @param results [Array<Mathpix::Result>] recent results
+        # @return [Hash] statistics
+        def self.compute_stats(results)
+          return { total: 0 } if results.empty?
+
+          total = results.length
+          printed_count = results.count(&:printed?)
+          handwritten_count = results.count(&:handwritten?)
+
+          confidences = results.map(&:confidence).compact
+          avg_confidence = confidences.empty? ? 0.0 : (confidences.sum / confidences.length.to_f)
+
+          {
+            total: total,
+            printed: printed_count,
+            handwritten: handwritten_count,
+            average_confidence: avg_confidence.round(3),
+            confidence_distribution: {
+              high: confidences.count { |c| c >= Mathpix::Configuration::CONFIDENCE_HIGH },
+              medium: confidences.count { |c| c >= Mathpix::Configuration::CONFIDENCE_MEDIUM && c < Mathpix::Configuration::CONFIDENCE_HIGH },
+              low: confidences.count { |c| c < Mathpix::Configuration::CONFIDENCE_MEDIUM }
+            }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/resources.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Mathpix
+  module MCP
+    module Resources
+      # Custom error classes
+      class ResourceError < StandardError; end
+      class RouteNotFoundError < ResourceError; end
+      class ResourceNotFoundError < ResourceError; end
+      class InvalidParameterError < ResourceError; end
+    end
+  end
+end
+
+require_relative 'resources/hierarchical_router'