groww-mcp 1.0.0

data/lib/groww_mcp/tools/market_tools.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module GrowwMcp
+  module Tools
+    class GetQuote < GrowwMcp::BaseTool
+      description "Get live market quote for a stock or F&O instrument. " \
+                  "Returns last price, OHLC, bid/ask, volume, and change %. " \
+                  "⚠️ Requires Groww Live Data subscription (₹499/mo)."
+
+      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.quote(trading_symbol, exchange: exchange, segment: segment)
+          format_response(result)
+        rescue GrowwMcp::ForbiddenError
+          MCP::Tool::Response.new([{
+            type: "text",
+            text: "❌ Live Data access denied. This requires the Groww Live Data subscription (₹499 + GST/month). " \
+                  "Subscribe at: Groww App → Settings → Trading APIs.",
+          }])
+        rescue GrowwMcp::ApiError => e
+          error_response(e)
+        end
+      end
+    end
+
+    class GetLTP < GrowwMcp::BaseTool
+      description "Get last traded price (LTP) for multiple stocks at once (max 50 symbols). " \
+                  "Symbols are sent to the API as comma-separated EXCHANGE_SYMBOL pairs " \
+                  "(e.g. NSE_RELIANCE,NSE_TCS) — bare symbols are automatically prefixed with the exchange. " \
+                  "⚠️ Requires Groww Live Data subscription (₹499/mo)."
+
+      input_schema(
+        properties: {
+          symbols: {
+            type: "array",
+            items: { type: "string" },
+            description: "Array of trading symbols (max 50). Bare symbols (e.g. RELIANCE) get the " \
+                         "exchange prefix added automatically; already-prefixed pairs (e.g. NSE_RELIANCE) " \
+                         "are used as-is.",
+          },
+          exchange: {
+            type: "string",
+            enum: %w[NSE BSE],
+            description: "Exchange used to prefix bare symbols (default: NSE)",
+          },
+          segment: {
+            type: "string",
+            enum: %w[CASH FNO],
+            description: "Market segment (default: CASH)",
+          },
+        },
+        required: ["symbols"],
+      )
+
+      class << self
+        def call(server_context:, symbols:, exchange: "NSE", segment: "CASH")
+          if symbols.length > 50
+            return MCP::Tool::Response.new([{ type: "text", text: "❌ Maximum 50 symbols allowed per request." }])
+          end
+
+          client = server_context[:client]
+          result = client.ltp(symbols, exchange: exchange, segment: segment)
+          format_response(result)
+        rescue GrowwMcp::ForbiddenError
+          MCP::Tool::Response.new([{
+            type: "text",
+            text: "❌ Live Data access denied. Requires Groww Live Data subscription (₹499 + GST/month).",
+          }])
+        rescue GrowwMcp::ApiError => e
+          error_response(e)
+        end
+      end
+    end
+
+    class GetOHLC < GrowwMcp::BaseTool
+      description "Get Open, High, Low, Close prices for multiple stocks (max 50). " \
+                  "Symbols are sent to the API as comma-separated EXCHANGE_SYMBOL pairs " \
+                  "(e.g. NSE_RELIANCE,NSE_TCS) — bare symbols are automatically prefixed with the exchange. " \
+                  "⚠️ Requires Groww Live Data subscription (₹499/mo)."
+
+      input_schema(
+        properties: {
+          symbols: {
+            type: "array",
+            items: { type: "string" },
+            description: "Array of trading symbols (max 50). Bare symbols (e.g. RELIANCE) get the " \
+                         "exchange prefix added automatically; already-prefixed pairs (e.g. NSE_RELIANCE) " \
+                         "are used as-is.",
+          },
+          exchange: {
+            type: "string",
+            enum: %w[NSE BSE],
+            description: "Exchange used to prefix bare symbols (default: NSE)",
+          },
+          segment: {
+            type: "string",
+            enum: %w[CASH FNO],
+            description: "Market segment (default: CASH)",
+          },
+        },
+        required: ["symbols"],
+      )
+
+      class << self
+        def call(server_context:, symbols:, exchange: "NSE", segment: "CASH")
+          if symbols.length > 50
+            return MCP::Tool::Response.new([{ type: "text", text: "❌ Maximum 50 symbols allowed per request." }])
+          end
+
+          client = server_context[:client]
+          result = client.ohlc(symbols, exchange: exchange, segment: segment)
+          format_response(result)
+        rescue GrowwMcp::ForbiddenError
+          MCP::Tool::Response.new([{
+            type: "text",
+            text: "❌ Live Data access denied. Requires Groww Live Data subscription (₹499 + GST/month).",
+          }])
+        rescue GrowwMcp::ApiError => e
+          error_response(e)
+        end
+      end
+    end
+
+    class GetHistoricalData < GrowwMcp::BaseTool
+      description "Get historical candlestick (OHLCV) data for a stock or F&O instrument. " \
+                  "Useful for technical analysis and backtesting. " \
+                  "⚠️ Requires Groww Live Data subscription (₹499/mo)."
+
+      input_schema(
+        properties: {
+          trading_symbol: {
+            type: "string",
+            description: "Trading symbol (e.g., RELIANCE, NIFTY24JUL25000CE)",
+          },
+          start_time: {
+            type: %w[integer string],
+            description: "Start time — either a \"yyyy-MM-dd HH:mm:ss\" string (e.g. \"2026-07-01 09:15:00\") " \
+                         "or a numeric epoch timestamp (epoch seconds are auto-converted to the " \
+                         "milliseconds the API expects; epoch milliseconds pass through as-is)",
+          },
+          end_time: {
+            type: %w[integer string],
+            description: "End time — either a \"yyyy-MM-dd HH:mm:ss\" string (e.g. \"2026-07-22 15:30:00\") " \
+                         "or a numeric epoch timestamp (epoch seconds are auto-converted to the " \
+                         "milliseconds the API expects; epoch milliseconds pass through as-is)",
+          },
+          exchange: {
+            type: "string",
+            enum: %w[NSE BSE],
+            description: "Exchange (default: NSE)",
+          },
+          segment: {
+            type: "string",
+            enum: %w[CASH FNO],
+            description: "Market segment (default: CASH)",
+          },
+          interval_in_minutes: {
+            type: "integer",
+            description: "Candle interval in minutes (optional — e.g. 1, 5, 15, 60, 1440 for daily)",
+          },
+        },
+        required: %w[trading_symbol start_time end_time],
+      )
+
+      class << self
+        def call(server_context:, trading_symbol:, start_time:, end_time:, exchange: "NSE", segment: "CASH",
+                 interval_in_minutes: nil)
+          client = server_context[:client]
+          result = client.historical_candles(trading_symbol, start_time, end_time,
+                                             exchange: exchange, segment: segment,
+                                             interval_in_minutes: interval_in_minutes)
+          format_response(result)
+        rescue GrowwMcp::ForbiddenError
+          MCP::Tool::Response.new([{
+            type: "text",
+            text: "❌ Historical Data access denied. Requires Groww Live Data subscription (₹499 + GST/month).",
+          }])
+        rescue GrowwMcp::ApiError => e
+          error_response(e)
+        end
+      end
+    end
+  end
+end

data/lib/groww_mcp/tools/option_chain_tools.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module GrowwMcp
+  module Tools
+    class GetOptionChain < GrowwMcp::BaseTool
+      description "Get the complete option chain for an underlying instrument (e.g., NIFTY, BANKNIFTY, RELIANCE) " \
+                  "for a specific expiry date. " \
+                  "Returns all available strike prices with CE and PE data including LTP, OI (Open Interest), " \
+                  "volume, IV (Implied Volatility), and Greeks (Delta, Gamma, Theta, Vega). " \
+                  "Essential for options analysis and strategy selection. " \
+                  "⚠️ Requires Groww Live Data subscription (₹499/mo)."
+
+      input_schema(
+        properties: {
+          trading_symbol: {
+            type: "string",
+            description: "Underlying symbol (e.g., NIFTY, BANKNIFTY, RELIANCE)",
+          },
+          expiry_date: {
+            type: "string",
+            description: "Expiry date in yyyy-MM-dd format (e.g., 2026-07-30)",
+          },
+          exchange: {
+            type: "string",
+            enum: %w[NSE BSE],
+            description: "Exchange (default: NSE)",
+          },
+        },
+        required: %w[trading_symbol expiry_date],
+      )
+
+      class << self
+        def call(server_context:, trading_symbol:, expiry_date:, exchange: "NSE")
+          client = server_context[:client]
+          result = client.option_chain(trading_symbol, expiry_date: expiry_date, exchange: exchange)
+          format_response(result)
+        rescue GrowwMcp::ForbiddenError
+          MCP::Tool::Response.new([{
+            type: "text",
+            text: "❌ Option Chain access denied. Requires Groww Live Data subscription (₹499 + GST/month). " \
+                  "Subscribe at: Groww App → Settings → Trading APIs.",
+          }])
+        rescue GrowwMcp::ApiError => e
+          error_response(e)
+        end
+      end
+    end
+
+    class GetGreeks < GrowwMcp::BaseTool
+      description "Get option Greeks (Delta, Gamma, Theta, Vega, Rho) and IV for a specific option contract. " \
+                  "Provide the option's trading symbol, its underlying, and the expiry date. " \
+                  "⚠️ Requires Groww Live Data subscription (₹499/mo)."
+
+      input_schema(
+        properties: {
+          trading_symbol: {
+            type: "string",
+            description: "Option contract trading symbol (e.g., NIFTY24JUL25000CE)",
+          },
+          underlying: {
+            type: "string",
+            description: "Underlying symbol (e.g., NIFTY, BANKNIFTY, RELIANCE)",
+          },
+          expiry: {
+            type: "string",
+            description: "Expiry date in yyyy-MM-dd format (e.g., 2026-07-30)",
+          },
+          exchange: {
+            type: "string",
+            enum: %w[NSE BSE],
+            description: "Exchange (default: NSE)",
+          },
+        },
+        required: %w[trading_symbol underlying expiry],
+      )
+
+      class << self
+        def call(server_context:, trading_symbol:, underlying:, expiry:, exchange: "NSE")
+          client = server_context[:client]
+          result = client.greeks(trading_symbol: trading_symbol, underlying: underlying,
+                                 expiry: expiry, exchange: exchange)
+          format_response(result)
+        rescue GrowwMcp::ForbiddenError
+          MCP::Tool::Response.new([{
+            type: "text",
+            text: "❌ Greeks access denied. Requires Groww Live Data subscription (₹499 + GST/month). " \
+                  "Subscribe at: Groww App → Settings → Trading APIs.",
+          }])
+        rescue GrowwMcp::ApiError => e
+          error_response(e)
+        end
+      end
+    end
+
+    class GetOrderTrades < GrowwMcp::BaseTool
+      description "Get all trade executions for a specific order. " \
+                  "An order can have multiple partial fills — this shows each fill with price, quantity, and timestamp."
+
+      input_schema(
+        properties: {
+          order_id: {
+            type: "string",
+            description: "Groww order ID",
+          },
+          segment: {
+            type: "string",
+            enum: %w[CASH FNO],
+            description: "Market segment (default: CASH)",
+          },
+        },
+        required: ["order_id"],
+      )
+
+      class << self
+        def call(server_context:, order_id:, segment: "CASH")
+          client = server_context[:client]
+          result = client.order_trades(order_id, segment: segment)
+          format_response(result)
+        rescue GrowwMcp::ApiError => e
+          error_response(e)
+        end
+      end
+    end
+  end
+end

data/lib/groww_mcp/tools/order_tools.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module GrowwMcp
+  module Tools
+    class GetOrders < GrowwMcp::BaseTool
+      description "Get list of all orders. Optionally filter by market segment (CASH/FNO) " \
+                  "and paginate results. Shows order status, prices, quantities, and timestamps."
+
+      input_schema(
+        properties: {
+          segment: {
+            type: "string",
+            enum: %w[CASH FNO],
+            description: "Filter by market segment (optional)",
+          },
+          page: {
+            type: "integer",
+            description: "Page number for pagination (optional)",
+          },
+          page_size: {
+            type: "integer",
+            description: "Number of orders per page (optional, default: 20)",
+          },
+        },
+      )
+
+      class << self
+        def call(server_context:, segment: nil, page: nil, page_size: nil)
+          client = server_context[:client]
+          result = client.order_list(segment: segment, page: page, page_size: page_size)
+          format_response(result)
+        rescue GrowwMcp::ApiError => e
+          error_response(e)
+        end
+      end
+    end
+
+    class GetOrderDetail < GrowwMcp::BaseTool
+      description "Get detailed status of a specific order by its Groww order ID. " \
+                  "Shows fill price, pending quantity, rejection reason, and timestamps."
+
+      input_schema(
+        properties: {
+          order_id: {
+            type: "string",
+            description: "Groww order ID",
+          },
+          segment: {
+            type: "string",
+            enum: %w[CASH FNO],
+            description: "Market segment (default: CASH)",
+          },
+        },
+        required: ["order_id"],
+      )
+
+      class << self
+        def call(server_context:, order_id:, segment: "CASH")
+          client = server_context[:client]
+          result = client.order_detail(order_id, segment: segment)
+          format_response(result)
+        rescue GrowwMcp::ApiError => e
+          error_response(e)
+        end
+      end
+    end
+
+    class PlaceOrder < GrowwMcp::BaseTool
+      description "Place a buy or sell order on Groww. Supports MARKET, LIMIT, SL, and SL_M order types. " \
+                  "For stocks use segment=CASH with product CNC (delivery) or MIS (intraday). " \
+                  "For F&O use segment=FNO with product NRML. " \
+                  "⚠️ This executes a REAL trade with REAL money. Always confirm with the user first."
+
+      input_schema(
+        properties: {
+          trading_symbol: {
+            type: "string",
+            description: "Stock/option symbol (e.g., RELIANCE, NIFTY24JUL25000CE)",
+          },
+          exchange: {
+            type: "string",
+            enum: %w[NSE BSE],
+            description: "Exchange (default: NSE)",
+          },
+          transaction_type: {
+            type: "string",
+            enum: %w[BUY SELL],
+            description: "Buy or sell",
+          },
+          order_type: {
+            type: "string",
+            enum: %w[MARKET LIMIT SL SL_M],
+            description: "MARKET=instant, LIMIT=at price, SL=stop loss limit, SL_M=stop loss market",
+          },
+          quantity: {
+            type: "integer",
+            description: "Number of shares/lots",
+          },
+          price: {
+            type: "number",
+            description: "Limit price (required for LIMIT and SL orders)",
+          },
+          trigger_price: {
+            type: "number",
+            description: "Trigger price (required for SL and SL_M orders)",
+          },
+          product: {
+            type: "string",
+            enum: %w[CNC MIS NRML],
+            description: "CNC=delivery, MIS=intraday, NRML=F&O",
+          },
+          segment: {
+            type: "string",
+            enum: %w[CASH FNO],
+            description: "Market segment (default: CASH)",
+          },
+          validity: {
+            type: "string",
+            enum: %w[DAY],
+            description: "Order validity (default: DAY)",
+          },
+        },
+        required: %w[trading_symbol transaction_type order_type quantity product],
+      )
+
+      class << self
+        def call(server_context:, trading_symbol:, transaction_type:, order_type:, quantity:, product:,
+                 exchange: "NSE", price: nil, trigger_price: nil, segment: "CASH", validity: "DAY")
+          client = server_context[:client]
+          order = {
+            trading_symbol: trading_symbol,
+            exchange: exchange,
+            transaction_type: transaction_type,
+            order_type: order_type,
+            quantity: quantity,
+            product: product,
+            segment: segment,
+            validity: validity,
+          }
+          order[:price] = price if price
+          order[:trigger_price] = trigger_price if trigger_price
+
+          result = client.place_order(order)
+          format_response(result)
+        rescue GrowwMcp::ApiError => e
+          error_response(e)
+        end
+      end
+    end
+
+    class ModifyOrder < GrowwMcp::BaseTool
+      description "Modify an existing open order (change quantity, price, or trigger price). " \
+                  "The Groww API requires quantity, order_type, and segment on every modify — " \
+                  "pass the order's current values for anything you are not changing."
+
+      input_schema(
+        properties: {
+          order_id: { type: "string", description: "Groww order ID to modify" },
+          quantity: { type: "integer", description: "Quantity (required — pass current value if unchanged)" },
+          order_type: { type: "string", enum: %w[MARKET LIMIT SL SL_M], description: "Order type (required — pass current value if unchanged)" },
+          segment: { type: "string", enum: %w[CASH FNO], description: "Market segment of the order" },
+          price: { type: "number", description: "New price (optional)" },
+          trigger_price: { type: "number", description: "New trigger price (optional)" },
+        },
+        required: %w[order_id quantity order_type segment],
+      )
+
+      class << self
+        def call(server_context:, order_id:, quantity:, order_type:, segment:, price: nil, trigger_price: nil)
+          client = server_context[:client]
+          mods = {
+            quantity: quantity,
+            order_type: order_type,
+            segment: segment,
+          }
+          mods[:price] = price if price
+          mods[:trigger_price] = trigger_price if trigger_price
+
+          result = client.modify_order(order_id, mods)
+          format_response(result)
+        rescue GrowwMcp::ApiError => e
+          error_response(e)
+        end
+      end
+    end
+
+    class CancelOrder < GrowwMcp::BaseTool
+      description "Cancel an open/pending order by its Groww order ID."
+
+      input_schema(
+        properties: {
+          order_id: { type: "string", description: "Groww order ID to cancel" },
+          segment: { type: "string", enum: %w[CASH FNO], description: "Market segment (default: CASH)" },
+        },
+        required: ["order_id"],
+      )
+
+      class << self
+        def call(server_context:, order_id:, segment: "CASH")
+          client = server_context[:client]
+          result = client.cancel_order(order_id, segment: segment)
+          format_response(result)
+        rescue GrowwMcp::ApiError => e
+          error_response(e)
+        end
+      end
+    end
+  end
+end

data/lib/groww_mcp/tools/portfolio_tools.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module GrowwMcp
+  module Tools
+    class GetHoldings < GrowwMcp::BaseTool
+      description "Get all current stock holdings from your DEMAT account. " \
+                  "Returns each stock with ISIN, trading symbol, quantity, average buy price, " \
+                  "pledged/locked quantities, and tradable exchanges."
+
+      input_schema(properties: {})
+
+      class << self
+        def call(server_context:)
+          client = server_context[:client]
+          result = client.holdings
+          format_response(result)
+        rescue GrowwMcp::ApiError => e
+          error_response(e)
+        end
+      end
+    end
+
+    class GetPositions < GrowwMcp::BaseTool
+      description "Get all open intraday and F&O positions with unrealized P&L. " \
+                  "Optionally filter by market segment (CASH or FNO)."
+
+      input_schema(
+        properties: {
+          segment: {
+            type: "string",
+            enum: %w[CASH FNO],
+            description: "Filter by market segment (optional)",
+          },
+        },
+      )
+
+      class << self
+        def call(server_context:, segment: nil)
+          client = server_context[:client]
+          result = client.positions(segment: segment)
+          format_response(result)
+        rescue GrowwMcp::ApiError => e
+          error_response(e)
+        end
+      end
+    end
+
+    class GetMargins < GrowwMcp::BaseTool
+      description "Get available margin and funds details including clear cash, collateral, " \
+                  "equity margin (CNC/MIS), F&O margin (SPAN/exposure), and commodity margin."
+
+      input_schema(properties: {})
+
+      class << self
+        def call(server_context:)
+          client = server_context[:client]
+          result = client.margins
+          format_response(result)
+        rescue GrowwMcp::ApiError => e
+          error_response(e)
+        end
+      end
+    end
+
+    class CalculateMargin < GrowwMcp::BaseTool
+      description "Calculate required margin for one or more orders before placing them. " \
+                  "Useful to check if you have sufficient funds."
+
+      input_schema(
+        properties: {
+          segment: {
+            type: "string",
+            enum: %w[CASH FNO],
+            description: "Market segment for the whole basket (sent as query param)",
+          },
+          orders: {
+            type: "array",
+            description: "Array of order objects to calculate margin for (sent as the JSON request body)",
+            items: {
+              type: "object",
+              properties: {
+                trading_symbol: { type: "string", description: "Stock/option symbol (e.g., RELIANCE, NIFTY24JUL25000CE)" },
+                transaction_type: { type: "string", enum: %w[BUY SELL], description: "Buy or sell" },
+                quantity: { type: "integer", description: "Number of shares/lots" },
+                price: { type: "number", description: "Limit price (for LIMIT/SL orders)" },
+                order_type: { type: "string", enum: %w[MARKET LIMIT SL SL_M], description: "Order type" },
+                product: { type: "string", enum: %w[CNC MIS NRML], description: "CNC=delivery, MIS=intraday, NRML=F&O" },
+              },
+              required: %w[trading_symbol transaction_type quantity order_type product],
+            },
+          },
+        },
+        required: %w[segment orders],
+      )
+
+      class << self
+        def call(server_context:, segment:, orders:)
+          client = server_context[:client]
+          result = client.calculate_margin(orders, segment: segment)
+          format_response(result)
+        rescue GrowwMcp::ApiError => e
+          error_response(e)
+        end
+      end
+    end
+  end
+end