@xiaozhi-client/mcp-core 1.9.7-beta.3 → 1.9.7-beta.6

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { EventEmitter } from 'node:events';
 
 /**
@@ -6,6 +9,11 @@ import { EventEmitter } from 'node:events';
  * 统一管理所有 MCP 相关的类型定义
  */
 
+/**
+ * MCP 传输层联合类型定义
+ * 支持 STDIO、SSE、StreamableHTTP 三种传输协议
+ */
+type MCPServerTransport = StdioClientTransport | SSEClientTransport | StreamableHTTPClientTransport;
 /**
  * 通信方式枚举
  * 定义 MCP 支持的传输类型
@@ -15,6 +23,30 @@ declare enum MCPTransportType {
     SSE = "sse",
     STREAMABLE_HTTP = "streamable-http"
 }
+/**
+ * MCP 服务事件回调接口
+ * 用于替代 EventBus 依赖，提供灵活的事件处理机制
+ */
+interface MCPServiceEventCallbacks {
+    /** 连接成功回调 */
+    onConnected?: (data: {
+        serviceName: string;
+        tools: Tool[];
+        connectionTime: Date;
+    }) => void;
+    /** 断开连接回调 */
+    onDisconnected?: (data: {
+        serviceName: string;
+        reason?: string;
+        disconnectionTime: Date;
+    }) => void;
+    /** 连接失败回调 */
+    onConnectionFailed?: (data: {
+        serviceName: string;
+        error: Error;
+        attempt: number;
+    }) => void;
+}
 /**
  * ModelScope SSE 自定义选项接口
  */
@@ -122,10 +154,6 @@ interface ToolInfo {
     originalName: string;
     tool: Tool;
 }
-/**
- * 工具状态过滤选项
- */
-type ToolStatusFilter = "enabled" | "disabled" | "all";
 /**
  * 增强的工具信息接口
  */
@@ -227,69 +255,345 @@ declare class ToolCallError extends Error {
 }
 
 /**
- * 简化版 MCP 服务管理器
- * 专门为 endpoint 包设计，提供核心 MCP 服务管理功能
+ * MCP 连接类
+ * 负责管理单个 MCP 服务的连接、工具管理和调用
  */
+declare class MCPConnection {
+    private config;
+    private client;
+    private transport;
+    private tools;
+    private connectionState;
+    private connectionTimeout;
+    private initialized;
+    private callbacks?;
+    constructor(config: MCPServiceConfig, callbacks?: MCPServiceEventCallbacks);
+    /**
+     * 验证配置
+     */
+    private validateConfig;
+    /**
+     * 连接到 MCP 服务
+     */
+    connect(): Promise<void>;
+    /**
+     * 尝试建立连接
+     */
+    private attemptConnection;
+    /**
+     * 处理连接成功
+     */
+    private handleConnectionSuccess;
+    /**
+     * 处理连接错误
+     */
+    private handleConnectionError;
+    /**
+     * 清理连接资源
+     */
+    private cleanupConnection;
+    /**
+     * 刷新工具列表
+     */
+    private refreshTools;
+    /**
+     * 断开连接
+     */
+    disconnect(): Promise<void>;
+    /**
+     * 获取工具列表
+     */
+    getTools(): Tool[];
+    /**
+     * 调用工具
+     */
+    callTool(name: string, arguments_: Record<string, unknown>): Promise<ToolCallResult>;
+    /**
+     * 获取服务配置
+     */
+    getConfig(): MCPServiceConfig;
+    /**
+     * 获取服务状态
+     */
+    getStatus(): MCPServiceStatus;
+    /**
+     * 检查是否已连接
+     */
+    isConnected(): boolean;
+}
 
 /**
- * 简化版 MCP 服务管理器
- * 提供 MCP 服务的核心管理功能
+ * MCP 服务管理器
+ * 提供简洁的 API 来管理多个 MCP 服务
  */
-declare class MCPServiceManager extends EventEmitter {
+
+/**
+ * 用户友好的传输类型
+ * 用于简化和标准化用户输入
+ */
+type UserFriendlyTransportType = "stdio" | "sse" | "http" | MCPTransportType;
+/**
+ * MCP 服务管理器
+ * 提供简洁的 API 来管理多个 MCP 服务
+ *
+ * @example
+ * ```typescript
+ * const manager = new MCPManager();
+ *
+ * // 添加服务
+ * manager.addServer('datetime', {
+ *   type: 'stdio',
+ *   command: 'node',
+ *   args: ['datetime.js']
+ * });
+ *
+ * // 连接所有服务
+ * await manager.connect();
+ *
+ * // 调用工具
+ * const result = await manager.callTool('datetime', 'get_current_time', {
+ *   format: 'YYYY-MM-DD HH:mm:ss'
+ * });
+ *
+ * // 断开连接
+ * await manager.disconnect();
+ * ```
+ */
+declare class MCPManager extends EventEmitter {
+    private connections;
     private configs;
-    private tools;
-    private isInitialized;
-    constructor(configs?: Record<string, MCPServiceConfig>);
+    constructor();
     /**
-     * 添加服务配置
+     * 添加 MCP 服务器配置
+     * @param name 服务器名称
+     * @param config 服务器配置
+     *
+     * @example
+     * ```typescript
+     * // 添加 stdio 服务
+     * manager.addServer('calculator', {
+     *   type: 'stdio',
+     *   command: 'node',
+     *   args: ['calculator.js']
+     * });
+     *
+     * // 添加 HTTP 服务
+     * manager.addServer('web-search', {
+     *   type: 'http',
+     *   url: 'https://api.example.com/mcp',
+     *   headers: {
+     *     Authorization: 'Bearer your-api-key'
+     *   }
+     * });
+     * ```
      */
-    addServiceConfig(name: string, config: MCPServiceConfig): void;
+    addServer(name: string, config: Omit<MCPServiceConfig, "name"> & {
+        type?: UserFriendlyTransportType;
+    }): void;
     /**
-     * 更新服务配置
+     * 移除服务器配置
+     * @param name 服务器名称
      */
-    updateServiceConfig(name: string, config: MCPServiceConfig): void;
+    removeServer(name: string): boolean;
     /**
-     * 移除服务配置
+     * 连接所有已添加的 MCP 服务
+     * 所有服务并行连接，单个服务失败不会影响其他服务
+     *
+     * @example
+     * ```typescript
+     * await manager.connect();
+     * ```
      */
-    removeServiceConfig(name: string): void;
+    connect(): Promise<void>;
     /**
-     * 获取所有服务配置
+     * 断开所有 MCP 服务连接
+     *
+     * @example
+     * ```typescript
+     * await manager.disconnect();
+     * ```
      */
-    getServiceConfigs(): Record<string, MCPServiceConfig>;
+    disconnect(): Promise<void>;
     /**
-     * 启动所有服务
+     * 调用指定服务的工具
+     * @param serverName 服务名称
+     * @param toolName 工具名称
+     * @param args 工具参数
+     *
+     * @example
+     * ```typescript
+     * const result = await manager.callTool('datetime', 'get_current_time', {
+     *   format: 'YYYY-MM-DD HH:mm:ss'
+     * });
+     * ```
      */
-    startAllServices(): Promise<void>;
+    callTool(serverName: string, toolName: string, args: Record<string, unknown>): Promise<ToolCallResult>;
     /**
-     * 启动单个服务
+     * 列出所有可用的工具
+     * @returns 工具列表，格式为 [{ name, serverName, description, inputSchema }]
+     *
+     * @example
+     * ```typescript
+     * const tools = manager.listTools();
+     * console.log('可用工具:', tools.map(t => `${t.serverName}/${t.name}`));
+     * ```
      */
-    startService(serviceName: string): Promise<void>;
+    listTools(): Array<{
+        name: string;
+        serverName: string;
+        description: string;
+        inputSchema: unknown;
+    }>;
     /**
-     * 获取所有工具列表
+     * 获取服务状态
+     * @param serverName 服务名称
+     * @returns 服务状态，如果服务不存在则返回 null
+     *
+     * @example
+     * ```typescript
+     * const status = manager.getServerStatus('datetime');
+     * if (status) {
+     *   console.log(`已连接: ${status.connected}, 工具数: ${status.toolCount}`);
+     * }
+     * ```
      */
-    getAllTools(status?: ToolStatusFilter): EnhancedToolInfo[];
+    getServerStatus(serverName: string): {
+        connected: boolean;
+        toolCount: number;
+    } | null;
     /**
-     * 调用工具
+     * 获取所有服务的状态
+     * @returns 所有服务的状态映射
+     *
+     * @example
+     * ```typescript
+     * const statuses = manager.getAllServerStatus();
+     * console.log(statuses);
+     * // {
+     * //   datetime: { connected: true, toolCount: 3 },
+     * //   calculator: { connected: true, toolCount: 1 }
+     * // }
+     * ```
      */
-    callTool(toolName: string, _arguments_: Record<string, unknown>, _options?: {
-        timeout?: number;
-    }): Promise<ToolCallResult>;
+    getAllServerStatus(): Record<string, {
+        connected: boolean;
+        toolCount: number;
+    }>;
     /**
-     * 添加工具（用于测试或自定义工具）
+     * 检查服务是否已连接
+     * @param serverName 服务名称
+     *
+     * @example
+     * ```typescript
+     * if (manager.isConnected('datetime')) {
+     *   console.log('datetime 服务已连接');
+     * }
+     * ```
      */
-    addTool(tool: EnhancedToolInfo): void;
+    isConnected(serverName: string): boolean;
     /**
-     * 移除工具
+     * 获取已配置的服务列表
+     * @returns 服务名称数组
+     *
+     * @example
+     * ```typescript
+     * const servers = manager.getServerNames();
+     * console.log('已配置的服务:', servers);
+     * ```
      */
-    removeTool(toolName: string): void;
+    getServerNames(): string[];
     /**
-     * 获取管理器状态
+     * 获取已连接的服务列表
+     * @returns 已连接的服务名称数组
+     *
+     * @example
+     * ```typescript
+     * const connectedServers = manager.getConnectedServerNames();
+     * console.log('已连接的服务:', connectedServers);
+     * ```
      */
-    getStatus(): ManagerStatus;
+    getConnectedServerNames(): string[];
+}
+
+/**
+ * 创建 transport 实例
+ * @param config MCP 服务配置
+ * @returns transport 实例
+ */
+declare function createTransport(config: MCPServiceConfig): MCPServerTransport;
+/**
+ * 验证配置
+ */
+declare function validateConfig(config: MCPServiceConfig): void;
+/**
+ * 获取支持的传输类型列表
+ */
+declare function getSupportedTypes(): MCPTransportType[];
+/**
+ * Transport 工厂对象（保持 API 兼容性）
+ */
+declare const TransportFactory: {
+    create: typeof createTransport;
+    validateConfig: typeof validateConfig;
+    getSupportedTypes: typeof getSupportedTypes;
+};
+
+/**
+ * MCP 服务器配置 Type 字段标准化工具
+ * 支持将各种 type 字段格式转换为标准的中划线格式
+ */
+/**
+ * MCP 服务器配置的基础接口
+ * 定义包含可选 type 字段的配置对象结构
+ */
+interface MCPBaseConfig {
+    type?: string;
+    [key: string]: unknown;
+}
+/**
+ * MCP 服务器配置 Type 字段标准化工具类
+ */
+declare namespace TypeFieldNormalizer {
     /**
-     * 清理资源
+     * 标准化type字段格式
+     * 支持将各种格式转换为标准的中划线格式
      */
-    cleanup(): Promise<void>;
+    function normalizeTypeField<T extends MCPBaseConfig>(config: T): T;
+    function normalizeTypeField(config: unknown): unknown;
 }
+/**
+ * 导出便捷函数
+ */
+declare function normalizeTypeField<T extends MCPBaseConfig>(config: T): T;
+declare function normalizeTypeField(config: unknown): unknown;
+
+/**
+ * 根据 URL 路径推断传输类型
+ * 基于路径末尾推断，支持包含多个 / 的复杂路径
+ *
+ * @param url - 要推断的 URL
+ * @param options - 可选配置项
+ * @returns 推断出的传输类型
+ */
+declare function inferTransportTypeFromUrl(url: string, options?: {
+    serviceName?: string;
+}): MCPTransportType;
+/**
+ * 完整的配置类型推断（包括 command 字段）
+ *
+ * @param config - MCP 服务配置
+ * @returns 完整的配置对象，包含推断出的类型
+ */
+declare function inferTransportTypeFromConfig(config: MCPServiceConfig): MCPServiceConfig;
+/**
+ * 验证工具调用参数
+ * 对传入的参数进行完整性和格式验证
+ *
+ * @param params 待验证的参数
+ * @param options 验证选项
+ * @returns 验证后的参数
+ * @throws ToolCallError 验证失败时抛出
+ */
+declare function validateToolCallParams(params: unknown, options?: ToolCallValidationOptions): ValidatedToolCallParams;
 
-export { ConnectionState, type CustomMCPTool, type EnhancedToolInfo, type JSONSchema, type MCPServiceConfig, type MCPServiceConnectionStatus, MCPServiceManager, type MCPServiceStatus, MCPTransportType, type ManagerStatus, type ModelScopeSSEOptions, ToolCallError, ToolCallErrorCode, type ToolCallParams, type ToolCallResult, type ToolCallValidationOptions, type ToolInfo, type UnifiedServerConfig, type UnifiedServerStatus, type ValidatedToolCallParams, ensureToolJSONSchema, isValidToolJSONSchema };
+export { ConnectionState, type CustomMCPTool, type EnhancedToolInfo, type JSONSchema, MCPConnection, MCPManager, type MCPServerTransport, type MCPServiceConfig, type MCPServiceConnectionStatus, type MCPServiceEventCallbacks, MCPManager as MCPServiceManager, type MCPServiceStatus, MCPTransportType, type ManagerStatus, type ModelScopeSSEOptions, ToolCallError, ToolCallErrorCode, type ToolCallParams, type ToolCallResult, type ToolCallValidationOptions, type ToolInfo, TransportFactory, TypeFieldNormalizer, type UnifiedServerConfig, type UnifiedServerStatus, type ValidatedToolCallParams, ensureToolJSONSchema, inferTransportTypeFromConfig, inferTransportTypeFromUrl, isValidToolJSONSchema, normalizeTypeField, validateToolCallParams };