mathpix-mcp 1.0.0

data/lib/mathpix/mcp/base_tool.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+
+module Mathpix
+  module MCP
+    module Tools
+      # Base class for all Mathpix MCP tools
+      #
+      # Uses official Ruby MCP SDK (MCP::Tool)
+      # Provides common utilities for Mathpix-specific tools
+      #
+      #
+      # @example Tool implementation
+      #   class ExampleTool < BaseTool
+      #     description "Example tool"
+      #     input_schema(
+      #       properties: { message: { type: "string" } },
+      #       required: ["message"]
+      #     )
+      #
+      #     def self.call(message:, server_context:)
+      #       client = server_context[:mathpix_client]
+      #       # Use client to make API calls
+      #       text_response("Result: #{message}")
+      #     end
+      #   end
+      class BaseTool < ::MCP::Tool
+        class << self
+          protected
+
+          # Get Mathpix client from server context
+          #
+          # @param server_context [Hash] MCP server context
+          # @return [Mathpix::Client] Mathpix API client
+          def mathpix_client(server_context)
+            server_context[:mathpix_client] || raise(ArgumentError, 'mathpix_client not in server_context')
+          end
+
+          # Create text response (official MCP format)
+          #
+          # @param text [String] response text
+          # @return [::MCP::Tool::Response]
+          def text_response(text)
+            ::MCP::Tool::Response.new([{
+                                        type: 'text',
+                                        text: text
+                                      }])
+          end
+
+          # Create JSON response with text wrapper
+          #
+          # @param data [Hash] JSON data
+          # @return [::MCP::Tool::Response]
+          def json_response(data)
+            text_response(JSON.pretty_generate(data))
+          end
+
+          # Create error response
+          #
+          # @param error [StandardError, String] error object or message
+          # @return [::MCP::Tool::Response]
+          def error_response(error)
+            message = error.is_a?(StandardError) ? error.message : error.to_s
+            details = error.is_a?(Mathpix::Error) ? error.details : {}
+
+            error_data = {
+              error: true,
+              message: message,
+              type: error.is_a?(StandardError) ? error.class.name : 'Error'
+            }
+            error_data[:status] = error.status if error.is_a?(Mathpix::APIError) && error.status
+            error_data[:details] = details unless details.nil? || details.empty?
+
+            json_response(error_data)
+          end
+
+          # Extract formats from arguments
+          #
+          # @param formats [Array, nil] format array
+          # @param client [Mathpix::Client] client for defaults
+          # @return [Array<Symbol>] format symbols
+          def extract_formats(formats, client)
+            return client.config.default_formats if formats.nil? || formats.empty?
+
+            Array(formats).map(&:to_sym)
+          end
+
+          # Normalize path (expand ~, resolve relative paths)
+          #
+          # @param path [String] file path
+          # @return [String] normalized path
+          def normalize_path(path)
+            File.expand_path(path)
+          rescue StandardError
+            path
+          end
+
+          # Check if path is a URL
+          #
+          # @param path [String] path or URL
+          # @return [Boolean]
+          def url?(path)
+            path.to_s.start_with?('http://', 'https://')
+          end
+
+          # Characters of inline preview returned alongside a saved artifact.
+          PREVIEW_CHARS = 2_000
+
+          # Map an OCR format name to a sensible file extension.
+          ARTIFACT_EXT = {
+            'markdown' => 'md', 'md' => 'md', 'mmd' => 'mmd',
+            'latex' => 'tex', 'latex_styled' => 'tex', 'latex_simplified' => 'tex',
+            'text' => 'txt', 'text_display' => 'txt', 'asciimath' => 'txt',
+            'mathml' => 'mml', 'html' => 'html', 'data' => 'json',
+            'line_data' => 'json', 'word_data' => 'json'
+          }.freeze
+
+          # Directory where OCR artifacts are written when no explicit
+          # output_path is given. Configurable via MATHPIX_OUTPUT_DIR; defaults
+          # to the system temp dir.
+          #
+          # @return [String]
+          def artifact_dir
+            dir = ENV.fetch('MATHPIX_OUTPUT_DIR', nil)
+            dir && !dir.empty? ? File.expand_path(dir) : Dir.tmpdir
+          end
+
+          # Make a value safe to embed in a filename.
+          #
+          # @param value [#to_s]
+          # @return [String]
+          def sanitize(value)
+            value.to_s.gsub(/[^a-zA-Z0-9_-]/, '_')
+          end
+
+          # Short inline preview of a piece of content.
+          #
+          # @param content [String, nil]
+          # @param limit [Integer]
+          # @return [String, nil]
+          def preview_of(content, limit = PREVIEW_CHARS)
+            return nil if content.nil?
+
+            str = content.to_s
+            str.length > limit ? "#{str[0, limit]}…" : str
+          end
+
+          # Derive a sibling path with a different extension.
+          #
+          # @param base [String] base file path
+          # @param ext [String] extension without the dot
+          # @return [String]
+          def sibling_path(base, ext)
+            dir = File.dirname(base)
+            stem = File.basename(base, File.extname(base))
+            File.join(dir, "#{stem}.#{ext}")
+          end
+
+          # Write OCR artifacts to disk so their (potentially large) content
+          # never enters the model context. The first format is written to
+          # base_path (honoring any extension the caller chose); the rest are
+          # written to siblings whose extension is derived from the format name.
+          #
+          # @param contents [Hash{String,Symbol=>String}] format => content
+          # @param base_path [String] primary output path
+          # @return [Hash{String=>Hash}] format => { path:, bytes: }
+          def write_artifacts(contents, base_path)
+            base_path = File.expand_path(base_path)
+            ensure_dir(File.dirname(base_path))
+            saved = {}
+            first = true
+
+            contents.each do |format, content|
+              next if content.nil? || content.to_s.empty?
+
+              name = format.to_s
+              path =
+                if first
+                  first = false
+                  base_path
+                else
+                  sibling_path(base_path, ARTIFACT_EXT[name] || 'txt')
+                end
+
+              str = content.is_a?(String) ? content : JSON.pretty_generate(content)
+              File.write(path, str)
+              saved[name] = { path: path, bytes: str.bytesize }
+            end
+
+            saved
+          end
+
+          # Build a default artifact base path inside artifact_dir.
+          #
+          # @param stem [String] human-meaningful filename stem
+          # @param ext [String] extension without the dot
+          # @return [String]
+          def default_artifact_path(stem, ext)
+            File.join(artifact_dir, "mathpix_#{sanitize(stem)}.#{ext}")
+          end
+
+          # Ensure a directory exists (lazily requiring fileutils so tools that
+          # never write files don't pay for it).
+          def ensure_dir(dir)
+            require 'fileutils'
+            FileUtils.mkdir_p(dir)
+          end
+
+          # Safe execute with error handling
+          #
+          # @yield Block to execute
+          # @return [::MCP::Tool::Response]
+          def safe_execute
+            yield
+          rescue Mathpix::Error => e
+            error_response(e)
+          rescue StandardError => e
+            error_response(e)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/http_app.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'rack'
+require 'mcp/server/transports/streamable_http_transport'
+
+module Mathpix
+  module MCP
+    # Builds a Rack application that serves the Mathpix MCP server over the
+    # MCP Streamable HTTP transport, guarded by a bearer token.
+    #
+    # @example config.ru
+    #   require 'mathpix/mcp/http_app'
+    #   run Mathpix::MCP::HttpApp.build
+    module HttpApp
+      module_function
+
+      # Build the bearer-guarded Rack app.
+      #
+      # @param token [String] required bearer token (defaults to MATHPIX_MCP_TOKEN)
+      # @param server [Mathpix::MCP::Server] optional pre-built server
+      # @return [#call] a Rack application
+      # @raise [RuntimeError] if no token is configured
+      def build(token: ENV.fetch('MATHPIX_MCP_TOKEN', nil), server: nil)
+        raise 'MATHPIX_MCP_TOKEN must be set to run the HTTP transport (bearer-token auth is required)' if token.nil? || token.empty?
+
+        mcp_server = (server || Mathpix::MCP::Server.new).mcp_server
+        # stateless + JSON responses keep this simple and sidestep session
+        # state entirely; bearer auth guards every request.
+        transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(
+          mcp_server, stateless: true, enable_json_response: true
+        )
+        BearerAuth.new(transport, token: token)
+      end
+
+      # Rack middleware enforcing a constant-time bearer-token check.
+      class BearerAuth
+        def initialize(app, token:)
+          @app = app
+          @token = token
+        end
+
+        def call(env)
+          provided = env['HTTP_AUTHORIZATION'].to_s.sub(/\ABearer\s+/i, '')
+          return unauthorized unless Rack::Utils.secure_compare(@token, provided)
+
+          @app.call(env)
+        end
+
+        private
+
+        def unauthorized
+          [401,
+           { 'content-type' => 'application/json' },
+           [JSON.generate(error: true, message: 'Unauthorized: missing or invalid bearer token')]]
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/server.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+begin
+  require 'mcp'
+  require 'mcp/server/transports/stdio_transport' # transport 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 OCR.
+    #
+    # Uses the official Ruby MCP SDK. Provides 9 tools as thin delegates to
+    # Mathpix::Client over the stdio transport.
+    #
+    # @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::Server::Transports::StdioTransport]
+      def create_stdio_transport
+        ::MCP::Server::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)
+        }
+      end
+
+      # Class method: run server directly
+      #
+      # @example
+      #   Mathpix::MCP::Server.run
+      def self.run(**)
+        new(**).run
+      end
+
+      private
+
+      # Create the official MCP::Server with the tool classes
+      #
+      # Uses official Ruby MCP SDK structure
+      def create_mcp_server
+        ::MCP::Server.new(
+          name: @name,
+          version: @version,
+          tools: tool_classes,
+          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
+    end
+  end
+end

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

@@ -0,0 +1,147 @@
+# 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
+      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 concurrently (default: false)'
+            },
+            max_parallel: {
+              type: 'number',
+              description: 'Maximum number of concurrent requests when parallel is true (default: 3)'
+            },
+            output_dir: {
+              type: 'string',
+              description: 'Directory to write each image\'s OCR result into. Recognized content ' \
+                           'is always saved to files (never returned inline); defaults to ' \
+                           'MATHPIX_OUTPUT_DIR or the system temp dir.'
+            }
+          },
+          required: ['image_paths']
+        )
+
+        def self.call(image_paths:, server_context:, formats: nil, parallel: false, max_parallel: 3, output_dir: nil)
+          safe_execute do
+            client = mathpix_client(server_context)
+
+            # Extract formats or use defaults
+            output_formats = extract_formats(formats, client)
+            dir = output_dir && !output_dir.empty? ? File.expand_path(output_dir) : artifact_dir
+
+            # Normalize paths
+            normalized_paths = image_paths.map do |path|
+              url?(path) ? path : normalize_path(path)
+            end
+
+            # Process images (concurrently when requested)
+            results =
+              if parallel
+                process_batch_parallel(client, normalized_paths, output_formats, max_parallel.to_i, dir)
+              else
+                process_batch_sequential(client, normalized_paths, output_formats, dir)
+              end
+
+            # Format response
+            response_data = {
+              success: true,
+              batch_size: image_paths.length,
+              formats: output_formats,
+              parallel: parallel,
+              results: results,
+              summary: {
+                total: results.length,
+                successful: results.count { |r| r[:success] },
+                failed: results.count { |r| !r[:success] }
+              }
+            }
+
+            json_response(response_data)
+          end
+        end
+
+        # Convert a single image, writing its recognized content to a file and
+        # returning a result/error hash (never raises). The OCR text/latex is
+        # saved to disk rather than inlined so a large batch can't overflow the
+        # model context.
+        def self.convert_one(client, path, index, formats, dir)
+          result = client.snap(path, formats: formats)
+          contents = {
+            'latex' => result.latex,
+            'text' => result.text,
+            'mathml' => result.mathml,
+            'asciimath' => result.asciimath
+          }.compact
+          stem = url?(path) ? "image_#{index}" : File.basename(path, File.extname(path))
+          saved = write_artifacts(contents, File.join(dir, "mathpix_#{sanitize(stem)}.tex"))
+          {
+            index: index,
+            image_path: path,
+            success: true,
+            confidence: result.confidence,
+            saved_files: saved,
+            preview: preview_of(result.latex || result.text, 200)
+          }
+        rescue Mathpix::Error => e
+          {
+            index: index,
+            image_path: path,
+            success: false,
+            error: e.message
+          }
+        end
+
+        def self.process_batch_sequential(client, paths, formats, dir)
+          paths.map.with_index { |path, index| convert_one(client, path, index, formats, dir) }
+        end
+
+        # Bounded thread pool: at most max_parallel concurrent HTTP requests.
+        # Results are written back by original index so ordering is preserved.
+        def self.process_batch_parallel(client, paths, formats, max_parallel, dir)
+          max_parallel = 1 if max_parallel < 1
+          results = Array.new(paths.length)
+          queue = Queue.new
+          paths.each_with_index { |path, i| queue << [path, i] }
+
+          worker_count = [max_parallel, paths.length].min
+          workers = Array.new(worker_count) do
+            Thread.new do
+              loop do
+                path, index = begin
+                  queue.pop(true) # non-blocking; raises ThreadError when empty
+                rescue ThreadError
+                  break
+                end
+                results[index] = convert_one(client, path, index, formats, dir)
+              end
+            end
+          end
+
+          workers.each(&:join)
+          results
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# 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
+      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][:pages_completed] = status_data['num_pages_completed']
+              # The /v3/pdf status payload does NOT contain markdown_url/latex_url/
+              # html_url (those were always nil). The converted content lives at
+              # the /pdf/{id}.{ext} endpoints — report those, and how to fetch.
+              endpoint = client.config.endpoint
+              response_data[:results] = {
+                markdown_endpoint: "#{endpoint}/pdf/#{conversion_id}.mmd",
+                html_endpoint: "#{endpoint}/pdf/#{conversion_id}.html",
+                tex_endpoint: "#{endpoint}/pdf/#{conversion_id}.tex",
+                note: 'Fetch these with app_id/app_key headers, or call ' \
+                      'convert_document_tool to get the content directly.'
+              }
+            end
+
+            # Add error info if failed
+            if %w[error failed].include?(status_data['status'])
+              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