mathpix-mcp 1.0.0

data/lib/mathpix/configuration.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Mathpix
+  # Configuration class with security defaults and validation
+  # Seed: 1069 - Deterministic configuration values
+  class Configuration
+    # Security constants
+    HTTPS_ONLY = true
+    MAX_FILE_SIZE_MB = 10
+    MAX_PATH_LENGTH = 1024
+    ALLOWED_SCHEMES = %w[https].freeze
+
+    # Resource limits
+    MIN_LIMIT = 1
+    MAX_LIMIT = 100
+    DEFAULT_LIMIT = 10
+
+    # Confidence thresholds (balanced ternary seed 1069)
+    CONFIDENCE_HIGH = 0.9
+    CONFIDENCE_MEDIUM = 0.7
+    CONFIDENCE_LOW = 0.5
+
+    # Rate limiting (requests per minute)
+    RATE_LIMIT_DEFAULT = 60
+    RATE_LIMIT_BURST = 10
+
+    attr_accessor :app_id, :app_key, :api_url, :timeout, :default_formats,
+                  :user_agent, :enforce_https, :max_file_size_mb, :logger, :seed
+
+    attr_reader :rate_limit, :confidence_thresholds
+
+    # Alias endpoint for api_url
+    alias endpoint api_url
+    alias endpoint= api_url=
+
+    def initialize
+      @app_id = ENV.fetch('MATHPIX_APP_ID', nil)
+      @app_key = ENV.fetch('MATHPIX_APP_KEY', nil)
+      @api_url = ENV.fetch('MATHPIX_API_URL', 'https://api.mathpix.com/v3')
+      @timeout = ENV.fetch('MATHPIX_TIMEOUT', '30').to_i
+      @default_formats = [:latex_styled]
+      @user_agent = "mathpix-ruby/#{Mathpix::VERSION}"
+
+      # Security settings
+      @enforce_https = HTTPS_ONLY
+      @max_file_size_mb = MAX_FILE_SIZE_MB
+      @max_path_length = MAX_PATH_LENGTH
+
+      # Resource limits
+      @min_limit = MIN_LIMIT
+      @max_limit = MAX_LIMIT
+      @default_limit = DEFAULT_LIMIT
+
+      # Confidence thresholds
+      @confidence_thresholds = {
+        high: CONFIDENCE_HIGH,
+        medium: CONFIDENCE_MEDIUM,
+        low: CONFIDENCE_LOW
+      }
+
+      # Rate limiting
+      @rate_limit = RATE_LIMIT_DEFAULT
+
+      # Structured logging
+      @logger = nil # Can be set to Logger instance
+    end
+
+    def validate!
+      raise ConfigurationError, 'app_id is required' if app_id.nil? || app_id.empty?
+      raise ConfigurationError, 'app_key is required' if app_key.nil? || app_key.empty?
+
+      # Validate API URL uses HTTPS
+      raise ConfigurationError, 'API URL must use HTTPS' if enforce_https && !api_url.start_with?('https://')
+
+      # Validate timeout
+      raise ConfigurationError, 'Timeout must be between 1 and 300 seconds' if timeout <= 0 || timeout > 300
+
+      true
+    end
+
+    # Sanitize limit to be within bounds
+    #
+    # @param limit [Integer] requested limit
+    # @return [Integer] clamped limit
+    def sanitize_limit(limit)
+      [[limit.to_i, @min_limit].max, @max_limit].min
+    end
+
+    # Check if URL is allowed (HTTPS only)
+    #
+    # @param url [String] URL to validate
+    # @return [Boolean]
+    def valid_url?(url)
+      return false unless url.is_a?(String)
+      return false if url.length > @max_path_length
+
+      uri = URI.parse(url)
+
+      # Must be HTTP(S) scheme
+      return false unless %w[http https].include?(uri.scheme)
+
+      # Enforce HTTPS if enabled
+      return false if enforce_https && uri.scheme != 'https'
+
+      # Must have a host
+      return false if uri.host.nil? || uri.host.empty?
+
+      # Block localhost and private IPs
+      return false if uri.host.match?(/^(localhost|127\.|0\.0\.0\.0|::1)/)
+      return false if uri.host.match?(/^(10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.)/)
+
+      true
+    rescue URI::InvalidURIError
+      false
+    end
+
+    # Auto-upgrade HTTP to HTTPS for remote URLs
+    #
+    # This provides the same behavior for seamless URL support
+    #
+    # @param url [String] URL that may be HTTP or HTTPS
+    # @return [String] URL with https:// scheme
+    # @example
+    #   upgrade_to_https('http://example.com/img.png')
+    #   # => 'https://example.com/img.png'
+    def upgrade_to_https(url)
+      return url unless url.is_a?(String)
+      return url unless url.start_with?('http://')
+
+      url.sub(%r{^http://}, 'https://')
+    end
+
+    # Sanitize file path to prevent directory traversal
+    #
+    # @param path [String] file path
+    # @return [String, nil] sanitized path or nil if invalid
+    def sanitize_path(path)
+      return nil unless path.is_a?(String)
+      return nil if path.length > @max_path_length
+
+      # Remove null bytes
+      path = path.tr("\0", '')
+
+      # Normalize path
+      normalized = File.expand_path(path)
+
+      # Check for directory traversal attempts
+      return nil if normalized.include?('../')
+      return nil if normalized.match?(%r{\.\.[/\\]})
+
+      # Check file exists (for local paths)
+      return nil unless File.exist?(normalized)
+
+      # Check file size
+      size_mb = File.size(normalized).to_f / (1024 * 1024)
+      return nil if size_mb > @max_file_size_mb
+
+      normalized
+    rescue StandardError
+      nil
+    end
+
+    # Log structured message
+    #
+    # @param level [Symbol] log level (:debug, :info, :warn, :error)
+    # @param message [String] log message
+    # @param data [Hash] structured data
+    def log(level, message, data = {})
+      return unless @logger
+
+      structured_message = {
+        timestamp: Time.now.utc.iso8601,
+        level: level,
+        message: message,
+        seed: 1069,
+        **data
+      }.to_json
+
+      @logger.send(level, structured_message)
+    end
+  end
+end

data/lib/mathpix/document.rb

@@ -0,0 +1,345 @@
+# frozen_string_literal: true
+
+module Mathpix
+  # Document processing builder (PDF, DOCX, PPTX)
+  class Document
+    attr_reader :client, :document_path, :options
+
+    def initialize(client, document_path)
+      @client = client
+      @document_path = document_path
+      @options = {}
+    end
+
+    # Set output formats
+    # @param formats [Array<Symbol>] format names
+    # @return [self]
+    # @example
+    #   doc.with_formats(:markdown, :latex, :docx)
+    def with_formats(*formats)
+      @options[:formats] = formats.flatten
+      self
+    end
+
+    # Enable table extraction
+    # @param options [Hash] table options
+    # @return [self]
+    def with_tables(**options)
+      @options[:include_table_html] = true
+      @options.merge!(options)
+      self
+    end
+
+    # Enable diagram extraction
+    # @return [self]
+    def with_diagrams
+      @options[:include_diagram_svg] = true
+      self
+    end
+
+    # Set quality level
+    # @param level [Symbol] :low, :medium, :high
+    # @return [self]
+    def quality(level)
+      @options[:quality] = level
+      self
+    end
+
+    # Enable line-level data (bounding boxes)
+    # @return [self]
+    def with_line_data
+      @options[:include_line_data] = true
+      self
+    end
+
+    # Enable word-level data (bounding boxes)
+    # @return [self]
+    def with_word_data
+      @options[:include_word_data] = true
+      self
+    end
+
+    # Set page range for processing
+    # @param start_page [Integer] first page (1-indexed)
+    # @param end_page [Integer, nil] last page (nil = all)
+    # @return [self]
+    def pages(start_page, end_page = nil)
+      @options[:page_ranges] = { start: start_page, end: end_page }
+      self
+    end
+
+    # Execute document conversion (async operation).
+    #
+    # The whole document is uploaded in a single request — the Mathpix /v3/pdf
+    # endpoint paginates large PDFs server-side.
+    #
+    # @return [DocumentConversion] conversion object (async)
+    # @example
+    #   conversion = Mathpix::Document.new(client, 'paper.pdf')
+    #     .with_formats(:markdown, :latex)
+    #     .convert
+    #   conversion.wait_until_complete
+    #   conversion.save_markdown('output.md')
+    def convert
+      doc_type = detect_document_type
+      conversion_id = client.convert_document(
+        document_path: document_path,
+        document_type: doc_type,
+        **options
+      )
+      DocumentConversion.new(client, conversion_id, document_path, doc_type)
+    end
+
+    alias call convert
+    alias run convert
+
+    private
+
+    # Detect document type from file extension
+    # @return [Symbol] :pdf, :docx, :pptx
+    def detect_document_type
+      ext = File.extname(document_path).downcase
+      case ext
+      when '.pdf' then :pdf
+      when '.docx' then :docx
+      when '.pptx' then :pptx
+      else
+        raise InvalidImageError.new(
+          "Unsupported document format: #{ext}",
+          recommended_format: 'pdf, docx, pptx'
+        )
+      end
+    end
+  end
+
+  # Document Conversion Result (async operation)
+  #
+  # Polls Mathpix API until conversion completes
+  class DocumentConversion
+    attr_reader :client, :conversion_id, :document_path, :document_type
+
+    def initialize(client, conversion_id, document_path, document_type)
+      @client = client
+      @conversion_id = conversion_id
+      @document_path = document_path
+      @document_type = document_type
+    end
+
+    # Wait for conversion to complete
+    #
+    # @param max_wait [Integer] maximum wait time in seconds
+    # @param poll_interval [Float] seconds between polls
+    # @return [self]
+    def wait_until_complete(max_wait: 600, poll_interval: 3.0)
+      start_time = Time.now
+
+      loop do
+        status_data = client.get_document_status(conversion_id)
+        status = status_data['status']
+
+        case status
+        when 'completed'
+          @result = DocumentResult.new(build_result_data(status_data), document_path, document_type)
+          return self
+        when 'error', 'failed'
+          raise ConversionError.new(
+            "Document conversion failed: #{extract_status_error(status_data)}",
+            conversion_id: conversion_id,
+            conversion_status: status
+          )
+        else
+          # Any non-terminal status keeps polling. Mathpix reports several
+          # intermediate states (received, loaded, split, processing,
+          # pending, ...) — we only stop on 'completed' or an error.
+          elapsed = Time.now - start_time
+          if elapsed > max_wait
+            raise TimeoutError, "Document conversion timed out after #{max_wait}s (last status: #{status})"
+          end
+
+          sleep poll_interval
+        end
+      end
+    end
+
+    # Get result (must wait_until_complete first)
+    # @return [DocumentResult]
+    def result
+      @result || raise(ConversionError, 'Conversion not yet complete. Call wait_until_complete first.')
+    end
+
+    # Convenience method: wait and get result
+    # @return [DocumentResult]
+    def complete!
+      wait_until_complete
+      result
+    end
+
+    # Save markdown output
+    # @param path [String] output file path
+    def save_markdown(path)
+      complete! unless @result
+      @result.save_markdown(path)
+    end
+
+    # Save LaTeX output
+    # @param path [String] output file path
+    def save_latex(path)
+      complete! unless @result
+      @result.save_latex(path)
+    end
+
+    # Save HTML output
+    # @param path [String] output file path
+    def save_html(path)
+      complete! unless @result
+      @result.save_html(path)
+    end
+
+    # Save DOCX output
+    # @param path [String] output file path
+    def save_docx(path)
+      complete! unless @result
+      @result.save_docx(path)
+    end
+
+    private
+
+    # Merge fetched output content into the status payload so DocumentResult
+    # can expose markdown/html. The /v3/pdf/{id} status JSON never contains the
+    # converted text — it must be fetched from the .{ext} endpoints.
+    def build_result_data(status_data)
+      data = status_data.dup
+      data['markdown'] ||= fetch_output('mmd')
+      data['html'] ||= fetch_output('html')
+      data
+    end
+
+    def fetch_output(format)
+      client.get_document_output(conversion_id, format)
+    rescue Mathpix::Error
+      nil
+    end
+
+    # Pull a descriptive failure reason from a Mathpix status payload.
+    def extract_status_error(status_data)
+      info = status_data['error_info']
+      (info && (info['message'] || info['id'])) ||
+        status_data['error'] ||
+        'unknown error'
+    end
+  end
+
+  # Document Result object
+  #
+  # Represents processed document with extracted content
+  class DocumentResult < Result
+    attr_reader :document_path, :document_type
+
+    def initialize(data, document_path = nil, document_type = nil)
+      super(data)
+      @document_path = document_path
+      @document_type = document_type
+    end
+
+    # Get all pages
+    # @return [Array<Hash>] page data
+    def pages
+      data['pages'] || []
+    end
+
+    # Get page count
+    # @return [Integer]
+    def page_count
+      pages.length
+    end
+
+    # Processing time (seconds if reported by the conversion, else nil)
+    # @return [Numeric, nil]
+    def processing_time
+      data['total_processing_time'] || data['processing_time'] || processing_time_ms
+    end
+
+    # Get all equations across all pages
+    # @return [Array<String>]
+    def equations
+      pages.flat_map { |p| p['equations'] || [] }
+    end
+
+    # Get all tables across all pages
+    # @return [Array<Hash>]
+    def tables
+      pages.flat_map { |p| p['tables'] || [] }
+    end
+
+    # Get all diagrams across all pages
+    # @return [Array<Hash>]
+    def diagrams
+      pages.flat_map { |p| p['diagrams'] || [] }
+    end
+
+    # Get markdown output
+    # @return [String, nil]
+    def markdown
+      data['markdown'] || data['mmd']
+    end
+
+    # Get LaTeX output
+    # @return [String, nil]
+    def latex
+      data['latex']
+    end
+
+    # Get HTML output
+    # @return [String, nil]
+    def html
+      data['html']
+    end
+
+    # Save markdown to file
+    # @param path [String] output file path
+    def save_markdown(path)
+      File.write(path, markdown) if markdown
+    end
+
+    # Save LaTeX to file
+    # @param path [String] output file path
+    def save_latex(path)
+      File.write(path, latex) if latex
+    end
+
+    # Save HTML to file
+    # @param path [String] output file path
+    def save_html(path)
+      File.write(path, html) if html
+    end
+
+    # Save DOCX output to file
+    # @param path [String] output file path
+    def save_docx(path)
+      if data['docx_url']
+        docx_data = client.download(data['docx_url'])
+        File.binwrite(path, docx_data)
+      elsif data['docx_data']
+        File.binwrite(path, data['docx_data'])
+      end
+    end
+
+    # Check if document is a specific type
+    # @return [Boolean]
+    def pdf?
+      document_type == :pdf
+    end
+
+    def docx?
+      document_type == :docx
+    end
+
+    def pptx?
+      document_type == :pptx
+    end
+  end
+
+  # Alias PDF class to Document for backward compatibility
+  PDF = Document
+  PDFResult = DocumentResult
+end

data/lib/mathpix/errors.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Mathpix
+  # Base error class
+  class Error < StandardError
+    attr_reader :details
+
+    def initialize(message, details: {})
+      super(message)
+      @details = details
+    end
+  end
+
+  # Configuration error
+  class ConfigurationError < Error; end
+
+  # API error
+  class APIError < Error
+    attr_reader :status
+
+    def initialize(message, status: nil, details: {})
+      super(message, details: details)
+      @status = status
+    end
+  end
+
+  # Rate limit error
+  class RateLimitError < APIError
+    attr_reader :retry_after
+
+    def initialize(message, retry_after: nil, **)
+      super(message, **)
+      @retry_after = retry_after
+    end
+  end
+
+  # Server error (5xx)
+  class ServerError < APIError; end
+
+  # Network/timeout error
+  class NetworkError < Error; end
+  class TimeoutError < NetworkError; end
+
+  # Low confidence error
+  class LowConfidenceError < Error
+    attr_reader :confidence, :suggestions
+
+    def initialize(message, confidence: nil, suggestions: [])
+      super(message)
+      @confidence = confidence
+      @suggestions = suggestions
+    end
+  end
+
+  # Invalid request error (malformed input)
+  class InvalidRequestError < Error; end
+
+  # Invalid image error
+  class InvalidImageError < Error
+    attr_reader :recommended_format
+
+    def initialize(message, recommended_format: nil)
+      super(message)
+      @recommended_format = recommended_format
+    end
+  end
+
+  # Conversion error
+  class ConversionError < Error
+    attr_reader :conversion_id, :conversion_status
+
+    def initialize(message, conversion_id: nil, conversion_status: nil)
+      super(message)
+      @conversion_id = conversion_id
+      @conversion_status = conversion_status
+    end
+  end
+end