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;

mod option_chain;
use option_chain::option_chain_data_filter;

#[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 = "Company profile labels/details for a security. Futu API v10.6: OpenQuoteContext.get_company_profile."
    )]
    async fn futu_get_company_profile(
        &self,
        Parameters(req): Parameters<SymbolReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_company_profile", symbol = %req.symbol);
        let client = self
            .read_client_or_err("futu_get_company_profile", &req_ctx, None, None)
            .await?;
        Self::wrap_result(handlers::reference::get_company_profile(&client, &req.symbol).await)
    }

    #[tool(
        description = "Company executives / directors for a security. Futu API v10.6: OpenQuoteContext.get_company_executives."
    )]
    async fn futu_get_company_executives(
        &self,
        Parameters(req): Parameters<SymbolReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_company_executives", symbol = %req.symbol);
        let client = self
            .read_client_or_err("futu_get_company_executives", &req_ctx, None, None)
            .await?;
        Self::wrap_result(handlers::reference::get_company_executives(&client, &req.symbol).await)
    }

    #[tool(
        description = "Company executive/director background for a security. Futu API v10.6: OpenQuoteContext.get_company_executive_background."
    )]
    async fn futu_get_company_executive_background(
        &self,
        Parameters(req): Parameters<CompanyExecutiveBackgroundReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_company_executive_background",
            symbol = %req.symbol,
            leader_name = %req.leader_name
        );
        let client = self
            .read_client_or_err(
                "futu_get_company_executive_background",
                &req_ctx,
                None,
                None,
            )
            .await?;
        Self::wrap_result(
            handlers::reference::get_company_executive_background(
                &client,
                &req.symbol,
                &req.leader_name,
            )
            .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> {
        let max_count = req.validated_max_count()?;
        let session = req.validated_session()?;
        let next_req_key = req.decoded_next_req_key()?;
        tracing::info!(
            tool = "futu_get_history_kline",
            symbol = %req.symbol,
            kl_type = %req.kl_type,
            rehab = %req.rehab_type,
            extended_time = ?req.extended_time,
            session = ?session,
            has_next_req_key = next_req_key.is_some(),
        );
        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,
                max_count,
                req.need_kl_fields_flag,
                req.extended_time,
                session,
                next_req_key.as_deref(),
            )
            .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> {
        req.validate()?;
        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 data_filter = option_chain_data_filter(&req);
        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> {
        req.validate()?;
        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, 2=HK_FUTURE, 11=US, 21=SH/CN, 22=SZ, 31=SG, 41=JP, 61=MY."
    )]
    async fn futu_get_ipo_list(
        &self,
        Parameters(req): Parameters<IpoListReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        req.validate()?;
        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 = "IPO calendar projection over get_ipo_list. Rust read-only enhancement for calendar-style IPO monitoring; not a separate C++ FTAPI endpoint."
    )]
    async fn futu_get_ipo_calendar(
        &self,
        Parameters(req): Parameters<IpoCalendarReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        req.validate()?;
        tracing::info!(
            tool = "futu_get_ipo_calendar",
            market = req.market,
            event_types = ?req.event_types,
            begin_date = ?req.begin_date,
            end_date = ?req.end_date
        );
        let client = self
            .read_client_or_err("futu_get_ipo_calendar", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::reference::get_ipo_calendar(
                &client,
                req.market,
                &req.event_types,
                req.begin_date.as_deref(),
                req.end_date.as_deref(),
            )
            .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=custom, 2=system, 3=all."
    )]
    async fn futu_get_user_security_group(
        &self,
        Parameters(req): Parameters<UserSecurityGroupReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        req.validate()?;
        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> {
        req.validate()?;
        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> {
        req.validate()?;
        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 percent values (e.g. 4.5 means 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> {
        req.validate()?;
        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). Total follows the account's dynamic API quota after login; FUTU_HISTORY_KL_QUOTA_MAX only overrides it when explicitly set. 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> {
        req.validate()?;
        // 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 = "Option implied-volatility analysis. Futu API v10.6: OpenQuoteContext.get_option_volatility."
    )]
    async fn futu_get_option_volatility(
        &self,
        Parameters(req): Parameters<OptionVolatilityReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        req.validate()?;
        tracing::info!(
            tool = "futu_get_option_volatility",
            symbol = %req.symbol,
            query_time_period = ?req.query_time_period,
            hv_time_period = ?req.hv_time_period
        );
        let client = self
            .read_client_or_err("futu_get_option_volatility", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::reference::get_option_volatility(
                &client,
                &req.symbol,
                req.query_time_period,
                req.hv_time_period,
            )
            .await,
        )
    }

    #[tool(
        description = "Option exercise probability history. Futu API v10.6: OpenQuoteContext.get_option_exercise_probability."
    )]
    async fn futu_get_option_exercise_probability(
        &self,
        Parameters(req): Parameters<OptionExerciseProbabilityReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_option_exercise_probability", symbol = %req.symbol);
        let client = self
            .read_client_or_err("futu_get_option_exercise_probability", &req_ctx, None, None)
            .await?;
        Self::wrap_result(
            handlers::reference::get_option_exercise_probability(&client, &req.symbol).await,
        )
    }
}