mathpix 0.1.0

data/lib/mathpix/mcp/server.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+begin
+  require 'mcp'
+  require 'mcp/transports/stdio'  # Transport classes not auto-loaded
+rescue LoadError
+  raise LoadError, <<~ERROR
+    The 'mcp' gem is required for MCP server functionality.
+
+    Add to your Gemfile:
+      gem 'mcp'
+
+    Or install directly:
+      gem install mcp
+
+    Official Ruby MCP SDK: https://github.com/modelcontextprotocol/ruby-sdk
+  ERROR
+end
+
+module Mathpix
+  module MCP
+    # MCP Server for Mathpix API
+    #
+    # Uses official Ruby MCP SDK (modelcontextprotocol/ruby-sdk)
+    # Provides 9 tools and 4 resources as thin delegates to core Mathpix::Client
+    #
+    # The geodesic path: official SDK, thin wrapper, thick core
+    #
+    # @example Start STDIO server
+    #   require 'mathpix/mcp'
+    #
+    #   Mathpix.configure do |config|
+    #     config.app_id = ENV['MATHPIX_APP_ID']
+    #     config.app_key = ENV['MATHPIX_APP_KEY']
+    #   end
+    #
+    #   Mathpix::MCP::Server.run
+    #
+    # @example With custom configuration
+    #   server = Mathpix::MCP::Server.new(
+    #     name: "mathpix-custom",
+    #     version: "1.0.0",
+    #     mathpix_client: custom_client
+    #   )
+    #   transport = server.create_stdio_transport
+    #   transport.open
+    class Server
+      attr_reader :name, :version, :mathpix_client, :mcp_server
+
+      # Initialize MCP server
+      #
+      # @param name [String] server name
+      # @param version [String] server version
+      # @param mathpix_client [Mathpix::Client] optional client instance
+      def initialize(name: "mathpix", version: Mathpix::VERSION, mathpix_client: nil)
+        @name = name
+        @version = version
+        @mathpix_client = mathpix_client || Mathpix.client
+        @mcp_server = create_mcp_server
+      end
+
+      # Create STDIO transport (standard MCP transport)
+      #
+      # @return [::MCP::Transports::StdioTransport]
+      def create_stdio_transport
+        ::MCP::Transports::StdioTransport.new(@mcp_server)
+      end
+
+      # Run MCP server with STDIO transport (blocking)
+      #
+      # Standard way to run MCP server via stdio
+      def run
+        transport = create_stdio_transport
+        transport.open
+      end
+
+      # Server capabilities
+      #
+      # @return [Hash] MCP server capabilities
+      def capabilities
+        {
+          tools: tool_classes.map(&:name),
+          resources: resource_specs.map { |r| r[:uri] }
+        }
+      end
+
+      # Class method: run server directly
+      #
+      # @example
+      #   Mathpix::MCP::Server.run
+      def self.run(**options)
+        new(**options).run
+      end
+
+      private
+
+      # Create official MCP::Server with tools and resources
+      #
+      # Uses official Ruby MCP SDK structure
+      def create_mcp_server
+        ::MCP::Server.new(
+          name: @name,
+          version: @version,
+          tools: tool_classes,
+          resources: build_resources,
+          server_context: { mathpix_client: @mathpix_client }
+        )
+      end
+
+      # List of all tool classes (using official MCP::Tool)
+      #
+      # @return [Array<Class>] tool classes
+      def tool_classes
+        [
+          Tools::ConvertImageTool,
+          Tools::ConvertDocumentTool,
+          Tools::ConvertStrokesTool,
+          Tools::BatchConvertTool,
+          Tools::CheckDocumentStatusTool,
+          Tools::SearchResultsTool,
+          Tools::GetUsageTool,
+          Tools::GetAccountInfoTool,
+          Tools::ListFormatsTool
+        ]
+      end
+
+      # Build MCP::Resource objects from specifications
+      #
+      # @return [Array<::MCP::Resource>] resource objects
+      def build_resources
+        resource_specs.map do |spec|
+          ::MCP::Resource.new(
+            uri: spec[:uri],
+            name: spec[:name],
+            description: spec[:description],
+            mime_type: spec[:mime_type]
+          )
+        end
+      end
+
+      # Resource specifications
+      #
+      # @return [Array<Hash>] resource specs
+      def resource_specs
+        [
+          {
+            uri: "mathpix://snip/recent/latest",
+            name: "latest-snip",
+            description: "Most recent capture result",
+            mime_type: "application/json"
+          },
+          {
+            uri: "mathpix://snip/stats",
+            name: "snip-stats",
+            description: "Overall capture statistics",
+            mime_type: "application/json"
+          },
+          {
+            uri: "mathpix://snip/recent?limit=10",
+            name: "recent-snips",
+            description: "Recent capture results (default limit 10)",
+            mime_type: "application/json"
+          },
+          {
+            uri: "mathpix://formats/list",
+            name: "formats-list",
+            description: "Available output formats",
+            mime_type: "application/json"
+          }
+        ]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+
+module Mathpix
+  module MCP
+    module Tools
+      # Batch Convert Tool
+      #
+      # Converts multiple images in batch for efficiency
+      # Thin delegate to Mathpix::Client#snap with batch processing
+      #
+      # The geodesic path: official SDK + batch iteration
+      class BatchConvertTool < BaseTool
+        description "Convert multiple images in batch using Mathpix OCR"
+
+        input_schema(
+          properties: {
+            image_paths: {
+              type: "array",
+              items: { type: "string" },
+              description: "Array of image paths or URLs to process"
+            },
+            formats: {
+              type: "array",
+              items: { type: "string" },
+              description: "Output formats for all images: latex, text, mathml, asciimath (default: latex_styled, text)"
+            },
+            parallel: {
+              type: "boolean",
+              description: "Process images in parallel (default: false)"
+            },
+            max_parallel: {
+              type: "number",
+              description: "Maximum number of parallel requests (default: 3)"
+            }
+          },
+          required: ["image_paths"]
+        )
+
+        def self.call(image_paths:, formats: nil, parallel: false, max_parallel: 3, server_context:)
+          safe_execute do
+            client = mathpix_client(server_context)
+
+            # Extract formats or use defaults
+            output_formats = extract_formats(formats, client)
+
+            # Normalize paths
+            normalized_paths = image_paths.map do |path|
+              url?(path) ? path : normalize_path(path)
+            end
+
+            # Process images
+            results = if parallel
+              # TODO: Implement parallel processing (requires threading)
+              # For now, process sequentially
+              process_batch_sequential(client, normalized_paths, output_formats)
+            else
+              process_batch_sequential(client, normalized_paths, output_formats)
+            end
+
+            # Format response
+            response_data = {
+              success: true,
+              batch_size: image_paths.length,
+              formats: output_formats,
+              results: results,
+              summary: {
+                total: results.length,
+                successful: results.count { |r| r[:success] },
+                failed: results.count { |r| !r[:success] }
+              }
+            }
+
+            json_response(response_data)
+          end
+        end
+
+        private
+
+        def self.process_batch_sequential(client, paths, formats)
+          paths.map.with_index do |path, index|
+            begin
+              result = client.snap(path, formats: formats)
+              {
+                index: index,
+                image_path: path,
+                success: true,
+                latex: result.latex,
+                text: result.text,
+                confidence: result.confidence
+              }
+            rescue Mathpix::Error => e
+              {
+                index: index,
+                image_path: path,
+                success: false,
+                error: e.message
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+
+module Mathpix
+  module MCP
+    module Tools
+      # Check Document Status Tool
+      #
+      # Polls document conversion status for async operations
+      # Thin delegate to Mathpix::Client#get_document_status
+      #
+      # The geodesic path: official SDK + status polling
+      class CheckDocumentStatusTool < BaseTool
+        description "Check the status of a document conversion (PDF, DOCX, PPTX)"
+
+        input_schema(
+          properties: {
+            conversion_id: {
+              type: "string",
+              description: "Document conversion ID returned from convert_document"
+            }
+          },
+          required: ["conversion_id"]
+        )
+
+        def self.call(conversion_id:, server_context:)
+          safe_execute do
+            client = mathpix_client(server_context)
+
+            # Delegate to core gem
+            status_data = client.get_document_status(conversion_id)
+
+            # Format response
+            response_data = {
+              success: true,
+              conversion_id: conversion_id,
+              status: status_data['status'],
+              progress: status_data['percent_done'],
+              metadata: {}
+            }
+
+            # Add completion data if available
+            if status_data['status'] == 'completed'
+              response_data[:metadata][:pages] = status_data['num_pages']
+              response_data[:metadata][:processing_time] = status_data['processing_time']
+              response_data[:results] = {
+                markdown_url: status_data['markdown_url'],
+                latex_url: status_data['latex_url'],
+                html_url: status_data['html_url']
+              }
+            end
+
+            # Add error info if failed
+            if status_data['status'] == 'error' || status_data['status'] == 'failed'
+              response_data[:error] = status_data['error']
+              response_data[:error_info] = status_data['error_info']
+            end
+
+            json_response(response_data)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+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
+      #
+      # The geodesic path: official SDK + Document class delegation
+      class ConvertDocumentTool < BaseTool
+        description "Convert document (PDF, DOCX, PPTX) to Markdown, LaTeX, HTML, or other formats using Mathpix OCR"
+
+        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"
+            },
+            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:, formats: nil, include_tables: false, max_wait: 600, poll_interval: 3.0, server_context:)
+          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
+            conversion = doc.convert
+
+            # Wait for completion
+            conversion.wait_until_complete(max_wait: max_wait, poll_interval: poll_interval)
+            result = conversion.result
+
+            # Format response
+            response_data = {
+              success: true,
+              document_path: document_path,
+              formats: output_formats,
+              conversion_id: conversion.conversion_id,
+              results: {
+                markdown: result.markdown,
+                latex: result.latex,
+                html: result.html
+              },
+              metadata: {
+                document_type: conversion.document_type,
+                pages: result.pages,
+                processing_time: result.processing_time
+              }
+            }
+
+            json_response(response_data)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# 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
+      #
+      # The geodesic path: official SDK + core gem delegation
+      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)"
+            }
+          },
+          required: ["image_path"]
+        )
+
+        def self.call(image_path:, formats: nil, include_line_data: false, include_word_data: false, confidence_threshold: nil, server_context:)
+          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)
+
+            # Build options
+            options = {}
+            options[:formats] = output_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
+
+            # Delegate to core gem
+            result = client.snap(image_path, **options)
+
+            # Format response
+            response_data = {
+              success: true,
+              image_path: image_path,
+              formats: output_formats,
+              results: {
+                latex: result.latex,
+                text: result.text,
+                confidence: result.confidence,
+                is_printed: result.printed?,
+                is_handwritten: result.handwritten?,
+                position: result.position
+              }
+            }
+
+            # Add optional data
+            response_data[:line_data] = result.line_data if include_line_data
+            response_data[:word_data] = result.word_data if include_word_data
+            response_data[:results][:mathml] = result.mathml if result.mathml
+            response_data[:results][:asciimath] = result.asciimath if result.asciimath
+
+            json_response(response_data)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# 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
+      #
+      # The geodesic path: official SDK + stroke recognition
+      class ConvertStrokesTool < BaseTool
+        description "Convert handwritten strokes to LaTeX, text, or other formats using Mathpix OCR"
+
+        input_schema(
+          properties: {
+            strokes: {
+              type: "array",
+              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"
+            }
+          },
+          required: ["strokes"]
+        )
+
+        def self.call(strokes:, formats: nil, width: nil, height: nil, server_context:)
+          safe_execute do
+            client = mathpix_client(server_context)
+
+            # Extract formats or use defaults
+            output_formats = extract_formats(formats, client)
+
+            # Build strokes data structure
+            strokes_data = {
+              strokes: strokes
+            }
+            strokes_data[:width] = width if width
+            strokes_data[:height] = height if height
+
+            # Delegate to core gem snap method with strokes
+            result = client.snap(strokes_data, formats: output_formats)
+
+            # Format response
+            response_data = {
+              success: true,
+              input_type: "strokes",
+              stroke_count: strokes.length,
+              formats: output_formats,
+              results: {
+                latex: result.latex,
+                text: result.text,
+                confidence: result.confidence,
+                is_handwritten: result.handwritten?,
+                position: result.position
+              }
+            }
+
+            # Add optional formats
+            response_data[:results][:mathml] = result.mathml if result.mathml
+            response_data[:results][:asciimath] = result.asciimath if result.asciimath
+
+            json_response(response_data)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# 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)
+      #
+      # The geodesic path: official SDK + account management
+      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)
+
+            begin
+              # Try to call the account endpoint
+              account_data = client.get('/account')
+
+              response_data = {
+                success: true,
+                account: {
+                  email: account_data['email'],
+                  plan: account_data['plan'],
+                  created_at: account_data['created_at'],
+                  limits: {
+                    monthly_requests: account_data['monthly_requests'],
+                    max_file_size: account_data['max_file_size'],
+                    features: account_data['features']
+                  }
+                }
+              }
+
+              json_response(response_data)
+            rescue Mathpix::APIError => e
+              # Handle API-specific errors properly
+              error_response(e)
+            rescue StandardError => e
+              # Handle unexpected errors
+              error_response(e)
+            end
+          end
+        end
+      end
+    end
+  end
+end