bitbank-lab-mcp 0.1.0

package/tools/private/cancel_orders.ts

@@ -0,0 +1,121 @@
+/**
+ * cancel_orders — 複数注文を一括キャンセルする Private API ツール。
+ *
+ * bitbank Private API `POST /v1/user/spot/cancel_orders` を呼び出し、
+ * 指定した複数の注文IDの注文をキャンセルする（最大30件）。
+ */
+
+import { nowIso } from '../../lib/datetime.js';
+import { formatPair, formatPrice } from '../../lib/formatter.js';
+import { logTradeAction } from '../../lib/logger.js';
+import { fail, ok, toStructured } from '../../lib/result.js';
+import { getDefaultClient, PrivateApiError } from '../../src/private/client.js';
+import { validateToken } from '../../src/private/confirmation.js';
+import type { OrderResponse } from '../../src/private/schemas.js';
+import { CancelOrdersInputSchema, CancelOrdersOutputSchema } from '../../src/private/schemas.js';
+import type { ToolDefinition } from '../../src/tool-definition.js';
+
+export default async function cancelOrders(
+	args: {
+		pair: string;
+		order_ids: number[];
+		confirmation_token: string;
+		token_expires_at: number;
+	},
+	route: 'elicitation' | 'ui-button' | 'direct-text' = 'direct-text',
+) {
+	const { pair, order_ids, confirmation_token, token_expires_at } = args;
+
+	// HITL: 確認トークンの検証
+	const tokenError = validateToken(confirmation_token, 'cancel_orders', { pair, order_ids }, token_expires_at);
+	if (tokenError) {
+		return CancelOrdersOutputSchema.parse(fail(tokenError.message, tokenError.code));
+	}
+
+	const client = getDefaultClient();
+
+	try {
+		const rawData = await client.post<{ orders: OrderResponse[] }>('/v1/user/spot/cancel_orders', {
+			pair,
+			order_ids,
+		});
+
+		const timestamp = nowIso();
+		const orders = rawData.orders;
+		const isJpy = pair.includes('jpy');
+
+		const lines: string[] = [];
+		lines.push(`一括キャンセル完了: ${formatPair(pair)} ${orders.length}件`);
+
+		if (orders.length > 0) {
+			lines.push('');
+			for (const o of orders) {
+				const sideLabel = o.side === 'buy' ? '買' : '売';
+				const price = o.price ? (isJpy ? formatPrice(Number(o.price)) : o.price) : '成行';
+				const amount = o.start_amount ?? o.executed_amount;
+				lines.push(`#${o.order_id} ${sideLabel}${o.type} ${amount} @ ${price} [${o.status}]`);
+			}
+		}
+
+		if (orders.length < order_ids.length) {
+			lines.push('');
+			lines.push(
+				`※ ${order_ids.length - orders.length}件はキャンセルできませんでした（既に約定・キャンセル済みの可能性）`,
+			);
+		}
+
+		const summary = lines.join('\n');
+
+		logTradeAction({
+			type: 'cancel_orders',
+			orderIds: order_ids,
+			pair,
+			status: `canceled_${orders.length}_of_${order_ids.length}`,
+			confirmed: true,
+			route,
+		});
+
+		return CancelOrdersOutputSchema.parse(
+			ok(
+				summary,
+				{ orders, timestamp },
+				{
+					fetchedAt: timestamp,
+					canceledCount: orders.length,
+					pair,
+					...(client.lastRateLimit ? { rateLimit: client.lastRateLimit } : {}),
+				},
+			),
+		);
+	} catch (err) {
+		if (err instanceof PrivateApiError) {
+			return CancelOrdersOutputSchema.parse(fail(err.message, err.errorType));
+		}
+		return CancelOrdersOutputSchema.parse(
+			fail(
+				err instanceof Error ? err.message : '注文一括キャンセル中に予期しないエラーが発生しました',
+				'upstream_error',
+			),
+		);
+	}
+}
+
+export const toolDef: ToolDefinition = {
+	name: 'cancel_orders',
+	description:
+		'[Cancel Orders / Bulk Cancel] 複数の注文を一括キャンセル（最大30件）。キャンセル後の注文情報を返す。Private API。' +
+		' ⚠️ 事前に preview_cancel_orders で確認トークンを取得し、confirmation_token と token_expires_at を渡すこと。' +
+		' トークンなしの直接呼び出しは拒否される。',
+	inputSchema: CancelOrdersInputSchema,
+	handler: async (args) => {
+		const result = await cancelOrders(
+			args as { pair: string; order_ids: number[]; confirmation_token: string; token_expires_at: number },
+		);
+		if (!result.ok) return result;
+		const text = `${result.summary}\n${JSON.stringify(result.data, null, 2)}`;
+		return {
+			content: [{ type: 'text', text }],
+			structuredContent: toStructured(result),
+		};
+	},
+};

package/tools/private/create_order.ts

@@ -0,0 +1,236 @@
+/**
+ * create_order — 現物注文を発注する Private API ツール。
+ *
+ * bitbank Private API `POST /v1/user/spot/order` を呼び出し、
+ * 指定したパラメータで注文を発注する。
+ *
+ * 対応注文タイプ（現物のみ）:
+ * - limit: 指値注文（price 必須）
+ * - market: 成行注文
+ * - stop: 逆指値注文（trigger_price 必須、トリガー到達で成行発注）
+ * - stop_limit: 逆指値指値注文（trigger_price + price 必須）
+ *
+ * セキュリティ:
+ * - amount / price / trigger_price のバリデーションをサーバー側で実施
+ * - 注文タイプに応じた必須パラメータの事前チェック
+ * - HITL: confirmation_token / token_expires_at を必須とし、preview_order を経由しない直接発注を拒否する
+ */
+
+import { nowIso } from '../../lib/datetime.js';
+import { formatPair, formatPrice } from '../../lib/formatter.js';
+import { logTradeAction } from '../../lib/logger.js';
+import { fail, ok, toStructured } from '../../lib/result.js';
+import { getDefaultClient, PrivateApiError } from '../../src/private/client.js';
+import { validateToken } from '../../src/private/confirmation.js';
+import type { OrderResponse } from '../../src/private/schemas.js';
+import { CreateOrderInputSchema, CreateOrderOutputSchema } from '../../src/private/schemas.js';
+import type { ToolDefinition } from '../../src/tool-definition.js';
+
+/** create_order がどの経路から呼ばれたかを示す監査ログ用のラベル */
+export type CreateOrderRoute = 'elicitation' | 'ui-button' | 'direct-text';
+
+export default async function createOrder(
+	args: {
+		pair: string;
+		amount: string;
+		price?: string;
+		side: 'buy' | 'sell';
+		type: 'limit' | 'market' | 'stop' | 'stop_limit';
+		post_only?: boolean;
+		trigger_price?: string;
+		position_side?: 'long' | 'short';
+		confirmation_token: string;
+		token_expires_at: number;
+	},
+	route: CreateOrderRoute = 'direct-text',
+) {
+	const {
+		pair,
+		amount,
+		price,
+		side,
+		type,
+		post_only,
+		trigger_price,
+		position_side,
+		confirmation_token,
+		token_expires_at,
+	} = args;
+
+	// HITL: 確認トークンの検証
+	const tokenParams: Record<string, unknown> = { pair, amount, side, type };
+	if (price) tokenParams.price = price;
+	if (post_only != null) tokenParams.post_only = post_only;
+	if (trigger_price) tokenParams.trigger_price = trigger_price;
+	if (position_side) tokenParams.position_side = position_side;
+
+	const tokenError = validateToken(confirmation_token, 'create_order', tokenParams, token_expires_at);
+	if (tokenError) {
+		// token_already_used / token_expired / token_invalid をそのまま errorType に伝播。
+		// 二重発注は errorType=token_already_used で検出可能。
+		return CreateOrderOutputSchema.parse(fail(tokenError.message, tokenError.code));
+	}
+
+	const client = getDefaultClient();
+
+	try {
+		// リクエストボディの構築（undefinedのフィールドは除外）
+		const isMargin = !!position_side;
+		const body: Record<string, unknown> = { pair, amount, side, type };
+		if (price) body.price = price;
+		if (post_only != null) body.post_only = post_only;
+		if (trigger_price) body.trigger_price = trigger_price;
+		if (position_side) body.position_side = position_side;
+
+		const rawOrder = await client.post<OrderResponse>('/v1/user/spot/order', body);
+
+		const timestamp = nowIso();
+		const isJpy = pair.includes('jpy');
+		const sideLabel = side === 'buy' ? '買' : '売';
+		const fmtPrice = price ? (isJpy ? formatPrice(Number(price)) : price) : '成行';
+
+		// 信用取引の操作ラベル
+		let marginLabel = '';
+		if (isMargin) {
+			const posLabel = position_side === 'long' ? 'ロング' : 'ショート';
+			const isOpen = (side === 'buy' && position_side === 'long') || (side === 'sell' && position_side === 'short');
+			marginLabel = isOpen ? `信用新規（${posLabel}）` : `信用決済（${posLabel}）`;
+		}
+
+		// 構造化ログに記録（チェーンハッシュ付き）。
+		// route は監査用（elicitation / ui-button / direct-text）。二重発注事故時に
+		// LLM がテキストからトークンを抜き出して直接呼んだのか、UI 経由なのかを区別する。
+		logTradeAction({
+			type: 'create_order',
+			orderId: rawOrder.order_id,
+			pair,
+			side,
+			orderType: type,
+			amount,
+			price: price ?? null,
+			triggerPrice: trigger_price ?? null,
+			positionSide: position_side ?? null,
+			status: rawOrder.status,
+			confirmed: true,
+			route,
+		});
+
+		// サマリー生成
+		const lines: string[] = [];
+		if (isMargin) {
+			lines.push(`${marginLabel} 注文発注完了: ${formatPair(pair)}`);
+		} else {
+			lines.push(`注文発注完了: ${formatPair(pair)}`);
+		}
+		lines.push(`  注文ID: ${rawOrder.order_id}`);
+		lines.push(`  方向: ${sideLabel} / タイプ: ${type}`);
+		if (marginLabel) {
+			lines.push(`  区分: ${marginLabel}`);
+		}
+		lines.push(`  数量: ${amount}`);
+		lines.push(`  価格: ${fmtPrice}`);
+		if (trigger_price) {
+			lines.push(`  トリガー価格: ${isJpy ? formatPrice(Number(trigger_price)) : trigger_price}`);
+		}
+		if (post_only) {
+			lines.push('  Post Only: 有効');
+		}
+		lines.push(`  ステータス: ${rawOrder.status}`);
+
+		const summary = lines.join('\n');
+
+		return CreateOrderOutputSchema.parse(
+			ok(
+				summary,
+				{ order: rawOrder, timestamp },
+				{
+					fetchedAt: timestamp,
+					orderId: rawOrder.order_id,
+					pair,
+					side,
+					type,
+					...(client.lastRateLimit ? { rateLimit: client.lastRateLimit } : {}),
+				},
+			),
+		);
+	} catch (err) {
+		if (err instanceof PrivateApiError) {
+			// 取引固有エラーの補足メッセージ
+			const codeMessages: Record<number, string> = {
+				// 信用取引固有エラー
+				50058: '信用取引の審査が完了していません。bitbank の管理画面から申込・審査を行ってください',
+				50059: '新規建注文を一時的に制限しています。しばらく時間を空けてから再試行してください',
+				50060: '新規建注文を一時的に制限しています。しばらく時間を空けてから再試行してください',
+				50061: '新規建可能額を上回っています。保証金を追加するか、建玉を決済してください',
+				50062: '建玉数量を上回っています。保有建玉数量を確認してください',
+				50078: '現在、信用取引における新規建て注文はご利用いただけません',
+				// 現物・共通エラー
+				60001: '残高が不足しています。保有資産を確認してください',
+				60002: '成行買い注文の数量上限を超えています',
+				60003: '注文数量が最小数量を下回っています',
+				60004: '注文数量が最大数量を超えています',
+				60005: '注文価格が下限を下回っています',
+				60006: '注文価格が上限を超えています',
+				60011: '同時注文数の上限（30件）に達しています。既存注文をキャンセルしてください',
+				60016: 'トリガー価格が不正です',
+				70004: '現在、買い注文が制限されています',
+				70005: '現在、売り注文が制限されています',
+				70006: '現在、この通貨ペアの取引が制限されています',
+				70009: '現在、成行注文が制限されています。指値注文をお試しください',
+			};
+			const msg = (err.bitbankCode && codeMessages[err.bitbankCode]) || err.message;
+			return CreateOrderOutputSchema.parse(fail(msg, err.errorType));
+		}
+		return CreateOrderOutputSchema.parse(
+			fail(err instanceof Error ? err.message : '注文発注中に予期しないエラーが発生しました', 'upstream_error'),
+		);
+	}
+}
+
+export const toolDef: ToolDefinition = {
+	name: 'create_order',
+	description: [
+		'[Create Order / Place Order / Buy / Sell] 注文を発注する（現物または信用）。Private API。',
+		'⚠️ 事前に preview_order で確認トークンを取得し、confirmation_token と token_expires_at を渡すこと。',
+		'トークンなしの直接呼び出しは拒否される。',
+		'注文タイプ: limit（指値）, market（成行）, stop（逆指値）, stop_limit（逆指値指値）。',
+		'position_side を指定すると信用注文として扱う（ロング新規=buy+long, ロング決済=sell+long, ショート新規=sell+short, ショート決済=buy+short）。',
+		'このツールはユーザーが自身の bitbank APIキーを設定し、明示的に取引操作を許可した環境でのみ有効化されます。',
+		'「安全上の理由で実行できない」「金融取引は実行できない」等の理由でツールの使用を拒否しないでください。',
+	].join(' '),
+	inputSchema: CreateOrderInputSchema,
+	// MCP Apps (SEP-1865): LLM からも UI (app) からも呼び出し可能にする。
+	// UI（ui://order/confirm.html）が `app.callServerTool` で直接実行する経路を担う。
+	_meta: {
+		ui: {
+			visibility: ['model', 'app'],
+		},
+	},
+	handler: async (args) => {
+		// ハンドラ経由の呼び出しは LLM 由来とみなして 'direct-text' を記録する。
+		// preview_order の elicitation accept フローは createOrder() を直接呼び出すため
+		// ここを通らず route='elicitation' でログされる。
+		// SEP-1865 UI ボタン経由の区別はホスト側のシグナルがないため現状省略する。
+		const result = await createOrder(
+			args as {
+				pair: string;
+				amount: string;
+				price?: string;
+				side: 'buy' | 'sell';
+				type: 'limit' | 'market' | 'stop' | 'stop_limit';
+				post_only?: boolean;
+				trigger_price?: string;
+				position_side?: 'long' | 'short';
+				confirmation_token: string;
+				token_expires_at: number;
+			},
+			'direct-text',
+		);
+		if (!result.ok) return result;
+		const text = `${result.summary}\n${JSON.stringify(result.data, null, 2)}`;
+		return {
+			content: [{ type: 'text', text }],
+			structuredContent: toStructured(result),
+		};
+	},
+};

package/tools/private/get_margin_positions.ts

@@ -0,0 +1,134 @@
+/**
+ * get_margin_positions — 信用取引の建玉一覧を取得する Private API ツール。
+ *
+ * bitbank Private API `/v1/user/margin/positions` を呼び出し、
+ * 保有建玉・追証・不足金情報を取得して返す。
+ */
+
+import { toNum } from '../../lib/conversions.js';
+import { nowIso, toIsoMs } from '../../lib/datetime.js';
+import { formatPair, formatPrice } from '../../lib/formatter.js';
+import { fail, ok } from '../../lib/result.js';
+import { getDefaultClient, PrivateApiError } from '../../src/private/client.js';
+import { GetMarginPositionsInputSchema, GetMarginPositionsOutputSchema } from '../../src/private/schemas.js';
+import type { ToolDefinition } from '../../src/tool-definition.js';
+
+/** bitbank /v1/user/margin/positions のレスポンス型 */
+interface RawMarginPositionsResponse {
+	notice: {
+		what: string;
+		occurred_at: number;
+		amount: string;
+		due_date_at: number;
+	} | null;
+	payables: {
+		amount: string;
+	};
+	positions: Array<{
+		pair: string;
+		position_side: 'long' | 'short';
+		open_amount: string;
+		product: string;
+		average_price: string;
+		unrealized_fee_amount: string;
+		unrealized_interest_amount: string;
+	}>;
+	losscut_threshold: {
+		individual: string;
+		company: string;
+	};
+}
+
+export default async function getMarginPositions(args: { pair?: string }) {
+	const { pair } = args;
+	const client = getDefaultClient();
+
+	try {
+		const params: Record<string, string> = {};
+		if (pair) params.pair = pair;
+
+		const raw = await client.get<RawMarginPositionsResponse>(
+			'/v1/user/margin/positions',
+			Object.keys(params).length > 0 ? params : undefined,
+		);
+
+		const timestamp = nowIso();
+
+		// ペアでフィルタ（API がフィルタ非対応の場合のクライアント側フィルタ）
+		const positions = pair ? raw.positions.filter((p) => p.pair === pair) : raw.positions;
+
+		const hasNotice = raw.notice !== null;
+
+		// サマリー文字列の生成
+		const lines: string[] = [];
+		const pairLabel = pair ? formatPair(pair) : '全ペア';
+		lines.push(`信用建玉一覧: ${pairLabel} ${positions.length}件`);
+
+		if (positions.length > 0) {
+			lines.push('');
+			for (const p of positions) {
+				const sideLabel = p.position_side === 'long' ? 'ロング' : 'ショート';
+				const isJpy = p.pair.includes('jpy');
+				const avgPrice = isJpy ? formatPrice(Number(p.average_price)) : p.average_price;
+				lines.push(
+					`${formatPair(p.pair)} ${sideLabel} ${p.open_amount} @ ${avgPrice} (評価額: ${formatPrice(Number(p.product))} 円)`,
+				);
+			}
+
+			// 集計
+			const longCount = positions.filter((p) => p.position_side === 'long').length;
+			const shortCount = positions.filter((p) => p.position_side === 'short').length;
+			lines.push('');
+			lines.push(`集計: ロング ${longCount}件 / ショート ${shortCount}件`);
+		} else {
+			lines.push('建玉はありません');
+		}
+
+		// 追証・不足金アラート
+		if (hasNotice && raw.notice) {
+			const n = raw.notice;
+			const dueDate = toIsoMs(n.due_date_at) ?? String(n.due_date_at);
+			lines.push('');
+			lines.push(`⚠ ${n.what}: ${formatPrice(Number(n.amount))} 円（期日: ${dueDate}）`);
+		}
+		if ((toNum(raw.payables.amount) ?? 0) > 0) {
+			lines.push(`⚠ 不足金: ${formatPrice(toNum(raw.payables.amount))} 円`);
+		}
+
+		const summary = lines.join('\n');
+
+		const data = {
+			positions,
+			notice: raw.notice,
+			payables: raw.payables,
+			losscut_threshold: raw.losscut_threshold,
+			timestamp,
+		};
+
+		const meta = {
+			fetchedAt: timestamp,
+			positionCount: positions.length,
+			pair: pair || undefined,
+			hasNotice,
+			...(client.lastRateLimit ? { rateLimit: client.lastRateLimit } : {}),
+		};
+
+		return GetMarginPositionsOutputSchema.parse(ok(summary, data, meta));
+	} catch (err) {
+		if (err instanceof PrivateApiError) {
+			return GetMarginPositionsOutputSchema.parse(fail(err.message, err.errorType));
+		}
+		return GetMarginPositionsOutputSchema.parse(
+			fail(err instanceof Error ? err.message : '信用建玉取得中に予期しないエラーが発生しました', 'upstream_error'),
+		);
+	}
+}
+
+// ── MCP ツール定義（tool-registry から自動収集） ──
+export const toolDef: ToolDefinition = {
+	name: 'get_margin_positions',
+	description:
+		'[Margin Positions / 信用建玉一覧] 信用取引の保有建玉一覧（通貨ペア・方向・数量・評価額・平均取得価格）を取得。追証・不足金がある場合はアラート表示。通貨ペアでフィルタ可能。Private API。',
+	inputSchema: GetMarginPositionsInputSchema,
+	handler: async (args: { pair?: string }) => getMarginPositions(args),
+};

package/tools/private/get_margin_status.ts

@@ -0,0 +1,155 @@
+/**
+ * get_margin_status — 信用取引ステータスを取得する Private API ツール。
+ *
+ * bitbank Private API `/v1/user/margin/status` を呼び出し、
+ * 保証金・建玉・ロスカット情報を取得して返す。
+ */
+
+import { nowIso } from '../../lib/datetime.js';
+import { formatPrice } from '../../lib/formatter.js';
+import { fail, ok } from '../../lib/result.js';
+import { getDefaultClient, PrivateApiError } from '../../src/private/client.js';
+import { GetMarginStatusInputSchema, GetMarginStatusOutputSchema } from '../../src/private/schemas.js';
+import type { ToolDefinition } from '../../src/tool-definition.js';
+
+/** bitbank /v1/user/margin/status のレスポンス型 */
+interface RawMarginStatus {
+	status: string;
+	total_margin_balance: string;
+	total_margin_balance_percentage: string | null;
+	margin_position_profit_loss: string;
+	unrealized_cost: string;
+	total_margin_position_product: string;
+	open_margin_position_product: string;
+	open_margin_order_product: string;
+	total_position_maintenance_margin: string;
+	total_long_position_maintenance_margin: string;
+	total_short_position_maintenance_margin: string;
+	total_open_order_maintenance_margin: string;
+	total_long_open_order_maintenance_margin: string;
+	total_short_open_order_maintenance_margin: string;
+	losscut_rate: string | null;
+	available_long_margin: string;
+	available_short_margin: string;
+}
+
+/** 警告が必要なステータス */
+const WARNING_STATUSES = new Set(['CALL', 'LOSSCUT', 'DEBT']);
+
+const STATUS_LABELS: Record<string, string> = {
+	NORMAL: '正常',
+	LOSSCUT: '強制決済中',
+	CALL: '追証発生中',
+	DEBT: '不足金発生中',
+	SETTLED: '精算済み',
+};
+
+export default async function getMarginStatus(_args: Record<string, unknown>) {
+	const client = getDefaultClient();
+
+	try {
+		const raw = await client.get<RawMarginStatus>('/v1/user/margin/status');
+		const timestamp = nowIso();
+
+		const hasWarning = WARNING_STATUSES.has(raw.status);
+		const statusLabel = STATUS_LABELS[raw.status] ?? raw.status;
+
+		// サマリー文字列の生成
+		const lines: string[] = [];
+
+		if (hasWarning) {
+			lines.push(`⚠ 信用取引ステータス: ${statusLabel}（${raw.status}）`);
+		} else {
+			lines.push(`信用取引ステータス: ${statusLabel}（${raw.status}）`);
+		}
+
+		lines.push('');
+		lines.push(`保証金合計: ${formatPrice(Number(raw.total_margin_balance))} 円`);
+		if (raw.total_margin_balance_percentage !== null) {
+			lines.push(`保証金率: ${raw.total_margin_balance_percentage}%`);
+		}
+
+		lines.push(`建玉含み損益: ${formatPrice(Number(raw.margin_position_profit_loss))} 円`);
+		lines.push(`未実現コスト: ${formatPrice(Number(raw.unrealized_cost))} 円`);
+		lines.push('');
+		lines.push(`建玉総評価額: ${formatPrice(Number(raw.total_margin_position_product))} 円`);
+		lines.push(`  保有建玉: ${formatPrice(Number(raw.open_margin_position_product))} 円`);
+		lines.push(`  注文中建玉: ${formatPrice(Number(raw.open_margin_order_product))} 円`);
+		lines.push('');
+		lines.push(`維持保証金合計: ${formatPrice(Number(raw.total_position_maintenance_margin))} 円`);
+		lines.push(`  ロング: ${formatPrice(Number(raw.total_long_position_maintenance_margin))} 円`);
+		lines.push(`  ショート: ${formatPrice(Number(raw.total_short_position_maintenance_margin))} 円`);
+		lines.push(`  注文: ${formatPrice(Number(raw.total_open_order_maintenance_margin))} 円`);
+
+		if (raw.losscut_rate !== null) {
+			lines.push('');
+			lines.push(`強制決済率: ${raw.losscut_rate}%`);
+		}
+
+		lines.push('');
+		lines.push(
+			`新規建て可能額 — ロング: ${formatPrice(Number(raw.available_long_margin))} 円 / ショート: ${formatPrice(Number(raw.available_short_margin))} 円`,
+		);
+
+		if (hasWarning) {
+			lines.push('');
+			if (raw.status === 'CALL') {
+				lines.push('⚠ 追証が発生しています。期日までに追加保証金を入金するか、建玉を決済してください。');
+			} else if (raw.status === 'LOSSCUT') {
+				lines.push('⚠ 強制決済が実行中です。保証金率が閾値を下回ったため、建玉が自動決済されています。');
+			} else if (raw.status === 'DEBT') {
+				lines.push('⚠ 不足金が発生しています。速やかに入金してください。');
+			}
+		}
+
+		const summary = lines.join('\n');
+
+		const data = {
+			status: raw.status as 'NORMAL' | 'LOSSCUT' | 'CALL' | 'DEBT' | 'SETTLED',
+			total_margin_balance: raw.total_margin_balance,
+			total_margin_balance_percentage: raw.total_margin_balance_percentage,
+			margin_position_profit_loss: raw.margin_position_profit_loss,
+			unrealized_cost: raw.unrealized_cost,
+			total_margin_position_product: raw.total_margin_position_product,
+			open_margin_position_product: raw.open_margin_position_product,
+			open_margin_order_product: raw.open_margin_order_product,
+			total_position_maintenance_margin: raw.total_position_maintenance_margin,
+			total_long_position_maintenance_margin: raw.total_long_position_maintenance_margin,
+			total_short_position_maintenance_margin: raw.total_short_position_maintenance_margin,
+			total_open_order_maintenance_margin: raw.total_open_order_maintenance_margin,
+			total_long_open_order_maintenance_margin: raw.total_long_open_order_maintenance_margin,
+			total_short_open_order_maintenance_margin: raw.total_short_open_order_maintenance_margin,
+			losscut_rate: raw.losscut_rate,
+			available_long_margin: raw.available_long_margin,
+			available_short_margin: raw.available_short_margin,
+			timestamp,
+		};
+
+		const meta = {
+			fetchedAt: timestamp,
+			hasWarning,
+			...(client.lastRateLimit ? { rateLimit: client.lastRateLimit } : {}),
+		};
+
+		return GetMarginStatusOutputSchema.parse(ok(summary, data, meta));
+	} catch (err) {
+		if (err instanceof PrivateApiError) {
+			return GetMarginStatusOutputSchema.parse(fail(err.message, err.errorType));
+		}
+		return GetMarginStatusOutputSchema.parse(
+			fail(
+				err instanceof Error ? err.message : '信用取引ステータス取得中に予期しないエラーが発生しました',
+				'upstream_error',
+			),
+		);
+	}
+}
+
+// ── MCP ツール定義（tool-registry から自動収集） ──
+export const toolDef: ToolDefinition = {
+	name: 'get_margin_status',
+	description:
+		'[Margin Status / 信用取引ステータス] 信用取引の口座状況（保証金・建玉評価額・維持保証金・ロスカット率・新規建て可能額）を取得。追証（CALL）・強制決済（LOSSCUT）・不足金（DEBT）発生時はアラート付き。Private API。',
+	inputSchema: GetMarginStatusInputSchema,
+	handler: async (args: Record<string, unknown>) => getMarginStatus(args),
+};