bcs-mcp 0.2.5

package/dist/tools/read.js

@@ -0,0 +1,884 @@
+import { z } from "zod";
+import { API } from "../endpoints.js";
+import { BcsApiError, bcsFetch } from "../client.js";
+import { fetchInstruments, pickPrimaryCard, resolveClassCode, resolveClassCodes } from "../instruments-cache.js";
+import { fail, toMsk, parseDate, daysFromNow, notifyProgress, computeChunks, mapPool, pickList, omit, } from "../helpers.js";
+import { outputParams, deliver, createSafeWriter } from "../output.js";
+import { ok } from "../helpers.js";
+const RO = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+/** API hard limit: at most 1000 bars per candles request; chunks stay below it */
+const CHUNK_BARS = 900;
+const MAX_INLINE_BARS = 1000;
+/** Inline candles walk backwards through at most this many chunks (bounds rate-limit usage) */
+const MAX_INLINE_CHUNKS = 8;
+const MAX_CATALOG_PAGES = 200; // backstop for by-type full dumps (200 × 100 instruments)
+const MAX_SEARCH_PAGES = 500; // backstop for orders/trades full dumps (500 × 100 records)
+const ENRICH_CONCURRENCY = 4;
+/**
+ * /last-trades caps: one request's period ≤ 1 HOUR (400 otherwise) AND the response
+ * ≤ ~4 MB. Both modes therefore fetch hour windows (inline walks backwards from `to`
+ * until `limit` trades are collected); a window is bisected when the 4 MB cap trips.
+ */
+const TRADE_WINDOW_MS = 3_600_000;
+const MIN_TRADE_WINDOW_MS = 5 * 60_000;
+/** /last-trades serves ONLY the current UTC day — window starts must be clamped to 00:00Z */
+const startOfUtcDay = (d) => new Date(Math.floor(d.getTime() / 86_400_000) * 86_400_000);
+const TIMEFRAME_MS = {
+    M1: 60_000,
+    M5: 300_000,
+    M15: 900_000,
+    M30: 1_800_000,
+    H1: 3_600_000,
+    H4: 14_400_000,
+    D: 86_400_000,
+    W: 604_800_000,
+    MN: 2_592_000_000,
+};
+const SIDE_LABELS = { "1": "buy", "2": "sell" };
+// Trading endpoints use 1/2 only; orders/search extends the same scale (docs enum)
+const ORDER_TYPE_LABELS = {
+    "1": "market",
+    "2": "limit",
+    "3": "iceberg",
+    "4": "stop-limit",
+    "5": "take-profit (limit)",
+    "6": "stop-loss",
+    "7": "take-profit & stop-loss",
+    "10": "limit 30 days",
+    "11": "take-profit",
+    "12": "trailing-stop",
+};
+// FIX OrdStatus (the STATUS endpoint relays FIX execution reports: messageType 8, executionType, …)
+const ORDER_STATUS_LABELS = {
+    "0": "new",
+    "1": "partially filled",
+    "2": "filled",
+    "3": "done for day",
+    "4": "cancelled",
+    "5": "replaced",
+    "6": "pending cancel",
+    "7": "stopped",
+    "8": "rejected",
+    "9": "suspended",
+    A: "pending new",
+    C: "expired",
+    E: "pending replace",
+};
+// orders/search has its OWN 3-value scale (docs enum) — NOT the FIX codes above:
+// there "1" means cancelled, not partially filled
+const SEARCH_ORDER_STATUS_LABELS = {
+    "1": "cancelled",
+    "2": "filled",
+    "3": "active",
+};
+const label = (map, v) => map[String(v)] ?? String(v ?? "");
+const BOND_PRICE_NOTE = "Bond prices are quoted in % of face value, not currency.";
+const round2 = (x) => Math.round(x * 100) / 100;
+/**
+ * /trading-schedule/daily-schedule times come as bare UTC "HH:MM:SS" (verified
+ * against the real MOEX schedule) while every other endpoint is +03:00 —
+ * convert to MSK wall time (fixed UTC+3 for current dates).
+ */
+const utcTimeToMsk = (s) => {
+    const m = /^(\d{2}):(\d{2}):(\d{2})$/.exec(String(s ?? ""));
+    if (!m)
+        return String(s ?? "");
+    return `${String((Number(m[1]) + 3) % 24).padStart(2, "0")}:${m[2]}:${m[3]}`;
+};
+/** Is `now` inside [start, end)? All "HH:MM:SS" in one zone; the interval may wrap past midnight */
+const inDayInterval = (now, start, end) => start <= end ? now >= start && now < end : now >= start || now < end;
+// One daily-schedule fetch per board per day: get_trading_schedule serves from it
+// and get_trading_status cross-checks against it without extra API fan-out
+const dayScheduleCache = new Map();
+function fetchDaySchedule(ticker, classCode) {
+    const day = new Date().toISOString().slice(0, 10);
+    const hit = dayScheduleCache.get(classCode);
+    if (hit && hit.day === day)
+        return hit.promise;
+    const promise = bcsFetch(API.information, "/trading-schedule/daily-schedule", {
+        query: { ticker, classCode },
+    });
+    promise.catch(() => dayScheduleCache.delete(classCode)); // failures don't stick
+    dayScheduleCache.set(classCode, { day, promise });
+    return promise;
+}
+async function fetchBars(ticker, classCode, from, to, timeFrame) {
+    const res = await bcsFetch(API.marketData, "/candles-chart", {
+        query: {
+            ticker,
+            classCode,
+            startDate: from.toISOString(),
+            endDate: to.toISOString(),
+            timeFrame,
+        },
+    });
+    // The API returns bars newest-first — normalize to ascending by the raw instant.
+    // Ordering/dedup always uses the raw epoch (_t): localized MSK strings are not
+    // monotonic across historical clock changes and must never be compared.
+    return pickList(res, "bars")
+        .map((b) => ({ ...b, _t: Date.parse(String(b.time ?? "")) }))
+        .sort((a, b) => (a._t ?? 0) - (b._t ?? 0));
+}
+const mapBar = (b) => ({
+    time: toMsk(b.time),
+    open: b.open,
+    close: b.close,
+    high: b.high,
+    low: b.low,
+    volume: b.volume,
+});
+/** Card fields that only add noise for an LLM consumer */
+const NOISY_CARD_KEYS = [
+    "logoLink",
+    "excludeTypeFlags",
+    "excludeTypes",
+    "bcsScoreColor",
+    "displayNameSecond",
+    "cfi",
+    "currencyStepPrice",
+    "businessSectorId",
+    "businessCountryCode",
+    "isBcsProduct",
+];
+const NOISY_POSITION_KEYS = ["logoLink", "scale", "ratioQuantity", "subAccountId", "agreementId"];
+const slimInstrument = (raw) => omit(raw, NOISY_CARD_KEYS);
+export function registerReadTools(server) {
+    server.registerTool("get_portfolio", {
+        title: "Get Portfolio",
+        description: "Portfolio of the account bound to the token: every position (securities, money, metals) with quantity, average/current price, value in RUB/USD/EUR, unrealized and daily P&L, portfolio share, accrued interest for bonds. Includes totals by instrument type. " +
+            "The API reports each position once per settlement term (T0/T1/T2/T365) — by default a single slice is returned and totals cover only it; term=all returns the raw duplicates (totals then count every position several times). csv output writes the positions array.",
+        inputSchema: {
+            term: z
+                .enum(["T0", "T1", "T2", "T365", "all"])
+                .default("T0")
+                .describe("Settlement slice to return (the API duplicates positions per term)"),
+            ...outputParams,
+        },
+        annotations: RO,
+    }, async ({ term, outputPath, outputFormat }) => {
+        try {
+            const res = await bcsFetch(API.portfolio, "/portfolio");
+            const positions = pickList(res, "positions");
+            let slice = term === "all" ? positions : positions.filter((p) => String(p.term ?? "") === term);
+            if (!slice.length && positions.length) {
+                // unknown term labels from the API — fall back to one record per instrument, never ×N totals
+                const seen = new Set();
+                slice = positions.filter((p) => {
+                    const k = `${p.ticker}|${p.board ?? ""}|${p.instrumentType}`;
+                    if (seen.has(k))
+                        return false;
+                    seen.add(k);
+                    return true;
+                });
+            }
+            const value = (p) => (typeof p.currentValueRub === "number" ? p.currentValueRub : 0);
+            const byType = {};
+            let totalRub = 0;
+            for (const p of slice) {
+                totalRub += value(p);
+                const t = String(p.upperType ?? p.instrumentType ?? "OTHER");
+                byType[t] = (byType[t] ?? 0) + value(p);
+            }
+            totalRub = round2(totalRub);
+            for (const k of Object.keys(byType))
+                byType[k] = round2(byType[k]);
+            // The API always sends portfolioShare=0 — compute it WITHIN each term slice
+            // (with term=all the grand total is ×N terms, a share of it would be meaningless)
+            const termTotal = new Map();
+            for (const p of slice) {
+                const k = String(p.term ?? "");
+                termTotal.set(k, (termTotal.get(k) ?? 0) + value(p));
+            }
+            const rows = slice.map((p) => {
+                const tt = termTotal.get(String(p.term ?? "")) ?? 0;
+                return {
+                    ...omit(p, NOISY_POSITION_KEYS),
+                    portfolioShare: tt > 0 ? round2((value(p) / tt) * 100) : 0,
+                };
+            });
+            const account = positions[0]?.account ?? "";
+            const data = { account, term, totalRub, byType, positions: rows };
+            return await deliver(data, rows, { outputPath, outputFormat }, { account, totalRub });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("get_limits", {
+        title: "Get Limits",
+        description: "Account limits: money limits per currency with computed free (= quantity − locked, summarized in freeByCurrency), securities (depo) limits, futures holdings and limits. " +
+            "Note: the API returns a start-of-day snapshot (see loadDate) in a single T365 slice — not intraday. Zero rows are hidden unless includeZero=true.",
+        inputSchema: {
+            includeZero: z.boolean().default(false).describe("Include zero money/depo rows (empty positions)"),
+            ...outputParams,
+        },
+        annotations: RO,
+    }, async ({ includeZero, outputPath, outputFormat }) => {
+        try {
+            const data = await bcsFetch(API.limits, "/limits");
+            const qty = (r) => {
+                const q = r.quantity;
+                return typeof q?.value === "number" ? q.value : 0;
+            };
+            const num = (v) => (typeof v === "number" ? v : 0);
+            const moneyRaw = Array.isArray(data.moneyLimits) ? data.moneyLimits : [];
+            const depoRaw = Array.isArray(data.depoLimit) ? data.depoLimit : [];
+            const money = moneyRaw
+                .map((r) => ({ ...r, free: round2(qty(r) - num(r.locked)) }))
+                .filter((r) => includeZero || qty(r) !== 0 || num(r.locked) !== 0);
+            const depo = depoRaw.filter((r) => includeZero || qty(r) !== 0 || num(r.averagePrice) !== 0);
+            const freeByCurrency = {};
+            for (const r of money) {
+                const c = String(r.currencyCode ?? "?");
+                freeByCurrency[c] = round2((freeByCurrency[c] ?? 0) + r.free);
+            }
+            return await deliver({ ...data, freeByCurrency, moneyLimits: money, depoLimit: depo }, null, { outputPath, outputFormat });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("get_discounts", {
+        title: "Get Instrument Discounts",
+        description: "Margin discount rates per instrument from the marginal-indicators service. The API exposes discountLong only (no short rates), and values are raw BCS coefficients — observed as 1 for every instrument, so verify against the web cabinet before relying on them. Optional tickers filter is applied client-side.",
+        inputSchema: {
+            tickers: z.array(z.string()).optional().describe("Filter to these tickers (uppercase)"),
+            ...outputParams,
+        },
+        annotations: RO,
+    }, async ({ tickers, outputPath, outputFormat }) => {
+        try {
+            const res = await bcsFetch(API.marginal, "/instruments-discounts");
+            let rows = pickList(res, "discounts");
+            if (tickers?.length) {
+                const want = new Set(tickers.map((t) => t.toUpperCase()));
+                rows = rows.filter((r) => want.has(String(r.ticker ?? "").toUpperCase()));
+            }
+            return await deliver(rows, rows, { outputPath, outputFormat });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("find_instrument", {
+        title: "Find Instruments",
+        description: "Instrument cards by tickers (batch) or ISINs: name, type, boards (classCode/exchange — classCode is needed by candles/orders), lot size, ISIN, issuer; for bonds — face value, maturity, coupon rate/frequency, accrued interest; for stocks — dividend yield, sector, EPS growth, credit rating, BCS score. Start here to resolve a ticker before other calls. " +
+            "By default one merged card per instrument is returned (primary board; other listings in otherBoards; off-exchange rows flagged offExchange) — pass allBoards=true for the raw per-board cards.",
+        inputSchema: {
+            tickers: z.array(z.string()).min(1).max(50).optional().describe("Tickers, e.g. [\"SBER\", \"LKOH\"]"),
+            isins: z.array(z.string()).min(1).max(50).optional().describe("ISINs (alternative to tickers)"),
+            allBoards: z
+                .boolean()
+                .default(false)
+                .describe("Return every per-board card instead of one merged card per instrument"),
+            ...outputParams,
+        },
+        annotations: RO,
+    }, async ({ tickers, isins, allBoards, outputPath, outputFormat }) => {
+        try {
+            if (tickers?.length && isins?.length) {
+                return fail(new Error("pass either tickers or isins, not both (results would be ambiguous)"));
+            }
+            if (!tickers?.length && !isins?.length) {
+                return fail(new Error("pass tickers or isins"));
+            }
+            const cards = tickers?.length
+                ? await fetchInstruments(tickers.map((t) => t.toUpperCase()))
+                : pickList(await bcsFetch(API.information, "/instruments/by-isins", {
+                    method: "POST",
+                    body: { isins },
+                }), "instruments");
+            let rows;
+            if (allBoards) {
+                rows = cards.map(slimInstrument);
+            }
+            else {
+                // One card per instrument: analytics (bcsScore, priceChange*) are only
+                // filled on the primary board — the rest degrade to otherBoards
+                const groups = new Map();
+                for (const c of cards) {
+                    const k = String(c.ticker ?? c.isin ?? "?");
+                    const g = groups.get(k);
+                    if (g)
+                        g.push(c);
+                    else
+                        groups.set(k, [c]);
+                }
+                rows = [...groups.values()].map((g) => {
+                    const main = pickPrimaryCard(g) ?? g[0];
+                    const otherBoards = g
+                        .filter((c) => c !== main)
+                        .flatMap((c) => (Array.isArray(c.boards) ? c.boards : []));
+                    const mainBoards = Array.isArray(main.boards) ? main.boards : [];
+                    const offExchange = !mainBoards.some((b) => b.exchange === "MOEX" || b.exchange === "SPB");
+                    return {
+                        ...slimInstrument(main),
+                        ...(otherBoards.length ? { otherBoards } : {}),
+                        ...(offExchange ? { offExchange: true } : {}),
+                    };
+                });
+            }
+            return await deliver(rows, rows, { outputPath, outputFormat });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("get_instruments_by_type", {
+        title: "Get Instruments By Type",
+        description: "Tradable instruments of a type, paginated (page/size, max 100 per page). " +
+            "Pass outputPath to fetch ALL pages into a file; without it a single page is returned inline. " +
+            "baseAssetTicker is required for type=OPTIONS.",
+        inputSchema: {
+            type: z
+                .enum([
+                "CURRENCY",
+                "STOCK",
+                "FOREIGN_STOCK",
+                "BONDS",
+                "NOTES",
+                "DEPOSITARY_RECEIPTS",
+                "EURO_BONDS",
+                "MUTUAL_FUNDS",
+                "ETF",
+                "FUTURES",
+                "OPTIONS",
+                "GOODS",
+                "INDICES",
+            ])
+                .describe("Instrument type"),
+            baseAssetTicker: z.string().optional().describe("Base asset ticker (required for OPTIONS)"),
+            page: z.number().int().min(0).default(0).describe("Page number (ignored with outputPath — all pages are fetched)"),
+            size: z.number().int().min(1).max(100).default(50).describe("Records per page"),
+            ...outputParams,
+        },
+        annotations: RO,
+    }, async ({ type, baseAssetTicker, page, size, outputPath, outputFormat }, extra) => {
+        try {
+            const fetchPage = async (p, s) => pickList(await bcsFetch(API.information, "/instruments/by-type", {
+                query: {
+                    type,
+                    ...(baseAssetTicker ? { baseAssetTicker } : {}),
+                    page: String(p),
+                    size: String(s),
+                },
+            }), "instruments");
+            if (!outputPath) {
+                const items = (await fetchPage(page, size)).map(slimInstrument);
+                return await deliver({ page, count: items.length, has_more: items.length === size, instruments: items }, items, {});
+            }
+            // File mode: walk all pages (a full page means there may be more)
+            const all = [];
+            for (let p = 0; p < MAX_CATALOG_PAGES; p++) {
+                const items = await fetchPage(p, 100);
+                all.push(...items.map(slimInstrument));
+                await notifyProgress(extra, p + 1, undefined, `page ${p + 1}: ${all.length} instruments`);
+                if (items.length < 100)
+                    break;
+            }
+            return await deliver(all, all, { outputPath, outputFormat }, { total: all.length });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("get_trading_schedule", {
+        title: "Get Trading Schedule",
+        description: "Trading sessions of an instrument for the current day: session types with start/end times in MSK (+03:00), sorted. " +
+            "Intervals with tradingSessionStatus=OPEN are the periods when trading is on.",
+        inputSchema: {
+            ticker: z.string().describe("Ticker, e.g. SBER"),
+            classCode: z.string().optional().describe("Board class code (resolved via find_instrument when omitted)"),
+            ...outputParams,
+        },
+        annotations: RO,
+    }, async ({ ticker, classCode, outputPath, outputFormat }) => {
+        try {
+            const t = ticker.toUpperCase();
+            const cc = await resolveClassCode(t, classCode);
+            const data = await fetchDaySchedule(t, cc);
+            const intervals = (Array.isArray(data.dailySchedule) ? data.dailySchedule : [])
+                .map((iv) => ({ ...iv, startDate: utcTimeToMsk(iv.startDate), endDate: utcTimeToMsk(iv.endDate) }))
+                .sort((a, b) => String(a.startDate).localeCompare(String(b.startDate)));
+            const out = {
+                ticker: t,
+                classCode: cc,
+                date: toMsk(new Date()).slice(0, 10),
+                timezone: "+03:00 (Europe/Moscow; the API reports bare UTC times — converted here)",
+                isWorkDay: data.isWorkDay,
+                dailySchedule: intervals,
+            };
+            return await deliver(out, intervals, { outputPath, outputFormat });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("get_trading_status", {
+        title: "Get Trading Status",
+        description: "Current trading session status per instrument: session type, OPEN/CLOSE, time of the next status change. " +
+            "Each row is cross-checked against today's schedule; on mismatch a warning + scheduleSaysNow field is added " +
+            "(the upstream status endpoint has been observed reporting CLOSE during an open evening session).",
+        inputSchema: {
+            tickers: z.array(z.string()).min(1).max(50).describe("Tickers"),
+            classCodes: z
+                .array(z.string())
+                .optional()
+                .describe("Board class codes, same order as tickers (resolved via find_instrument when omitted)"),
+            ...outputParams,
+        },
+        annotations: RO,
+    }, async ({ tickers, classCodes, outputPath, outputFormat }) => {
+        try {
+            const upper = tickers.map((t) => t.toUpperCase());
+            const codes = await resolveClassCodes(upper, classCodes);
+            const rows = await mapPool(upper, ENRICH_CONCURRENCY, async (t, i) => {
+                try {
+                    const s = await bcsFetch(API.information, "/trading-schedule/status", {
+                        query: { ticker: t, classCode: codes[i] },
+                    });
+                    const row = { ticker: t, classCode: codes[i], ...s, nextSessionDate: toMsk(s.nextSessionDate) };
+                    // The status endpoint has been seen lying (CLOSE during the open evening
+                    // session) — cross-check against today's schedule, best-effort
+                    try {
+                        const sched = await fetchDaySchedule(t, codes[i]);
+                        const nowUtc = new Date().toISOString().slice(11, 19);
+                        const openNow = (Array.isArray(sched.dailySchedule) ? sched.dailySchedule : []).some((iv) => String(iv.tradingSessionStatus) === "OPEN" &&
+                            inDayInterval(nowUtc, String(iv.startDate ?? ""), String(iv.endDate ?? "")));
+                        if (openNow !== (String(s.tradingSessionStatus) === "OPEN")) {
+                            row.scheduleSaysNow = openNow ? "OPEN" : "CLOSE";
+                            row.warning =
+                                "status and today's schedule disagree — the status endpoint is known to lag (e.g. evening session); verify with get_order_book";
+                        }
+                    }
+                    catch {
+                        // cross-check only — never fail the status row
+                    }
+                    return row;
+                }
+                catch (e) {
+                    return { ticker: t, error: e instanceof Error ? e.message : String(e) };
+                }
+            });
+            return await deliver(rows, rows, { outputPath, outputFormat });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("get_candles", {
+        title: "Get Candles",
+        description: "OHLCV candles. timeFrame: M1/M5/M15/M30/H1/H4/D/W/MN. The API caps one request at 1000 bars; " +
+            "inline calls return the most recent ~1000 TRADING bars of the range (truncated flag set when the range " +
+            "was not fully covered). Pass outputPath to fetch the FULL period via chunked requests (streamed to disk, " +
+            `deduplicated, with progress). ${BOND_PRICE_NOTE}`,
+        inputSchema: {
+            ticker: z.string().describe("Ticker, e.g. SBER"),
+            classCode: z.string().optional().describe("Board class code (resolved via find_instrument when omitted)"),
+            timeFrame: z.enum(["M1", "M5", "M15", "M30", "H1", "H4", "D", "W", "MN"]).default("D"),
+            from: z.string().optional().describe("Start, ISO 8601 (default: 30 days ago)"),
+            to: z.string().optional().describe("End, ISO 8601 (default: now)"),
+            ...outputParams,
+        },
+        annotations: RO,
+    }, async ({ ticker, classCode, timeFrame, from, to, outputPath, outputFormat }, extra) => {
+        try {
+            const t = ticker.toUpperCase();
+            const cc = await resolveClassCode(t, classCode);
+            const fromD = parseDate(from, daysFromNow(-30));
+            const toD = parseDate(to, new Date());
+            if (fromD >= toD)
+                return fail(new Error("`from` must be before `to`"));
+            const chunks = computeChunks(fromD, toD, CHUNK_BARS * TIMEFRAME_MS[timeFrame]);
+            if (!outputPath) {
+                // Inline: walk chunks backwards (newest first) until enough TRADING bars are
+                // collected — a calendar-time clamp would return nothing after weekends and
+                // needlessly truncate sparse timeframes.
+                let acc = [];
+                let chunksUsed = 0;
+                for (let i = chunks.length - 1; i >= 0 && acc.length < MAX_INLINE_BARS && chunksUsed < MAX_INLINE_CHUNKS; i--) {
+                    const got = await fetchBars(t, cc, chunks[i].from, chunks[i].to, timeFrame);
+                    const headEpoch = acc[0]?._t;
+                    acc = (headEpoch == null ? got : got.filter((b) => (b._t ?? NaN) < headEpoch)).concat(acc);
+                    chunksUsed++;
+                }
+                const truncated = acc.length > MAX_INLINE_BARS || chunksUsed < chunks.length;
+                const bars = acc.slice(-MAX_INLINE_BARS).map(mapBar);
+                return await deliver({
+                    ticker: t,
+                    classCode: cc,
+                    timeFrame,
+                    ...(truncated ? { truncated: true, note: "range not fully covered inline — use outputPath for the full period" } : {}),
+                    bars,
+                }, null, {});
+            }
+            // File mode: stream every chunk to disk — full multi-year histories must not
+            // accumulate in memory. Bars have a fixed schema, so csv columns are static.
+            const format = outputFormat ?? (outputPath.endsWith(".csv") ? "csv" : "json");
+            const writer = await createSafeWriter(outputPath);
+            const sample = [];
+            let records = 0;
+            let lastEpoch = -Infinity;
+            try {
+                if (format === "csv")
+                    await writer.write("time,open,close,high,low,volume\n");
+                else
+                    await writer.write(`{"ticker":${JSON.stringify(t)},"classCode":${JSON.stringify(cc)},"timeFrame":${JSON.stringify(timeFrame)},"bars":[`);
+                for (let i = 0; i < chunks.length; i++) {
+                    const got = await fetchBars(t, cc, chunks[i].from, chunks[i].to, timeFrame);
+                    for (const b of got) {
+                        const epoch = b._t ?? NaN;
+                        if (epoch <= lastEpoch)
+                            continue; // chunk borders overlap — dedupe by the raw instant
+                        const row = mapBar(b);
+                        if (sample.length < 2)
+                            sample.push(row);
+                        if (format === "csv") {
+                            await writer.write(`${row.time},${b.open ?? ""},${b.close ?? ""},${b.high ?? ""},${b.low ?? ""},${b.volume ?? ""}\n`);
+                        }
+                        else {
+                            await writer.write(`${records ? "," : ""}${JSON.stringify(row)}`);
+                        }
+                        records++;
+                        if (!Number.isNaN(epoch))
+                            lastEpoch = epoch;
+                    }
+                    await notifyProgress(extra, i + 1, chunks.length, `chunk ${i + 1}/${chunks.length}: ${records} bars`);
+                }
+                if (format === "json")
+                    await writer.write("]}\n");
+                const bytes = await writer.close();
+                return ok({ savedTo: writer.savedTo, format, records, sample, bytes, ticker: t, timeFrame });
+            }
+            catch (e) {
+                await writer.close();
+                await writer.remove();
+                throw e;
+            }
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("get_quotes", {
+        title: "Get Quotes",
+        description: "Real-time quotes for up to 100 instruments: bid/offer, last price, day open/close/high/low, change. " +
+            `classCode is resolved via find_instrument when omitted. ${BOND_PRICE_NOTE} ` +
+            "Note: your own positions already carry currentPrice in get_portfolio.",
+        inputSchema: {
+            tickers: z.array(z.string()).min(1).max(100).describe("Tickers, e.g. [\"SBER\", \"LKOH\"]"),
+            classCodes: z
+                .array(z.string())
+                .optional()
+                .describe("Board class codes, same order as tickers; missing entries are resolved automatically"),
+            ...outputParams,
+        },
+        annotations: RO,
+    }, async ({ tickers, classCodes, outputPath, outputFormat }) => {
+        try {
+            const upper = tickers.map((t) => t.toUpperCase());
+            // Per-index fallback: an explicit code is used where given, the rest are
+            // batch-resolved (one by-tickers request per 50, not N single requests)
+            const codes = await resolveClassCodes(upper, classCodes);
+            const instruments = upper.map((ticker, i) => ({ ticker, classCode: codes[i] }));
+            const res = await bcsFetch(API.marketData, "/quotes", {
+                method: "POST",
+                body: { instruments },
+            });
+            const rows = pickList(res, "records").map((q) => ({ ...q, dateTime: toMsk(q.dateTime) }));
+            return await deliver(rows, rows, { outputPath, outputFormat });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("get_order_book", {
+        title: "Get Order Book",
+        description: "Order book (L2 depth of market) for one instrument: bids/asks with prices and quantities, total volumes. " +
+            `${BOND_PRICE_NOTE} Outside the trading session the API may report 404 "no data".`,
+        inputSchema: {
+            ticker: z.string().describe("Ticker, e.g. SBER"),
+            classCode: z.string().optional().describe("Board class code (resolved via find_instrument when omitted)"),
+            ...outputParams,
+        },
+        annotations: RO,
+    }, async ({ ticker, classCode, outputPath, outputFormat }) => {
+        try {
+            const t = ticker.toUpperCase();
+            const cc = await resolveClassCode(t, classCode);
+            const data = await bcsFetch(API.marketData, "/order-book", {
+                query: { ticker: t, classCode: cc },
+            });
+            return await deliver({ ...data, dateTime: toMsk(data.dateTime) }, null, { outputPath, outputFormat });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("get_recent_trades", {
+        title: "Get Recent Trades",
+        description: "Anonymized recent trades feed for one instrument: time, side, price, quantity, volume. " +
+            "Returns the newest `limit` trades, fetched hour-by-hour backwards from `to` (the BCS backend caps one request at a 1-hour period and ~4 MB response). " +
+            "Optional from/to select an explicit window. " +
+            "IMPORTANT: the API serves trades of the CURRENT UTC DAY only (from 00:00 UTC = 03:00 MSK) — earlier window starts are clamped, yesterday is unavailable. " +
+            "Records carry no trade id: identical rows within the same second are genuine distinct trades, not duplicates. " +
+            `Pass outputPath to dump a period (default: the whole current UTC day) to a file via hour-by-hour windows. ${BOND_PRICE_NOTE}`,
+        inputSchema: {
+            ticker: z.string().describe("Ticker, e.g. SBER"),
+            classCode: z.string().optional().describe("Board class code (resolved via find_instrument when omitted)"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(10_000)
+                .default(200)
+                .describe("Max trades returned inline, newest first (ignored with outputPath — the whole period is written)"),
+            from: z.string().optional().describe("Start of period, ISO 8601 (default: auto-widening recent window inline / start of the current UTC day with outputPath); clamped to 00:00 UTC of the current day — the API keeps no older trades"),
+            to: z.string().optional().describe("End of period, ISO 8601 (default: now)"),
+            ...outputParams,
+        },
+        annotations: RO,
+    }, async ({ ticker, classCode, limit, from, to, outputPath, outputFormat }, extra) => {
+        try {
+            const t = ticker.toUpperCase();
+            const cc = await resolveClassCode(t, classCode);
+            const fetchWindow = async (fromD, toD) => {
+                const res = await bcsFetch(API.marketData, "/last-trades", {
+                    method: "POST",
+                    body: { ticker: t, classCode: cc, startDateTime: fromD.toISOString(), endDateTime: toD.toISOString() },
+                });
+                const lo = fromD.getTime();
+                const hi = toD.getTime();
+                // window bound semantics are undocumented — enforce [from, to) client-side
+                // so adjacent windows never duplicate or drop boundary trades
+                return pickList(res, "records")
+                    .map((r) => ({ ...r, _t: Date.parse(String(r.dateTime ?? "")) }))
+                    .filter((r) => !Number.isNaN(r._t) && r._t >= lo && r._t < hi);
+            };
+            const mapRow = ({ _t, ...r }) => ({
+                ...r,
+                side: label(SIDE_LABELS, r.side),
+                dateTime: toMsk(r.dateTime),
+            });
+            // Fetch [lo, hi) into sink; callers keep hi−lo ≤ 1 hour (the period cap),
+            // bisection handles the rarer ~4 MB response cap
+            const fetchChunked = async (lo, hi, sink) => {
+                try {
+                    sink.push(...(await fetchWindow(new Date(lo), new Date(hi))));
+                }
+                catch (e) {
+                    if (e instanceof BcsApiError && e.kind === "too-large" && hi - lo > MIN_TRADE_WINDOW_MS) {
+                        const mid = Math.floor((lo + hi) / 2);
+                        await fetchChunked(lo, mid, sink);
+                        await fetchChunked(mid, hi, sink);
+                        return;
+                    }
+                    throw e;
+                }
+            };
+            const toD = parseDate(to, new Date());
+            const dayStart = startOfUtcDay(new Date());
+            if (toD <= dayStart) {
+                return fail(new Error(`the API keeps trades of the current UTC day only (from ${dayStart.toISOString()}) — the requested window ends before that`));
+            }
+            const CLAMP_NOTE = "window start clamped to 00:00 UTC — the API keeps no older trades";
+            // Both modes honor the clamp; the requested `from` defaults differ
+            const requested = parseDate(from, dayStart); // default: the whole current UTC day
+            const clamped = Boolean(from) && requested < dayStart;
+            const fromD = requested < dayStart ? dayStart : requested;
+            if (fromD >= toD)
+                return fail(new Error("`from` must be before `to`"));
+            if (!outputPath) {
+                // Walk hour windows backwards from `to`, stop once `limit` trades are collected
+                const feed = [];
+                let cursor = toD.getTime();
+                const floor = fromD.getTime();
+                while (cursor > floor && feed.length < limit) {
+                    const lo = Math.max(cursor - TRADE_WINDOW_MS, floor);
+                    await fetchChunked(lo, cursor, feed);
+                    cursor = lo;
+                }
+                // stopped early with an explicit `from` — flag that windowFrom is the COVERED start
+                const partial = cursor > floor && Boolean(from);
+                feed.sort((a, b) => b._t - a._t); // newest first
+                const rows = feed.slice(0, limit).map(mapRow);
+                return await deliver({
+                    ticker: t,
+                    classCode: cc,
+                    windowFrom: toMsk(new Date(cursor)),
+                    windowTo: toMsk(toD),
+                    ...(clamped ? { note: CLAMP_NOTE } : {}),
+                    ...(partial ? { coverage: "stopped after collecting `limit` trades — windowFrom is the covered start, not the requested one" } : {}),
+                    feedTotal: feed.length,
+                    trades: rows,
+                }, rows, {});
+            }
+            // File mode: hour windows over the whole period, chronological file
+            const all = [];
+            const windows = computeChunks(fromD, toD, TRADE_WINDOW_MS);
+            for (let i = 0; i < windows.length; i++) {
+                const got = [];
+                await fetchChunked(windows[i].from.getTime(), windows[i].to.getTime(), got);
+                got.sort((a, b) => a._t - b._t);
+                all.push(...got.map(mapRow));
+                await notifyProgress(extra, i + 1, windows.length, `window ${i + 1}/${windows.length}: ${all.length} trades`);
+            }
+            return await deliver(all, all, { outputPath, outputFormat }, {
+                windowFrom: toMsk(fromD),
+                windowTo: toMsk(toD),
+                ...(clamped ? { note: CLAMP_NOTE } : {}),
+            });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    // ─── Orders / trades search (one factory — the two tools must never drift apart) ───
+    const SEARCH_404_HINT = "no records matched — note the search endpoints only hold data since 2026-01-26; widen or drop the date/ticker filters.";
+    const registerSearchTool = (spec) => {
+        server.registerTool(spec.name, {
+            title: spec.title,
+            description: spec.description,
+            inputSchema: {
+                page: z.number().int().min(0).default(0).describe("Page number, from 0 (ignored with outputPath — all pages are fetched)"),
+                size: z.number().int().min(1).max(100).default(50).describe("Records per page"),
+                from: z.string().optional().describe("Filter: start of period, ISO 8601"),
+                to: z.string().optional().describe("Filter: end of period, ISO 8601"),
+                tickers: z.array(z.string()).optional().describe("Filter by tickers"),
+                ...outputParams,
+            },
+            annotations: RO,
+        }, async ({ page, size, from, to, tickers, outputPath, outputFormat }, extra) => {
+            try {
+                const body = {
+                    ...(from ? { startDateTime: parseDate(from, new Date()).toISOString() } : {}),
+                    ...(to ? { endDateTime: parseDate(to, new Date()).toISOString() } : {}),
+                    ...(tickers?.length ? { tickers: tickers.map((t) => t.toUpperCase()) } : {}),
+                };
+                const fetchPage = (p, s) => bcsFetch(spec.base, spec.path, {
+                    method: "POST",
+                    query: { page: String(p), size: String(s) },
+                    body,
+                });
+                if (!outputPath) {
+                    const res = await fetchPage(page, size);
+                    const rows = (res.records ?? []).map(spec.mapRow);
+                    return await deliver({ page, totalPages: res.totalPages, totalRecords: res.totalRecords, [spec.resultKey]: rows }, rows, { outputPath, outputFormat }, { totalRecords: res.totalRecords });
+                }
+                // File mode: walk ALL pages, like every other outputPath tool
+                const all = [];
+                let totalRecords;
+                for (let p = 0; p < MAX_SEARCH_PAGES; p++) {
+                    const res = await fetchPage(p, 100);
+                    const rows = res.records ?? [];
+                    all.push(...rows.map(spec.mapRow));
+                    totalRecords = res.totalRecords ?? totalRecords;
+                    await notifyProgress(extra, p + 1, res.totalPages, `page ${p + 1}: ${all.length} records`);
+                    if (rows.length < 100 || (res.totalPages != null && p + 1 >= res.totalPages))
+                        break;
+                }
+                return await deliver(all, all, { outputPath, outputFormat }, { totalRecords });
+            }
+            catch (e) {
+                return fail(e, { 404: SEARCH_404_HINT });
+            }
+        });
+    };
+    // For get_order_status (FIX status scale)
+    const mapOrderRow = (o) => ({
+        ...o,
+        side: label(SIDE_LABELS, o.side),
+        orderType: label(ORDER_TYPE_LABELS, o.orderType),
+        ...(o.orderStatus != null ? { orderStatus: label(ORDER_STATUS_LABELS, o.orderStatus) } : {}),
+        orderDateTime: toMsk(o.orderDateTime),
+        updateDateTime: toMsk(o.updateDateTime),
+    });
+    // For get_orders rows (search status scale; executionDateTime comes in UTC unlike its siblings)
+    const mapSearchOrderRow = (o) => ({
+        ...o,
+        side: label(SIDE_LABELS, o.side),
+        orderType: label(ORDER_TYPE_LABELS, o.orderType),
+        orderStatus: label(SEARCH_ORDER_STATUS_LABELS, o.orderStatus),
+        orderDateTime: toMsk(o.orderDateTime),
+        updateDateTime: toMsk(o.updateDateTime),
+        ...(o.executionDateTime ? { executionDateTime: toMsk(o.executionDateTime) } : {}),
+    });
+    registerSearchTool({
+        name: "get_orders",
+        title: "Search Orders",
+        description: "Your orders on the account (data since 2026-01-26): ticker, side, type, quantity/filled, price, orderStatus (cancelled/filled/active), timestamps. " +
+            "Paginated (page/size), optional date and ticker filters; with outputPath ALL pages are dumped to a file. " +
+            "Orders rejected before reaching the exchange do NOT appear here — check them via get_order_status by client UUID.",
+        base: API.orderDetails,
+        path: "/orders/search",
+        resultKey: "orders",
+        mapRow: mapSearchOrderRow,
+    });
+    registerSearchTool({
+        name: "get_trades",
+        title: "Search Trades",
+        description: "Your executed trades on the account (data since 2026-01-26): ticker, side, quantity, price, volume, trade time (tradeDateTime, MSK). " +
+            "Paginated (page/size), optional date and ticker filters; with outputPath ALL pages are dumped to a file. " +
+            "Note: trades only — cash operations (dividends received, fees, deposits) are not available in BCS Trade API.",
+        base: API.tradeDetails,
+        path: "/trades/search",
+        resultKey: "trades",
+        // executionDateTime comes back always-empty from the API — drop it, tradeDateTime is the real time
+        mapRow: ({ executionDateTime, ...d }) => ({
+            ...d,
+            side: label(SIDE_LABELS, d.side),
+            tradeDateTime: toMsk(d.tradeDateTime),
+            ...(typeof d.volume === "number" ? { volume: round2(d.volume) } : {}),
+            ...(executionDateTime ? { executionDateTime: toMsk(executionDateTime) } : {}),
+        }),
+    });
+    server.registerTool("get_order_status", {
+        title: "Get Order Status",
+        description: "Status of one order by ID. orderIdType 1 = client UUID (from place_order), 2 = exchange order number in the form YYMMDD-CLASSCODE-NUMBER with a 6-digit date (e.g. 260501-TQBR-79628540663).",
+        inputSchema: {
+            orderId: z.string().describe("Order ID"),
+            orderIdType: z.enum(["1", "2"]).default("1").describe("1 — client UUID, 2 — exchange order number"),
+            ...outputParams,
+        },
+        annotations: RO,
+    }, async ({ orderId, orderIdType, outputPath, outputFormat }) => {
+        try {
+            const o = await bcsFetch(API.operations, "/orders", {
+                query: { orderIdType, orderId },
+            });
+            // Real responses nest the execution report: {clientOrderId, originalClientOrderId, data:{side, orderType, orderStatus, transactionTime, …}}
+            const data = o?.data && typeof o.data === "object" ? o.data : null;
+            const mapped = data
+                ? {
+                    ...o,
+                    data: {
+                        ...data,
+                        side: label(SIDE_LABELS, data.side),
+                        orderType: label(ORDER_TYPE_LABELS, data.orderType),
+                        orderStatus: label(ORDER_STATUS_LABELS, data.orderStatus),
+                        transactionTime: toMsk(data.transactionTime),
+                    },
+                }
+                : mapOrderRow(o ?? {});
+            return await deliver(mapped, null, { outputPath, outputFormat });
+        }
+        catch (e) {
+            return fail(e, { 404: "order not found — check orderId and orderIdType (1 = client UUID, 2 = exchange number YYMMDD-CLASS-NUM)" });
+        }
+    });
+}
+/** Order row decorated for humans — shared with get_order_status via trading confirm context */
+export function describeOrderRow(o) {
+    // GET /orders nests the execution report under `data`; older shapes were flat
+    const d = (o.data && typeof o.data === "object" ? o.data : o);
+    const side = label(SIDE_LABELS, d.side);
+    const type = label(ORDER_TYPE_LABELS, d.orderType);
+    const qty = d.orderQuantity ?? d.quantity ?? "?";
+    return `${d.ticker ?? "?"} ${side} ${type} ${qty} шт.${d.price != null ? ` @ ${d.price}` : ""}`;
+}
+//# sourceMappingURL=read.js.map