robinhood_get_position

Instructions

Implementation Reference

• src/robinhood_mcp/server.py:121-132 (registration)

  MCP tool registration for 'robinhood_get_position' using @mcp.tool() decorator. Delegates to tools.get_position().

  @mcp.tool()
  def robinhood_get_position(symbol: str) -> dict:
      """Get one current stock position with a faster single-symbol lookup.
  
      Args:
          symbol: Stock ticker symbol (e.g., "HIMS", "AAPL")
  
      Returns a dict with held=False if absent, otherwise the position details
      for that symbol including quantity, price, average buy price, and P&L.
      """
      _ensure_logged_in()
      return get_position(symbol)

• src/robinhood_mcp/tools.py:177-241 (handler)

  Core implementation of get_position(). Looks up cached positions first, otherwise validates the symbol instrument, fetches open stock positions, matches by instrument URL, and computes price/quantity/P&L fields.

  def get_position(symbol: str) -> dict[str, Any]:
      """Get a single position by symbol without rebuilding all holdings.
  
      Returns:
          Dict with held=False if absent, otherwise position details including
          price, quantity, average_buy_price, equity, percent_change, and equity_change.
      """
      symbol = _normalize_symbol(symbol)
      cached_positions = _get_positions_cached(time.monotonic())
      if cached_positions is not None:
          cached_position = cached_positions.get(symbol)
          if isinstance(cached_position, dict):
              return _position_payload(symbol, cached_position)
          _validate_symbol_instrument(symbol)
          return {"symbol": symbol, "held": False}
  
      instrument_url = _validate_symbol_instrument(symbol)
  
      positions = _safe_call(rh.account.get_open_stock_positions)
      if not isinstance(positions, list):
          raise RobinhoodError("Unexpected positions response type")
  
      match = next(
          (
              item
              for item in positions
              if isinstance(item, dict) and item.get("instrument") == instrument_url
          ),
          None,
      )
      if not match:
          return {"symbol": symbol, "held": False}
  
      quote = get_quote(symbol)
      price = quote.get("last_trade_price") or quote.get("mark_price")
      quantity = match.get("quantity")
      average_buy_price = match.get("average_buy_price")
      if price in (None, "") or quantity in (None, "") or average_buy_price in (None, ""):
          raise RobinhoodError(f"Incomplete position data for symbol: {symbol}")
  
      try:
          quantity_f = float(quantity)
          price_f = float(price)
          average_buy_price_f = float(average_buy_price)
      except (TypeError, ValueError) as e:
          raise RobinhoodError(f"Invalid numeric position data for symbol: {symbol}") from e
  
      equity = quantity_f * price_f
      equity_change = equity - (quantity_f * average_buy_price_f)
      percent_change = (
          0.0
          if average_buy_price_f == 0.0
          else ((price_f - average_buy_price_f) * 100 / average_buy_price_f)
      )
      return _position_payload(
          symbol,
          {
              "price": f"{price_f:.2f}",
              "quantity": quantity,
              "average_buy_price": average_buy_price,
              "equity": f"{equity:.2f}",
              "percent_change": f"{percent_change:.2f}",
              "equity_change": f"{equity_change:.2f}",
          },
      )

• src/robinhood_mcp/tools.py:157-161 (helper)

  Helper function _position_payload() builds a stable position response dict with a fixed set of fields (price, quantity, average_buy_price, equity, percent_change, equity_change) and a 'held' boolean.

  def _position_payload(symbol: str, data: dict[str, Any]) -> dict[str, Any]:
      """Build a stable position response with a fixed set of fields."""
      fields = {k: data.get(k) for k in _POSITION_FIELDS}
      held = all(v not in (None, "") for v in fields.values())
      return {"symbol": symbol, "held": held, **fields}

• src/robinhood_mcp/tools.py:164-174 (helper)

  Helper function _validate_symbol_instrument() resolves a ticker symbol to its instrument URL via the Robinhood API, raising RobinhoodError for unknown symbols.

  def _validate_symbol_instrument(symbol: str) -> str:
      """Resolve a symbol to its instrument URL, raising on unknown tickers."""
      instruments = _safe_call(rh.stocks.get_instruments_by_symbols, symbol)
      if (
          not isinstance(instruments, list)
          or not instruments
          or not isinstance(instruments[0], dict)
          or not instruments[0].get("url")
      ):
          raise RobinhoodError(f"No instrument found for symbol: {symbol}")
      return instruments[0]["url"]

• src/robinhood_mcp/tools.py:49-56 (helper)

  Helper function _normalize_symbol() validates and normalizes a ticker symbol (uppercase, strip whitespace).

  def _normalize_symbol(symbol: str) -> str:
      """Normalize and validate ticker symbols."""
      if not symbol or not isinstance(symbol, str):
          raise RobinhoodError("Symbol must be a non-empty string")
      symbol = symbol.upper().strip()
      if not symbol:
          raise RobinhoodError("Symbol must be a non-empty string")
      return symbol