futu_mcp/tools/

reference.rs

//! MCP market analysis, reference-data, and quote-system metadata tools.

use crate::handlers;
use crate::tool_args::*;
use rmcp::{
    RoleServer, handler::server::wrapper::Parameters, service::RequestContext, tool, tool_router,
};

use super::FutuServer;

#[tool_router(router = reference_tool_router, vis = "pub(crate)")]
impl FutuServer {
    // ===== v1.4.25: 行情分析 =====

    #[tool(
        description = "Capital flow (net inflow) time series for a security. Python SDK: OpenQuoteContext.get_capital_flow."
    )]
    async fn futu_get_capital_flow(
        &self,
        Parameters(req): Parameters<CapitalFlowReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_capital_flow", symbol = %req.symbol);
        let client = self
            .read_client_or_err("futu_get_capital_flow", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::analysis::get_capital_flow(
                &client,
                &req.symbol,
                req.period_type,
                req.begin_time,
                req.end_time,
            )
            .await,
        )
    }

    #[tool(
        description = "Capital distribution (super/big/mid/small order in/out flow amounts) snapshot. Python SDK: OpenQuoteContext.get_capital_distribution."
    )]
    async fn futu_get_capital_distribution(
        &self,
        Parameters(req): Parameters<SymbolReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_capital_distribution", symbol = %req.symbol);
        let client = self
            .read_client_or_err("futu_get_capital_distribution", &req_ctx, None, None)
            .await?;
        Self::wrap_result(handlers::analysis::get_capital_distribution(&client, &req.symbol).await)
    }

    #[tool(
        description = "Query current market state for a list of securities (open/closed/lunch-break etc). Python SDK: OpenQuoteContext.get_market_state."
    )]
    async fn futu_get_market_state(
        &self,
        Parameters(req): Parameters<MarketStateReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_market_state", count = req.symbols.len());
        let client = self
            .read_client_or_err("futu_get_market_state", &req_ctx, None, None)
            .await?;
        Self::wrap_result(handlers::analysis::get_market_state(&client, &req.symbols).await)
    }

    // ===== v1.4.26 新增：history_kline / owner_plate / reference / option_chain =====

    #[tool(
        description = "Historical K-line / OHLCV time series with rehab type control (forward/backward/none) and pagination-friendly max_count. Python SDK: OpenQuoteContext.request_history_kline."
    )]
    async fn futu_get_history_kline(
        &self,
        Parameters(req): Parameters<HistoryKLineReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_history_kline",
            symbol = %req.symbol,
            kl_type = %req.kl_type,
            rehab = %req.rehab_type
        );
        let client = self
            .read_client_or_err("futu_get_history_kline", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::analysis::get_history_kline(
                &client,
                &req.symbol,
                &req.kl_type,
                &req.rehab_type,
                &req.begin,
                &req.end,
                req.max_count,
            )
            .await,
        )
    }

    #[tool(
        description = "List plates (industry/concept/region) that contain given stocks. Python SDK: OpenQuoteContext.get_owner_plate."
    )]
    async fn futu_get_owner_plate(
        &self,
        Parameters(req): Parameters<SymbolListReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_owner_plate", count = req.symbols.len());
        let client = self
            .read_client_or_err("futu_get_owner_plate", &req_ctx, None, None)
            .await?;
        Self::wrap_result(handlers::analysis::get_owner_plate(&client, &req.symbols).await)
    }

    #[tool(
        description = "Related securities of an underlying: list all warrants/futures/options derived from a given stock. Python SDK: OpenQuoteContext.get_referencestock_list."
    )]
    async fn futu_get_reference(
        &self,
        Parameters(req): Parameters<ReferenceReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_reference",
            symbol = %req.symbol,
            reference_type = %req.reference_type
        );
        let client = self
            .read_client_or_err("futu_get_reference", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::analysis::get_reference(&client, &req.symbol, &req.reference_type).await,
        )
    }

    #[tool(
        description = "Option chain of an underlying stock within an expiry date range, grouped by strike time with call/put symbol lists. Python SDK: OpenQuoteContext.get_option_chain."
    )]
    async fn futu_get_option_chain(
        &self,
        Parameters(req): Parameters<OptionChainReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_option_chain",
            owner = %req.owner_symbol,
            begin = %req.begin_time,
            end = %req.end_time
        );
        let client = self
            .read_client_or_err("futu_get_option_chain", &req_ctx, None, None)
            .await?;
        // v1.4.38 Phase 3: 把 MCP 侧的 Greek filter 字段组装成 proto DataFilter
        let any_filter = req.delta_min.is_some()
            || req.delta_max.is_some()
            || req.iv_min.is_some()
            || req.iv_max.is_some()
            || req.oi_min.is_some()
            || req.oi_max.is_some()
            || req.gamma_min.is_some()
            || req.gamma_max.is_some()
            || req.vega_min.is_some()
            || req.vega_max.is_some()
            || req.theta_min.is_some()
            || req.theta_max.is_some();
        let data_filter = if any_filter {
            Some(futu_proto::qot_get_option_chain::DataFilter {
                implied_volatility_min: req.iv_min,
                implied_volatility_max: req.iv_max,
                delta_min: req.delta_min,
                delta_max: req.delta_max,
                gamma_min: req.gamma_min,
                gamma_max: req.gamma_max,
                vega_min: req.vega_min,
                vega_max: req.vega_max,
                theta_min: req.theta_min,
                theta_max: req.theta_max,
                rho_min: None,
                rho_max: None,
                net_open_interest_min: None,
                net_open_interest_max: None,
                open_interest_min: req.oi_min,
                open_interest_max: req.oi_max,
                vol_min: None,
                vol_max: None,
            })
        } else {
            None
        };
        Self::wrap_result(
            handlers::analysis::get_option_chain(
                &client,
                handlers::analysis::OptionChainInput {
                    owner_symbol: &req.owner_symbol,
                    begin_time: &req.begin_time,
                    end_time: &req.end_time,
                    option_type_str: req.option_type.as_deref(),
                    data_filter,
                },
            )
            .await,
        )
    }

    // ------- v1.4.29 参考数据 / 衍生证券 -------

    #[tool(
        description = "List warrants on an underlying stock (or whole-market when owner_symbol omitted), sorted by volume desc. Python SDK: OpenQuoteContext.get_warrant. For advanced filtering (strike/premium/delta/etc.) use REST /api/warrant directly."
    )]
    async fn futu_get_warrant(
        &self,
        Parameters(req): Parameters<WarrantReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_warrant",
            // v1.4.90 P2-C: Option<String> → &str ("" 哨兵)
            owner = %crate::state::audit_fmt::opt_str(req.owner_symbol.as_deref()),
            begin = req.begin,
            num = req.num
        );
        let client = self
            .read_client_or_err("futu_get_warrant", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::reference::get_warrant(
                &client,
                req.owner_symbol.as_deref(),
                req.begin,
                req.num,
            )
            .await,
        )
    }

    #[tool(
        description = "Upcoming / recent IPOs for a market. Python SDK: OpenQuoteContext.get_ipo_list. market: 1=HK, 11=US, 21=SH, 22=SZ."
    )]
    async fn futu_get_ipo_list(
        &self,
        Parameters(req): Parameters<IpoListReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_ipo_list", market = req.market);
        let client = self
            .read_client_or_err("futu_get_ipo_list", &req_ctx, None, None)
            .await?;
        Self::wrap_result(handlers::reference::get_ipo_list(&client, req.market).await)
    }

    #[tool(
        description = "Future contract info (contract size, last trade date, trading hours). Python SDK: OpenQuoteContext.get_future_info."
    )]
    async fn futu_get_future_info(
        &self,
        Parameters(req): Parameters<FutureInfoReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_future_info", count = req.symbols.len());
        let client = self
            .read_client_or_err("futu_get_future_info", &req_ctx, None, None)
            .await?;
        Self::wrap_result(handlers::reference::get_future_info(&client, &req.symbols).await)
    }

    #[tool(
        description = "List the user's custom + system watchlist groups. Python SDK: OpenQuoteContext.get_user_security_group. group_type: 1=all, 2=custom, 3=system."
    )]
    async fn futu_get_user_security_group(
        &self,
        Parameters(req): Parameters<UserSecurityGroupReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_user_security_group",
            group_type = req.group_type
        );
        let client = self
            .read_client_or_err("futu_get_user_security_group", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::reference::get_user_security_group(&client, req.group_type).await,
        )
    }

    #[tool(
        description = "Stock filter / scanner (minimal: market + pagination). Python SDK: OpenQuoteContext.get_stock_filter. For condition-based filters (PE/cap/volume/etc.) use REST /api/stock-filter directly."
    )]
    async fn futu_get_stock_filter(
        &self,
        Parameters(req): Parameters<StockFilterReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_stock_filter",
            market = req.market,
            begin = req.begin,
            num = req.num
        );
        let client = self
            .read_client_or_err("futu_get_stock_filter", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::reference::get_stock_filter(&client, req.market, req.begin, req.num).await,
        )
    }

    // ------- v1.4.30 市场元数据 / 复权 / 自选 -------

    #[tool(
        description = "Trading days for a market in a date range. Python SDK: OpenQuoteContext.request_trading_days. Note: returns natural-day-minus-weekends-and-holidays, excluding temporary market closures."
    )]
    async fn futu_get_trading_days(
        &self,
        Parameters(req): Parameters<TradingDaysReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_trading_days",
            market = req.market,
            begin = %req.begin_time,
            end = %req.end_time
        );
        let client = self
            .read_client_or_err("futu_get_trading_days", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::reference::get_trading_days(
                &client,
                req.market,
                &req.begin_time,
                &req.end_time,
            )
            .await,
        )
    }

    #[tool(
        description = "Rehab (dividend / split / bonus) events and adjustment factors. Required for long-term K-line alignment. Python SDK: OpenQuoteContext.get_rehab."
    )]
    async fn futu_get_rehab(
        &self,
        Parameters(req): Parameters<SymbolReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_rehab", symbol = %req.symbol);
        let client = self
            .read_client_or_err("futu_get_rehab", &req_ctx, None, None)
            .await?;
        Self::wrap_result(handlers::reference::get_rehab(&client, &req.symbol).await)
    }

    #[tool(
        description = "Suspend (trading halt) days for securities in a date range. Python SDK: OpenQuoteContext.get_suspend."
    )]
    async fn futu_get_suspend(
        &self,
        Parameters(req): Parameters<SuspendReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_suspend",
            count = req.symbols.len(),
            begin = %req.begin_time,
            end = %req.end_time
        );
        let client = self
            .read_client_or_err("futu_get_suspend", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::reference::get_suspend(&client, &req.symbols, &req.begin_time, &req.end_time)
                .await,
        )
    }

    #[tool(
        description = "List securities in a user watchlist group. Python SDK: OpenQuoteContext.get_user_security. Use futu_get_user_security_group to find available group names."
    )]
    async fn futu_get_user_security(
        &self,
        Parameters(req): Parameters<UserSecurityReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_user_security", group = %req.group_name);
        let client = self
            .read_client_or_err("futu_get_user_security", &req_ctx, None, None)
            .await?;
        Self::wrap_result(handlers::reference::get_user_security(&client, &req.group_name).await)
    }

    // ------- v1.4.30 系统元数据 -------

    #[tool(
        description = "Get gateway global state: per-market trading status, server version / time, quote & trade login status. Python SDK: OpenContext.get_global_state."
    )]
    async fn futu_get_global_state(
        &self,
        Parameters(_req): Parameters<NoArgs>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_global_state");
        let client = self
            .read_client_or_err("futu_get_global_state", &req_ctx, None, None)
            .await?;
        Self::wrap_result(handlers::core::get_global_state(&client).await)
    }

    #[tool(
        description = "Get user info: nickname, per-market quote permissions, subscribe quota, history-K quota. Python SDK: OpenContext.get_user_info."
    )]
    async fn futu_get_user_info(
        &self,
        Parameters(_req): Parameters<NoArgs>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_user_info");
        let client = self
            .read_client_or_err("futu_get_user_info", &req_ctx, None, None)
            .await?;
        Self::wrap_result(handlers::core::get_user_info(&client).await)
    }

    #[tool(
        description = "Get quote-rights profile grouped like Futu OpenD GUI: HK/US/CN/SG/JP/crypto permissions, raw values, labels and quota. Set refresh=true to trigger request_highest_quote_right first."
    )]
    async fn futu_get_quote_rights(
        &self,
        Parameters(req): Parameters<QuoteRightsReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_quote_rights",
            refresh = req.refresh.unwrap_or(false)
        );
        let client = self
            .read_client_or_err("futu_get_quote_rights", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::core::get_quote_rights(&client, req.refresh.unwrap_or(false)).await,
        )
    }

    #[tool(
        description = "Get delay-statistics summary: counts of quote-push / request-reply / place-order samples. Python SDK: OpenContext.get_delay_statistics. For raw per-segment buckets use REST /api/delay-statistics."
    )]
    async fn futu_get_delay_statistics(
        &self,
        Parameters(_req): Parameters<NoArgs>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_delay_statistics");
        let client = self
            .read_client_or_err("futu_get_delay_statistics", &req_ctx, None, None)
            .await?;
        Self::wrap_result(handlers::core::get_delay_statistics(&client).await)
    }

    #[tool(
        description = "Query Futu Token / moomoo Token enable + bind state. Returns 4 fields: \
            nn_token_enable, nn_token_bind, mm_token_enable, mm_token_bind \
            (1=enabled/bound, 0=disabled/unbound). \
            Use case: when /api/unlock-trade fails with -20011 (\"please enable Futu Token\"), \
            call this tool first to diagnose which side is missing token binding."
    )]
    async fn futu_get_token_state(
        &self,
        Parameters(_req): Parameters<NoArgs>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_token_state");
        let client = self
            .read_client_or_err("futu_get_token_state", &req_ctx, None, None)
            .await?;
        // app_id default "all" (查 NN+MM 两边); caller 没传 = None → daemon 内部 default.
        Self::wrap_result(handlers::core::get_token_state(&client, None).await)
    }

    #[tool(
        description = "Risk-free rate for HK / US / JP markets (option pricing baseline, \
            e.g. Black-Scholes). Returns rate as percent (e.g. 4.5) plus raw uint64 \
            (×10^9). Useful for pricing options or computing implied volatility / cost of carry."
    )]
    async fn futu_get_risk_free_rate(
        &self,
        Parameters(_req): Parameters<NoArgs>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_risk_free_rate");
        let client = self
            .read_client_or_err("futu_get_risk_free_rate", &req_ctx, None, None)
            .await?;
        Self::wrap_result(handlers::core::get_risk_free_rate(&client).await)
    }

    #[tool(
        description = "Get full spread tables (price tick rules per market). Returns \
            spread_table_list with spread_code + price intervals (price_from / price_to / \
            value, in actual decimals). Useful for client-side price validation before \
            PlaceOrder / ModifyOrder."
    )]
    async fn futu_get_spread_table(
        &self,
        Parameters(_req): Parameters<NoArgs>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_spread_table");
        let client = self
            .read_client_or_err("futu_get_spread_table", &req_ctx, None, None)
            .await?;
        Self::wrap_result(handlers::core::get_spread_table(&client).await)
    }

    #[tool(description = "Per-stock ticker statistic \
            (avg_price / volume / buy_volume / sell_volume / neutral_volume / trade_num). \
            Symbol format: 'HK.00700' / 'US.AAPL'. Pre-condition: must \
            subscribe / get_static_info first to populate stock_id in static_cache. \
            ticker_type: 0=ALL, 1=BUY, 2=SELL, 3=BUY_AND_SELL, 4=NEUTRAL. \
            stat_type: 0=ALL, 1=BEFORE, 2=TRADING, 3=AFTER (market session).")]
    async fn futu_get_ticker_statistic(
        &self,
        Parameters(req): Parameters<TickerStatisticReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_ticker_statistic", symbol = %req.symbol);
        let client = self
            .read_client_or_err("futu_get_ticker_statistic", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::core::get_ticker_statistic(
                &client,
                &req.symbol,
                req.ticker_type,
                req.stat_type,
            )
            .await,
        )
    }

    #[tool(
        description = "Per-stock ticker statistic detail (price-level distribution). \
            Companion of futu_get_ticker_statistic. Typical flow: \
            (1) call futu_get_ticker_statistic to get ticker_time + summary stats, \
            (2) call this tool with same ticker_time to get DetailItem list \
            (price / buy_volume / sell_volume / volume / ratio / neutral_volume per price level). \
            Symbol format: 'HK.00700' / 'US.AAPL'. Pre-condition: must subscribe / get_static_info \
            first to populate stock_id in static_cache. \
            ticker_type: 0=ALL, 1=BUY, 2=SELL, 3=BUY_AND_SELL, 4=NEUTRAL. \
            stat_type: 0=ALL, 1=BEFORE, 2=TRADING, 3=AFTER. \
            select_num: 0=all levels, 1..N=top N (backend max ~100). \
            data_from / data_max_count: pagination."
    )]
    async fn futu_get_ticker_statistic_detail(
        &self,
        Parameters(req): Parameters<TickerStatisticDetailReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_ticker_statistic_detail", symbol = %req.symbol);
        let client = self
            .read_client_or_err("futu_get_ticker_statistic_detail", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::core::get_ticker_statistic_detail(
                &client,
                handlers::core::TickerStatisticDetailInput {
                    symbol: &req.symbol,
                    ticker_type: req.ticker_type,
                    ticker_time: req.ticker_time,
                    select_num: req.select_num,
                    data_from: req.data_from,
                    data_max_count: req.data_max_count,
                    stat_type: req.stat_type,
                },
            )
            .await,
        )
    }

    // ------- v1.4.30 交易扩展 -------

    // ------- v1.4.30 P2 完成品（100% 覆盖） -------

    #[tool(
        description = "Historical K-line download quota (used / remain). Python SDK: OpenQuoteContext.get_history_kl_quota."
    )]
    async fn futu_get_history_kl_quota(
        &self,
        Parameters(req): Parameters<HistoryKlQuotaReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_history_kl_quota", detail = req.get_detail);
        let client = self
            .read_client_or_err("futu_get_history_kl_quota", &req_ctx, None, None)
            .await?;
        Self::wrap_result(handlers::reference::get_history_kl_quota(&client, req.get_detail).await)
    }

    #[tool(
        description = "Top-holder share change list (institution / fund / executive). Python SDK: OpenQuoteContext.get_holding_change_list."
    )]
    async fn futu_get_holding_change(
        &self,
        Parameters(req): Parameters<HoldingChangeReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_holding_change",
            symbol = %req.symbol,
            category = req.holder_category
        );
        let client = self
            .read_client_or_err("futu_get_holding_change", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::reference::get_holding_change(
                &client,
                &req.symbol,
                req.holder_category,
                req.begin_time.as_deref(),
                req.end_time.as_deref(),
            )
            .await,
        )
    }

    #[tool(
        description = "Modify watchlist group — add / delete / move-out stocks. `op` is an INTEGER (not a string literal): 1=AddInto, 2=Delete-from-group, 3=MoveOut. Python SDK: OpenQuoteContext.modify_user_security."
    )]
    async fn futu_modify_user_security(
        &self,
        Parameters(req): Parameters<ModifyUserSecurityReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        // v1.4.104 codex round 1 F2 (P1) fix: 改 caller-specific scope check
        // (之前 require_tool_scope 只看 startup key, narrow Bearer 仍可用
        // startup key 的 qot:read scope 修改 watchlist 全局状态).
        // require_acc_read_with_acc_id 内部用 scope_for_tool(tool) 拿 needed_scope
        // (此 tool 是 ToolScope::Read(QotRead)), 走 caller-specific 路径.
        tracing::info!(
            tool = "futu_modify_user_security",
            group = %req.group_name,
            op = req.op,
            count = req.symbols.len()
        );
        let client = self
            .read_client_or_err("futu_modify_user_security", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::reference::modify_user_security(
                &client,
                &req.group_name,
                req.op,
                &req.symbols,
            )
            .await,
        )
    }

    #[tool(
        description = "Code change / temporary-ticker info (currently HK market only). Python SDK: OpenQuoteContext.get_code_change."
    )]
    async fn futu_get_code_change(
        &self,
        Parameters(req): Parameters<CodeChangeReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_code_change", count = req.symbols.len());
        let client = self
            .read_client_or_err("futu_get_code_change", &req_ctx, None, None)
            .await?;
        Self::wrap_result(handlers::reference::get_code_change(&client, &req.symbols).await)
    }

    #[tool(description = "Set price reminder. `op` accepts integer code 1-6 \
                       (1=Add, 2=Del, 3=Enable, 4=Disable, 5=Modify, 6=DeleteAll); \
                       MCP also accepts string aliases Add/Del/Enable/Disable/Modify/DeleteAll \
                       (and legacy SetAdd/SetDel/SetEnable/SetDisable/DelAll). \
                       Add (op=1) requires reminder_type + freq + value. \
                       Modify (op=5) requires key (other fields preserved when omitted). \
                       Python SDK: OpenQuoteContext.set_price_reminder.")]
    async fn futu_set_price_reminder(
        &self,
        Parameters(req): Parameters<SetPriceReminderReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        // v1.4.104 codex round 1 F2 (P1) fix: 改 caller-specific scope check
        // (之前 require_tool_scope 只看 startup key, HTTP Bearer 调用方权限
        // 没真核, narrow Bearer 仍能修改 / 删除全局 price reminder 状态).
        // v1.4.84 §5 B4: op-conditional required field check
        req.validate()?;
        tracing::info!(
            tool = "futu_set_price_reminder",
            symbol = %req.symbol,
            op = req.op
        );
        let client = self
            .read_client_or_err("futu_set_price_reminder", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::reference::set_price_reminder(
                &client,
                handlers::reference::SetPriceReminderInput {
                    symbol: &req.symbol,
                    op: req.op,
                    key: req.key,
                    reminder_type: req.reminder_type,
                    freq: req.freq,
                    value: req.value,
                    note: req.note.as_deref(),
                    reminder_session_list: &req.reminder_session_list,
                },
            )
            .await,
        )
    }

    #[tool(
        description = "Query price reminders (by symbol or market). Python SDK: OpenQuoteContext.get_price_reminder."
    )]
    async fn futu_get_price_reminder(
        &self,
        Parameters(req): Parameters<GetPriceReminderReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        // v1.4.84 §5 B4: symbol XOR market required
        req.validate()?;
        tracing::info!(
            tool = "futu_get_price_reminder",
            // v1.4.90 P2-C: Option<String> / Option<i32> 都 flatten，避免 record_debug 编 string
            symbol = %crate::state::audit_fmt::opt_str(req.symbol.as_deref()),
            market = crate::state::audit_fmt::opt_i32(req.market)
        );
        let client = self
            .read_client_or_err("futu_get_price_reminder", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::reference::get_price_reminder(&client, req.symbol.as_deref(), req.market)
                .await,
        )
    }

    #[tool(
        description = "Option expiration-date list for an underlying (HSI / HSCEI or HK/US equity). Python SDK: OpenQuoteContext.get_option_expiration_date."
    )]
    async fn futu_get_option_expiration_date(
        &self,
        Parameters(req): Parameters<OptionExpirationDateReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_option_expiration_date",
            owner = %req.owner_symbol
        );
        let client = self
            .read_client_or_err("futu_get_option_expiration_date", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::reference::get_option_expiration_date(
                &client,
                &req.owner_symbol,
                req.index_option_type,
            )
            .await,
        )
    }
}