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};

use super::FutuServer;

impl FutuServer {
    // ------- 账户（只读） -------

    async fn futu_list_accounts_impl(
        &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,
        )
    }

    async fn futu_get_funds_impl(
        &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,
            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,
        )
    }

    async fn futu_get_positions_impl(
        &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,
            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,
        )
    }

    async fn futu_get_orders_impl(
        &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);
        Self::wrap_result(
            handlers::trade::get_orders(&resolved.client, &req.env, resolved.acc_id, &req.market)
                .await,
        )
    }

    async fn futu_get_deals_impl(
        &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);
        Self::wrap_result(
            handlers::trade::get_deals(&resolved.client, &req.env, resolved.acc_id, &req.market)
                .await,
        )
    }

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

    async fn futu_get_max_trd_qtys_impl(
        &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, 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,
        )
    }

    async fn futu_get_order_fee_impl(
        &self,
        Parameters(req): Parameters<OrderFeeReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_order_fee", market = %req.market, 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,
        )
    }

    async fn futu_get_margin_ratio_impl(
        &self,
        Parameters(req): Parameters<MarginRatioReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_margin_ratio", market = %req.market, 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,
        )
    }

    async fn futu_get_history_orders_impl(
        &self,
        Parameters(req): Parameters<HistoryQueryReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_history_orders", market = %req.market);
        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,
        )
    }

    async fn futu_get_history_deals_impl(
        &self,
        Parameters(req): Parameters<HistoryQueryReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(tool = "futu_get_history_deals", market = %req.market);
        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,
        )
    }

    async fn futu_get_acc_cash_flow_impl(
        &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,
            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 登记全部共享。
    async fn futu_get_flow_summary_impl(
        &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,
            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，并补齐移动端默认分页字段。
    // ========================================================================

    async fn futu_get_cash_log_impl(
        &self,
        Parameters(req): Parameters<CashLogReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_cash_log",
            env = %req.env,
            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,
        )
    }

    async fn futu_get_cash_detail_impl(
        &self,
        Parameters(req): Parameters<CashDetailReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_cash_detail",
            env = %req.env,
            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,
        )
    }

    async fn futu_get_biz_group_impl(
        &self,
        Parameters(req): Parameters<BizGroupReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_biz_group",
            env = %req.env,
            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 已返回字段。
    // ========================================================================

    async fn futu_get_margin_info_impl(
        &self,
        Parameters(req): Parameters<MarginInfoReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_margin_info",
            env = %req.env,
            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 报告。
    // ========================================================================

    async fn futu_get_account_flag_impl(
        &self,
        Parameters(req): Parameters<AccountFlagReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        tracing::info!(
            tool = "futu_get_account_flag",
            env = %req.env,
            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 报告。
    // ========================================================================

    async fn futu_get_bond_total_asset_impl(
        &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,
            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,
        )
    }

    async fn futu_get_bond_single_asset_impl(
        &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,
            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,
        )
    }

    async fn futu_get_bond_position_list_impl(
        &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,
            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,
        )
    }

    async fn futu_get_bond_answer_state_impl(
        &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,
            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,
        )
    }

    async fn futu_get_bond_trade_reminder_impl(
        &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,
            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,
        )
    }
}

include!(concat!(
    env!("OUT_DIR"),
    "/generated_mcp_routes_trade_read.rs"
));