bitbank-lab-mcp 0.1.0

package/src/http.ts

@@ -0,0 +1,107 @@
+import { randomUUID } from 'node:crypto';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import express from 'express';
+import rateLimit from 'express-rate-limit';
+import type { NextFunction, Request, RequestHandler, Response } from 'express-serve-static-core';
+
+const PORT = Number(process.env.PORT ?? 8787);
+const ENDPOINT = '/mcp';
+
+/** レート制限: ウィンドウ（ミリ秒）。デフォルト 60 秒 */
+const RATE_LIMIT_WINDOW_MS = Number(process.env.RATE_LIMIT_WINDOW_MS ?? 60_000);
+/** レート制限: ウィンドウあたり最大リクエスト数。デフォルト 60 */
+const RATE_LIMIT_MAX = Number(process.env.RATE_LIMIT_MAX ?? 60);
+
+const app = express();
+app.use(express.json({ limit: '2mb' }));
+
+// ngrok Free のブラウザ警告回避用ヘッダ
+app.use((_req: Request, res: Response, next: NextFunction) => {
+	res.setHeader('ngrok-skip-browser-warning', '1');
+	next();
+});
+
+// 簡易ヘルスチェック
+app.get('/health', (_req: Request, res: Response) => {
+	res.json({ ok: true, ts: Date.now() });
+});
+// 最低限の /mcp ルート（メタ確認用）
+app.get(ENDPOINT, (_req: Request, res: Response) => {
+	res.json({
+		version: '1.0',
+		actions: [
+			{
+				name: 'ping',
+				description: 'Health check action',
+				parameters: { type: 'object', properties: { message: { type: 'string', description: 'Any message' } } },
+			},
+		],
+	});
+});
+
+// 最小サーバ（必要に応じて既存の登録ロジックに差し替え可）
+const server = new McpServer({ name: 'bb-mcp', version: '1.0.0' });
+// SDK の registerTool 型が厳密すぎるため、空スキーマ登録にキャストを集約
+(server as unknown as { registerTool: (n: string, s: unknown, h: unknown) => void }).registerTool(
+	'ping',
+	{
+		description: 'Return a ping response',
+		inputSchema: { message: { type: 'string', description: 'Any message' } },
+	},
+	async (args: Record<string, unknown>) => {
+		return { content: [{ type: 'text', text: `pong: ${String(args.message ?? '')}` }] };
+	},
+);
+
+// Streamable HTTP transport
+const allowedHosts = (process.env.ALLOWED_HOSTS ?? 'localhost,127.0.0.1,*.ngrok-free.dev')
+	.split(',')
+	.map((s) => s.trim())
+	.filter(Boolean);
+const allowedOrigins = (process.env.ALLOWED_ORIGINS ?? '')
+	.split(',')
+	.map((s) => s.trim())
+	.filter(Boolean);
+
+// StreamableHTTPServerTransport のコンストラクタ型が SDK で正確に export されていないためキャストを集約
+type Transport = Parameters<typeof server.connect>[0];
+const HttpTransport = StreamableHTTPServerTransport as unknown as new (
+	opts: Record<string, unknown>,
+) => Transport & {
+	handleRequest?: (req: IncomingMessage, res: ServerResponse, body?: unknown) => Promise<void>;
+};
+const transport = new HttpTransport({
+	path: ENDPOINT,
+	sessionIdGenerator: () => randomUUID(),
+	enableDnsRebindingProtection: true,
+	...(allowedHosts.length ? { allowedHosts } : {}),
+	...(allowedOrigins.length ? { allowedOrigins } : {}),
+});
+
+await server.connect(transport);
+
+// /mcp エンドポイントにレート制限を適用（stdio には影響しない）
+const mcpLimiter = rateLimit({
+	windowMs: RATE_LIMIT_WINDOW_MS,
+	max: RATE_LIMIT_MAX,
+	standardHeaders: 'draft-7',
+	legacyHeaders: false,
+	message: { error: 'Too many requests. Please try again later.' },
+});
+app.use(ENDPOINT, mcpLimiter as unknown as RequestHandler);
+
+// SDK 公式の handleRequest を使って HTTP リクエストを処理する
+const mw: RequestHandler =
+	typeof transport.handleRequest === 'function'
+		? (req, res, next) => {
+				transport.handleRequest!(req, res, req.body).catch(next);
+			}
+		: (_req: Request, _res: Response, next: NextFunction) => next();
+app.use(ENDPOINT, mw);
+
+app.listen(PORT, '::', () => {
+	// eslint-disable-next-line no-console
+	console.log(`MCP HTTP listening on http://localhost:${PORT}${ENDPOINT}`);
+});

package/src/private/auth.ts

@@ -0,0 +1,104 @@
+/**
+ * bitbank Private API 認証モジュール。
+ *
+ * ACCESS-TIME-WINDOW 方式を採用。
+ * 署名対象文字列: requestTime + timeWindow + path/body
+ * ヘッダー: ACCESS-KEY, ACCESS-REQUEST-TIME, ACCESS-TIME-WINDOW, ACCESS-SIGNATURE
+ *
+ * @see https://github.com/bitbankinc/bitbank-api-docs/blob/master/rest-api.md
+ */
+
+import { createHmac } from 'node:crypto';
+import { getPrivateApiConfig } from './config.js';
+
+/** デフォルトの TIME-WINDOW（ミリ秒）。最大 60000 まで設定可能 */
+const DEFAULT_TIME_WINDOW = '5000';
+
+export interface AuthHeaders {
+	'ACCESS-KEY': string;
+	'ACCESS-REQUEST-TIME': string;
+	'ACCESS-TIME-WINDOW': string;
+	'ACCESS-SIGNATURE': string;
+}
+
+/**
+ * GET リクエスト用の署名対象文字列を組み立てる。
+ * 形式: requestTime + timeWindow + path（クエリパラメータ含む）
+ */
+export function buildGetMessage(requestTime: string, timeWindow: string, path: string): string {
+	return requestTime + timeWindow + path;
+}
+
+/**
+ * POST リクエスト用の署名対象文字列を組み立てる。
+ * 形式: requestTime + timeWindow + JSON body
+ */
+export function buildPostMessage(requestTime: string, timeWindow: string, body: string): string {
+	return requestTime + timeWindow + body;
+}
+
+/**
+ * HMAC-SHA256 署名を生成する。
+ * テスト時に秘密鍵とメッセージを直接渡せるよう、純粋関数として分離。
+ */
+export function sign(secret: string, message: string): string {
+	return createHmac('sha256', secret).update(message).digest('hex');
+}
+
+/**
+ * GET リクエスト用の認証ヘッダーを生成する。
+ *
+ * @param path - リクエストパス（例: '/v1/user/assets'）、クエリパラメータ含む
+ * @param requestTime - テスト時に固定値を注入可能。省略時はミリ秒タイムスタンプ
+ * @param timeWindow - TIME-WINDOW 値（ミリ秒）。省略時は 5000
+ */
+export function createGetAuthHeaders(
+	path: string,
+	requestTime?: string,
+	timeWindow: string = DEFAULT_TIME_WINDOW,
+): AuthHeaders {
+	const config = getPrivateApiConfig();
+	if (!config) {
+		throw new Error('BITBANK_API_KEY / BITBANK_API_SECRET が未設定です');
+	}
+
+	const rt = requestTime ?? Date.now().toString();
+	const message = buildGetMessage(rt, timeWindow, path);
+	const signature = sign(config.apiSecret, message);
+
+	return {
+		'ACCESS-KEY': config.apiKey,
+		'ACCESS-REQUEST-TIME': rt,
+		'ACCESS-TIME-WINDOW': timeWindow,
+		'ACCESS-SIGNATURE': signature,
+	};
+}
+
+/**
+ * POST リクエスト用の認証ヘッダーを生成する。
+ *
+ * @param body - JSON.stringify 済みのリクエストボディ
+ * @param requestTime - テスト時に固定値を注入可能。省略時はミリ秒タイムスタンプ
+ * @param timeWindow - TIME-WINDOW 値（ミリ秒）。省略時は 5000
+ */
+export function createPostAuthHeaders(
+	body: string,
+	requestTime?: string,
+	timeWindow: string = DEFAULT_TIME_WINDOW,
+): AuthHeaders {
+	const config = getPrivateApiConfig();
+	if (!config) {
+		throw new Error('BITBANK_API_KEY / BITBANK_API_SECRET が未設定です');
+	}
+
+	const rt = requestTime ?? Date.now().toString();
+	const message = buildPostMessage(rt, timeWindow, body);
+	const signature = sign(config.apiSecret, message);
+
+	return {
+		'ACCESS-KEY': config.apiKey,
+		'ACCESS-REQUEST-TIME': rt,
+		'ACCESS-TIME-WINDOW': timeWindow,
+		'ACCESS-SIGNATURE': signature,
+	};
+}

package/src/private/client.ts

@@ -0,0 +1,298 @@
+/**
+ * bitbank Private API HTTP クライアント。
+ *
+ * - 認証ヘッダーの付与を隠蔽し、ツールから直接認証を意識させない
+ * - HTTP 層を注入可能にし、テスト時に mock に差し替えられる
+ * - レート制限（429 / エラーコード 10009）は Retry-After に従いリトライ
+ * - Base URL: https://api.bitbank.cc（public.bitbank.cc とは別）
+ *
+ * @see https://github.com/bitbankinc/bitbank-api-docs/blob/master/rest-api.md
+ * @see https://github.com/bitbankinc/bitbank-api-docs/blob/master/errors.md
+ */
+
+import { extractRateLimit, type RateLimitInfo } from '../../lib/http.js';
+import { createGetAuthHeaders, createPostAuthHeaders } from './auth.js';
+
+/** テスト時に差し替え可能な HTTP fetcher 型 */
+export type HttpFetcher = (url: string, init: RequestInit) => Promise<Response>;
+
+/** bitbank API の標準レスポンス形式 */
+export interface BitbankApiResponse<T = unknown> {
+	success: number;
+	data: T;
+}
+
+/** Private API クライアントのエラー */
+export class PrivateApiError extends Error {
+	constructor(
+		message: string,
+		public readonly errorType: string,
+		public readonly statusCode?: number,
+		public readonly bitbankCode?: number,
+	) {
+		super(message);
+		this.name = 'PrivateApiError';
+	}
+}
+
+/**
+ * bitbank エラーコードの分類。
+ * @see https://github.com/bitbankinc/bitbank-api-docs/blob/master/errors.md
+ */
+// 認証系: 20001〜20005
+const AUTH_ERROR_CODES = new Set([20001, 20002, 20003, 20004, 20005]);
+// レート制限: 10009
+const RATE_LIMIT_CODES = new Set([10009]);
+// メンテナンス/過負荷: 10007, 10008
+const MAINTENANCE_CODES = new Set([10007, 10008]);
+
+export interface PrivateClientOptions {
+	fetcher?: HttpFetcher;
+	timeoutMs?: number;
+	maxRetries?: number;
+}
+
+export class BitbankPrivateClient {
+	private static readonly BASE_URL = 'https://api.bitbank.cc';
+	private readonly fetcher: HttpFetcher;
+	private readonly timeoutMs: number;
+	private readonly maxRetries: number;
+
+	/** 直近の成功レスポンスから抽出したレートリミット情報（ヘッダ未提供時は null） */
+	lastRateLimit: RateLimitInfo | null = null;
+
+	constructor(opts: PrivateClientOptions = {}) {
+		this.fetcher = opts.fetcher ?? globalThis.fetch.bind(globalThis);
+		this.timeoutMs = opts.timeoutMs ?? 5000;
+		this.maxRetries = opts.maxRetries ?? 2;
+	}
+
+	/**
+	 * GET リクエスト
+	 * @param path - API パス（例: '/v1/user/assets'）
+	 * @param params - クエリパラメータ
+	 */
+	async get<T>(path: string, params?: Record<string, string>): Promise<T> {
+		let fullPath = path;
+		if (params) {
+			const qs = new URLSearchParams(params).toString();
+			if (qs) fullPath = `${path}?${qs}`;
+		}
+
+		const url = `${BitbankPrivateClient.BASE_URL}${fullPath}`;
+		const headers = createGetAuthHeaders(fullPath);
+
+		return this.request<T>(url, {
+			method: 'GET',
+			headers: {
+				...headers,
+				'Content-Type': 'application/json',
+			},
+		});
+	}
+
+	/**
+	 * POST リクエスト
+	 * @param path - API パス
+	 * @param body - リクエストボディ
+	 */
+	async post<T>(path: string, body: Record<string, unknown>): Promise<T> {
+		const url = `${BitbankPrivateClient.BASE_URL}${path}`;
+		const jsonBody = JSON.stringify(body);
+		const headers = createPostAuthHeaders(jsonBody);
+
+		return this.request<T>(url, {
+			method: 'POST',
+			headers: {
+				...headers,
+				'Content-Type': 'application/json',
+			},
+			body: jsonBody,
+		});
+	}
+
+	/**
+	 * 共通リクエスト処理（リトライ・タイムアウト・エラーハンドリング）
+	 */
+	private async request<T>(url: string, init: RequestInit): Promise<T> {
+		let lastErr: unknown;
+
+		for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+			const ctrl = new AbortController();
+			const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+
+			try {
+				const res = await this.fetcher(url, { ...init, signal: ctrl.signal });
+				clearTimeout(timer);
+
+				// 429 Rate Limit（HTTP レベル）
+				if (res.status === 429) {
+					const retryAfter = res.headers.get('Retry-After');
+					const waitMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : 1000;
+					if (attempt < this.maxRetries) {
+						await new Promise((r) => setTimeout(r, waitMs));
+						continue;
+					}
+					throw new PrivateApiError(
+						`レート制限超過。${retryAfter ? `${retryAfter}秒` : 'しばらく'}待ってから再試行してください`,
+						'rate_limit_error',
+						429,
+					);
+				}
+
+				// 5xx Server Error
+				if (res.status >= 500) {
+					if (attempt < this.maxRetries) {
+						await new Promise((r) => setTimeout(r, 200 * 2 ** attempt));
+						continue;
+					}
+					throw new PrivateApiError(
+						`bitbank サーバーエラー (HTTP ${res.status})。一時的な障害の可能性があります`,
+						'upstream_error',
+						res.status,
+					);
+				}
+
+				// レスポンスボディを取得
+				const body = await res.text().catch(() => '');
+
+				// HTTP エラー（4xx 等）
+				if (!res.ok) {
+					const errorCode = this.extractErrorCode(body);
+					throw this.classifyBitbankError(res.status, errorCode);
+				}
+
+				// Success レスポンスのパース
+				let json: BitbankApiResponse<T>;
+				try {
+					json = JSON.parse(body) as BitbankApiResponse<T>;
+				} catch {
+					throw new PrivateApiError('レスポンスの JSON パースに失敗しました', 'upstream_error');
+				}
+
+				// レートリミット情報を抽出（成功時）
+				this.lastRateLimit = extractRateLimit(res.headers);
+
+				// success: 0 の場合（HTTP 200 でもエラー）
+				if (json.success !== 1) {
+					const errorCode = (json.data as Record<string, unknown>)?.code as number | undefined;
+
+					// レート制限エラーはリトライ
+					if (errorCode != null && RATE_LIMIT_CODES.has(errorCode)) {
+						if (attempt < this.maxRetries) {
+							await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+							continue;
+						}
+					}
+
+					throw this.classifyBitbankError(200, errorCode ?? null);
+				}
+
+				return json.data;
+			} catch (err) {
+				clearTimeout(timer);
+				if (err instanceof PrivateApiError) throw err;
+
+				// AbortError = timeout
+				if (err instanceof Error && err.name === 'AbortError') {
+					lastErr = new PrivateApiError(`タイムアウト (${this.timeoutMs}ms)`, 'upstream_error');
+				} else {
+					lastErr = err;
+				}
+
+				if (attempt < this.maxRetries) {
+					await new Promise((r) => setTimeout(r, 200 * 2 ** attempt));
+				}
+			}
+		}
+
+		if (lastErr instanceof PrivateApiError) throw lastErr;
+		throw new PrivateApiError(lastErr instanceof Error ? lastErr.message : 'ネットワークエラー', 'upstream_error');
+	}
+
+	/** bitbank エラーレスポンスからエラーコードを抽出 */
+	private extractErrorCode(body: string): number | null {
+		try {
+			const parsed = JSON.parse(body);
+			return parsed?.data?.code ?? null;
+		} catch {
+			return null;
+		}
+	}
+
+	/**
+	 * bitbank エラーコードを分類し、適切な PrivateApiError を生成する。
+	 *
+	 * エラーコード体系:
+	 * - 10000 番台: システムエラー（10009 はレート制限）
+	 * - 20000 番台: 認証エラー
+	 * - 30000 番台: 必須パラメータ不足
+	 * - 40000 番台: パラメータ不正
+	 * - 50000 番台: データエラー
+	 * - 60000 番台: 数値制限超過
+	 * - 70000 番台: 取引制限中
+	 */
+	private classifyBitbankError(httpStatus: number, errorCode: number | null): PrivateApiError {
+		// 認証エラー
+		if (errorCode != null && AUTH_ERROR_CODES.has(errorCode)) {
+			const details: Record<number, string> = {
+				20001: 'API 認証に失敗しました',
+				20002: 'API キーが無効です',
+				20003: 'API キーが見つかりません',
+				20004: 'ACCESS-NONCE / ACCESS-REQUEST-TIME が未指定です',
+				20005: '署名が無効です。API シークレットを確認してください',
+			};
+			return new PrivateApiError(details[errorCode] ?? 'API 認証エラー', 'authentication_error', httpStatus, errorCode);
+		}
+
+		// レート制限
+		if (errorCode != null && RATE_LIMIT_CODES.has(errorCode)) {
+			return new PrivateApiError(
+				'リクエスト頻度が高すぎます。しばらく待ってから再試行してください',
+				'rate_limit_error',
+				httpStatus,
+				errorCode,
+			);
+		}
+
+		// メンテナンス / 過負荷
+		if (errorCode != null && MAINTENANCE_CODES.has(errorCode)) {
+			return new PrivateApiError(
+				errorCode === 10007
+					? 'bitbank はメンテナンス中です'
+					: 'bitbank サーバーが過負荷状態です。しばらく待ってから再試行してください',
+				'upstream_error',
+				httpStatus,
+				errorCode,
+			);
+		}
+
+		// HTTP 401/403（エラーコードなし）
+		if (httpStatus === 401 || httpStatus === 403) {
+			return new PrivateApiError(
+				'API キーまたは署名が不正です。bitbank 管理画面でキーを確認してください',
+				'authentication_error',
+				httpStatus,
+				errorCode ?? undefined,
+			);
+		}
+
+		// その他
+		return new PrivateApiError(
+			`bitbank API エラー (HTTP ${httpStatus}${errorCode ? `, code: ${errorCode}` : ''})`,
+			'upstream_error',
+			httpStatus,
+			errorCode ?? undefined,
+		);
+	}
+}
+
+/** デフォルトのシングルトンインスタンス */
+let defaultClient: BitbankPrivateClient | null = null;
+
+export function getDefaultClient(): BitbankPrivateClient {
+	if (!defaultClient) {
+		defaultClient = new BitbankPrivateClient();
+	}
+	return defaultClient;
+}

package/src/private/config.ts

@@ -0,0 +1,25 @@
+/**
+ * Private API の有効化チェック。
+ * BITBANK_API_KEY と BITBANK_API_SECRET の両方が設定されている場合のみ有効。
+ */
+
+export interface PrivateApiConfig {
+	apiKey: string;
+	apiSecret: string;
+}
+
+/** Private API が有効かどうかを返す */
+export function isPrivateApiEnabled(): boolean {
+	return !!(process.env.BITBANK_API_KEY?.trim() && process.env.BITBANK_API_SECRET?.trim());
+}
+
+/**
+ * 環境変数から Private API 設定を読み込む。
+ * 未設定・空白のみの場合は null を返す。
+ */
+export function getPrivateApiConfig(): PrivateApiConfig | null {
+	const apiKey = process.env.BITBANK_API_KEY?.trim();
+	const apiSecret = process.env.BITBANK_API_SECRET?.trim();
+	if (!apiKey || !apiSecret) return null;
+	return { apiKey, apiSecret };
+}