feat(tools): return structured client responses

Author: jkoelker

src/schwab_mcp/tools/account.py

@@ -4,13 +4,13 @@
 
 from schwab_mcp.context import SchwabContext, SchwabServerContext
 from schwab_mcp.tools.registry import register
-from schwab_mcp.tools.utils import call
+from schwab_mcp.tools.utils import JSONType, call
 
 
 @register
 async def get_account_numbers(
     ctx: SchwabContext,
-) -> str:
+) -> JSONType:
     """
     Returns mapping of account IDs to account hashes. Hashes required for account-specific calls. Use first.
     """
@@ -21,7 +21,7 @@ async def get_account_numbers(
 @register
 async def get_accounts(
     ctx: SchwabContext,
-) -> str:
+) -> JSONType:
     """
     Returns balances/info for all linked accounts (funds, cash, margin). Does not return hashes; use get_account_numbers first.
     """
@@ -32,7 +32,7 @@ async def get_accounts(
 @register
 async def get_accounts_with_positions(
     ctx: SchwabContext,
-) -> str:
+) -> JSONType:
     """
     Returns balances, info, and positions (holdings, cost, gain/loss) for all linked accounts. Does not return hashes; use get_account_numbers first.
     """
@@ -47,7 +47,7 @@ async def get_accounts_with_positions(
 async def get_account(
     ctx: SchwabContext,
     account_hash: Annotated[str, "Account hash for the Schwab account"],
-) -> str:
+) -> JSONType:
     """
     Returns balance/info for a specific account via account_hash (from get_account_numbers). Includes funds, cash, margin info.
     """
@@ -59,7 +59,7 @@ async def get_account(
 async def get_account_with_positions(
     ctx: SchwabContext,
     account_hash: Annotated[str, "Account hash for the Schwab account"],
-) -> str:
+) -> JSONType:
     """
     Returns balance, info, and positions for a specific account via account_hash. Includes holdings, quantity, cost basis, unrealized gain/loss.
     """
@@ -74,7 +74,7 @@ async def get_account_with_positions(
 @register
 async def get_user_preferences(
     ctx: SchwabContext,
-) -> str:
+) -> JSONType:
     """
     Returns user preferences (nicknames, display settings, notifications) for all linked accounts.
     """

src/schwab_mcp/tools/history.py

@@ -6,7 +6,7 @@
 
 from schwab_mcp.context import SchwabContext, SchwabServerContext
 from schwab_mcp.tools.registry import register
-from schwab_mcp.tools.utils import call
+from schwab_mcp.tools.utils import JSONType, call
 
 
 def _parse_iso_datetime(value: str | None) -> datetime.datetime | None:
@@ -43,7 +43,7 @@ async def get_advanced_price_history(
     ] = None,
     extended_hours: Annotated[bool | None, "Include extended hours data"] = None,
     previous_close: Annotated[bool | None, "Include previous close data"] = None,
-) -> str:
+) -> JSONType:
     """
     Get price history with advanced period/frequency options. Specify period/frequency OR start/end datetimes.
 
@@ -107,7 +107,7 @@ async def get_price_history_every_minute(
     ] = None,
     extended_hours: Annotated[bool | None, "Include extended hours data"] = None,
     previous_close: Annotated[bool | None, "Include previous close data"] = None,
-) -> str:
+) -> JSONType:
     """
     Get OHLCV price history per minute. For detailed intraday analysis. Max 48 days history. Dates ISO format.
     """
@@ -139,7 +139,7 @@ async def get_price_history_every_five_minutes(
     ] = None,
     extended_hours: Annotated[bool | None, "Include extended hours data"] = None,
     previous_close: Annotated[bool | None, "Include previous close data"] = None,
-) -> str:
+) -> JSONType:
     """
     Get OHLCV price history per 5 minutes. Balance between detail and noise. Approx. 9 months history. Dates ISO format.
     """
@@ -171,7 +171,7 @@ async def get_price_history_every_ten_minutes(
     ] = None,
     extended_hours: Annotated[bool | None, "Include extended hours data"] = None,
     previous_close: Annotated[bool | None, "Include previous close data"] = None,
-) -> str:
+) -> JSONType:
     """
     Get OHLCV price history per 10 minutes. Good for intraday trends/levels. Approx. 9 months history. Dates ISO format.
     """
@@ -203,7 +203,7 @@ async def get_price_history_every_fifteen_minutes(
     ] = None,
     extended_hours: Annotated[bool | None, "Include extended hours data"] = None,
     previous_close: Annotated[bool | None, "Include previous close data"] = None,
-) -> str:
+) -> JSONType:
     """
     Get OHLCV price history per 15 minutes. Shows significant intraday moves, filters noise. Approx. 9 months history. Dates ISO format.
     """
@@ -235,7 +235,7 @@ async def get_price_history_every_thirty_minutes(
     ] = None,
     extended_hours: Annotated[bool | None, "Include extended hours data"] = None,
     previous_close: Annotated[bool | None, "Include previous close data"] = None,
-) -> str:
+) -> JSONType:
     """
     Get OHLCV price history per 30 minutes. For broader intraday trends, filters noise. Approx. 9 months history. Dates ISO format.
     """
@@ -273,7 +273,7 @@ async def get_price_history_every_day(
     previous_close: Annotated[
         bool | None, "Include the previous market day's closing price"
     ] = None,
-) -> str:
+) -> JSONType:
     """
     Get daily OHLCV price history. For medium/long-term analysis. Extensive history (back to 1985 possible). Dates ISO format.
     """
@@ -305,7 +305,7 @@ async def get_price_history_every_week(
     ] = None,
     extended_hours: Annotated[bool | None, "Include extended hours data"] = None,
     previous_close: Annotated[bool | None, "Include previous close data"] = None,
-) -> str:
+) -> JSONType:
     """
     Get weekly OHLCV price history. For long-term analysis, major cycles. Extensive history (back to 1985 possible). Dates ISO format.
     """

src/schwab_mcp/tools/options.py

@@ -6,7 +6,7 @@
 
 from schwab_mcp.context import SchwabContext, SchwabServerContext
 from schwab_mcp.tools.registry import register
-from schwab_mcp.tools.utils import call
+from schwab_mcp.tools.utils import JSONType, call
 
 
 def _parse_date(value: str | datetime.date | None) -> datetime.date | None:
@@ -41,7 +41,7 @@ async def get_option_chain(
         str | datetime.date | None,
         "End date for option expiration ('YYYY-MM-DD' or datetime.date)",
     ] = None,
-) -> str:
+) -> JSONType:
     """
     Returns option chain data (strikes, expirations, prices) for a symbol. Use for standard chains.
     Params: symbol, contract_type (CALL/PUT/ALL), strike_count (default 25), include_quotes (bool), from_date (YYYY-MM-DD), to_date (YYYY-MM-DD).
@@ -117,7 +117,7 @@ async def get_advanced_option_chain(
     option_type: Annotated[
         str | None, "Filter option type: STANDARD, NON_STANDARD, ALL (default)"
     ] = None,
-) -> str:
+) -> JSONType:
     """
     Returns advanced option chain data with strategies, filters, and theoretical calculations. Use for complex analysis.
     Params: symbol, contract_type, strike_count, include_quotes, strategy (SINGLE/ANALYTICAL/etc.), interval, strike, strike_range (ITM/NTM/etc.), from/to_date, volatility/underlying_price/interest_rate/days_to_expiration (for ANALYTICAL), exp_month, option_type (STANDARD/NON_STANDARD/ALL).
@@ -160,7 +160,7 @@ async def get_advanced_option_chain(
 async def get_option_expiration_chain(
     ctx: SchwabContext,
     symbol: Annotated[str, "Symbol of the underlying security"],
-) -> str:
+) -> JSONType:
     """
     Returns available option expiration dates for a symbol, without contract details. Lightweight call to find available cycles. Param: symbol.
     """

src/schwab_mcp/tools/orders.py

@@ -27,7 +27,7 @@
 from schwab.orders.options import OptionSymbol
 from schwab_mcp.context import SchwabContext, SchwabServerContext
 from schwab_mcp.tools.registry import register
-from schwab_mcp.tools.utils import call
+from schwab_mcp.tools.utils import JSONType, call
 
 
 # Internal helper function to apply session and duration settings
@@ -170,7 +170,7 @@ async def get_order(
     ctx: SchwabContext,
     account_hash: Annotated[str, "Account hash for the Schwab account"],
     order_id: Annotated[str, "Order ID to get details for"],
-) -> str:
+) -> JSONType:
     """
     Returns details for a specific order (ID, status, price, quantity, execution details). Params: account_hash, order_id.
     """
@@ -195,7 +195,7 @@ async def get_orders(
         list[str] | str | None,
         "Filter by order status (e.g., WORKING, FILLED, CANCELED). See full list below.",
     ] = None,
-) -> str:
+) -> JSONType:
     """
     Returns order history for an account. Filter by date range (max 60 days past) and status.
     Params: account_hash, max_results, from_date (YYYY-MM-DD), to_date (YYYY-MM-DD), status (list/str).
@@ -239,7 +239,7 @@ async def cancel_order(
     ctx: SchwabContext,
     account_hash: Annotated[str, "Account hash for the Schwab account"],
     order_id: Annotated[str, "Order ID to cancel"],
-) -> str:
+) -> JSONType:
     """
     Cancels a pending order. Cannot cancel executed/terminal orders. Params: account_hash, order_id. Returns cancellation request confirmation; check status after. *Write operation.*
     """
@@ -267,7 +267,7 @@ async def place_equity_order(
         str | None,
         "Order duration: DAY (default), GOOD_TILL_CANCEL, FILL_OR_KILL (Limit/StopLimit only)",
     ] = "DAY",
-) -> str:
+) -> JSONType:
     """
     Places a single equity order (MARKET, LIMIT, STOP, STOP_LIMIT).
     Params: account_hash, symbol, quantity, instruction (BUY/SELL), order_type.
@@ -315,7 +315,7 @@ async def place_option_order(
         str | None,
         "Order duration: DAY (default), GOOD_TILL_CANCEL, FILL_OR_KILL (Limit only)",
     ] = "DAY",
-) -> str:
+) -> JSONType:
     """
     Places a single option order (MARKET, LIMIT).
     Params: account_hash, symbol, quantity, instruction (BUY_TO_OPEN/etc.), order_type.
@@ -426,7 +426,7 @@ async def place_one_cancels_other_order(
     second_order_spec: Annotated[
         dict, "Second order specification (dict from build_equity/option_order_spec)"
     ],
-) -> str:
+) -> JSONType:
     """
     Creates OCO order: execution of one cancels the other. Use for take-profit/stop-loss pairs.
     Params: account_hash, first_order_spec (dict), second_order_spec (dict).
@@ -460,7 +460,7 @@ async def place_first_triggers_second_order(
         dict,
         "Second (triggered) order specification (dict from build_equity/option_order_spec)",
     ],
-) -> str:
+) -> JSONType:
     """
     Creates conditional order: second order placed only after first executes. Use for activating exits after entry.
     Params: account_hash, first_order_spec (dict), second_order_spec (dict).
@@ -533,7 +533,7 @@ async def place_bracket_order(
     duration: Annotated[
         str | None, "Order duration: DAY (default), GOOD_TILL_CANCEL"
     ] = "DAY",
-) -> str:
+) -> JSONType:
     """
     Creates a bracket order: entry + OCO take-profit/stop-loss. Exits trigger after entry executes.
     Params: account_hash, symbol, quantity, entry_instruction (BUY/SELL), entry_type (MARKET/LIMIT/STOP/STOP_LIMIT), profit_price, loss_price.

src/schwab_mcp/tools/quotes.py

@@ -4,7 +4,7 @@
 
 from schwab_mcp.context import SchwabContext, SchwabServerContext
 from schwab_mcp.tools.registry import register
-from schwab_mcp.tools.utils import call
+from schwab_mcp.tools.utils import JSONType, call
 
 
 @register
@@ -21,7 +21,7 @@ async def get_quotes(
     indicative: Annotated[
         bool | None, "True for indicative quotes (extended hours/futures)"
     ] = None,
-) -> str:
+) -> JSONType:
     """
     Returns current market quotes for specified symbols (stocks, ETFs, indices, options).
     Params: symbols (list or comma-separated string), fields (list/str: QUOTE/FUNDAMENTAL/etc.), indicative (bool).

src/schwab_mcp/tools/tools.py

@@ -5,7 +5,7 @@
 import datetime
 from schwab_mcp.context import SchwabContext, SchwabServerContext
 from schwab_mcp.tools.registry import register
-from schwab_mcp.tools.utils import call
+from schwab_mcp.tools.utils import JSONType, call
 
 
 @register
@@ -27,7 +27,7 @@ async def get_market_hours(
         str | None,
         "Date ('YYYY-MM-DD', default today, max 1 year future)",
     ] = None,
-) -> str:
+) -> JSONType:
     """
     Get market hours for specified markets (EQUITY, OPTION, etc.) on a given date (YYYY-MM-DD, default today).
     """
@@ -60,7 +60,7 @@ async def get_movers(
     frequency: Annotated[
         str | None, "Min % change threshold: ZERO, ONE, FIVE, TEN, THIRTY, SIXTY"
     ] = None,
-) -> str:
+) -> JSONType:
     """
     Get top 10 movers for an index/market (e.g., DJI, SPX, NASDAQ).
     Params: index, sort (VOLUME/TRADES/PERCENT_CHANGE_UP/DOWN), frequency (min % change: ZERO/ONE/etc.).
@@ -87,7 +87,7 @@ async def get_instruments(
             "DESCRIPTION_SEARCH, DESCRIPTION_REGEX, SEARCH, FUNDAMENTAL"
         ),
     ] = "symbol-search",
-) -> str:
+) -> JSONType:
     """
     Search for instruments by symbol or description.
     Params: symbol (search term), projection (SYMBOL_SEARCH/SYMBOL_REGEX/etc., default symbol-search).

src/schwab_mcp/tools/transactions.py

@@ -6,7 +6,7 @@
 
 from schwab_mcp.context import SchwabContext, SchwabServerContext
 from schwab_mcp.tools.registry import register
-from schwab_mcp.tools.utils import call
+from schwab_mcp.tools.utils import JSONType, call
 
 
 @register
@@ -25,7 +25,7 @@ async def get_transactions(
         "Filter by type(s) (list/str): TRADE, DIVIDEND_OR_INTEREST, ACH_RECEIPT, etc. Default all.",
     ] = None,
     symbol: Annotated[str | None, "Filter transactions by security symbol"] = None,
-) -> str:
+) -> JSONType:
     """
     Get transaction history (trades, deposits, dividends, etc.) for an account. Filter by date range (max 60 days past), type, symbol.
     Params: account_hash, start_date (YYYY-MM-DD), end_date (YYYY-MM-DD), transaction_type (list/str: TRADE/DIVIDEND_OR_INTEREST/etc.), symbol.
@@ -67,7 +67,7 @@ async def get_transaction(
     ctx: SchwabContext,
     account_hash: Annotated[str, "Account hash for the Schwab account"],
     transaction_id: Annotated[str, "Transaction ID (from get_transactions)"],
-) -> str:
+) -> JSONType:
     """
     Get detailed info for a specific transaction by ID.
     Params: account_hash, transaction_id (from get_transactions).

src/schwab_mcp/tools/utils.py

@@ -1,15 +1,26 @@
 from __future__ import annotations
 
 from collections.abc import Awaitable, Callable
-from typing import Any
+from typing import Any, TypeAlias
 
 
-async def call(func: Callable[..., Awaitable[Any]], *args: Any, **kwargs: Any) -> Any:
-    """Call a method on the Schwab client and return the response text."""
+JSONPrimitive = str | int | float | bool | None
+JSONType: TypeAlias = JSONPrimitive | dict[str, "JSONType"] | list["JSONType"]
+
+
+async def call(func: Callable[..., Awaitable[Any]], *args: Any, **kwargs: Any) -> JSONType:
+    """Call a Schwab client endpoint and return its JSON payload."""
 
     response = await func(*args, **kwargs)
     response.raise_for_status()
-    return response.text
+
+    if getattr(response, "status_code", None) == 204:
+        return None
+
+    try:
+        return response.json()
+    except ValueError as exc:
+        raise ValueError("Expected JSON response from Schwab endpoint") from exc
 
 
-__all__ = ["call"]
+__all__ = ["call", "JSONType"]