bitbank-lab-mcp 0.1.0

package/src/schema/backtest.ts

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+
+// === Trading Process: Backtest Schemas ===
+
+export const BacktestTimeframeEnum = z.enum(['1D', '4H', '1H']);
+export const BacktestPeriodEnum = z.enum(['1M', '3M', '6M']);
+
+const BacktestTradeSchema = z.object({
+	entry_time: z.string(),
+	entry_price: z.number(),
+	exit_time: z.string(),
+	exit_price: z.number(),
+	pnl_pct: z.number(),
+	fee_pct: z.number(),
+});
+
+const EquityPointSchema = z.object({
+	time: z.string(),
+	equity_pct: z.number(),
+});
+
+const DrawdownPointSchema = z.object({
+	time: z.string(),
+	drawdown_pct: z.number(),
+});
+
+// === Generic Backtest Schema ===
+
+export const StrategyTypeEnum = z.enum(['sma_cross', 'rsi', 'macd_cross', 'bb_breakout']);
+
+export const StrategyConfigSchema = z.object({
+	type: StrategyTypeEnum.describe('Strategy type'),
+	params: z.record(z.string(), z.number()).optional().default({}).describe('Strategy parameters (overrides defaults)'),
+});
+
+export const RunBacktestInputSchema = z.object({
+	pair: z.string().optional().default('btc_jpy').describe('Trading pair (e.g., btc_jpy)'),
+	timeframe: BacktestTimeframeEnum.optional()
+		.default('1D')
+		.describe('Candle timeframe: 1D (daily), 4H (4-hour), 1H (hourly)'),
+	period: BacktestPeriodEnum.optional().default('3M').describe('Backtest period: 1M, 3M, or 6M'),
+	strategy: StrategyConfigSchema.describe('Strategy configuration'),
+	fee_bp: z.number().min(0).max(100).optional().default(12).describe('One-way fee in basis points'),
+	execution: z.literal('t+1_open').optional().default('t+1_open').describe('Execution timing (fixed: t+1_open)'),
+	outputDir: z.string().optional().default('/mnt/user-data/outputs').describe('Output directory for chart files'),
+	savePng: z.boolean().optional().default(true).describe('Save chart as PNG file (default: true)'),
+	includeSvg: z
+		.boolean()
+		.optional()
+		.default(false)
+		.describe('Include SVG string in response (default: false, for token saving)'),
+	chartDetail: z
+		.enum(['default', 'full'])
+		.optional()
+		.default('default')
+		.describe(
+			'Chart detail level: default (equity+DD only) or full (price+indicator+equity+DD+position). Use full ONLY when user explicitly requests price chart or indicator visualization.',
+		),
+});
+
+const GenericBacktestSummarySchema = z.object({
+	total_pnl_pct: z.number(),
+	trade_count: z.number(),
+	win_rate: z.number(),
+	max_drawdown_pct: z.number(),
+	buy_hold_pnl_pct: z.number(),
+	excess_return_pct: z.number(),
+	profit_factor: z.number().nullable().describe('Profit Factor (gross profit / gross loss). null if no losing trades'),
+	sharpe_ratio: z.number().nullable().describe('Annualized Sharpe Ratio (daily returns, sqrt(365))'),
+	avg_pnl_pct: z.number().describe('Average P&L per trade [%]'),
+});
+
+export const RunBacktestOutputSchema = z.union([
+	z.object({
+		ok: z.literal(true),
+		summary: z.string(),
+		data: z.object({
+			input: z.object({
+				pair: z.string(),
+				timeframe: z.string(),
+				period: z.string(),
+				strategy: StrategyConfigSchema,
+				fee_bp: z.number(),
+				execution: z.string(),
+			}),
+			summary: GenericBacktestSummarySchema,
+			trades: z.array(BacktestTradeSchema),
+			equity_curve: z.array(EquityPointSchema),
+			drawdown_curve: z.array(DrawdownPointSchema),
+			overlays: z.array(z.any()),
+		}),
+		chartPath: z.string().optional().describe('Path to saved PNG chart file'),
+		svg: z.string().optional().describe('SVG string (only if includeSvg: true)'),
+	}),
+	z.object({
+		ok: z.literal(false),
+		error: z.string(),
+		availableStrategies: z.array(StrategyTypeEnum).optional(),
+	}),
+]);

package/src/schema/base.ts

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+
+export const CandleTypeEnum = z.enum([
+	'1min',
+	'5min',
+	'15min',
+	'30min',
+	'1hour',
+	'4hour',
+	'8hour',
+	'12hour',
+	'1day',
+	'1week',
+	'1month',
+]);
+
+// ── Shared base schemas ──
+
+/** レートリミット情報スキーマ（レスポンスヘッダから抽出、ヘッダ未提供時は省略） */
+export const RateLimitSchema = z
+	.object({
+		remaining: z.number().describe('残りリクエスト数'),
+		limit: z.number().describe('期間あたりの上限数'),
+		reset: z.number().describe('リセット時刻（Unix epoch 秒）'),
+	})
+	.optional();
+
+/** pair + fetchedAt: 全 Meta スキーマの共通ベース */
+export const BaseMetaSchema = z.object({
+	pair: z.string(),
+	fetchedAt: z.string(),
+	rateLimit: RateLimitSchema,
+});
+
+/** pair デフォルト入力: z.string().optional().default('btc_jpy') */
+export const BasePairInputSchema = z.object({ pair: z.string().optional().default('btc_jpy') });
+
+/** 全ツール共通のエラー分岐 */
+export const FailResultSchema = z.object({
+	ok: z.literal(false),
+	summary: z.string(),
+	data: z.object({}).passthrough(),
+	meta: z.object({ errorType: z.string() }).passthrough(),
+});
+
+/** ok/fail Result union を生成するヘルパー */
+export function toolResultSchema<D extends z.ZodTypeAny, M extends z.ZodTypeAny>(data: D, meta: M) {
+	return z.union([z.object({ ok: z.literal(true), summary: z.string(), data, meta }), FailResultSchema]);
+}
+
+export const TrendLabelEnum = z.enum([
+	'strong_uptrend',
+	'uptrend',
+	'strong_downtrend',
+	'downtrend',
+	'overbought',
+	'oversold',
+	'sideways',
+	'insufficient_data',
+]);
+
+// === Shared output schemas (partial) ===
+export const NumericSeriesSchema = z
+	.array(z.union([z.number(), z.null()]))
+	.transform((arr) => arr.map((v) => (v == null ? null : Number(Number(v).toFixed(2)))));
+
+/**
+ * ローソク足スキーマ
+ * volume: base 通貨建ての合算取引量（買い+売り区別なし）。
+ *   例: btc_jpy → BTC 単位、eth_jpy → ETH 単位。
+ *   bitbank /candlestick API の OHLCV[4] をそのまま使用。
+ *   公式アプリの Volume バー（買い/売り色分け）とは集計方法が異なる。
+ */
+export const CandleSchema = z.object({
+	open: z.number(),
+	high: z.number(),
+	low: z.number(),
+	close: z.number(),
+	volume: z.number().optional(),
+	isoTime: z.string().nullable().optional(),
+	isoTimeLocal: z
+		.string()
+		.nullable()
+		.optional()
+		.describe('tz パラメータ指定時のローカル時刻（例: 2026-02-20T09:00:00）'),
+	time: z.union([z.string(), z.number()]).optional(),
+	timestamp: z.number().optional(),
+});

package/src/schema/candle-validate.ts

@@ -0,0 +1,135 @@
+import { z } from 'zod';
+import { BaseMetaSchema, CandleTypeEnum, toolResultSchema } from './base.js';
+
+// ── Input ──
+
+export const ValidateCandleDataInputSchema = z.object({
+	pair: z.string().optional().default('btc_jpy'),
+	type: CandleTypeEnum.optional().default('1day'),
+	date: z
+		.string()
+		.regex(/^\d{4}(\d{4})?$/, 'YYYYMMDD or YYYY format')
+		.optional()
+		.describe('YYYYMMDD or YYYY format. If omitted, uses latest data.'),
+	limit: z.number().int().min(10).max(1000).optional().default(200).describe('検証対象のローソク足本数（10〜1000）'),
+	price_sigma: z
+		.number()
+		.min(1)
+		.max(10)
+		.optional()
+		.describe('価格変化率がこの σ を超えたら異常値とみなす。省略時はペアのティア（major/mid/minor）に応じて自動設定'),
+	volume_multiplier: z
+		.number()
+		.min(2)
+		.max(100)
+		.optional()
+		.describe('出来高が全体平均の何倍を超えたらスパイクとみなすか。省略時はペアのティアに応じて自動設定'),
+	tz: z.string().optional().default('Asia/Tokyo').describe('タイムゾーン（デフォルト: Asia/Tokyo）'),
+});
+
+// ── Output sub-schemas ──
+
+const CompletenessSchema = z.object({
+	expected: z.number(),
+	actual: z.number(),
+	missing: z.number(),
+	missingTimestamps: z.array(z.string()),
+	ratio: z.number(),
+});
+
+const DuplicatesSchema = z.object({
+	count: z.number(),
+	timestamps: z.array(z.string()),
+});
+
+const IntegrityIssueSchema = z.object({
+	index: z.number(),
+	isoTime: z.string().nullable(),
+	issues: z.array(z.string()),
+});
+
+const IntegritySchema = z.object({
+	totalChecked: z.number(),
+	invalidCount: z.number(),
+	issues: z.array(IntegrityIssueSchema),
+});
+
+const PriceAnomalySchema = z.object({
+	index: z.number(),
+	isoTime: z.string().nullable(),
+	returnPct: z.number(),
+	sigma: z.number(),
+});
+
+const PriceAnomalyResultSchema = z.object({
+	totalBars: z.number(),
+	anomalyCount: z.number(),
+	anomalies: z.array(PriceAnomalySchema),
+	stats: z
+		.object({
+			mean: z.number(),
+			stddev: z.number(),
+			threshold: z.number(),
+		})
+		.nullable(),
+});
+
+const VolumeAnomalySchema = z.object({
+	index: z.number(),
+	isoTime: z.string().nullable(),
+	volume: z.number(),
+	reason: z.enum(['zero', 'spike']),
+	multiplier: z.number().optional(),
+});
+
+const VolumeAnomalyResultSchema = z.object({
+	totalBars: z.number(),
+	anomalyCount: z.number(),
+	zeroCount: z.number(),
+	spikeCount: z.number(),
+	anomalies: z.array(VolumeAnomalySchema),
+	stats: z
+		.object({
+			avgVolume: z.number(),
+			threshold: z.number(),
+		})
+		.nullable(),
+});
+
+const QualityScoreSchema = z.object({
+	score: z.number().min(0).max(100),
+	breakdown: z.object({
+		completeness: z.number(),
+		integrity: z.number(),
+		priceStability: z.number(),
+		volumeHealth: z.number(),
+	}),
+	grade: z.enum(['A', 'B', 'C', 'D', 'F']),
+});
+
+// ── Output ──
+
+export const ValidateCandleDataDataSchema = z.object({
+	completeness: CompletenessSchema,
+	duplicates: DuplicatesSchema,
+	integrity: IntegritySchema,
+	priceAnomalies: PriceAnomalyResultSchema,
+	volumeAnomalies: VolumeAnomalyResultSchema,
+	qualityScore: QualityScoreSchema,
+});
+
+export const ValidateCandleDataMetaSchema = BaseMetaSchema.extend({
+	type: CandleTypeEnum,
+	count: z.number().int(),
+	tier: z.enum(['major', 'mid', 'minor']),
+	thresholds: z.object({
+		priceSigma: z.number(),
+		volumeMultiplier: z.number(),
+		zeroVolumePenaltyWeight: z.number(),
+	}),
+});
+
+export const ValidateCandleDataOutputSchema = toolResultSchema(
+	ValidateCandleDataDataSchema,
+	ValidateCandleDataMetaSchema,
+);