mathpix-mcp 1.0.0

data/lib/mathpix/mcp.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# MCP (Model Context Protocol) integration for Mathpix
+#
+# This module provides MCP server functionality using the official Ruby MCP SDK.
+# All 9 tools are thin delegates to the core Mathpix::Client.
+#
+# Usage:
+#   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
+
+# Load MCP components (stdio server only)
+require_relative 'mcp/server'
+require_relative 'mcp/base_tool'
+
+# Load all 9 tools
+require_relative 'mcp/tools/convert_image_tool'
+require_relative 'mcp/tools/convert_document_tool'
+require_relative 'mcp/tools/convert_strokes_tool'
+require_relative 'mcp/tools/batch_convert_tool'
+require_relative 'mcp/tools/check_document_status_tool'
+require_relative 'mcp/tools/search_results_tool'
+require_relative 'mcp/tools/get_usage_tool'
+require_relative 'mcp/tools/get_account_info_tool'
+require_relative 'mcp/tools/list_formats_tool'

data/lib/mathpix/result.rb

@@ -0,0 +1,387 @@
+# frozen_string_literal: true
+
+module Mathpix
+  # OCR Result object
+  class Result
+    attr_reader :data, :source_path
+
+    def initialize(data, source_path = nil)
+      @data = data
+      @source_path = source_path
+    end
+
+    # Get source URL if image was processed from URL
+    #
+    # @return [String, nil] URL if source was remote, nil otherwise
+    def source_url
+      return nil unless @source_path.is_a?(String)
+
+      @source_path.start_with?('http://', 'https://') ? @source_path : nil
+    end
+
+    # Text result
+    # @return [String, nil]
+    def text
+      data['text']
+    end
+
+    # LaTeX styled output
+    # @return [String, nil]
+    def latex
+      data['latex_styled'] || data['latex']
+    end
+
+    alias latex_styled latex
+
+    # Simplified LaTeX
+    # @return [String, nil]
+    def latex_simplified
+      data['latex_simplified']
+    end
+
+    # MathML output
+    # @return [String, nil]
+    def mathml
+      data['mathml']
+    end
+
+    # AsciiMath output
+    # @return [String, nil]
+    def asciimath
+      data['asciimath']
+    end
+
+    # HTML output (may contain SVG)
+    # @return [String, nil]
+    def html
+      data['html']
+    end
+
+    # Confidence score
+    # @return [Float] 0.0-1.0
+    def confidence
+      data['confidence'] || 0.0
+    end
+
+    # Confidence rate (alternative)
+    # @return [Float] 0.0-1.0
+    def confidence_rate
+      data['confidence_rate'] || confidence
+    end
+
+    # Created timestamp
+    # @return [Time, nil]
+    def created_at
+      Time.parse(data['created']) if data['created']
+    rescue ArgumentError
+      nil
+    end
+
+    # Request ID
+    # @return [String, nil]
+    def request_id
+      data['request_id']
+    end
+
+    # Processing time in milliseconds
+    # @return [Integer, nil]
+    def processing_time_ms
+      data['processing_time_ms']
+    end
+
+    # Bounding box / position of the detected region, if the API returned one.
+    # @return [Hash, nil]
+    def position
+      data['position']
+    end
+
+    # Raw capture timestamp (used by recent/search results).
+    # @return [String, nil]
+    def timestamp
+      data['timestamp'] || data['created']
+    end
+
+    # Line-level data array (alias for lines_json).
+    # @return [Array<Hash>]
+    def line_data
+      lines_json
+    end
+
+    # Word-level data array, if present.
+    # @return [Array<Hash>]
+    def word_data
+      data['word_data'] || []
+    end
+
+    # Is content printed (vs handwritten)?
+    # @return [Boolean]
+    def printed?
+      data['is_printed'] == true
+    end
+
+    # Is content handwritten?
+    # @return [Boolean]
+    def handwritten?
+      data['is_handwritten'] == true
+    end
+
+    # Contains chart?
+    # @return [Boolean]
+    def chart?
+      data['contains_chart'] == true
+    end
+
+    # Contains diagram?
+    # @return [Boolean]
+    def diagram?
+      data['contains_diagram'] == true
+    end
+
+    # Contains table?
+    # @return [Boolean]
+    def table?
+      data['contains_table'] == true
+    end
+
+    # Get metadata
+    # @return [Hash]
+    def metadata
+      data['metadata'] || {}
+    end
+
+    # Get tags
+    # @return [Array<String>]
+    def tags
+      data['tags'] || []
+    end
+
+    # --- Line-by-line data ---
+
+    # Get line-by-line data with bounding boxes
+    #
+    # Requires snap(..., include_line_data: true)
+    #
+    # @return [Array<Line>] array of line objects
+    def lines
+      return [] unless data['line_data']
+
+      @lines ||= data['line_data'].map { |line_data| Line.new(line_data) }
+    end
+
+    # Get lines as JSON array (raw data)
+    # @return [Array<Hash>]
+    def lines_json
+      data['line_data'] || []
+    end
+
+    # Line data structure for bounding boxes and confidence
+    class Line
+      attr_reader :data
+
+      def initialize(data)
+        @data = data
+      end
+
+      # Line text content
+      # @return [String]
+      def text
+        data['text'] || ''
+      end
+
+      # Line confidence
+      # @return [Float]
+      def confidence
+        data['confidence'] || 0.0
+      end
+
+      # Bounding box coordinates [x, y, width, height]
+      # @return [Array<Integer>, nil]
+      def bbox
+        data['bbox']
+      end
+
+      alias bounding_box bbox
+
+      # Is this line handwritten?
+      # @return [Boolean]
+      def handwritten?
+        data['type'] == 'handwriting'
+      end
+
+      # Is this line printed?
+      # @return [Boolean]
+      def printed?
+        %w[printed print].include?(data['type'])
+      end
+
+      # LaTeX for this line
+      # @return [String, nil]
+      def latex
+        data['latex']
+      end
+
+      # MathML for this line
+      # @return [String, nil]
+      def mathml
+        data['mathml']
+      end
+
+      # Word-level data (if available)
+      # @return [Array<Word>]
+      def words
+        return [] unless data['words']
+
+        @words ||= data['words'].map { |word_data| Word.new(word_data) }
+      end
+
+      # Convert to hash
+      # @return [Hash]
+      def to_h
+        data
+      end
+
+      # Inspect
+      # @return [String]
+      def inspect
+        "#<Mathpix::Result::Line text=\"#{text&.[](0..30)}\" confidence=#{confidence}>"
+      end
+    end
+
+    # Word data structure for fine-grained bounding boxes
+    class Word
+      attr_reader :data
+
+      def initialize(data)
+        @data = data
+      end
+
+      # Word text
+      # @return [String]
+      def text
+        data['text'] || ''
+      end
+
+      # Word confidence
+      # @return [Float]
+      def confidence
+        data['confidence'] || 0.0
+      end
+
+      # Word bounding box
+      # @return [Array<Integer>, nil]
+      def bbox
+        data['bbox']
+      end
+
+      # Convert to hash
+      # @return [Hash]
+      def to_h
+        data
+      end
+
+      # Inspect
+      # @return [String]
+      def inspect
+        "#<Mathpix::Result::Word text=\"#{text}\" confidence=#{confidence}>"
+      end
+    end
+
+    # Convert to hash
+    # @return [Hash]
+    def to_h
+      data
+    end
+
+    # Convert to JSON
+    # @return [String]
+    def to_json(*)
+      data.to_json(*)
+    end
+
+    # Inspect
+    # @return [String]
+    def inspect
+      "#<Mathpix::Result confidence=#{confidence} text=#{text&.[](0..50)}>"
+    end
+
+    # --- Chemistry-specific methods ---
+
+    # SMILES notation (chemistry)
+    # @return [String, nil]
+    def smiles
+      text if chemistry?
+    end
+
+    # InChI notation (chemistry)
+    # @return [String, nil]
+    def inchi
+      data['inchi']
+    end
+
+    # InChI Key (chemistry)
+    # @return [String, nil]
+    def inchikey
+      data['inchikey']
+    end
+
+    # Molecular formula
+    # @return [String, nil]
+    def molecular_formula
+      data['molecular_formula']
+    end
+
+    # Molecular name
+    # @return [String, nil]
+    def molecular_name
+      data['molecular_name']
+    end
+
+    # Molecular weight
+    # @return [Float, nil]
+    def molecular_weight
+      data['molecular_weight']
+    end
+
+    # Has stereochemistry?
+    # @return [Boolean]
+    def stereochemistry?
+      data['has_stereochemistry'] == true || smiles&.include?('@')
+    end
+
+    # Is this a chemistry result?
+    # @return [Boolean]
+    def chemistry?
+      molecular_formula || inchi || smiles&.match?(%r{^[A-Za-z0-9@\[\]()=#+\-\\/.]+$})
+    end
+
+    # --- Success/Failure ---
+
+    # Was capture successful?
+    # @return [Boolean]
+    def success?
+      !text.nil? && confidence >= 0.5
+    end
+
+    # Was capture a failure?
+    # @return [Boolean]
+    def failure?
+      !success?
+    end
+
+    # Execute block if successful
+    # @yield [self]
+    # @return [self]
+    def on_success
+      yield self if success?
+      self
+    end
+
+    # Execute block if failed
+    # @yield [self]
+    # @return [self]
+    def on_failure
+      yield self if failure?
+      self
+    end
+  end
+end

data/lib/mathpix/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Mathpix
+  VERSION = '1.0.0'
+end

data/lib/mathpix.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'openssl'
+require 'json'
+require 'base64'
+
+require_relative 'mathpix/version'
+require_relative 'mathpix/errors'
+require_relative 'mathpix/configuration'
+require_relative 'mathpix/result'
+require_relative 'mathpix/client'
+require_relative 'mathpix/document'
+
+# Mathpix OCR engine for the MCP server.
+#
+# The classes under Mathpix:: are the engine the MCP tools delegate to
+# (see lib/mathpix/mcp). Only configuration and the shared client instance are
+# exposed at the top level — there is no general-purpose client API.
+module Mathpix
+  class << self
+    # Configure the Mathpix client.
+    #
+    # @yield [Configuration] config object
+    # @example
+    #   Mathpix.configure do |config|
+    #     config.app_id = ENV['MATHPIX_APP_ID']
+    #     config.app_key = ENV['MATHPIX_APP_KEY']
+    #   end
+    def configure
+      yield configuration
+    end
+
+    # Current configuration.
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Shared client instance used by the MCP tools.
+    # @return [Client]
+    def client
+      @client ||= Client.new(configuration)
+    end
+
+    # Reset configuration and client (mainly for tests).
+    def reset!
+      @configuration = Configuration.new
+      @client = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: mathpix-mcp
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Georgios Douzas
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.0.2
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+description: |
+  A Model Context Protocol server for Mathpix OCR, over stdio or Streamable
+  HTTP (bearer-token auth). Exposes tools to convert images and PDF/DOCX/PPTX
+  documents to LaTeX and Markdown, with descriptive errors and optional file
+  output for large results.
+email:
+- georgios.douzas@gmail.com
+executables:
+- mathpix-mcp
+- mathpix-mcp-http
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- bin/mathpix-mcp
+- bin/mathpix-mcp-http
+- config.ru
+- lib/mathpix.rb
+- lib/mathpix/client.rb
+- lib/mathpix/configuration.rb
+- lib/mathpix/document.rb
+- lib/mathpix/errors.rb
+- lib/mathpix/mcp.rb
+- lib/mathpix/mcp/base_tool.rb
+- lib/mathpix/mcp/http_app.rb
+- lib/mathpix/mcp/server.rb
+- lib/mathpix/mcp/tools/batch_convert_tool.rb
+- lib/mathpix/mcp/tools/check_document_status_tool.rb
+- lib/mathpix/mcp/tools/convert_document_tool.rb
+- lib/mathpix/mcp/tools/convert_image_tool.rb
+- lib/mathpix/mcp/tools/convert_strokes_tool.rb
+- lib/mathpix/mcp/tools/get_account_info_tool.rb
+- lib/mathpix/mcp/tools/get_usage_tool.rb
+- lib/mathpix/mcp/tools/list_formats_tool.rb
+- lib/mathpix/mcp/tools/search_results_tool.rb
+- lib/mathpix/result.rb
+- lib/mathpix/version.rb
+homepage: https://github.com/georgedouzas/mathpix-mcp
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/georgedouzas/mathpix-mcp
+  changelog_uri: https://github.com/georgedouzas/mathpix-mcp/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/georgedouzas/mathpix-mcp/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Mathpix OCR MCP server (stdio + HTTP)
+test_files: []