mathpix-mcp 1.0.0

data/lib/mathpix/mcp/tools/convert_document_tool.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+require_relative '../base_tool'
+
+module Mathpix
+  module MCP
+    module Tools
+      # Convert Document Tool
+      #
+      # Converts documents (PDF, DOCX, PPTX) to Markdown, LaTeX, or other formats
+      # Thin delegate to Mathpix::Document
+      class ConvertDocumentTool < BaseTool
+        description 'Convert document (PDF, DOCX, PPTX) to Markdown, LaTeX, HTML, or other formats using Mathpix OCR'
+
+        # Above this many characters, returning the converted content inline
+        # would risk overflowing the LLM context window, so the result is
+        # written to a file and only a path + preview is returned.
+        DEFAULT_MAX_INLINE_CHARS = 50_000
+
+        # Characters of the converted markdown to include as a preview when the
+        # full content is written to a file instead of returned inline.
+        PREVIEW_CHARS = 2_000
+
+        input_schema(
+          properties: {
+            document_path: {
+              type: 'string',
+              description: 'Path to document file or URL (PDF, DOCX, or PPTX)'
+            },
+            formats: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Output formats: markdown, latex, html, docx (default: markdown)'
+            },
+            include_tables: {
+              type: 'boolean',
+              description: 'Include table extraction as HTML'
+            },
+            output_path: {
+              type: 'string',
+              description: 'If set, write the converted output to this file (markdown). Other ' \
+                           'formats are written alongside with matching extensions. The response ' \
+                           'then returns file paths + a short preview instead of the full content.'
+            },
+            max_inline_chars: {
+              type: 'number',
+              description: 'Maximum characters to return inline before auto-saving to a file to ' \
+                           "avoid exceeding the model context (default: #{DEFAULT_MAX_INLINE_CHARS}). " \
+                           'Ignored when output_path is set.'
+            },
+            max_wait: {
+              type: 'number',
+              description: 'Maximum wait time in seconds for conversion (default: 600)'
+            },
+            poll_interval: {
+              type: 'number',
+              description: 'Polling interval in seconds (default: 3.0)'
+            }
+          },
+          required: ['document_path']
+        )
+
+        def self.call(document_path:, server_context:, formats: nil, include_tables: false,
+                      output_path: nil, max_inline_chars: DEFAULT_MAX_INLINE_CHARS,
+                      max_wait: 600, poll_interval: 3.0)
+          safe_execute do
+            client = mathpix_client(server_context)
+
+            # Normalize path
+            document_path = normalize_path(document_path) unless url?(document_path)
+
+            # Extract formats or use defaults
+            output_formats = extract_formats(formats, client)
+
+            # Use Document class (new unified interface)
+            doc = Mathpix::Document.new(client, document_path)
+            doc.with_formats(*output_formats)
+            doc.with_tables if include_tables
+
+            # Start conversion and wait for completion
+            conversion = doc.convert
+            conversion.wait_until_complete(max_wait: max_wait, poll_interval: poll_interval)
+            result = conversion.result
+
+            contents = {
+              markdown: result.markdown,
+              latex: result.latex,
+              html: result.html
+            }.compact
+
+            response_data = {
+              success: true,
+              document_path: document_path,
+              formats: output_formats,
+              conversion_id: conversion.conversion_id,
+              metadata: {
+                document_type: conversion.document_type,
+                pages: result.page_count,
+                processing_time: result.processing_time
+              }
+            }
+
+            total_chars = contents.values.sum(&:length)
+
+            if output_path
+              # Explicit save requested.
+              response_data[:saved_files] = save_contents(contents, File.expand_path(output_path))
+              response_data[:preview] = preview_of(result.markdown)
+            elsif total_chars <= max_inline_chars
+              # Small enough to return inline.
+              response_data[:results] = contents
+            else
+              # Too large to inline safely — auto-save to a temp file so the
+              # model's context isn't blown out.
+              default_path = File.join(Dir.tmpdir, "mathpix_#{sanitize(conversion.conversion_id)}.md")
+              response_data[:saved_files] = save_contents(contents, default_path)
+              response_data[:preview] = preview_of(result.markdown)
+              response_data[:note] =
+                "Converted output is #{total_chars} characters, which exceeds max_inline_chars " \
+                "(#{max_inline_chars}); it was written to a file to avoid exceeding the model " \
+                'context. Read the file at saved_files for the full content, pass output_path to ' \
+                'choose the destination, or raise max_inline_chars to force inline output.'
+            end
+
+            json_response(response_data)
+          end
+        end
+
+        # Write each available format to disk, deriving sibling paths for the
+        # non-markdown formats from the markdown target's name.
+        #
+        # @param contents [Hash{Symbol=>String}] format => content
+        # @param markdown_path [String] target path for the markdown output
+        # @return [Hash{Symbol=>Hash}] format => { path:, bytes: }
+        def self.save_contents(contents, markdown_path)
+          ext_for = { markdown: nil, latex: 'tex', html: 'html' }
+          saved = {}
+
+          contents.each do |format, content|
+            path =
+              if format == :markdown
+                markdown_path
+              else
+                sibling_path(markdown_path, ext_for[format] || format.to_s)
+              end
+
+            File.write(path, content)
+            saved[format] = { path: path, bytes: content.bytesize }
+          end
+
+          saved
+        end
+
+        # Derive a sibling path with a different extension.
+        def self.sibling_path(base, ext)
+          dir = File.dirname(base)
+          stem = File.basename(base, File.extname(base))
+          File.join(dir, "#{stem}.#{ext}")
+        end
+
+        # First PREVIEW_CHARS characters of the content, if any.
+        def self.preview_of(content)
+          return nil unless content
+
+          content.length > PREVIEW_CHARS ? "#{content[0, PREVIEW_CHARS]}…" : content
+        end
+
+        # Make a conversion id safe to use in a filename.
+        def self.sanitize(value)
+          value.to_s.gsub(/[^a-zA-Z0-9_-]/, '_')
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/tools/convert_image_tool.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+
+module Mathpix
+  module MCP
+    module Tools
+      # Convert Image Tool
+      #
+      # Converts images (PNG, JPG, etc.) to LaTeX, text, or other formats
+      # Thin delegate to Mathpix::Client#snap
+      class ConvertImageTool < BaseTool
+        description 'Convert image (PNG, JPG, etc.) to LaTeX, text, or other formats using Mathpix OCR'
+
+        input_schema(
+          properties: {
+            image_path: {
+              type: 'string',
+              description: 'Path to image file or URL (http:// or https://)'
+            },
+            formats: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Output formats: latex, text, mathml, asciimath, latex_styled, text_display, data, html (default: latex_styled, text)'
+            },
+            include_line_data: {
+              type: 'boolean',
+              description: 'Include line-level bounding boxes in response'
+            },
+            include_word_data: {
+              type: 'boolean',
+              description: 'Include word-level bounding boxes in response'
+            },
+            confidence_threshold: {
+              type: 'number',
+              description: 'Minimum confidence threshold (0.0-1.0)'
+            },
+            output_path: {
+              type: 'string',
+              description: 'Where to write the OCR result. The recognized content is always ' \
+                           'saved to a file (never returned inline); defaults to MATHPIX_OUTPUT_DIR ' \
+                           'or the system temp dir.'
+            }
+          },
+          required: ['image_path']
+        )
+
+        def self.call(image_path:, server_context:, formats: nil, include_line_data: false, include_word_data: false,
+                      confidence_threshold: nil, output_path: nil)
+          safe_execute do
+            client = mathpix_client(server_context)
+
+            # Normalize path (expand ~, resolve relative paths)
+            image_path = normalize_path(image_path) unless url?(image_path)
+
+            # Extract formats or use defaults
+            output_formats = extract_formats(formats, client)
+
+            # Delegate to core gem
+            result = client.snap(image_path,
+                                 **snap_options(output_formats, include_line_data, include_word_data,
+                                                confidence_threshold))
+
+            # Write recognized content (and any requested bounding-box data) to
+            # files so it never enters the model context.
+            contents = artifact_contents(result, include_line_data, include_word_data)
+            stem = url?(image_path) ? 'image' : File.basename(image_path, File.extname(image_path))
+            base = output_path && !output_path.empty? ? output_path : default_artifact_path(stem, 'tex')
+
+            json_response(
+              success: true,
+              image_path: image_path,
+              formats: output_formats,
+              confidence: result.confidence,
+              is_printed: result.printed?,
+              is_handwritten: result.handwritten?,
+              saved_files: write_artifacts(contents, base),
+              preview: preview_of(result.latex || result.text)
+            )
+          end
+        end
+
+        # Build the options hash passed to Client#snap.
+        def self.snap_options(formats, include_line_data, include_word_data, confidence_threshold)
+          options = { formats: formats }
+          options[:include_line_data] = true if include_line_data
+          options[:include_word_data] = true if include_word_data
+          options[:confidence_threshold] = confidence_threshold if confidence_threshold
+          options
+        end
+
+        # Available OCR formats (and optional bounding-box data) as a
+        # format => content hash.
+        def self.artifact_contents(result, include_line_data, include_word_data)
+          contents = {
+            'latex' => result.latex,
+            'text' => result.text,
+            'mathml' => result.mathml,
+            'asciimath' => result.asciimath
+          }.compact
+          contents['line_data'] = result.line_data if include_line_data && !result.line_data.empty?
+          contents['word_data'] = result.word_data if include_word_data && !result.word_data.empty?
+          contents
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/tools/convert_strokes_tool.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+
+module Mathpix
+  module MCP
+    module Tools
+      # Convert Strokes Tool
+      #
+      # Converts handwritten strokes to LaTeX, text, or other formats
+      # Thin delegate to Mathpix::Client#snap with strokes format
+      class ConvertStrokesTool < BaseTool
+        description 'Convert handwritten strokes to LaTeX, text, or other formats using Mathpix OCR'
+
+        input_schema(
+          properties: {
+            strokes: {
+              type: 'array',
+              items: {
+                type: 'array',
+                items: {
+                  type: 'array',
+                  items: { type: 'number' }
+                }
+              },
+              description: 'Array of stroke arrays, where each stroke is an array of [x, y] coordinates'
+            },
+            formats: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Output formats: latex, text, mathml, asciimath (default: latex_styled, text)'
+            },
+            width: {
+              type: 'number',
+              description: 'Canvas width for stroke normalization'
+            },
+            height: {
+              type: 'number',
+              description: 'Canvas height for stroke normalization'
+            },
+            output_path: {
+              type: 'string',
+              description: 'Where to write the OCR result. The recognized content is always ' \
+                           'saved to a file (never returned inline); defaults to MATHPIX_OUTPUT_DIR ' \
+                           'or the system temp dir.'
+            }
+          },
+          required: ['strokes']
+        )
+
+        def self.call(strokes:, server_context:, formats: nil, width: nil, height: nil, output_path: nil)
+          safe_execute do
+            client = mathpix_client(server_context)
+
+            # Extract formats or use defaults
+            output_formats = extract_formats(formats, client)
+
+            # Delegate to the strokes endpoint (transposes points internally)
+            options = { formats: output_formats }
+            options[:width] = width if width
+            options[:height] = height if height
+            result = client.convert_strokes(strokes, **options)
+
+            # Collect available formats and write them to disk so the recognized
+            # content never enters the model context.
+            contents = artifact_contents(result)
+            base = output_path && !output_path.empty? ? output_path : default_artifact_path('strokes', 'tex')
+            saved = write_artifacts(contents, base)
+
+            response_data = {
+              success: true,
+              input_type: 'strokes',
+              stroke_count: strokes.length,
+              formats: output_formats,
+              confidence: result.confidence,
+              is_handwritten: result.handwritten?,
+              saved_files: saved,
+              preview: preview_of(result.latex || result.text)
+            }
+
+            json_response(response_data)
+          end
+        end
+
+        # Available OCR formats as a format => content hash.
+        def self.artifact_contents(result)
+          {
+            'latex' => result.latex,
+            'text' => result.text,
+            'mathml' => result.mathml,
+            'asciimath' => result.asciimath
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/tools/get_account_info_tool.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+
+module Mathpix
+  module MCP
+    module Tools
+      # Get Account Info Tool
+      #
+      # Retrieves account information and plan details
+      # Thin delegate to Mathpix::Client (account endpoint)
+      class GetAccountInfoTool < BaseTool
+        description 'Get Mathpix account information, plan details, and limits'
+
+        input_schema(
+          properties: {},
+          required: []
+        )
+
+        def self.call(server_context:)
+          safe_execute do
+            client = mathpix_client(server_context)
+
+            # Mathpix's v3 API has no account/plan endpoint for app tokens
+            # (/v3/account returns 404). Derive the identifiers it does expose
+            # from /v3/ocr-usage and tell the caller where to find plan/limits.
+            rows = client.get('/ocr-usage', params: {})['ocr_usage'] || []
+            first = rows.first || {}
+
+            response_data = {
+              success: true,
+              account: {
+                app_id: first['app_id'] || client.config.app_id,
+                group_id: first['group_id']
+              },
+              note: 'Mathpix exposes no account/plan endpoint via the API; app_id/group_id are ' \
+                    'derived from /v3/ocr-usage. View plan, limits, and billing in the Mathpix ' \
+                    'console at https://console.mathpix.com.'
+            }
+
+            json_response(response_data)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/tools/get_usage_tool.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+
+module Mathpix
+  module MCP
+    module Tools
+      # Get Usage Tool
+      #
+      # Retrieves API usage statistics and account limits
+      # Thin delegate to Mathpix::Client (usage endpoint)
+      class GetUsageTool < BaseTool
+        description 'Get Mathpix API usage statistics and remaining credits'
+
+        input_schema(
+          properties: {
+            from_date: {
+              type: 'string',
+              description: 'ISO-8601 start date to report usage from (e.g. 2026-06-01T00:00:00.000Z). ' \
+                           'Omit to use the Mathpix default window.'
+            },
+            detailed: {
+              type: 'boolean',
+              description: 'Include the raw per-request usage rows (default: false)'
+            }
+          },
+          required: []
+        )
+
+        def self.call(server_context:, from_date: nil, detailed: false)
+          safe_execute do
+            client = mathpix_client(server_context)
+
+            # Mathpix exposes usage at /v3/ocr-usage; there is no /v3/usage.
+            params = {}
+            params[:from_date] = from_date if from_date && !from_date.empty?
+            usage_data = client.get('/ocr-usage', params: params)
+
+            rows = usage_data['ocr_usage'] || []
+            by_type = rows.each_with_object(Hash.new(0)) do |row, acc|
+              acc[row['usage_type']] += row['count'] || 0
+            end
+
+            response_data = {
+              success: true,
+              usage: {
+                app_id: rows.first&.fetch('app_id', nil),
+                group_id: rows.first&.fetch('group_id', nil),
+                total_requests: rows.sum { |row| row['count'] || 0 },
+                by_usage_type: by_type
+              }
+            }
+            response_data[:rows] = rows if detailed
+
+            json_response(response_data)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/tools/list_formats_tool.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+
+module Mathpix
+  module MCP
+    module Tools
+      # List Formats Tool
+      #
+      # Lists all available output formats for Mathpix OCR
+      # Static data from API documentation
+      class ListFormatsTool < BaseTool
+        description 'List all available output formats for Mathpix OCR operations'
+
+        input_schema(
+          properties: {
+            category: {
+              type: 'string',
+              description: 'Filter by category: image, document, or all (default: all)',
+              enum: %w[image document all]
+            }
+          },
+          required: []
+        )
+
+        def self.call(server_context:, category: 'all')
+          safe_execute do
+            # Static format definitions
+            image_formats = [
+              { name: 'latex_styled', description: 'LaTeX with styling', type: 'image' },
+              { name: 'text', description: 'Plain text', type: 'image' },
+              { name: 'latex_list', description: 'Array of LaTeX expressions', type: 'image' },
+              { name: 'mathml', description: 'MathML markup', type: 'image' },
+              { name: 'asciimath', description: 'AsciiMath notation', type: 'image' },
+              { name: 'text_display', description: 'Display-style text', type: 'image' },
+              { name: 'latex_simplified', description: 'Simplified LaTeX', type: 'image' },
+              { name: 'data', description: 'Full response data with metadata', type: 'image' },
+              { name: 'html', description: 'HTML markup', type: 'image' }
+            ]
+
+            document_formats = [
+              { name: 'markdown', description: 'Markdown format', type: 'document' },
+              { name: 'latex', description: 'LaTeX document', type: 'document' },
+              { name: 'html', description: 'HTML document', type: 'document' },
+              { name: 'docx', description: 'Microsoft Word document', type: 'document' },
+              { name: 'tex.zip', description: 'LaTeX with figures (zipped)', type: 'document' }
+            ]
+
+            # Filter by category
+            formats = case category
+                      when 'image'
+                        image_formats
+                      when 'document'
+                        document_formats
+                      when 'all'
+                        image_formats + document_formats
+                      else
+                        image_formats + document_formats
+                      end
+
+            # Format response
+            response_data = {
+              success: true,
+              category: category,
+              count: formats.length,
+              formats: formats,
+              usage: {
+                image_capture: 'Use with snap() or ConvertImageTool',
+                document_conversion: 'Use with document() or ConvertDocumentTool'
+              }
+            }
+
+            json_response(response_data)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/tools/search_results_tool.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+
+module Mathpix
+  module MCP
+    module Tools
+      # Search Results Tool
+      #
+      # Searches recent capture results with optional filtering
+      # Thin delegate to Mathpix::Client#recent with search
+      class SearchResultsTool < BaseTool
+        description 'Search recent Mathpix capture results with optional text filtering'
+
+        input_schema(
+          properties: {
+            query: {
+              type: 'string',
+              description: 'Search query to filter results by LaTeX or text content'
+            },
+            limit: {
+              type: 'number',
+              description: 'Maximum number of results to return (default: 10, max: 100)'
+            },
+            offset: {
+              type: 'number',
+              description: 'Offset for pagination (default: 0)'
+            },
+            include_content: {
+              type: 'boolean',
+              description: 'Write each result\'s full LaTeX/text to a file and return its path ' \
+                           '(default: false, previews only). Content is never returned inline.'
+            },
+            output_dir: {
+              type: 'string',
+              description: 'Directory for files written when include_content is true; defaults to ' \
+                           'MATHPIX_OUTPUT_DIR or the system temp dir.'
+            }
+          },
+          required: []
+        )
+
+        def self.call(server_context:, query: nil, limit: 10, offset: 0, include_content: false, output_dir: nil)
+          safe_execute do
+            client = mathpix_client(server_context)
+            dir = output_dir && !output_dir.empty? ? File.expand_path(output_dir) : artifact_dir
+
+            # Validate and constrain limit
+            limit = [[limit.to_i, 1].max, 100].min
+
+            # Get recent results from API
+            recent_results = client.recent(limit: limit + offset)
+
+            # Apply offset
+            results = recent_results.drop(offset)
+
+            # Apply search filter if query provided
+            if query && !query.empty?
+              query_lower = query.downcase
+              results = results.select do |result|
+                result.latex&.downcase&.include?(query_lower) ||
+                  result.text&.downcase&.include?(query_lower)
+              end
+            end
+
+            # Limit after filtering
+            results = results.take(limit)
+
+            # Format results. Previews are always inline; full content (when
+            # requested) is written to a file so it never enters the context.
+            formatted_results = results.each_with_index.map do |result, index|
+              item = {
+                id: result.request_id,
+                created_at: result.timestamp,
+                confidence: result.confidence,
+                is_printed: result.printed?,
+                is_handwritten: result.handwritten?,
+                latex_preview: truncate(result.latex, 100),
+                text_preview: truncate(result.text, 100)
+              }
+
+              if include_content
+                contents = { 'latex' => result.latex, 'text' => result.text }.compact
+                unless contents.empty?
+                  stem = result.request_id || "result_#{offset + index}"
+                  item[:saved_files] = write_artifacts(contents, File.join(dir, "mathpix_#{sanitize(stem)}.tex"))
+                end
+              end
+
+              item
+            end
+
+            # Format response
+            response_data = {
+              success: true,
+              query: query,
+              limit: limit,
+              offset: offset,
+              count: formatted_results.length,
+              results: formatted_results
+            }
+
+            json_response(response_data)
+          end
+        end
+
+        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