@unified-llm/core/dist/utils/mcp-utils.d.ts

Unified LLM interface (in-memory).

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import type { MCPServerConfig } from "../types/index.js";
type McpTransport = Parameters<Client["connect"]>[0];
export declare function createMcpTransport(server: MCPServerConfig): McpTransport;
export type SanitizedToolCallResultBundle<T = unknown> = {
    /**
     * MCP の callTool() が返した生の結果（参照を保持します）。
     * ここには巨大 base64 が含まれ得るため、LLM 履歴に混ぜないこと。
     */
    rawResult: T;
    /**
     * LLM 履歴に載せても破綻しにくいようにサニタイズした結果。
     * MCP の ToolResult（CallToolResult）形状を維持し、必須フィールドの型を壊しません。
     */
    sanitizedResult: T;
    /**
     * rawResult と sanitizedResult に差分があるか（= サニタイズが実際に適用されたか）。
     * - true: 何らかの短縮/置換が発生している
     * - false: raw と同一（参照も同一）を返している
     */
    isSanitized: boolean;
};
export type SanitizeToolCallResultOptions = {
    /**
     * type:"text" の text を短縮する上限（文字数）。
     * Playwright の snapshot 等で極端に長くなるのを抑制します。
     */
    maxTextChars?: number;
    /**
     * resource_link などの汎用文字列（title/description/name/uri）の上限（文字数）。
     */
    maxStringChars?: number;
    /**
     * image/audio の data、resource の blob がこの長さ以上の場合に「危険」と見做して省略します。
     * （LLM 履歴に混ざるとトークン爆発の主要因）
     */
    binaryOmitThresholdChars?: number;
    /**
     * 省略したバイナリ文字列を置換する文字列。
     * MCP 的に data/blob は string 必須なので、必ず string を返します。
     *
     * デフォルトは空文字（base64 としてもデコード可能＝空バイナリ）。
     */
    binaryReplacement?: string;
    /**
     * 指紋計算に使うサンプル長（先頭N文字）。
     * 巨大 base64 全量を走査しないようにするための上限。
     */
    fingerprintSampleChars?: number;
    /**
     * 指紋（非暗号学的）を付けるか。
     * Edge 互換の軽量指紋（FNV-1a 32bit）です。監査用ハッシュ用途ではありません。
     */
    enableFingerprint?: boolean;
    /**
     * CallToolResult.structuredContent を短縮するか。
     * structuredContent を後段が厳密に期待している場合は false 推奨。
     */
    sanitizeStructuredContent?: boolean;
    /**
     * structuredContent の文字列短縮上限（sanitizeStructuredContent=true の場合のみ）。
     */
    structuredContentMaxStringChars?: number;
};
/**
 * MCP の `client.callTool()` が返す結果を、
 * **(1) rawResult と (2) sanitizedResult に分離**して返します。
 *
 * ## なぜ分離するのか
 * - image/audio/resource.blob が base64 を含む場合、そのまま LLM 履歴に入れると
 *   トークン爆発・履歴欠落・API失敗の原因になります。
 * - しかし後段でバイナリが必要なケース（保存/解析/復元）があるため、
 *   **raw を捨てずに保持**できる形が必要です。
 *
 * ## MCPプロトコル互換性（重要）
 * - `content[]` は維持します。
 * - `type:"image"` / `type:"audio"` の `data` は **string のまま維持**します（必須フィールド）。
 *   省略する場合でも `data` を削除せず、`binaryReplacement`（デフォルトは空文字）に置換します。
 * - `type:"resource"` の `resource.blob` も同様に **string のまま維持**します（必須フィールド）。
 * - 省略・短縮した事実や指紋は `_meta.__sanitizer` に格納します（`_meta` は MCP が許容する拡張領域）。
 *
 * ## 戻り値の使い方（推奨）
 * - LLM へ渡す/履歴に積む：`sanitizedResult` だけ
 * - デバッグ保存/後段処理：`rawResult`（必要に応じて別ストレージへ）
 *
 * @param result MCP の callTool() 戻り値（そのまま渡してOK）
 * @param options サニタイズ閾値・置換文字列等
 */
export declare function sanitizeToolCallResult<T = unknown>(result: T, options?: SanitizeToolCallResultOptions): SanitizedToolCallResultBundle<T>;
export {};
//# sourceMappingURL=mcp-utils.d.ts.map