@huyooo/ai-chat-core 0.2.45 → 0.3.3

package/src/tool-manager/mcp-provider.ts

@@ -0,0 +1,509 @@
+/**
+ * McpProvider — 单个 MCP Server 的工具提供者
+ *
+ * 每个 MCP Server 连接对应一个 McpProvider 实例。
+ *
+ * 核心能力：
+ * - 连接 MCP Server（stdio / streamableHttp / sse）
+ * - 自动发现工具并适配为 Tool 接口
+ * - 监听 tools/list_changed，自动刷新 + 变更通知
+ * - MCP 错误 → throwToolError 对齐
+ * - 连接状态事件通知
+ * - 分层重连策略：
+ *     streamableHttp → SDK 内置 SSE 流级重连 + 应用层会话级重连
+ *     stdio / sse    → 应用层指数退避重连
+ * - 描述符缓存
+ */
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import type { Tool, JsonSchemaObject, JsonSchemaProperty } from '../types';
+import { throwToolError } from '../types';
+import type {
+  McpProviderExtended,
+  McpServerConfig,
+  McpConnectionStatus,
+  McpConnectionInfo,
+  ToolDescriptor,
+  ToolChangeListener,
+  ToolChangeEvent,
+  ConnectionStatusListener,
+  ConnectionStatusEvent,
+} from './types';
+import { createModuleLogger } from '../logger';
+import { createToolDescriptor, matchesToolDescriptorRef } from './identity';
+
+const logger = createModuleLogger('MCP');
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null;
+}
+
+/** 从 MCP content 数组中提取文本 */
+function extractContentText(content: unknown): string {
+  const texts: string[] = [];
+  if (Array.isArray(content)) {
+    for (const item of content) {
+      if (isRecord(item)) {
+        if (item.type === 'text' && typeof item.text === 'string') {
+          texts.push(item.text);
+        } else if (item.type === 'image') {
+          texts.push(`[image: ${item.mimeType || 'unknown'}]`);
+        } else if (item.type === 'resource') {
+          texts.push(JSON.stringify(item));
+        }
+      }
+    }
+  }
+  return texts.join('\n') || JSON.stringify(content);
+}
+
+/** 递归转换 JSON Schema 属性 */
+function convertProperty(prop: Record<string, unknown>): JsonSchemaProperty {
+  const result: JsonSchemaProperty = {
+    type: typeof prop.type === 'string' ? prop.type : 'string',
+  };
+  if (typeof prop.description === 'string') result.description = prop.description;
+  if (Array.isArray(prop.enum)) result.enum = prop.enum;
+  if (isRecord(prop.items)) {
+    result.items = convertProperty(prop.items);
+  }
+  if (isRecord(prop.properties)) {
+    result.properties = {};
+    for (const [key, value] of Object.entries(prop.properties)) {
+      if (isRecord(value)) {
+        result.properties[key] = convertProperty(value);
+      }
+    }
+  }
+  if (Array.isArray(prop.required)) {
+    result.required = prop.required.filter((r): r is string => typeof r === 'string');
+  }
+  return result;
+}
+
+/** 将 MCP inputSchema 转换为 JsonSchemaObject */
+function convertSchema(inputSchema: Record<string, unknown>): JsonSchemaObject {
+  const properties: Record<string, JsonSchemaProperty> = {};
+  const required: string[] = [];
+
+  if (isRecord(inputSchema.properties)) {
+    for (const [key, value] of Object.entries(inputSchema.properties)) {
+      if (isRecord(value)) {
+        properties[key] = convertProperty(value);
+      }
+    }
+  }
+  if (Array.isArray(inputSchema.required)) {
+    required.push(...inputSchema.required.filter((r): r is string => typeof r === 'string'));
+  }
+
+  return {
+    type: 'object',
+    properties,
+    required: required.length > 0 ? required : undefined,
+  };
+}
+
+export function createMcpProvider(config: McpServerConfig & { source?: import('../governance/types').AssetSource }): McpProviderExtended {
+  const { name, source: configSource } = config;
+  const providerSource = configSource ?? 'bundled';
+  let client: Client | null = null;
+  let transport: StdioClientTransport | SSEClientTransport | StreamableHTTPClientTransport | null = null;
+  let status: McpConnectionStatus = 'disconnected';
+  let error: string | undefined;
+  let lastConnectedAt: number | undefined;
+  let currentReconnectAttempts = 0;
+  let intentionalClose = false;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  /** streamableHttp 会话 ID（重连时复用以恢复会话） */
+  let lastSessionId: string | undefined = config.transport === 'streamableHttp'
+    ? config.sessionId
+    : undefined;
+
+  const tools = new Map<string, Tool>();
+  const listeners = new Set<ToolChangeListener>();
+  const statusListeners = new Set<ConnectionStatusListener>();
+  let cachedDescriptors: ToolDescriptor[] = [];
+
+  function emit(event: ToolChangeEvent) {
+    for (const fn of listeners) fn(event);
+  }
+
+  function emitStatus() {
+    const e: ConnectionStatusEvent = { provider: name, status, error };
+    for (const fn of statusListeners) fn(e);
+  }
+
+  function rebuildCache() {
+    cachedDescriptors = Array.from(tools.values()).map(toDescriptor);
+  }
+
+  function toDescriptor(tool: Tool): ToolDescriptor {
+    return createToolDescriptor(tool, name, providerSource, { category: 'mcp' });
+  }
+
+  /** 将 MCP 工具转换为 Tool 接口 */
+  function adaptTool(
+    mcpTool: { name: string; description?: string; inputSchema: Record<string, unknown> },
+    mcpClient: Client,
+  ): Tool {
+    const parameters = convertSchema(mcpTool.inputSchema);
+    return {
+      name: mcpTool.name,
+      assetId: name,
+      description: mcpTool.description || `MCP tool from ${name}`,
+      parameters,
+      execute: async (args: Record<string, unknown>) => {
+        const result = await mcpClient.callTool({
+          name: mcpTool.name,
+          arguments: args,
+        });
+        const text = extractContentText(result.content);
+        if (result.isError) {
+          throwToolError({ message: text, code: 'OPERATION_FAILED', retryable: true });
+        }
+        return { text, _summary: text };
+      },
+    };
+  }
+
+  /** 处理 MCP Server 推送的工具列表变更 */
+  function handleToolsListChanged(
+    mcpTools: Array<{ name: string; description?: string; inputSchema: Record<string, unknown> }>,
+  ) {
+    if (!client || status !== 'connected') return;
+
+    const oldNames = new Set(tools.keys());
+    const newNames = new Set(mcpTools.map(t => t.name));
+
+    const removedNames = [...oldNames].filter(n => !newNames.has(n));
+    const removedDescriptors: ToolDescriptor[] = [];
+    for (const rn of removedNames) {
+      const t = tools.get(rn);
+      if (t) removedDescriptors.push(toDescriptor(t));
+      tools.delete(rn);
+    }
+
+    const addedDescriptors: ToolDescriptor[] = [];
+    for (const mt of mcpTools) {
+      const adapted = adaptTool(mt, client);
+      tools.set(adapted.name, adapted);
+      if (!oldNames.has(adapted.name)) {
+        addedDescriptors.push(toDescriptor(adapted));
+      }
+    }
+
+    rebuildCache();
+
+    logger.info(
+      { serverName: name, added: addedDescriptors.map(d => d.name), removed: removedNames },
+      `[${name}] 工具列表已更新: +${addedDescriptors.length} -${removedNames.length}`,
+    );
+
+    if (removedDescriptors.length > 0) {
+      emit({ type: 'removed', tools: removedDescriptors, provider: name });
+    }
+    if (addedDescriptors.length > 0) {
+      emit({ type: 'added', tools: addedDescriptors, provider: name });
+    }
+  }
+
+  // ══════════════════════ 重连逻辑 ══════════════════════
+
+  function cancelReconnect() {
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+  }
+
+  function scheduleReconnect() {
+    if (intentionalClose) return;
+
+    // streamableHttp 默认启用应用层重连（SDK 只处理 SSE 流级，会话断开仍需应用层恢复）
+    const reconnectEnabled = config.transport === 'streamableHttp'
+      ? config.reconnect?.enabled !== false
+      : config.reconnect?.enabled === true;
+    if (!reconnectEnabled) return;
+
+    const maxRetries = config.reconnect?.maxRetries ?? 5;
+    const initialDelay = config.reconnect?.initialDelayMs ?? 1000;
+    const maxDelay = config.reconnect?.maxDelayMs ?? 30000;
+
+    if (currentReconnectAttempts >= maxRetries) {
+      status = 'error';
+      error = `重连失败（已尝试 ${maxRetries} 次）`;
+      emitStatus();
+      logger.error({ name, attempts: maxRetries }, `[${name}] 重连次数耗尽`);
+      return;
+    }
+
+    const baseDelay = Math.min(initialDelay * Math.pow(2, currentReconnectAttempts), maxDelay);
+    const jitter = Math.random() * 0.3 * baseDelay;
+    const delay = Math.round(baseDelay + jitter);
+    currentReconnectAttempts++;
+
+    logger.info(
+      { name, attempt: currentReconnectAttempts, delay },
+      `[${name}] ${delay}ms 后重连 (${currentReconnectAttempts}/${maxRetries})`,
+    );
+
+    reconnectTimer = setTimeout(async () => {
+      try {
+        await provider.reconnect();
+        currentReconnectAttempts = 0;
+        logger.info({ name }, `[${name}] 重连成功`);
+      } catch {
+        scheduleReconnect();
+      }
+    }, delay);
+  }
+
+  /**
+   * 非预期断连处理
+   *
+   * streamableHttp: SDK 已处理 SSE 流级断线重连，Client.onclose 代表会话级断开
+   * stdio / sse:    所有断线都走应用层重连
+   */
+  function handleUnexpectedClose() {
+    if (intentionalClose) return;
+    status = 'disconnected';
+    error = '连接意外断开';
+    emitStatus();
+    logger.warn({ name }, `[${name}] 连接意外断开`);
+    scheduleReconnect();
+  }
+
+  // ══════════════════════ Provider 实现 ══════════════════════
+
+  const provider: McpProviderExtended = {
+    id: name,
+    source: providerSource,
+
+    async init() {
+      cancelReconnect();
+      logger.info({ name }, `[${name}] 正在连接...`);
+      status = 'connecting';
+      emitStatus();
+
+      const mcpClient = new Client(
+        { name: 'ai-chat-mcp-client', version: '1.0.0' },
+        {
+          listChanged: {
+            tools: {
+              debounceMs: 300,
+              onChanged: (err: unknown, mcpTools: Array<{ name: string; description?: string; inputSchema: Record<string, unknown> }> | null) => {
+                if (err) {
+                  logger.error({ name, error: err }, `[${name}] 工具列表刷新失败`);
+                  return;
+                }
+                handleToolsListChanged(mcpTools ?? []);
+              },
+            },
+          },
+        },
+      );
+
+      let mcpTransport: StdioClientTransport | SSEClientTransport | StreamableHTTPClientTransport;
+
+      if (config.transport === 'stdio') {
+        if (!config.command) throw new Error(`[${name}] stdio 模式必须指定 command`);
+        mcpTransport = new StdioClientTransport({
+          command: config.command,
+          args: config.args,
+          env: config.env,
+          cwd: config.cwd,
+        });
+      } else if (config.transport === 'streamableHttp') {
+        if (!config.url) throw new Error(`[${name}] streamableHttp 模式必须指定 url`);
+        const httpTransport = new StreamableHTTPClientTransport(
+          new URL(config.url),
+          {
+            requestInit: config.headers ? { headers: config.headers } : undefined,
+            sessionId: lastSessionId,
+            reconnectionOptions: config.reconnectionOptions ? {
+              initialReconnectionDelay: config.reconnectionOptions.initialReconnectionDelay ?? 1000,
+              maxReconnectionDelay: config.reconnectionOptions.maxReconnectionDelay ?? 30000,
+              reconnectionDelayGrowFactor: config.reconnectionOptions.reconnectionDelayGrowFactor ?? 1.5,
+              maxRetries: config.reconnectionOptions.maxRetries ?? 2,
+            } : undefined,
+          },
+        );
+        mcpTransport = httpTransport;
+      } else if (config.transport === 'sse') {
+        if (!config.url) throw new Error(`[${name}] sse 模式必须指定 url`);
+        logger.warn({ name }, `[${name}] SSEClientTransport 已被 SDK 标记 deprecated，建议迁移到 streamableHttp`);
+        mcpTransport = new SSEClientTransport(
+          new URL(config.url),
+          config.headers ? { requestInit: { headers: config.headers } } : undefined,
+        );
+      } else {
+        throw new Error(`[${name}] 不支持的传输方式`);
+      }
+
+      try {
+        await mcpClient.connect(mcpTransport);
+
+        // 断连检测：Client.onclose 在连接关闭时触发
+        mcpClient.onclose = handleUnexpectedClose;
+
+        client = mcpClient;
+        transport = mcpTransport;
+        status = 'connected';
+        lastConnectedAt = Date.now();
+        error = undefined;
+
+        // 保存 sessionId 供重连时复用
+        if (mcpTransport instanceof StreamableHTTPClientTransport) {
+          lastSessionId = mcpTransport.sessionId;
+        }
+
+        emitStatus();
+        logger.info({ name }, `[${name}] 已连接`);
+
+        // 发现工具
+        const { tools: mcpTools } = await mcpClient.listTools();
+        const descriptors: ToolDescriptor[] = [];
+        for (const mt of mcpTools) {
+          const adapted = adaptTool(mt, mcpClient);
+          tools.set(adapted.name, adapted);
+          descriptors.push(toDescriptor(adapted));
+        }
+        rebuildCache();
+
+        logger.info(
+          { name, toolCount: tools.size, toolNames: [...tools.keys()] },
+          `[${name}] 发现 ${tools.size} 个工具`,
+        );
+
+        if (descriptors.length > 0) {
+          emit({ type: 'added', tools: descriptors, provider: name });
+        }
+      } catch (e) {
+        status = 'error';
+        error = e instanceof Error ? e.message : String(e);
+        emitStatus();
+        logger.error({ name, error }, `[${name}] 连接失败`);
+        throw e;
+      }
+    },
+
+    async destroy() {
+      cancelReconnect();
+      intentionalClose = true;
+
+      const removedDescriptors = cachedDescriptors.slice();
+
+      // streamableHttp: 主动通知服务端终止会话
+      if (transport instanceof StreamableHTTPClientTransport) {
+        try { await transport.terminateSession(); } catch { }
+      }
+
+      if (client) {
+        try {
+          await client.close();
+          logger.info({ name }, `[${name}] 已断开`);
+        } catch (e) {
+          logger.error({ name, error: e }, `[${name}] 断开失败`);
+        }
+      }
+
+      client = null;
+      transport = null;
+      status = 'disconnected';
+      tools.clear();
+      cachedDescriptors = [];
+
+      if (removedDescriptors.length > 0) {
+        emit({ type: 'removed', tools: removedDescriptors, provider: name });
+      }
+
+      listeners.clear();
+      statusListeners.clear();
+      intentionalClose = false;
+    },
+
+    async reconnect() {
+      cancelReconnect();
+
+      // 记录旧工具用于 diff
+      const oldNames = new Set(tools.keys());
+      const removedDescriptors = cachedDescriptors.slice();
+
+      // 静默断开（不触发 handleUnexpectedClose）
+      intentionalClose = true;
+      if (client) {
+        try { await client.close(); } catch { }
+      }
+      client = null;
+      transport = null;
+      intentionalClose = false;
+
+      tools.clear();
+      cachedDescriptors = [];
+
+      // 通知旧工具移除（标记 reconnecting 让 manager 自动恢复会话）
+      if (removedDescriptors.length > 0) {
+        emit({ type: 'removed', tools: removedDescriptors, provider: name, reconnecting: true });
+      }
+
+      // 重新初始化（会 emit 'added' 事件）
+      await provider.init();
+    },
+
+    getDescriptors(): ToolDescriptor[] {
+      return cachedDescriptors.slice();
+    },
+
+    async loadTool(ref: string): Promise<Tool | null> {
+      for (const tool of tools.values()) {
+        if (matchesToolDescriptorRef(toDescriptor(tool), ref)) return tool;
+      }
+      return null;
+    },
+
+    addChangeListener(listener: ToolChangeListener) {
+      listeners.add(listener);
+    },
+
+    removeChangeListener(listener: ToolChangeListener) {
+      listeners.delete(listener);
+    },
+
+    addConnectionStatusListener(listener: ConnectionStatusListener) {
+      statusListeners.add(listener);
+    },
+
+    removeConnectionStatusListener(listener: ConnectionStatusListener) {
+      statusListeners.delete(listener);
+    },
+
+    getStatus(): McpConnectionStatus {
+      return status;
+    },
+
+    getError(): string | undefined {
+      return error;
+    },
+
+    getConfig(): McpServerConfig {
+      return config;
+    },
+
+    getConnectionInfo(): McpConnectionInfo {
+      return {
+        name,
+        status,
+        toolCount: tools.size,
+        error,
+        lastConnectedAt,
+        reconnectAttempts: currentReconnectAttempts,
+      };
+    },
+  };
+
+  return provider;
+}

package/src/tool-manager/summaries.ts

@@ -0,0 +1,136 @@
+/**
+ * Tool / MCP 管理摘要与详情构造
+ *
+ * - 从 ToolDescriptor、连接快照生成 Managed*Summary / Detail
+ */
+
+import {
+  createAssetSummaryBase,
+  createLocalMcpServerGovernance,
+  createLocalToolGovernance,
+} from '../governance';
+import type {
+  ManagedMcpServerDetail,
+  ManagedToolDetail,
+  ManagedMcpServerSummary,
+  ManagedToolSummary,
+  McpConnectionInfo,
+  ToolDescriptor,
+} from './types';
+
+export function createManagedToolSummary(
+  descriptor: ToolDescriptor,
+  extra: Partial<ManagedToolSummary> = {},
+): ManagedToolSummary {
+  const isMcp = descriptor.category === 'mcp';
+  const governance = extra.governance ?? (
+    !isMcp
+      ? createLocalToolGovernance({
+        approvalPolicy: descriptor.approvalPolicy,
+        sideEffectLevel: descriptor.sideEffectLevel,
+        hostDependency: descriptor.hostDependency,
+      })
+      : undefined
+  );
+
+  return {
+    ...createAssetSummaryBase({
+      kind: 'tool',
+      scope:
+        descriptor.source === 'system' || descriptor.source === 'bundled'
+          ? 'core'
+          : descriptor.source === 'user'
+            ? 'local'
+            : 'external',
+      runtime: isMcp ? 'mcp-provider' : 'in-process',
+      governance,
+    }),
+    ref: descriptor.alias,
+    id: descriptor.id,
+    assetId: descriptor.assetId,
+    alias: descriptor.alias,
+    name: descriptor.name,
+    displayName: descriptor.displayName,
+    description: descriptor.description,
+    category: descriptor.category,
+    tags: descriptor.tags,
+    source: descriptor.source,
+    provider: descriptor.provider,
+    ...extra,
+  };
+}
+
+export function createManagedToolDetail(
+  descriptor: ToolDescriptor,
+  extra: Partial<ManagedToolDetail> & Pick<ManagedToolDetail, 'parameters' | 'hasProject'>,
+): ManagedToolDetail {
+  return {
+    ...createManagedToolSummary(descriptor),
+    outputSchema: descriptor.outputSchema,
+    resolvedOutputSchema: descriptor.resolvedOutputSchema,
+    errorSchema: descriptor.errorSchema,
+    ...extra,
+  };
+}
+
+export function createManagedMcpServerSummary(input: {
+  name: string;
+  projectDir: string;
+  hasDistBundle: boolean;
+  description?: string;
+  category?: string;
+  tags?: string[];
+  enabled?: boolean;
+  connectionInfo?: McpConnectionInfo;
+  governance?: ManagedMcpServerSummary['governance'];
+  meta?: Record<string, unknown>;
+  code?: string;
+  dependencies?: Record<string, string>;
+  extra?: Partial<ManagedMcpServerSummary>;
+}): ManagedMcpServerSummary {
+  const enabled = input.enabled ?? false;
+  return {
+    ...createAssetSummaryBase({
+      kind: 'mcp-server',
+      scope: 'local',
+      runtime: 'mcp-provider',
+      governance: createLocalMcpServerGovernance(input.governance),
+    }),
+    ref: input.name,
+    name: input.name,
+    description: input.description,
+    category: input.category,
+    tags: input.tags ?? [],
+    enabled,
+    status: input.connectionInfo?.status ?? (enabled ? 'disconnected' : 'disabled'),
+    toolCount: input.connectionInfo?.toolCount ?? 0,
+    error: input.connectionInfo?.error,
+    hasDistBundle: input.hasDistBundle,
+    projectDir: input.projectDir,
+    ...input.extra,
+  };
+}
+
+export function createManagedMcpServerDetail(input: {
+  name: string;
+  projectDir: string;
+  hasDistBundle: boolean;
+  description?: string;
+  category?: string;
+  tags?: string[];
+  enabled?: boolean;
+  connectionInfo?: McpConnectionInfo;
+  governance?: ManagedMcpServerDetail['governance'];
+  meta?: Record<string, unknown>;
+  code?: string;
+  dependencies?: Record<string, string>;
+  extra?: Partial<ManagedMcpServerDetail>;
+}): ManagedMcpServerDetail {
+  return {
+    ...createManagedMcpServerSummary(input),
+    meta: input.meta,
+    code: input.code,
+    dependencies: input.dependencies,
+    ...input.extra,
+  };
+}