bitbank-lab-mcp 0.1.0

package/src/schema/types.ts

@@ -0,0 +1,97 @@
+import type { z } from 'zod';
+import type { CandleSchema, CandleTypeEnum, NumericSeriesSchema, TrendLabelEnum } from './base.js';
+import type { ValidateCandleDataDataSchema, ValidateCandleDataMetaSchema } from './candle-validate.js';
+import type {
+	BollingerBandsSeriesSchema,
+	ChartIndicatorsSchema,
+	ChartMetaSchema,
+	ChartPayloadSchema,
+	EmaSeriesFixedSchema,
+	IchimokuSeriesSchema,
+	RenderChartSvgInputSchema,
+	SmaSeriesFixedSchema,
+} from './chart.js';
+import type { GetIndicatorsDataSchema, GetIndicatorsMetaSchema, IndicatorsInternalSchema } from './indicators.js';
+import type {
+	GetCandlesDataSchemaOut,
+	GetCandlesMetaSchemaOut,
+	GetOrderbookDataSchemaOut,
+	GetOrderbookMetaSchemaOut,
+	GetTickerDataSchemaOut,
+	GetTickerMetaSchemaOut,
+	KeyPointSchema,
+	KeyPointsSchema,
+	OrderbookLevelSchema,
+	OrderbookLevelWithCumSchema,
+	OrderbookNormalizedSchema,
+	TickerNormalizedSchema,
+	VolumeStatsSchema,
+} from './market-data.js';
+
+// ═══════════════════════════════════════════════════════════════════
+// Inferred Types — single source of truth (replaces domain.d.ts)
+// ═══════════════════════════════════════════════════════════════════
+
+/** e.g., "btc_jpy" */
+export type Pair = `${string}_${string}`;
+
+// --- Core data types ---
+export type CandleType = z.infer<typeof CandleTypeEnum>;
+export type Candle = z.infer<typeof CandleSchema>;
+export type NumericSeries = z.output<typeof NumericSeriesSchema>;
+export type TickerNormalized = z.infer<typeof TickerNormalizedSchema>;
+export type OrderbookLevel = z.infer<typeof OrderbookLevelSchema>;
+export type OrderbookLevelWithCum = z.infer<typeof OrderbookLevelWithCumSchema>;
+export type OrderbookNormalized = z.infer<typeof OrderbookNormalizedSchema>;
+export type TrendLabel = z.infer<typeof TrendLabelEnum>;
+
+// --- Indicator series ---
+export type IchimokuSeries = z.infer<typeof IchimokuSeriesSchema>;
+export type BollingerBandsSeries = z.infer<typeof BollingerBandsSeriesSchema>;
+export type SmaSeriesFixed = z.infer<typeof SmaSeriesFixedSchema>;
+export type EmaSeriesFixed = z.infer<typeof EmaSeriesFixedSchema>;
+export type ChartIndicators = z.infer<typeof ChartIndicatorsSchema>;
+export type ChartMeta = z.infer<typeof ChartMetaSchema>;
+export type ChartPayload = z.infer<typeof ChartPayloadSchema>;
+export type IndicatorsInternal = z.infer<typeof IndicatorsInternalSchema>;
+
+// --- Tool DTOs ---
+export type GetIndicatorsData = z.infer<typeof GetIndicatorsDataSchema>;
+export type GetIndicatorsMeta = z.infer<typeof GetIndicatorsMetaSchema>;
+export type GetTickerData = z.infer<typeof GetTickerDataSchemaOut>;
+export type GetTickerMeta = z.infer<typeof GetTickerMetaSchemaOut>;
+export type GetOrderbookData = z.infer<typeof GetOrderbookDataSchemaOut>;
+export type GetOrderbookMeta = z.infer<typeof GetOrderbookMetaSchemaOut>;
+export type GetCandlesData = z.infer<typeof GetCandlesDataSchemaOut>;
+export type GetCandlesMeta = z.infer<typeof GetCandlesMetaSchemaOut>;
+export type KeyPoint = z.infer<typeof KeyPointSchema>;
+export type KeyPoints = z.infer<typeof KeyPointsSchema>;
+export type VolumeStats = z.infer<typeof VolumeStatsSchema>;
+
+// --- Chart / render options ---
+export type BbMode = 'default' | 'extended';
+export type IchimokuMode = 'default' | 'extended';
+export type ChartStyle = 'candles' | 'line' | 'depth';
+export type IchimokuOptions = { mode?: IchimokuMode };
+export type RenderChartSvgOptions = z.input<typeof RenderChartSvgInputSchema>;
+
+// --- Result pattern ---
+export interface OkResult<T = Record<string, unknown>, M = Record<string, unknown>> {
+	ok: true;
+	summary: string;
+	data: T;
+	meta: M;
+}
+
+export interface FailResult<M = Record<string, unknown>> {
+	ok: false;
+	summary: string;
+	data: Record<string, unknown>;
+	meta: { errorType: string } & M;
+}
+
+export type Result<T = unknown, M = unknown> = OkResult<T, M> | FailResult<M>;
+
+// --- Candle validation ---
+export type ValidateCandleDataData = z.infer<typeof ValidateCandleDataDataSchema>;
+export type ValidateCandleDataMeta = z.infer<typeof ValidateCandleDataMetaSchema>;

package/src/schemas.d.ts

@@ -0,0 +1,37 @@
+// Auto-typed facade for schemas.js so that schemas.js is the single source of truth.
+// Keep declarations minimal to avoid drift; use z.infer for consumer types.
+import type { z } from 'zod';
+
+export declare const GetTickerInputSchema: z.ZodObject<z.ZodRawShape>;
+export declare const GetOrderbookInputSchema: z.ZodObject<z.ZodRawShape>;
+export declare const GetCandlesInputSchema: z.ZodObject<z.ZodRawShape>;
+export declare const GetIndicatorsInputSchema: z.ZodObject<z.ZodRawShape>;
+
+export declare const CandleTypeEnum: z.ZodTypeAny;
+export declare const RenderChartSvgInputSchema: z.ZodObject<z.ZodRawShape>;
+export declare const RenderChartSvgOutputSchema: z.ZodObject<z.ZodRawShape>;
+
+export type RenderChartSvgInput = z.infer<typeof RenderChartSvgInputSchema>;
+export type RenderChartSvgOutput = z.infer<typeof RenderChartSvgOutputSchema>;
+export type GetTickerInput = z.infer<typeof GetTickerInputSchema>;
+export type GetOrderbookInput = z.infer<typeof GetOrderbookInputSchema>;
+export type GetCandlesInput = z.infer<typeof GetCandlesInputSchema>;
+export type GetIndicatorsInput = z.infer<typeof GetIndicatorsInputSchema>;
+
+export declare const NumericSeriesSchema: z.ZodTypeAny;
+export declare const CandleSchema: z.ZodTypeAny;
+export declare const IchimokuSeriesSchema: z.ZodTypeAny;
+export declare const BollingerBandsSeriesSchema: z.ZodTypeAny;
+export declare const SmaSeriesFixedSchema: z.ZodTypeAny;
+export declare const ChartIndicatorsSchema: z.ZodTypeAny;
+export declare const ChartMetaSchema: z.ZodTypeAny;
+export declare const ChartStatsSchema: z.ZodTypeAny;
+export declare const ChartPayloadSchema: z.ZodTypeAny;
+export declare const TrendLabelEnum: z.ZodTypeAny;
+export declare const IndicatorsInternalSchema: z.ZodTypeAny;
+export declare const GetIndicatorsDataSchema: z.ZodTypeAny;
+export declare const GetIndicatorsMetaSchema: z.ZodTypeAny;
+export declare const GetTickerOutputSchema: z.ZodTypeAny;
+export declare const GetOrderbookOutputSchema: z.ZodTypeAny;
+export declare const GetCandlesOutputSchema: z.ZodTypeAny;
+export declare const GetIndicatorsOutputSchema: z.ZodTypeAny;

package/src/schemas.ts

@@ -0,0 +1,7 @@
+// ── Schema barrel ──
+// 全スキーマは src/schema/ 配下のドメインモジュールに分割。
+// このファイルは後方互換のため re-export のみ行う。
+
+// ── Private API schemas（src/private/schemas.ts から re-export） ──
+export * from './private/schemas.js';
+export * from './schema/index.js';

package/src/server.ts

@@ -0,0 +1,405 @@
+import './env.js'; // must be first — loads .env before other modules read process.env
+import { randomUUID } from 'node:crypto';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { z } from 'zod';
+import { getErrorMessage } from '../lib/error.js';
+import { logError, logToolRun } from '../lib/logger.js';
+import { type PromptDef, prompts as promptDefs } from './prompts.js';
+import { appResourceRegistry } from './resources/app-resources.js';
+import { allToolDefs } from './tool-registry.js';
+
+const server = new McpServer({ name: 'bitbank-mcp', version: '0.4.2' });
+// Explicit registries for tools/prompts to improve STDIO inspector compatibility
+const registeredTools: Array<{
+	name: string;
+	description: string;
+	inputSchema: Record<string, unknown>;
+	_meta?: Record<string, unknown>;
+}> = [];
+const registeredPrompts: Array<{ name: string; description: string }> = [];
+
+type TextContent = { type: 'text'; text: string; _meta?: Record<string, unknown> };
+type ToolReturn = { content: TextContent[]; structuredContent?: Record<string, unknown> };
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+const respond = (result: unknown): ToolReturn => {
+	// 優先順位: custom content > summary > safe JSON fallback
+	let text = '';
+	if (isPlainObject(result)) {
+		const r = result;
+		// ツールが content を提供している場合（配列 or 文字列）を優先
+		if (Array.isArray(r.content)) {
+			const first = (r.content as unknown[]).find(
+				(c): c is { type: 'text'; text: string } => isPlainObject(c) && c.type === 'text' && typeof c.text === 'string',
+			);
+			if (first) {
+				text = first.text;
+			}
+		} else if (typeof r.content === 'string') {
+			text = r.content;
+		}
+		// 上記で未決定なら summary を採用
+		if (!text && typeof r.summary === 'string') {
+			text = r.summary;
+		}
+	}
+	// それでも空の場合は安全な短縮JSONにフォールバック
+	if (!text) {
+		try {
+			const json = JSON.stringify(
+				result,
+				(_key, value) => {
+					if (typeof value === 'string' && value.length > 2000) return `…omitted (${value.length} chars)`;
+					return value;
+				},
+				2,
+			);
+			text = json.length > 4000 ? `${json.slice(0, 4000)}\n…(truncated)…` : json;
+		} catch {
+			text = String(result);
+		}
+	}
+	// handler が McpResponse shape (`{ content, structuredContent: Result }`) を返している場合、
+	// 内側の structuredContent をそのまま採用する（二重ネストを防ぐ）。
+	// MCP Apps (SEP-1865) の iframe は `structuredContent` を直接参照するため、
+	// `{ structuredContent: { content, structuredContent: Result } }` のように包んでしまうと
+	// クライアント側で Result を取り出せない。
+	// Result shape (`{ ok, summary, data, meta }`) を直接返している場合は result 自体を採用する。
+	const structured = isPlainObject(result)
+		? isPlainObject(result.structuredContent)
+			? result.structuredContent
+			: result
+		: undefined;
+	return {
+		content: [{ type: 'text', text }],
+		...(structured ? { structuredContent: structured } : {}),
+	};
+};
+
+/** Zod スキーマ → MCP inspector 用 JSON Schema に変換する。
+ *  Zod 4 組み込みの toJSONSchema を使い、MCP 不要の additionalProperties を除去する。 */
+function zodToInputJsonSchema(schema: z.ZodTypeAny): Record<string, unknown> {
+	const json = z.toJSONSchema(schema, { target: 'openApi3' }) as Record<string, unknown>;
+	delete json.additionalProperties;
+	// default 付きフィールドは required から除外（Zod が parse 時に適用するため MCP 入力では不要）
+	const props = json.properties as Record<string, Record<string, unknown>> | undefined;
+	if (Array.isArray(json.required) && props) {
+		json.required = (json.required as string[]).filter((k) => !('default' in (props[k] ?? {})));
+		if ((json.required as string[]).length === 0) delete json.required;
+	}
+	return json;
+}
+
+/** SDK の registerTool に渡すための ZodRawShape を取得する。
+ *  .describe() / .default() / .optional() 等のラッパーを再帰的にアンラップする。 */
+function getRawShape(s: z.ZodTypeAny): z.ZodRawShape {
+	type Unwrappable = {
+		shape?: z.ZodRawShape;
+		_def?: { schema?: z.ZodTypeAny; innerType?: z.ZodTypeAny; in?: z.ZodTypeAny };
+	};
+	let cur = s as Unwrappable;
+	for (let i = 0; i < 6; i++) {
+		if (cur.shape) break;
+		const def = cur._def;
+		if (!def) break;
+		// Zod 3: ZodEffects uses _def.schema / Zod 4: uses _def.in
+		if (def.schema) {
+			cur = def.schema as Unwrappable;
+			continue;
+		}
+		if (def.in) {
+			cur = def.in as Unwrappable;
+			continue;
+		}
+		if (def.innerType) {
+			cur = def.innerType as Unwrappable;
+			continue;
+		}
+		break;
+	}
+	if (cur.shape) return cur.shape;
+	throw new Error('inputSchema must be or wrap a ZodObject');
+}
+
+function registerToolWithLog(
+	name: string,
+	schema: { description: string; inputSchema: z.ZodTypeAny; _meta?: Record<string, unknown> },
+	handler: (input: Record<string, unknown>, extra?: Record<string, unknown>) => Promise<unknown>,
+) {
+	// Build JSON Schema for listing
+	const inputSchemaJson = zodToInputJsonSchema(schema.inputSchema);
+	registeredTools.push({
+		name,
+		description: schema.description,
+		inputSchema: inputSchemaJson,
+		...(schema._meta ? { _meta: schema._meta } : {}),
+	});
+
+	// SDK の registerTool は第2引数に { inputSchema: ZodRawShape } を要求するが
+	// 型定義が厳密すぎて直接渡せないため、ここでキャストを集約する
+	const toolConfig: Record<string, unknown> = {
+		description: schema.description,
+		inputSchema: getRawShape(schema.inputSchema),
+	};
+	if (schema._meta) toolConfig._meta = schema._meta;
+	(server as unknown as { registerTool: (n: string, s: unknown, h: unknown) => void }).registerTool(
+		name,
+		toolConfig,
+		async (input: Record<string, unknown>, extra?: Record<string, unknown>) => {
+			const TOOL_TIMEOUT_MS = 60_000;
+			const t0 = Date.now();
+			try {
+				let timeoutId: ReturnType<typeof setTimeout> | undefined;
+				const timeoutPromise = new Promise<never>((_, reject) => {
+					timeoutId = setTimeout(
+						() => reject(new Error(`ツール実行がタイムアウトしました (${TOOL_TIMEOUT_MS / 1000}秒)`)),
+						TOOL_TIMEOUT_MS,
+					);
+				});
+				// elicitation 等で server.elicitInput / getClientCapabilities を使うツール向けに、
+				// SDK から渡される extra に McpServer インスタンスを合流させる。
+				const handlerExtra = { ...extra, server };
+				const result = await Promise.race([handler(input, handlerExtra), timeoutPromise]).finally(() => {
+					if (timeoutId) clearTimeout(timeoutId);
+				});
+				const ms = Date.now() - t0;
+				logToolRun({ tool: name, input, result, ms });
+				return respond(result);
+			} catch (err: unknown) {
+				const ms = Date.now() - t0;
+				logError(name, err, input);
+				const message = getErrorMessage(err);
+				return {
+					content: [{ type: 'text', text: `内部エラー: ${message || '不明なエラー'}` }],
+					structuredContent: {
+						ok: false,
+						summary: `内部エラー: ${message || '不明なエラー'}`,
+						meta: { ms, errorType: 'internal' },
+					},
+				};
+			}
+		},
+	);
+}
+
+// === Auto-register all tools from registry ===
+for (const def of allToolDefs) {
+	registerToolWithLog(
+		def.name,
+		{ description: def.description, inputSchema: def.inputSchema, ...(def._meta ? { _meta: def._meta } : {}) },
+		def.handler,
+	);
+}
+
+// === Register prompts (SDK 形式に寄せた最小導入) ===
+
+type PromptMessage = PromptDef['messages'][number];
+type ContentBlock = PromptMessage['content'][number];
+
+function toSdkMessages(msgs: PromptMessage[]) {
+	return msgs.map((msg) => {
+		const blocks: ContentBlock[] = Array.isArray(msg.content) ? msg.content : [];
+		const text = blocks
+			.map((b) => {
+				if (b.type === 'text' && typeof b.text === 'string') return b.text;
+				// tool_code ブロック: PromptDef の型定義外だが実データに存在する
+				if (b.type === 'tool_code') {
+					const tc = b as unknown as { tool_name?: string; tool_input?: unknown };
+					const tool = tc.tool_name || 'tool';
+					const args = tc.tool_input ? JSON.stringify(tc.tool_input) : '{}';
+					return `Call ${tool} with ${args}`;
+				}
+				return '';
+			})
+			.filter(Boolean)
+			.join('\n');
+		return {
+			role: msg.role === 'assistant' ? ('assistant' as const) : ('user' as const),
+			content: { type: 'text' as const, text },
+		};
+	});
+}
+
+function registerPromptSafe(name: string, def: Pick<PromptDef, 'description' | 'messages'>) {
+	const s = server as unknown as {
+		registerPrompt?: (name: string, meta: { description: string }, cb: () => unknown) => void;
+	};
+	if (typeof s.registerPrompt === 'function') {
+		registeredPrompts.push({ name, description: def.description });
+		s.registerPrompt(name, { description: def.description }, () => ({
+			description: def.description,
+			messages: toSdkMessages(def.messages),
+		}));
+	}
+}
+
+// === Register prompts from src/prompts.ts ===
+for (const p of promptDefs) {
+	registerPromptSafe(p.name, p);
+}
+
+// === Register MCP Apps UI resources ===
+// SDK の `registerResource` を使うことで `resources/list` と `resources/read` の
+// JSON-RPC ルーティングが SDK 内部で正しく行われる。
+// （以前の `setHandler('resources/...')` は SDK が要求する Zod スキーマではなく
+//  文字列を渡していたため silently no-op となり、本番で `Method not found` を返していた）
+for (const r of appResourceRegistry) {
+	const config: Record<string, unknown> = {
+		description: r.description,
+		mimeType: r.mimeType,
+		...(r.listMeta ? { _meta: r.listMeta } : {}),
+	};
+	(
+		server as unknown as {
+			registerResource: (
+				name: string,
+				uri: string,
+				config: Record<string, unknown>,
+				cb: (uri: URL) => Promise<unknown> | unknown,
+			) => void;
+		}
+	).registerResource(r.name, r.uri, config, async () => ({
+		contents: [
+			{
+				uri: r.uri,
+				mimeType: r.mimeType,
+				text: await r.read(),
+				...(r.contentMeta ? { _meta: r.contentMeta } : {}),
+			},
+		],
+	}));
+}
+
+// === トランスポート接続 ===
+// SDK の McpServer.connect() は 1:1 でトランスポートを結合する (SDK issue #961)。
+// MCP_ENABLE_HTTP=1 + PORT が設定されている場合は HTTP を優先し、stdio は接続しない。
+const enableHttp = process.env.MCP_ENABLE_HTTP === '1';
+const httpPort = (() => {
+	const p = Number(process.env.PORT);
+	return Number.isFinite(p) && p > 0 ? p : NaN;
+})();
+const useHttp = enableHttp && Number.isFinite(httpPort);
+
+if (!useHttp) {
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+
+// SDK の McpServer は setRequestHandler を public 型として export していないため、
+// 低レベル API アクセスのキャストをこのヘルパーに集約する。
+type HandlerFn = (request: unknown) => Promise<unknown>;
+function setHandler(method: string, fn: HandlerFn) {
+	(server as unknown as { setRequestHandler?: (method: string, fn: HandlerFn) => void }).setRequestHandler?.(
+		method,
+		fn,
+	);
+}
+
+// Fallback handlers to ensure list operations work over STDIO
+try {
+	setHandler('tools/list', async () => ({
+		tools: registeredTools.map((t) => ({
+			name: t.name,
+			description: t.description,
+			inputSchema: t.inputSchema,
+			...(t._meta ? { _meta: t._meta } : {}),
+		})),
+	}));
+	setHandler('prompts/list', async () => ({
+		prompts: registeredPrompts.map((p) => ({ name: p.name, description: p.description })),
+	}));
+	// prompts/get: convert content arrays to single TextContent objects per MCP spec
+	setHandler('prompts/get', async (request: unknown) => {
+		try {
+			const params = (request as { params?: { name?: string } })?.params;
+			const name = params?.name;
+			console.error('[prompts/get] Requested name:', name);
+			if (!name) {
+				throw new Error('Prompt name is required');
+			}
+
+			const promptDef = promptDefs.find((p) => p.name === name);
+			if (!promptDef) {
+				console.error('[prompts/get] ERROR: Prompt not found:', name);
+				throw new Error(`Prompt not found: ${name}`);
+			}
+
+			console.error('[prompts/get] Found prompt:', name, 'with', promptDef.messages.length, 'messages');
+			// prompts/get はテキストブロックのみ抽出（tool_code は除外）
+			const messages = promptDef.messages.map((msg) => {
+				const blocks: ContentBlock[] = Array.isArray(msg.content) ? msg.content : [];
+				const text = blocks
+					.filter((b): b is ContentBlock & { text: string } => b.type === 'text' && typeof b.text === 'string')
+					.map((b) => b.text)
+					.join('\n');
+				return {
+					role: msg.role === 'assistant' ? ('assistant' as const) : ('user' as const),
+					content: { type: 'text' as const, text },
+				};
+			});
+			return { description: promptDef.description, messages };
+		} catch (error: unknown) {
+			console.error('[prompts/get] EXCEPTION:', getErrorMessage(error));
+			throw error;
+		}
+	});
+} catch {}
+
+// Optional HTTP transport (/mcp) when MCP_ENABLE_HTTP=1 + PORT
+if (useHttp) {
+	try {
+		const { default: express } = await import('express');
+		const app = express();
+		app.use(express.json());
+		const allowedHosts = (process.env.ALLOWED_HOSTS || '127.0.0.1,localhost')
+			.split(',')
+			.map((s) => s.trim())
+			.filter(Boolean);
+		const allowedOrigins = (process.env.ALLOWED_ORIGINS || '')
+			.split(',')
+			.map((s) => s.trim())
+			.filter(Boolean);
+
+		// StreamableHTTPServerTransport のコンストラクタ引数・戻り値が SDK で正確に export されていないため
+		// Transport 互換型にキャストを集約する
+		type Transport = Parameters<typeof server.connect>[0];
+		type HandleRequestFn = (
+			req: import('node:http').IncomingMessage,
+			res: import('node:http').ServerResponse,
+			body?: unknown,
+		) => Promise<void>;
+		const HttpTransport = StreamableHTTPServerTransport as unknown as new (
+			opts: Record<string, unknown>,
+		) => Transport & {
+			handleRequest?: HandleRequestFn;
+		};
+		const httpTransport = new HttpTransport({
+			path: '/mcp',
+			sessionIdGenerator: () => randomUUID(),
+			enableDnsRebindingProtection: true,
+			...(allowedHosts.length ? { allowedHosts } : {}),
+			...(allowedOrigins.length ? { allowedOrigins } : {}),
+		});
+
+		await server.connect(httpTransport);
+
+		// SDK 公式の handleRequest を使って HTTP リクエストを処理する
+		if (typeof httpTransport.handleRequest === 'function') {
+			const handle = httpTransport.handleRequest.bind(httpTransport);
+			app.use('/mcp', (req, res, next) => {
+				handle(req, res, req.body).catch(next);
+			});
+		}
+		app.listen(httpPort, () => {
+			// no stdout/stderr output to avoid STDIO transport contamination
+		});
+	} catch (e) {
+		// eslint-disable-next-line no-console
+		console.warn('HTTP transport setup skipped:', getErrorMessage(e));
+	}
+}

package/src/tool-definition.ts

@@ -0,0 +1,44 @@
+import type { z } from 'zod';
+import type { Result } from './schemas.js';
+
+/** SVG 等を直接返すハンドラ用の事前フォーマット済み MCP レスポンス */
+export interface McpResponse {
+	content: Array<{ type: string; text: string }>;
+	structuredContent: Record<string, unknown>;
+}
+
+/**
+ * ハンドラに渡される MCP リクエストコンテキスト。
+ *
+ * elicitation/sampling 等のサーバー → クライアント呼び出しを行うツール用。
+ * SDK の `RequestHandlerExtra` をそのまま受け取れるよう構造的型で受ける。
+ * `server` プロパティは server.ts 側で `McpServer` を合流させて注入する。
+ */
+export interface ToolHandlerExtra {
+	[key: string]: unknown;
+}
+
+/**
+ * MCP ツール定義。各ツールファイル（または src/handlers/）で `toolDef` として export する。
+ * server.ts は tool-registry.ts 経由でこの定義を自動収集し registerToolWithLog に渡す。
+ *
+ * ツール追加/改修時は toolDef を更新するだけで server.ts の変更は不要。
+ */
+export interface ToolDefinition {
+	/** MCP ツール名 (e.g. 'get_ticker') */
+	name: string;
+	/** ツール説明（LLM 向け） */
+	description: string;
+	/** Zod 入力スキーマ */
+	inputSchema: z.ZodTypeAny;
+	/**
+	 * MCP ハンドラ（入力を受けて結果を返す）。respond() で自動ラップされる。
+	 * 第2引数 `extra` は elicitation 等で SDK のサーバー機能にアクセスする必要があるツールのみ参照する。
+	 */
+	handler(args: Record<string, unknown>, extra?: ToolHandlerExtra): Promise<Result | McpResponse>;
+	/**
+	 * MCP ツール メタデータ。MCP Apps (SEP-1865) の `_meta.ui.resourceUri` 等を保持する。
+	 * 未対応ホストでは無視される（Progressive Enhancement）。
+	 */
+	_meta?: Record<string, unknown>;
+}