groww-mcp 1.0.0

data/lib/groww_mcp/client.rb

@@ -0,0 +1,356 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "csv"
+require "tmpdir"
+
+module GrowwMcp
+  class Client
+    BASE_URL = "https://api.groww.in"
+    MAX_RETRIES = 3
+    RETRY_DELAY = 0.5
+    INSTRUMENTS_CACHE_PATH = File.join(Dir.tmpdir, "groww-mcp-instruments.csv")
+    INSTRUMENTS_CACHE_TTL = 24 * 60 * 60 # 24 hours
+
+    def initialize(auth)
+      @auth = auth
+    end
+
+    # === Portfolio ===
+
+    def holdings
+      get("/v1/holdings/user")
+    end
+
+    def positions(segment: nil)
+      path = "/v1/positions/user"
+      path += "?segment=#{segment}" if segment
+      get(path)
+    end
+
+    def margins
+      get("/v1/margins/detail/user")
+    end
+
+    # === Orders ===
+
+    def order_list(segment: nil, page: nil, page_size: nil)
+      params = {}
+      params[:segment] = segment if segment
+      params[:page] = page if page
+      params[:page_size] = page_size if page_size
+      get("/v1/order/list", params)
+    end
+
+    def order_detail(order_id, segment: "CASH")
+      get("/v1/order/detail/#{order_id}", segment: segment)
+    end
+
+    def place_order(order)
+      # reference_id lets Groww dedupe if the same order is ever re-submitted
+      order = { order_reference_id: generate_reference_id }.merge(order)
+      post("/v1/order/create", order)
+    end
+
+    def modify_order(order_id, modifications)
+      post("/v1/order/modify", modifications.merge(groww_order_id: order_id))
+    end
+
+    def cancel_order(order_id, segment: "CASH")
+      post("/v1/order/cancel", groww_order_id: order_id, segment: segment)
+    end
+
+    def order_trades(order_id, segment: "CASH")
+      get("/v1/order/trades/#{order_id}", segment: segment)
+    end
+
+    # === Smart Orders (GTT/OCO) ===
+
+    def smart_order_list(smart_order_type: nil, page: nil, page_size: nil)
+      params = {}
+      params[:smart_order_type] = smart_order_type if smart_order_type
+      params[:page] = page if page
+      params[:page_size] = page_size if page_size
+      get("/v1/order-advance/list", params)
+    end
+
+    def create_smart_order(order)
+      order = { reference_id: generate_reference_id }.merge(order)
+      post("/v1/order-advance/create", order)
+    end
+
+    def modify_smart_order(smart_order_id, smart_order_type:, segment:, modifications: {})
+      put("/v1/order-advance/modify/#{smart_order_id}",
+          modifications.merge(smart_order_type: smart_order_type, segment: segment))
+    end
+
+    def cancel_smart_order(smart_order_id, smart_order_type:, segment: "CASH")
+      post("/v1/order-advance/cancel/#{segment}/#{smart_order_type}/#{smart_order_id}", {})
+    end
+
+    # === Live Data (requires ₹499/mo subscription) ===
+
+    def quote(trading_symbol, exchange: "NSE", segment: "CASH")
+      get("/v1/live-data/quote", trading_symbol: trading_symbol, exchange: exchange, segment: segment)
+    end
+
+    def ltp(symbols, exchange: "NSE", segment: "CASH")
+      get("/v1/live-data/ltp", segment: segment, exchange_symbols: exchange_symbols(symbols, exchange))
+    end
+
+    def ohlc(symbols, exchange: "NSE", segment: "CASH")
+      get("/v1/live-data/ohlc", segment: segment, exchange_symbols: exchange_symbols(symbols, exchange))
+    end
+
+    # === Option Chain (requires ₹499/mo subscription) ===
+
+    def option_chain(underlying, expiry_date:, exchange: "NSE")
+      get("/v1/option-chain/exchange/#{exchange}/underlying/#{underlying}", expiry_date: expiry_date)
+    end
+
+    # === Greeks (requires ₹499/mo subscription) ===
+
+    def greeks(trading_symbol:, underlying:, expiry:, exchange: "NSE")
+      get("/v1/live-data/greeks/exchange/#{exchange}/underlying/#{underlying}" \
+          "/trading_symbol/#{trading_symbol}/expiry/#{expiry}")
+    end
+
+    # === Historical Data (requires ₹499/mo subscription) ===
+
+    def historical_candles(trading_symbol, start_time, end_time, exchange: "NSE", segment: "CASH",
+                           interval_in_minutes: nil)
+      params = {
+        trading_symbol: trading_symbol, exchange: exchange, segment: segment,
+        start_time: normalize_time(start_time), end_time: normalize_time(end_time),
+      }
+      params[:interval_in_minutes] = interval_in_minutes if interval_in_minutes
+      get("/v1/historical/candle/range", params)
+    end
+
+    # === Instruments (local — resolved from Groww's public instruments CSV) ===
+
+    # Case-insensitive substring search on trading symbol and name.
+    # Runs entirely locally against the cached instruments CSV — no API call,
+    # no Live Data subscription needed.
+    def search_instruments(query, limit: 20)
+      q = query.to_s.downcase
+      return [] if q.empty?
+
+      matches = []
+      instruments.each do |row|
+        symbol = row["trading_symbol"].to_s.downcase
+        name = row["name"].to_s.downcase
+        matches << row if symbol.include?(q) || name.include?(q)
+      end
+
+      # Rank so the most useful rows surface first: exact symbol match,
+      # then CASH (equity) before FNO contracts, then symbol-prefix matches.
+      matches.sort_by! do |row|
+        symbol = row["trading_symbol"].to_s.downcase
+        [symbol == q ? 0 : 1,
+         row["segment"] == "CASH" ? 0 : 1,
+         symbol.start_with?(q) ? 0 : 1,
+         symbol]
+      end
+      matches.first(limit).map(&:to_h)
+    end
+
+    # Exact trading-symbol match (case-insensitive), filtered by exchange/segment.
+    # Returns the matching row as a Hash, or nil if not found.
+    def instrument_detail(trading_symbol, exchange: "NSE", segment: "CASH")
+      instruments.each do |row|
+        next unless row["trading_symbol"].to_s.casecmp?(trading_symbol.to_s)
+        next if exchange && !row["exchange"].to_s.empty? && !row["exchange"].casecmp?(exchange.to_s)
+        next if segment && !row["segment"].to_s.empty? && !row["segment"].casecmp?(segment.to_s)
+
+        return row.to_h
+      end
+      nil
+    end
+
+    def download_instruments
+      uri = URI("https://growwapi-assets.groww.in/instruments/instrument.csv")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      response = http.request(Net::HTTP::Get.new(uri))
+      response.body
+    end
+
+    # === User ===
+
+    def profile
+      get("/v1/user/detail")
+    end
+
+    # === Margin ===
+
+    # Margin requirement for a basket of orders.
+    # Body is a JSON ARRAY of order objects; segment goes as a query param.
+    def calculate_margin(orders, segment:)
+      post("/v1/margins/detail/orders", orders, params: { segment: segment })
+    end
+
+    private
+
+    # Build the comma-separated "EXCHANGE_SYMBOL" pairs the live-data API expects,
+    # e.g. ["RELIANCE", "TCS"] + NSE => "NSE_RELIANCE,NSE_TCS".
+    # Symbols already containing "_" are passed through untouched.
+    def exchange_symbols(symbols, exchange)
+      Array(symbols).map { |s| s.include?("_") ? s : "#{exchange}_#{s}" }.join(",")
+    end
+
+    # Historical API accepts epoch MILLISECONDS or "yyyy-MM-dd HH:mm:ss" strings.
+    # Strings pass through; numbers that look like epoch seconds get converted to ms.
+    def normalize_time(value)
+      return value if value.is_a?(String)
+
+      n = value.to_i
+      n < 1_000_000_000_000 ? n * 1000 : n
+    end
+
+    # Cached, parsed instruments CSV (24h TTL, stored in the system tmp dir).
+    def instruments
+      if @instruments.nil? || (Time.now - @instruments_loaded_at) > INSTRUMENTS_CACHE_TTL
+        @instruments = CSV.parse(instruments_csv, headers: true)
+        @instruments_loaded_at = Time.now
+      end
+      @instruments
+    end
+
+    def instruments_csv
+      cache = INSTRUMENTS_CACHE_PATH
+      if File.exist?(cache) && (Time.now - File.mtime(cache)) < INSTRUMENTS_CACHE_TTL
+        File.read(cache)
+      else
+        data = download_instruments
+        File.write(cache, data)
+        data
+      end
+    end
+
+    def get(path, params = {})
+      token = @auth.ensure_token!
+
+      uri = URI("#{BASE_URL}#{path}")
+      unless params.empty? || path.include?("?")
+        uri.query = URI.encode_www_form(params)
+      end
+
+      request = Net::HTTP::Get.new(uri)
+      request["Authorization"] = "Bearer #{token}"
+      request["Accept"] = "application/json"
+      request["X-API-VERSION"] = "1.0"
+
+      execute(uri, request)
+    end
+
+    def post(path, body, params: {})
+      token = @auth.ensure_token!
+
+      uri = URI("#{BASE_URL}#{path}")
+      uri.query = URI.encode_www_form(params) unless params.empty?
+      request = Net::HTTP::Post.new(uri)
+      request["Authorization"] = "Bearer #{token}"
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "application/json"
+      request["X-API-VERSION"] = "1.0"
+      request.body = body.to_json
+
+      execute(uri, request, idempotent: false)
+    end
+
+    def put(path, body)
+      token = @auth.ensure_token!
+
+      uri = URI("#{BASE_URL}#{path}")
+      request = Net::HTTP::Put.new(uri)
+      request["Authorization"] = "Bearer #{token}"
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "application/json"
+      request["X-API-VERSION"] = "1.0"
+      request.body = body.to_json
+
+      execute(uri, request, idempotent: false)
+    end
+
+    def generate_reference_id
+      rand(10_000_000..99_999_999).to_s
+    end
+
+    def execute(uri, request, idempotent: true)
+      retries = 0
+      auth_retried = false
+
+      begin
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.open_timeout = 10
+        http.read_timeout = 15
+
+        response = http.request(request)
+
+        case response
+        when Net::HTTPSuccess
+          JSON.parse(response.body)
+        when Net::HTTPUnauthorized
+          if auth_retried
+            raise ApiError, "Groww API error (401): token expired — Groww tokens expire daily at " \
+                            "6 AM IST; update GROWW_ACCESS_TOKEN or switch to TOTP auth " \
+                            "(GROWW_TOTP_KEY + GROWW_TOTP_SECRET) for automatic refresh."
+          end
+          raise StaleTokenRetry
+        when Net::HTTPTooManyRequests
+          raise RateLimitError, "Rate limited. Try again later."
+        when Net::HTTPForbidden
+          raise ForbiddenError, "Access forbidden. This endpoint may require the Groww Live Data subscription (₹499/mo)."
+        else
+          error_body = JSON.parse(response.body) rescue {}
+          message = error_body.dig("error", "message") ||
+                    error_body.dig("error", "errorMessage") ||
+                    response.body
+          raise ApiError, "Groww API error (#{response.code}): #{message}"
+        end
+      rescue StaleTokenRetry
+        # 401 — the cached token is stale (Groww tokens expire daily at 6 AM IST).
+        # Invalidate it, fetch a fresh one, update the Authorization header on the
+        # already-built request, and retry exactly once.
+        auth_retried = true
+        @auth.invalidate!
+        request["Authorization"] = "Bearer #{@auth.ensure_token!}"
+        retry
+      rescue Net::OpenTimeout => e
+        # Connection was never established, so the request was not sent — safe to retry.
+        retries += 1
+        if retries <= MAX_RETRIES
+          sleep(RETRY_DELAY * retries)
+          retry
+        end
+        raise ApiError, "Network error after #{MAX_RETRIES} retries: #{e.message}"
+      rescue Net::ReadTimeout, Errno::ECONNRESET => e
+        # The request may have already reached Groww. Retrying a non-idempotent
+        # request (order create/modify/cancel) could execute it twice.
+        if idempotent
+          retries += 1
+          if retries <= MAX_RETRIES
+            sleep(RETRY_DELAY * retries)
+            retry
+          end
+          raise ApiError, "Network error after #{MAX_RETRIES} retries: #{e.message}"
+        end
+        raise ApiError, "Network error (#{e.class}): #{e.message}. NOT retried because the request " \
+                        "may have already been accepted by Groww — check order status " \
+                        "(get_orders / get_smart_orders) before submitting again."
+      end
+    end
+  end
+
+  class ApiError < StandardError; end
+  class RateLimitError < ApiError; end
+  class ForbiddenError < ApiError; end
+
+  # Internal sentinel: raised on the first 401 so Client#execute can refresh
+  # the token and retry the request once. Never propagates to callers.
+  class StaleTokenRetry < StandardError; end
+end

data/lib/groww_mcp/tools/auth_tools.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module GrowwMcp
+  module Tools
+    class Authenticate < GrowwMcp::BaseTool
+      description "Generate a fresh Groww access token using configured credentials (TOTP, API Key, or manual token). " \
+                  "Call this if other tools return authentication errors. The token is valid until 6:00 AM IST daily."
+
+      input_schema(
+        properties: {
+          force: {
+            type: "boolean",
+            description: "Force re-authentication even if current token is valid (default: false)",
+          },
+        },
+      )
+
+      class << self
+        def call(server_context:, force: false)
+          auth = server_context[:auth]
+
+          if force || !auth.token_valid?
+            auth.authenticate!
+            MCP::Tool::Response.new([{
+              type: "text",
+              text: "✅ Authenticated successfully. Token valid until #{auth.token_expiry || 'unknown (manual token)'}.",
+            }])
+          else
+            MCP::Tool::Response.new([{
+              type: "text",
+              text: "Token is still valid (expires: #{auth.token_expiry}). Use force: true to re-authenticate.",
+            }])
+          end
+        rescue GrowwMcp::AuthError => e
+          MCP::Tool::Response.new([{ type: "text", text: "❌ Authentication failed: #{e.message}" }])
+        end
+      end
+    end
+  end
+end

data/lib/groww_mcp/tools/instrument_tools.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module GrowwMcp
+  module Tools
+    class SearchInstruments < GrowwMcp::BaseTool
+      description "Search for tradable instruments (stocks, F&O, ETFs) by name or symbol. " \
+                  "Returns matching instruments with their trading symbols, exchanges, and segments. " \
+                  "Use this to find the correct trading_symbol before placing orders. " \
+                  "Search runs locally against Groww's public instruments CSV (cached 24h) — " \
+                  "fast, and works without the Live Data subscription."
+
+      input_schema(
+        properties: {
+          query: {
+            type: "string",
+            description: "Search query — stock name or symbol (e.g., 'Reliance', 'NIFTY', 'HDFC'). " \
+                         "Case-insensitive substring match on trading symbol and name.",
+          },
+          limit: {
+            type: "integer",
+            description: "Maximum number of results to return (default: 20)",
+          },
+        },
+        required: ["query"],
+      )
+
+      class << self
+        def call(server_context:, query:, limit: 20)
+          client = server_context[:client]
+          result = client.search_instruments(query, limit: limit)
+          if result.empty?
+            return MCP::Tool::Response.new([{ type: "text", text: "No instruments matched '#{query}'." }])
+          end
+
+          format_response(result)
+        rescue GrowwMcp::ApiError => e
+          error_response(e)
+        end
+      end
+    end
+
+    class GetInstrumentDetail < GrowwMcp::BaseTool
+      description "Get detailed information about a specific instrument including lot size, tick size, " \
+                  "expiry date (for F&O), and other contract details. " \
+                  "Resolved locally from Groww's public instruments CSV (cached 24h) — " \
+                  "works without the Live Data subscription."
+
+      input_schema(
+        properties: {
+          trading_symbol: {
+            type: "string",
+            description: "Trading symbol (e.g., RELIANCE, NIFTY24JUL25000CE)",
+          },
+          exchange: {
+            type: "string",
+            enum: %w[NSE BSE],
+            description: "Exchange (default: NSE)",
+          },
+          segment: {
+            type: "string",
+            enum: %w[CASH FNO],
+            description: "Market segment (default: CASH)",
+          },
+        },
+        required: ["trading_symbol"],
+      )
+
+      class << self
+        def call(server_context:, trading_symbol:, exchange: "NSE", segment: "CASH")
+          client = server_context[:client]
+          result = client.instrument_detail(trading_symbol, exchange: exchange, segment: segment)
+          if result.nil?
+            return MCP::Tool::Response.new([{
+              type: "text",
+              text: "No instrument found for '#{trading_symbol}' (#{exchange}/#{segment}). " \
+                    "Try search_instruments to find the exact trading symbol.",
+            }])
+          end
+
+          format_response(result)
+        rescue GrowwMcp::ApiError => e
+          error_response(e)
+        end
+      end
+    end
+
+    class DownloadInstruments < GrowwMcp::BaseTool
+      description "Download the complete list of all tradable instruments as CSV. " \
+                  "Returns a sample of the first 20 rows and total count. " \
+                  "Useful for finding exact trading symbols, ISIN codes, and lot sizes."
+
+      input_schema(properties: {})
+
+      class << self
+        def call(server_context:)
+          client = server_context[:client]
+          csv_data = client.download_instruments
+
+          lines = csv_data.split("\n")
+          sample = lines[0..20].join("\n")
+
+          MCP::Tool::Response.new([{
+            type: "text",
+            text: "Total instruments: #{lines.length - 1}\n\nSample (first 20 rows):\n#{sample}",
+          }])
+        rescue => e
+          error_response(e)
+        end
+      end
+    end
+  end
+end