bitbank-lab-mcp 0.1.0

package/tools/get_tickers_jpy.ts

@@ -0,0 +1,240 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { TtlCache } from '../lib/cache.js';
+import { toNum } from '../lib/conversions.js';
+import { nowIso } from '../lib/datetime.js';
+import { getErrorMessage } from '../lib/error.js';
+import { BITBANK_API_BASE } from '../lib/http.js';
+import { fail, ok } from '../lib/result.js';
+import { ALLOWED_PAIRS } from '../lib/validate.js';
+import { GetTickersJpyOutputSchema } from '../src/schemas.js';
+
+type Item = {
+	pair: string;
+	sell: string;
+	buy: string;
+	high: string;
+	low: string;
+	open: string;
+	last: string;
+	vol: string;
+	timestamp: number;
+};
+
+// テキスト summary にティッカー全件を含める（LLM が structuredContent.data を読めない対策）
+function buildTickerText(
+	baseSummary: string,
+	data: Array<Item & { change24h?: number | null; change24hPct?: number | null }>,
+): string {
+	const lines = data.map((t, i) => {
+		const chg = t.change24hPct != null ? ` chg:${t.change24hPct >= 0 ? '+' : ''}${t.change24hPct}%` : '';
+		return `[${i}] ${t.pair} last:${t.last} high:${t.high} low:${t.low} vol:${t.vol}${chg}`;
+	});
+	return (
+		baseSummary +
+		`\n\n📋 全${data.length}件のティッカー:\n` +
+		lines.join('\n') +
+		`\n\n---\n📌 含まれるもの: 現時点のスナップショット（last/high/low/vol/bid/ask/24h変動率）` +
+		`\n📌 含まれないもの: 価格の時系列推移、板の深度、個別約定履歴、テクニカル指標` +
+		`\n📌 補完ツール: get_candles（時系列OHLCV）, get_orderbook（板情報）, get_transactions（約定履歴）, analyze_indicators（指標）`
+	);
+}
+
+const CACHE_KEY = 'tickers_jpy';
+const tickerCache = new TtlCache<Item[]>({ ttlMs: 10_000, maxEntries: 1 });
+
+// === Auto mode (official pairs sync) ===
+let dynamicPairs: Set<string> | null = null;
+let dynamicPairsFetchedAt = 0;
+const PAIRS_TTL_MS = Number(process.env.BITBANK_PAIRS_TTL_MS ?? 15 * 60 * 1000); // 15min
+type PairsMode = 'strict' | 'auto' | 'off';
+function getPairsMode(): PairsMode {
+	// Back-compat: BITBANK_STRICT_PAIRS=0 → off
+	const strictEnv = String(process.env.BITBANK_STRICT_PAIRS ?? '1');
+	if (strictEnv === '0') return 'off';
+	const mode = String(process.env.BITBANK_PAIRS_MODE || 'strict').toLowerCase();
+	if (mode === 'auto') return 'auto';
+	if (mode === 'off') return 'off';
+	return 'strict';
+}
+async function fetchOfficialJpyPairs(timeoutMs: number, retries: number, retryWaitMs: number): Promise<Set<string>> {
+	const officialUrl = `${BITBANK_API_BASE}/tickers_jpy`;
+	let lastErr: unknown;
+	for (let i = 0; i <= retries; i++) {
+		const ctrl = new AbortController();
+		const t = setTimeout(() => ctrl.abort(), timeoutMs);
+		try {
+			const res = await fetch(officialUrl, { signal: ctrl.signal });
+			clearTimeout(t);
+			if (!res.ok) throw new Error(`HTTP ${res.status}`);
+			const raw = (await res.json()) as { success?: number; data?: Array<Record<string, unknown>> };
+			if (!raw || raw.success !== 1 || !Array.isArray(raw.data)) throw new Error('bad payload');
+			const set = new Set<string>();
+			for (const it of raw.data) {
+				const p = String(it?.pair || '').toLowerCase();
+				if (p.endsWith('_jpy')) set.add(p);
+			}
+			return set;
+		} catch (e: unknown) {
+			clearTimeout(t);
+			lastErr = e;
+			if (i < retries) await new Promise((r) => setTimeout(r, retryWaitMs));
+		}
+	}
+	throw lastErr ?? new Error('pairs fetch failed');
+}
+async function getFilterSet(
+	timeoutMs: number,
+	retries: number,
+	retryWaitMs: number,
+): Promise<{ mode: PairsMode; set: Set<string> | null; source: 'dynamic' | 'static' | 'off' }> {
+	const mode = getPairsMode();
+	if (mode === 'off') return { mode, set: null, source: 'off' };
+	if (mode === 'strict') return { mode, set: ALLOWED_PAIRS as Set<string>, source: 'static' };
+	// auto
+	const now = Date.now();
+	const stillFresh = dynamicPairs && now - dynamicPairsFetchedAt < PAIRS_TTL_MS;
+	if (!stillFresh) {
+		try {
+			dynamicPairs = await fetchOfficialJpyPairs(timeoutMs, retries, retryWaitMs);
+			dynamicPairsFetchedAt = now;
+		} catch {
+			// keep previous dynamic or fall back to static
+			if (!dynamicPairs || dynamicPairs.size === 0) {
+				return { mode, set: ALLOWED_PAIRS as Set<string>, source: 'static' };
+			}
+		}
+	}
+	return { mode, set: dynamicPairs!, source: 'dynamic' };
+}
+async function filterByMode(
+	items: Item[],
+	timeoutMs: number,
+	retries: number,
+	retryWaitMs: number,
+): Promise<{ data: Item[]; filterInfo: { mode: PairsMode; source: 'dynamic' | 'static' | 'off'; setSize: number } }> {
+	const { mode, set, source } = await getFilterSet(timeoutMs, retries, retryWaitMs);
+	if (!set) return { data: items, filterInfo: { mode, source, setSize: 0 } };
+	const out = items.filter((it) => set.has(String(it.pair).toLowerCase()));
+	return { data: out, filterInfo: { mode, source, setSize: set.size } };
+}
+
+export default async function getTickersJpy(opts?: { bypassCache?: boolean }) {
+	if (!opts?.bypassCache) {
+		const cached = tickerCache.get(CACHE_KEY);
+		if (cached) {
+			return GetTickersJpyOutputSchema.parse(
+				ok(buildTickerText('tickers_jpy (cache)', cached), cached, {
+					cache: { hit: true, key: CACHE_KEY },
+					ts: nowIso(),
+				}),
+			);
+		}
+	}
+
+	const url = String(process.env.TICKERS_JPY_URL || `${BITBANK_API_BASE}/tickers_jpy`);
+	const timeoutMs = Number(process.env.TICKERS_JPY_TIMEOUT_MS ?? 2000);
+	const retries = Number(process.env.TICKERS_JPY_RETRIES ?? 1);
+	const retryWaitMs = Number(process.env.TICKERS_JPY_RETRY_WAIT_MS ?? 500);
+	const t0 = Date.now();
+	try {
+		// テスト用: about:timeout を指定すると擬似タイムアウト
+		if (url === 'about:timeout') {
+			await new Promise((r) => setTimeout(r, Math.min(timeoutMs + 10, 1000)));
+			throw new Error('AbortError: simulated timeout');
+		}
+
+		// テスト用: file:// を指定するとローカルJSONを読み込む
+		if (url.startsWith('file://')) {
+			const filePath = url.replace('file://', '');
+			const abs = path.isAbsolute(filePath) ? filePath : path.join(process.cwd(), filePath);
+			const buf = fs.readFileSync(abs, 'utf8');
+			const raw = JSON.parse(buf);
+			if (!raw || raw.success !== 1 || !Array.isArray(raw.data)) {
+				return GetTickersJpyOutputSchema.parse(
+					fail('UPSTREAM_ERROR: unexpected response from bitbank API', 'upstream'),
+				);
+			}
+			const dataRaw: Item[] = raw.data as Item[];
+			const { data: filtered, filterInfo } = await filterByMode(dataRaw, timeoutMs, retries, retryWaitMs);
+			// 24h変動率を open/last から算出（%）
+			const data = filtered.map((it) => {
+				const openN = toNum(it.open);
+				const lastN = toNum(it.last);
+				const change =
+					openN != null && openN > 0 && lastN != null ? Number((((lastN - openN) / openN) * 100).toFixed(2)) : null;
+				return { ...it, change24h: change, change24hPct: change };
+			});
+			tickerCache.set(CACHE_KEY, data);
+			const ms = Date.now() - t0;
+			const payloadBytes = Buffer.byteLength(JSON.stringify(dataRaw));
+			const summaryText = buildTickerText(
+				`tickers_jpy fetched in ${ms}ms (${data.length}/${dataRaw.length} items after filter, ${payloadBytes} bytes raw, mode=${filterInfo.mode}/${filterInfo.source})`,
+				data,
+			);
+			return GetTickersJpyOutputSchema.parse(
+				ok(summaryText, data, { cache: { hit: false, key: 'tickers_jpy' }, ts: nowIso(), latencyMs: ms, payloadBytes }),
+			);
+		}
+
+		// 固定バックオフでの簡易リトライ
+		let lastErr: unknown;
+		let raw: { success?: number; data?: Item[] } | undefined;
+		for (let i = 0; i <= retries; i++) {
+			const ctrl = new AbortController();
+			const t = setTimeout(() => ctrl.abort(), timeoutMs);
+			try {
+				const res = await fetch(url, { signal: ctrl.signal });
+				clearTimeout(t);
+				if (!res.ok) throw new Error(`HTTP ${res.status}`);
+				raw = (await res.json()) as { success?: number; data?: Item[] };
+				break;
+			} catch (e: unknown) {
+				clearTimeout(t);
+				lastErr = e;
+				if (i < retries) await new Promise((r) => setTimeout(r, retryWaitMs));
+			}
+		}
+		if (!raw) throw lastErr ?? new Error('no response');
+		if (!raw || raw.success !== 1 || !Array.isArray(raw.data)) {
+			return GetTickersJpyOutputSchema.parse(fail('UPSTREAM_ERROR: unexpected response from bitbank API', 'upstream'));
+		}
+		const dataRaw: Item[] = raw.data as Item[];
+		const { data: filtered, filterInfo } = await filterByMode(dataRaw, timeoutMs, retries, retryWaitMs);
+		const data = filtered.map((it) => {
+			const openN = toNum(it.open);
+			const lastN = toNum(it.last);
+			const change =
+				openN != null && openN > 0 && lastN != null ? Number((((lastN - openN) / openN) * 100).toFixed(2)) : null;
+			return { ...it, change24h: change, change24hPct: change };
+		});
+		tickerCache.set(CACHE_KEY, data);
+		const ms = Date.now() - t0;
+		const payloadBytes = Buffer.byteLength(JSON.stringify(dataRaw));
+		// ロギングはサーバ側集約。ここではsummaryに最小指標を含める
+		const summaryTextHttp = buildTickerText(
+			`tickers_jpy fetched in ${ms}ms (${data.length}/${dataRaw.length} items after filter, ${payloadBytes} bytes raw, mode=${filterInfo.mode}/${filterInfo.source})`,
+			data,
+		);
+		return GetTickersJpyOutputSchema.parse(
+			ok(summaryTextHttp, data, {
+				cache: { hit: false, key: 'tickers_jpy' },
+				ts: nowIso(),
+				latencyMs: ms,
+				payloadBytes,
+				filtered: true,
+			}),
+		);
+	} catch (e: unknown) {
+		const msg = getErrorMessage(e) || 'network error';
+		const isTimeout =
+			msg.includes('AbortError') ||
+			msg.includes('timeout') ||
+			msg.includes('fetch failed') ||
+			msg.includes('ECONNREFUSED') ||
+			msg.includes('ENOTFOUND');
+		return GetTickersJpyOutputSchema.parse(
+			fail(isTimeout ? `TIMEOUT_OR_NETWORK` : `UPSTREAM_${msg}`, isTimeout ? 'timeout' : 'upstream'),
+		);
+	}
+}

package/tools/get_transactions.ts

@@ -0,0 +1,209 @@
+import type { z } from 'zod';
+import { toNum } from '../lib/conversions.js';
+import { dayjs, toIsoMs } from '../lib/datetime.js';
+import { formatPair, formatPrice } from '../lib/formatter.js';
+import { BITBANK_API_BASE, DEFAULT_RETRIES, fetchJsonWithRateLimit } from '../lib/http.js';
+import { failFromError, failFromValidation, ok } from '../lib/result.js';
+import { createMeta, ensurePair, validateLimit } from '../lib/validate.js';
+import {
+	type GetTransactionsDataSchemaOut,
+	GetTransactionsInputSchema,
+	type GetTransactionsMetaSchemaOut,
+	GetTransactionsOutputSchema,
+} from '../src/schemas.js';
+import type { ToolDefinition } from '../src/tool-definition.js';
+
+type TxnRaw = Record<string, unknown>;
+
+function toMs(input: unknown): number | null {
+	const n = toNum(input);
+	if (n == null) return null;
+	return n < 1e12 ? Math.floor(n * 1000) : Math.floor(n);
+}
+
+function normalizeSide(v: unknown): 'buy' | 'sell' | null {
+	const s = String(v ?? '')
+		.trim()
+		.toLowerCase();
+	if (s === 'buy') return 'buy';
+	if (s === 'sell') return 'sell';
+	return null;
+}
+
+type NormalizedTxn = { price: number; amount: number; side: 'buy' | 'sell'; timestampMs: number; isoTime: string };
+
+/**
+ * 取引サマリを生成
+ */
+function formatTransactionsSummary(pair: string, transactions: NormalizedTxn[], buys: number, sells: number): string {
+	const pairDisplay = formatPair(pair);
+	const _isJpy = pair.toLowerCase().includes('jpy');
+	const baseCurrency = pair.split('_')[0]?.toUpperCase() ?? '';
+	const lines: string[] = [];
+
+	const fmtPx = (price: number) => formatPrice(price, pair);
+
+	const formatTime = (ms: number): string => {
+		return dayjs(ms).tz('Asia/Tokyo').format('HH:mm:ss');
+	};
+
+	lines.push(`${pairDisplay} 直近取引 ${transactions.length}件`);
+
+	if (transactions.length > 0) {
+		const latestTxn = transactions[transactions.length - 1];
+		lines.push(`最新約定: ${fmtPx(latestTxn.price)}`);
+
+		// 買い/売り比率
+		const total = buys + sells;
+		const buyRatio = total > 0 ? Math.round((buys / total) * 100) : 0;
+		const sellRatio = 100 - buyRatio;
+		const dominant = buyRatio >= 60 ? '買い優勢' : buyRatio <= 40 ? '売り優勢' : '拮抗';
+		const dominantRatio = buyRatio >= 60 ? buyRatio : buyRatio <= 40 ? sellRatio : buyRatio;
+		lines.push(`買い: ${buys}件 / 売り: ${sells}件（${dominant} ${dominantRatio}%）`);
+
+		// 出来高合計
+		const totalVolume = transactions.reduce((sum, t) => sum + t.amount, 0);
+		const volStr = totalVolume >= 1 ? totalVolume.toFixed(4) : totalVolume.toFixed(6);
+		lines.push(`出来高: ${volStr} ${baseCurrency}`);
+
+		// 期間
+		const oldest = transactions[0];
+		const newest = transactions[transactions.length - 1];
+		lines.push(`期間: ${formatTime(oldest.timestampMs)}〜${formatTime(newest.timestampMs)}`);
+	}
+
+	return lines.join('\n');
+}
+
+export default async function getTransactions(pair: string = 'btc_jpy', limit: number = 60, date?: string) {
+	const chk = ensurePair(pair);
+	if (!chk.ok) return failFromValidation(chk, GetTransactionsOutputSchema);
+
+	const lim = validateLimit(limit, 1, 1000);
+	if (!lim.ok) return failFromValidation(lim, GetTransactionsOutputSchema);
+
+	const url =
+		date && /\d{8}/.test(String(date))
+			? `${BITBANK_API_BASE}/${chk.pair}/transactions/${date}`
+			: `${BITBANK_API_BASE}/${chk.pair}/transactions`;
+
+	try {
+		const { data: json, rateLimit } = await fetchJsonWithRateLimit(url, { timeoutMs: 4000, retries: DEFAULT_RETRIES });
+		const jsonObj = json as { data?: { transactions?: TxnRaw[] } };
+		const arr: TxnRaw[] = (jsonObj?.data?.transactions ?? []) as TxnRaw[];
+
+		const items = arr
+			.map((t) => {
+				const price = toNum(t.price);
+				const amount = toNum(t.amount ?? t.size);
+				const side = normalizeSide(t.side);
+				const ms = toMs(t.executed_at ?? t.timestamp ?? t.date);
+				const isoTime = toIsoMs(ms);
+				if (price == null || amount == null || side == null || isoTime == null) return null;
+				return { price, amount, side, timestampMs: ms as number, isoTime };
+			})
+			.filter(Boolean) as NormalizedTxn[];
+
+		const sorted = items.sort((a, b) => a.timestampMs - b.timestampMs);
+		const latest = sorted.slice(-lim.value);
+
+		const buys = latest.filter((t) => t.side === 'buy').length;
+		const sells = latest.filter((t) => t.side === 'sell').length;
+		const baseSummary = formatTransactionsSummary(chk.pair, latest, buys, sells);
+		// テキスト summary に全取引データを含める（LLM が structuredContent.data を読めない対策）
+		const txLines = latest.map((t, i) => {
+			const time = dayjs(t.timestampMs).tz('Asia/Tokyo').format('HH:mm:ss');
+			return `[${i}] ${time} ${t.side} ${t.price} x${t.amount}`;
+		});
+		const summary =
+			baseSummary +
+			`\n\n📋 全${latest.length}件の取引:\n` +
+			txLines.join('\n') +
+			`\n\n---\n📌 含まれるもの: 個別約定（時刻・売買方向・価格・数量）、買い/売り件数比率` +
+			`\n📌 含まれないもの: 集計済みフロー指標（CVD・Zスコア・スパイク）、OHLCV、板情報` +
+			`\n📌 補完ツール: get_flow_metrics（集計フロー・CVD・スパイク検出）, get_candles（OHLCV）, get_orderbook（板情報）`;
+
+		const data = { raw: json, normalized: latest };
+		const meta = createMeta(chk.pair, {
+			count: latest.length,
+			source: date ? 'by_date' : 'latest',
+			...(rateLimit ? { rateLimit } : {}),
+		});
+		return GetTransactionsOutputSchema.parse(
+			ok<z.infer<typeof GetTransactionsDataSchemaOut>, z.infer<typeof GetTransactionsMetaSchemaOut>>(
+				summary,
+				data,
+				meta as z.infer<typeof GetTransactionsMetaSchemaOut>,
+			),
+		);
+	} catch (e: unknown) {
+		// 失敗時は叩いた URL をエラーメッセージに含め、呼び出し側で原因を特定しやすくする。
+		// ただし AbortError は failFromError 側の timeout 判定で必要なのでそのまま渡す。
+		if (e instanceof Error && e.name === 'AbortError') {
+			return failFromError(e, {
+				schema: GetTransactionsOutputSchema,
+				timeoutMs: 4000,
+				defaultType: 'network',
+				defaultMessage: `ネットワークエラー [url: ${url}]`,
+			});
+		}
+		const baseMsg = e instanceof Error && e.message ? e.message : typeof e === 'string' ? e : 'ネットワークエラー';
+		const wrapped = new Error(`${baseMsg} [url: ${url}]`);
+		return failFromError(wrapped, {
+			schema: GetTransactionsOutputSchema,
+			timeoutMs: 4000,
+			defaultType: 'network',
+			defaultMessage: `ネットワークエラー [url: ${url}]`,
+		});
+	}
+}
+
+// ── MCP ツール定義（tool-registry から自動収集） ──
+export const toolDef: ToolDefinition = {
+	name: 'get_transactions',
+	description:
+		'[Transactions / Trades] 市場の約定履歴（transactions / recent trades）を取得。直近60件 or 日付指定。金額・価格でフィルタ可能。',
+	inputSchema: GetTransactionsInputSchema,
+	handler: async ({
+		pair,
+		limit,
+		date,
+		minAmount,
+		maxAmount,
+		minPrice,
+		maxPrice,
+		view,
+	}: {
+		pair?: string;
+		limit?: number;
+		date?: string;
+		minAmount?: number;
+		maxAmount?: number;
+		minPrice?: number;
+		maxPrice?: number;
+		view?: 'summary' | 'items';
+	}) => {
+		const res = await getTransactions(pair, limit, date);
+		if (!res?.ok) return res;
+		const hasFilter = minAmount != null || maxAmount != null || minPrice != null || maxPrice != null;
+		type TxItem = { price: number; amount: number; side: 'buy' | 'sell'; timestampMs: number; isoTime: string };
+		const items = (res?.data?.normalized ?? ([] as TxItem[])).filter(
+			(t: TxItem) =>
+				(minAmount == null || t.amount >= minAmount) &&
+				(maxAmount == null || t.amount <= maxAmount) &&
+				(minPrice == null || t.price >= minPrice) &&
+				(maxPrice == null || t.price <= maxPrice),
+		);
+		const summary = hasFilter
+			? `${String(pair).toUpperCase().replace('_', '/')} フィルタ後 ${items.length}件 (buy=${items.filter((t: TxItem) => t.side === 'buy').length} sell=${items.filter((t: TxItem) => t.side === 'sell').length})`
+			: res.summary;
+		if (view === 'items') {
+			const text = JSON.stringify(items, null, 2);
+			return {
+				content: [{ type: 'text', text }],
+				structuredContent: { ...res, summary, data: { ...res.data, normalized: items } } as Record<string, unknown>,
+			};
+		}
+		return { ...res, summary, data: { ...res.data, normalized: items } };
+	},
+};