futu_mcp/tools/

trade_read.rs

//! MCP trade-read/account tools (accounts, funds, positions, orders, Tier M read APIs).

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 = trade_read_tool_router, vis = "pub(crate)")]
impl FutuServer {
    // ------- 账户（只读） -------

    #[tool(
        description = "List all trading accounts (real + simulate) visible to the gateway login."
    )]
    async fn futu_list_accounts(
        &self,
        Parameters(_req): Parameters<NoArgs>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        // v1.4.103 B5: per-request Bearer 解析 (HTTP) → caller-specific scope check.
        // v1.4.104 codex F3 (P2) fix: 用 pipeline 返的 snapshot 做 list filter,
        // 不再 re-resolve from Bearer/startup (避免 SIGHUP race / drift —
        // pipeline 授权时的 KeyRecord 与 filter 用的同一实例).
        let snap = self.require_acc_read_with_acc_id("futu_list_accounts", &req_ctx, None, None)?;
        tracing::info!(tool = "futu_list_accounts");
        let client = self.client_or_err().await?;
        // v1.4.103 codex F2.5 (P2) + v1.4.104 codex F3 (P2): 按 caller 的
        // allowed_acc_ids snapshot (来自 pipeline 授权决策, 同一 KeyRecord)
        // filter list, 防受限 key 跨账户 enumerate. 与 REST `/api/accounts`
        // filter (codex F6) 对齐.
        let allowed_card_nums = snap
            .rec
            .as_ref()
            .and_then(|r| r.allowed_card_nums.as_deref());
        Self::wrap_result(
            handlers::trade::list_accounts_filtered(
                &client,
                snap.allowed_acc_ids.as_ref(),
                allowed_card_nums,
            )
            .await,
        )
    }

    #[tool(
        description = "Get account funds summary (total assets, cash, market value, buying power) for a given account + market.\n\n\
                       **Cash semantics**: top-level `cash` field is \
                       backend's summary cash in the response `currency` (i.e. `union_currency` for \
                       futures/universal, primary market currency for legacy accounts). It is **NOT** \
                       the sum of `cash_info_list[].cash` across currencies (different currencies \
                       cannot be summed without FX conversion). For per-currency breakdown, read \
                       `cash_info_list`. To match Futu mobile app's '现金总值 in HKD' display, \
                       client-side compute `sum(cash_info_list[i].cash * fx_rate(currency[i], HKD))` \
                       — daemon does not perform FX aggregation."
    )]
    async fn futu_get_funds(
        &self,
        Parameters(req): Parameters<TrdAccReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        let resolved = self
            .resolve_read_trd_account("futu_get_funds", &req, &req_ctx)
            .await?;
        tracing::info!(
            tool = "futu_get_funds",
            market = %req.market,
            acc_id = resolved.acc_id,
            env = %req.env,
            currency = ?req.currency,
        );
        // v1.4.103 (external reviewer 反馈 P1): 综合账户币种不一致 fix — 透传 currency.
        Self::wrap_result(
            handlers::trade::get_funds_with_currency(
                &resolved.client,
                &req.env,
                resolved.acc_id,
                &req.market,
                req.currency.as_deref(),
            )
            .await,
        )
    }

    #[tool(description = "Get current positions (holdings) for an account in a given market.")]
    async fn futu_get_positions(
        &self,
        Parameters(req): Parameters<PositionReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        let acc_req = req.as_trd_acc_req();
        let resolved = self
            .resolve_read_trd_account("futu_get_positions", &acc_req, &req_ctx)
            .await?;
        tracing::info!(
            tool = "futu_get_positions",
            market = %req.market,
            acc_id = resolved.acc_id,
            currency = ?req.currency,
            option_strategy_view = req.option_strategy_view,
        );
        Self::wrap_result(
            handlers::trade::get_positions(
                &resolved.client,
                &req.env,
                resolved.acc_id,
                &req.market,
                req.currency.as_deref(),
                req.option_strategy_view,
            )
            .await,
        )
    }

    #[tool(
        description = "Get today's orders (including pending / filled / cancelled) for an account in a given market."
    )]
    async fn futu_get_orders(
        &self,
        Parameters(req): Parameters<TrdAccReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        let resolved = self
            .resolve_read_trd_account("futu_get_orders", &req, &req_ctx)
            .await?;
        tracing::info!(tool = "futu_get_orders", market = %req.market, acc_id = resolved.acc_id);
        Self::wrap_result(
            handlers::trade::get_orders(&resolved.client, &req.env, resolved.acc_id, &req.market)
                .await,
        )
    }

    #[tool(description = "Get today's deals / order fills for an account in a given market.")]
    async fn futu_get_deals(
        &self,
        Parameters(req): Parameters<TrdAccReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        let resolved = self
            .resolve_read_trd_account("futu_get_deals", &req, &req_ctx)
            .await?;
        tracing::info!(tool = "futu_get_deals", market = %req.market, acc_id = resolved.acc_id);
        Self::wrap_result(
            handlers::trade::get_deals(&resolved.client, &req.env, resolved.acc_id, &req.market)
                .await,
        )
    }

    // ===== v1.4.25: 交易扩展查询 (py-futu-api 对齐) =====

    #[tool(
        description = "Max buy/sell/short/buy-back qtys before placing an order. Python SDK: OpenTradeContext.acctradinginfo_query. For NORMAL (limit) orders, price is required. order_type aligns with Trd_Common.OrderType enum (1=limit, 2=market, etc)."
    )]
    async fn futu_get_max_trd_qtys(
        &self,
        Parameters(req): Parameters<MaxTrdQtysReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_max_trd_qtys", market = %req.market, acc_id = req.acc_id, code = %req.code);
        let client = self
            .read_client_or_err("futu_get_max_trd_qtys", &req_ctx, None, Some(req.acc_id))
            .await?;
        Self::wrap_result(
            handlers::trade::get_max_trd_qtys(
                &client,
                handlers::trade::MaxTrdQtysInput {
                    env: &req.env,
                    acc_id: req.acc_id,
                    market: &req.market,
                    order_type: req.order_type,
                    code: &req.code,
                    price: req.price,
                    jp_acc_type: req.jp_acc_type,
                    order_id: req.order_id,
                },
            )
            .await,
        )
    }

    #[tool(
        description = "Query order fee breakdown (commission / platform fee / stamp duty) by order_id_ex list. Python SDK: OpenTradeContext.order_fee_query."
    )]
    async fn futu_get_order_fee(
        &self,
        Parameters(req): Parameters<OrderFeeReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_order_fee", market = %req.market, acc_id = req.acc_id, count = req.order_id_ex_list.len());
        let client = self
            .read_client_or_err("futu_get_order_fee", &req_ctx, None, Some(req.acc_id))
            .await?;
        Self::wrap_result(
            handlers::trade::get_order_fee(
                &client,
                &req.env,
                req.acc_id,
                &req.market,
                &req.order_id_ex_list,
            )
            .await,
        )
    }

    #[tool(
        description = "Query margin ratio (long/short permissions, short-pool remaining, long/short initial margin ratios) by symbol list. Python SDK: OpenTradeContext.get_margin_ratio."
    )]
    async fn futu_get_margin_ratio(
        &self,
        Parameters(req): Parameters<MarginRatioReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_margin_ratio", market = %req.market, acc_id = req.acc_id, count = req.codes.len());
        let client = self
            .read_client_or_err("futu_get_margin_ratio", &req_ctx, None, Some(req.acc_id))
            .await?;
        Self::wrap_result(
            handlers::trade::get_margin_ratio(
                &client,
                &req.env,
                req.acc_id,
                &req.market,
                &req.codes,
            )
            .await,
        )
    }

    #[tool(
        description = "Query historical orders (filled / cancelled) with optional time range + code filter. Python SDK: OpenTradeContext.history_order_list_query."
    )]
    async fn futu_get_history_orders(
        &self,
        Parameters(req): Parameters<HistoryQueryReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_history_orders", market = %req.market, acc_id = req.acc_id);
        let client = self
            .read_client_or_err("futu_get_history_orders", &req_ctx, None, Some(req.acc_id))
            .await?;
        Self::wrap_result(
            handlers::trade::get_history_orders(
                &client,
                handlers::trade::HistoryQueryInput {
                    env: &req.env,
                    acc_id: req.acc_id,
                    market: &req.market,
                    code_list: req.code_list,
                    begin_time: req.begin_time,
                    end_time: req.end_time,
                },
            )
            .await,
        )
    }

    #[tool(
        description = "Query historical deals / fills with optional time range + code filter. Python SDK: OpenTradeContext.history_deal_list_query."
    )]
    async fn futu_get_history_deals(
        &self,
        Parameters(req): Parameters<HistoryQueryReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_history_deals", market = %req.market, acc_id = req.acc_id);
        let client = self
            .read_client_or_err("futu_get_history_deals", &req_ctx, None, Some(req.acc_id))
            .await?;
        Self::wrap_result(
            handlers::trade::get_history_deals(
                &client,
                handlers::trade::HistoryQueryInput {
                    env: &req.env,
                    acc_id: req.acc_id,
                    market: &req.market,
                    code_list: req.code_list,
                    begin_time: req.begin_time,
                    end_time: req.end_time,
                },
            )
            .await,
        )
    }

    #[tool(
        description = "Account cash-flow statement for a clearing date. Python SDK: OpenTradeContext.get_acc_cash_flow."
    )]
    async fn futu_get_acc_cash_flow(
        &self,
        Parameters(req): Parameters<AccCashFlowReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_acc_cash_flow",
            env = %req.env,
            acc_id = req.acc_id,
            market = %req.market,
            date = %req.clearing_date
        );
        let client = self
            .read_client_or_err("futu_get_acc_cash_flow", &req_ctx, None, Some(req.acc_id))
            .await?;
        Self::wrap_result(
            handlers::trade::get_acc_cash_flow(
                &client,
                &req.env,
                req.acc_id,
                &req.market,
                &req.clearing_date,
                req.direction,
            )
            .await,
        )
    }

    /// v1.4.73 BUG-002 fix: MCP alias `futu_get_flow_summary` 指向同 handler。
    ///
    /// external reviewer v1.4.71 验收报告的 AI tester 列此为 P0（"MCP 58 工具无对应 `futu_get_flow_summary`，
    /// 有 `margin_ratio` / `order_fee` 同类查询"）。审查后发现：REST 侧两个
    /// endpoint 并存 `/api/flow-summary` (原) + `/api/acc-cash-flow` (v1.4.51 alias)，
    /// MCP 只有 `futu_get_acc_cash_flow` （v1.4.30 P2 实装）。
    ///
    /// 用户期待 MCP 与 REST `/api/flow-summary` 同名的 tool，这是 UX 对称问题。
    /// 本 alias 保持与主 tool `futu_get_acc_cash_flow` **语义完全一致**，
    /// 参数结构 + handler 调用 + scope 登记全部共享。
    #[tool(
        description = "Alias of futu_get_acc_cash_flow (MCP-REST naming symmetry with /api/flow-summary). Account cash-flow statement for a clearing date. Python SDK: OpenTradeContext.get_acc_cash_flow."
    )]
    async fn futu_get_flow_summary(
        &self,
        Parameters(req): Parameters<AccCashFlowReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        // v1.4.73: alias 下面所有行为等同 futu_get_acc_cash_flow
        tracing::info!(
            tool = "futu_get_flow_summary",
            alias_of = "futu_get_acc_cash_flow",
            env = %req.env,
            acc_id = req.acc_id,
            market = %req.market,
            date = %req.clearing_date
        );
        let client = self
            .read_client_or_err("futu_get_flow_summary", &req_ctx, None, Some(req.acc_id))
            .await?;
        Self::wrap_result(
            handlers::trade::get_acc_cash_flow(
                &client,
                &req.env,
                req.acc_id,
                &req.market,
                &req.clearing_date,
                req.direction,
            )
            .await,
        )
    }

    // ========================================================================
    // v1.4.95 U1 (Tier M MCP): cash log mobile-driven extension tools
    //
    // 来源: v1.4.94 M1 ship 了 REST + gRPC FTAPI, MCP 推迟到 v1.4.95.
    // 比 futu_get_acc_cash_flow 字段更全 (10+ vs 3): 时间范围 / 业务分组 /
    // 货币 / 关键词 / 股票 / 方向 多维过滤 + cursor 分页.
    //
    // gateway handler 与 REST `/api/cash-log` 共用同一实现：从已鉴权账户派生
    // native account/market，并补齐移动端默认分页字段。
    // ========================================================================

    #[tool(
        description = "Fetch detailed account cash log entries with richer filters than futu_get_acc_cash_flow. Native time range, business group / currency / keyword / symbol / direction filters, cursor-based pagination. When max_cnt is omitted the daemon uses the mobile default of 50."
    )]
    async fn futu_get_cash_log(
        &self,
        Parameters(req): Parameters<CashLogReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_cash_log",
            env = %req.env,
            acc_id = req.acc_id,
            market = ?req.market,
            has_keyword = req.keyword.is_some(),
            has_symbol = req.symbol.is_some()
        );
        let client = self
            .read_client_or_err("futu_get_cash_log", &req_ctx, None, Some(req.acc_id))
            .await?;
        Self::wrap_result(
            handlers::trade::get_cash_log(
                &client,
                handlers::trade::CashLogInput {
                    env: &req.env,
                    acc_id: req.acc_id,
                    begin_time: req.begin_time,
                    end_time: req.end_time,
                    biz_group_id: req.biz_group_id,
                    biz_sub_group_id: req.biz_sub_group_id,
                    in_out: req.in_out,
                    keyword: req.keyword,
                    symbol: req.symbol,
                    stock_id: req.stock_id,
                    log_id: req.log_id,
                    max_cnt: req.max_cnt,
                    currency: req.currency,
                },
            )
            .await,
        )
    }

    #[tool(
        description = "Fetch a single cash log entry detail. Use after futu_get_cash_log; log_id comes from monthly_logs[].entries[].log_id."
    )]
    async fn futu_get_cash_detail(
        &self,
        Parameters(req): Parameters<CashDetailReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_cash_detail",
            env = %req.env,
            acc_id = req.acc_id,
            market = ?req.market,
            log_id_len = req.log_id.len()
        );
        let client = self
            .read_client_or_err("futu_get_cash_detail", &req_ctx, None, Some(req.acc_id))
            .await?;
        Self::wrap_result(
            handlers::trade::get_cash_detail(&client, &req.env, req.acc_id, req.log_id.clone())
                .await,
        )
    }

    #[tool(
        description = "Fetch cash log business group, currency, and direction metadata for client UI filters. Returns biz_groups with sub_groups, currencies, and directions."
    )]
    async fn futu_get_biz_group(
        &self,
        Parameters(req): Parameters<BizGroupReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_biz_group",
            env = %req.env,
            acc_id = req.acc_id,
            market = ?req.market
        );
        let client = self
            .read_client_or_err("futu_get_biz_group", &req_ctx, None, Some(req.acc_id))
            .await?;
        Self::wrap_result(handlers::trade::get_biz_group(&client, &req.env, req.acc_id).await)
    }

    // ========================================================================
    // v1.4.95 U2-D Tier M (mobile-driven extension): per-account margin info
    //
    // 与 futu_get_margin_ratio (per-security ratio) 互补: 本 tool 给账户全景.
    // 仅 HK / US / CN_AH 3 市场 (mobile cmd 3101/3102/3107).
    //
    // v1.4.107: risk_user_account_info::MarginInfo 字段号对齐 mobile proto,
    // MCP 投影不再裁剪 backend 已返回字段。
    // ========================================================================

    #[tool(
        description = "Per-account margin info: buying power, leverage, risk status, liquidity, HK margin fields, and mobile risk metadata. Supports HK / US / CN_AH markets (mobile cmd 3101/3102/3107). Complements futu_get_margin_ratio, which is per-security."
    )]
    async fn futu_get_margin_info(
        &self,
        Parameters(req): Parameters<MarginInfoReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_margin_info",
            env = %req.env,
            acc_id = req.acc_id,
            market = %req.market
        );
        let client = self
            .read_client_or_err("futu_get_margin_info", &req_ctx, None, Some(req.acc_id))
            .await?;
        Self::wrap_result(
            handlers::trade::get_margin_info(&client, &req.env, req.acc_id, &req.market).await,
        )
    }

    // ========================================================================
    // v1.4.95 U2-A Tier M (mobile-driven extension): account compliance flag
    //
    // 用户高级交易准入 (期权 / 衍生品 / OTC / CFD 等) 强制要求 flag=1.
    // LLM agent 用此 tool 检查用户合规状态.
    //
    // v1.4.107: MCP schema 只描述可调用契约；内部 verify/来源证据留在 codex 报告。
    // ========================================================================

    #[tool(
        description = "Query account compliance flag (product access, risk disclosure, opt-in status). Common flag_id values: 5=US options, 22=derivatives disclosure, 10=fund KYC R1-R5, 16=PDT, 23=US OTC, 11=HK options. The response includes item_present and flag_value_present so clients can distinguish a missing flag record from an explicit flag_value=0."
    )]
    async fn futu_get_account_flag(
        &self,
        Parameters(req): Parameters<AccountFlagReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_account_flag",
            env = %req.env,
            acc_id = req.acc_id,
            flag_id = req.flag_id
        );
        let client = self
            .read_client_or_err("futu_get_account_flag", &req_ctx, None, Some(req.acc_id))
            .await?;
        Self::wrap_result(
            handlers::trade::get_account_flag(&client, &req.env, req.acc_id, req.flag_id).await,
        )
    }

    // ========================================================================
    // v1.4.95 U2-B Tier M (mobile-driven extension): bond holdings + trade prep
    //
    // 5 endpoint × 5 cmd_id (9373/9374/9375/10043/10057). 仅 HK / US / SG
    // 债券账户有数据.
    //
    // v1.4.107: MCP schema 只描述可调用契约；内部 verify/来源证据留在 codex 报告。
    // ========================================================================

    #[tool(
        description = "Bond account total asset and P&L summary for HK/US/SG bond accounts. Returns total_asset, position_incomes, today_incomes, accrued_interest, and ccy."
    )]
    async fn futu_get_bond_total_asset(
        &self,
        Parameters(req): Parameters<BondAccountReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_bond_total_asset",
            env = %req.env,
            acc_id = req.acc_id,
            market = %req.market
        );
        let client = self
            .read_client_or_err(
                "futu_get_bond_total_asset",
                &req_ctx,
                None,
                Some(req.acc_id),
            )
            .await?;
        Self::wrap_result(
            handlers::trade::get_bond_total_asset(&client, &req.env, req.acc_id, &req.market).await,
        )
    }

    #[tool(
        description = "Single bond position for HK/US/SG bond accounts, including market value, quantity, cost, expiry, dividend schedule, accrued interest, legacy notice fields, notice_list, currency, and price."
    )]
    async fn futu_get_bond_single_asset(
        &self,
        Parameters(req): Parameters<BondSymbolReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_bond_single_asset",
            env = %req.env,
            acc_id = req.acc_id,
            market = %req.market,
            symbol = %req.symbol
        );
        let client = self
            .read_client_or_err(
                "futu_get_bond_single_asset",
                &req_ctx,
                None,
                Some(req.acc_id),
            )
            .await?;
        Self::wrap_result(
            handlers::trade::get_bond_single_asset(
                &client,
                &req.env,
                req.acc_id,
                &req.market,
                &req.symbol,
            )
            .await,
        )
    }

    #[tool(
        description = "Bond account position list for HK/US/SG bond accounts. Returns total and bond_list items with name, symbol, market value, quantity, price, cost, incomes, accrued interest, notice, call flag, and ccy."
    )]
    async fn futu_get_bond_position_list(
        &self,
        Parameters(req): Parameters<BondAccountReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_bond_position_list",
            env = %req.env,
            acc_id = req.acc_id,
            market = %req.market
        );
        let client = self
            .read_client_or_err(
                "futu_get_bond_position_list",
                &req_ctx,
                None,
                Some(req.acc_id),
            )
            .await?;
        Self::wrap_result(
            handlers::trade::get_bond_position_list(&client, &req.env, req.acc_id, &req.market)
                .await,
        )
    }

    #[tool(
        description = "Query whether the user needs to answer a suitability questionnaire before bond trading. Returns need_to_answer plus notice fields such as title, content, and confirm_url."
    )]
    async fn futu_get_bond_answer_state(
        &self,
        Parameters(req): Parameters<BondSymbolReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_bond_answer_state",
            env = %req.env,
            acc_id = req.acc_id,
            market = %req.market,
            symbol = %req.symbol
        );
        let client = self
            .read_client_or_err(
                "futu_get_bond_answer_state",
                &req_ctx,
                None,
                Some(req.acc_id),
            )
            .await?;
        Self::wrap_result(
            handlers::trade::get_bond_answer_state(
                &client,
                &req.env,
                req.acc_id,
                &req.market,
                &req.symbol,
            )
            .await,
        )
    }

    #[tool(
        description = "Bond trade reminders for buy/sell availability, complex product, high risk, and pre-qualification. Returns ReminderItem fields for tradeable, complex_product, high_risk, sell_tradeable, and pre_qualification."
    )]
    async fn futu_get_bond_trade_reminder(
        &self,
        Parameters(req): Parameters<BondSymbolReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_bond_trade_reminder",
            env = %req.env,
            acc_id = req.acc_id,
            market = %req.market,
            symbol = %req.symbol
        );
        let client = self
            .read_client_or_err(
                "futu_get_bond_trade_reminder",
                &req_ctx,
                None,
                Some(req.acc_id),
            )
            .await?;
        Self::wrap_result(
            handlers::trade::get_bond_trade_reminder(
                &client,
                &req.env,
                req.acc_id,
                &req.market,
                &req.symbol,
            )
            .await,
        )
    }
}