@xiaozhi-client/mcp-core 1.10.5 → 1.10.6-beta.1

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@xiaozhi-client/mcp-core",
-  "version": "1.10.5",
+  "version": "1.10.6-beta.1",
+  "private": false,
   "description": "MCP 协议核心实现，提供服务连接和管理功能",
   "type": "module",
   "main": "./dist/index.js",

package/dist/index.d.ts

@@ -1,681 +0,0 @@
-import { Tool, CompatibilityCallToolResult } from '@modelcontextprotocol/sdk/types.js';
-export { CompatibilityCallToolResult as ToolCallResult } 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';
-
-/**
- * MCP 核心库类型定义
- * 统一管理所有 MCP 相关的类型定义
- */
-
-/**
- * MCP 传输层联合类型定义
- * 支持 STDIO、SSE、StreamableHTTP 三种传输协议
- */
-type MCPServerTransport = StdioClientTransport | SSEClientTransport | StreamableHTTPClientTransport;
-/**
- * 通信方式枚举
- * 定义 MCP 支持的传输类型
- */
-declare enum MCPTransportType {
-    STDIO = "stdio",
-    SSE = "sse",
-    HTTP = "http"
-}
-/**
- * 传输类型字符串字面量
- * 方便外部用户直接使用字符串而不需要导入枚举
- */
-type MCPTransportTypeString = "stdio" | "sse" | "http";
-/**
- * 传输类型输入值（枚举或字符串字面量）
- */
-type MCPTransportTypeInput = MCPTransportType | MCPTransportTypeString;
-/**
- * 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 自定义选项接口
- */
-interface ModelScopeSSEOptions {
-    eventSourceInit?: {
-        fetch?: (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
-    };
-    requestInit?: RequestInit;
-}
-/**
- * 心跳检测配置接口
- */
-interface HeartbeatConfig {
-    /** 是否启用心跳检测（默认 true） */
-    enabled?: boolean;
-    /** 心跳间隔（毫秒，默认 30000 = 30秒） */
-    interval?: number;
-}
-/**
- * MCP 服务配置接口
- * 包含所有 MCP 服务的配置选项（不包含服务名称）
- *
- * @description
- * 与 MCP 官方配置格式保持一致，支持三种传输类型：
- * - stdio: 本地进程通信 { command, args, env }
- * - sse: Server-Sent Events { url, headers }
- * - http: Streamable HTTP { url, headers }
- *
- * 向后兼容：自动将 streamable-http/streamable_http/streamableHttp 转换为 http
- */
-interface MCPServiceConfig {
-    type?: MCPTransportTypeInput;
-    command?: string;
-    args?: string[];
-    env?: Record<string, string>;
-    url?: string;
-    apiKey?: string;
-    headers?: Record<string, string>;
-    customSSEOptions?: ModelScopeSSEOptions;
-    heartbeat?: HeartbeatConfig;
-}
-/**
- * 内部使用的 MCP 服务配置接口（包含 name 字段）
- * 用于 TransportFactory 等内部函数
- */
-interface InternalMCPServiceConfig extends MCPServiceConfig {
-    name: string;
-}
-/**
- * 连接状态枚举
- */
-declare enum ConnectionState {
-    DISCONNECTED = "disconnected",
-    CONNECTING = "connecting",
-    CONNECTED = "connected",
-    RECONNECTING = "reconnecting",
-    FAILED = "failed",
-    ERROR = "error"
-}
-/**
- * MCP 服务状态接口
- */
-interface MCPServiceStatus {
-    name: string;
-    connected: boolean;
-    initialized: boolean;
-    transportType: MCPTransportType;
-    toolCount: number;
-    lastError?: string;
-    connectionState: ConnectionState;
-}
-
-/**
- * JSON Schema 类型定义
- */
-type JSONSchema = (Record<string, unknown> & {
-    type: "object";
-    properties?: Record<string, unknown>;
-    required?: string[];
-    additionalProperties?: boolean;
-}) | Record<string, unknown>;
-/**
- * 类型守卫：检查对象是否为有效的 MCP Tool JSON Schema
- */
-declare function isValidToolJSONSchema(obj: unknown): obj is {
-    type: "object";
-    properties?: Record<string, unknown>;
-    required?: string[];
-    additionalProperties?: boolean;
-};
-/**
- * 确保对象符合 MCP Tool JSON Schema 格式
- */
-declare function ensureToolJSONSchema(schema: JSONSchema): {
-    type: "object";
-    properties?: Record<string, object>;
-    required?: string[];
-    additionalProperties?: boolean;
-};
-/**
- * CustomMCP 工具类型定义
- */
-interface CustomMCPTool {
-    name: string;
-    description?: string;
-    inputSchema: JSONSchema;
-    handler?: {
-        type: string;
-        config?: Record<string, unknown>;
-    };
-}
-/**
- * 工具信息接口
- */
-interface ToolInfo {
-    serviceName: string;
-    originalName: string;
-    tool: Tool;
-}
-/**
- * 增强的工具信息接口
- */
-interface EnhancedToolInfo {
-    /** 工具唯一标识符，格式为 "{serviceName}__{originalName}" */
-    name: string;
-    /** 工具描述信息 */
-    description: string;
-    /** 工具输入参数的 JSON Schema 定义 */
-    inputSchema: JSONSchema;
-    /** 工具所属的 MCP 服务名称 */
-    serviceName: string;
-    /** 工具在 MCP 服务中的原始名称 */
-    originalName: string;
-    /** 工具是否启用 */
-    enabled: boolean;
-    /** 工具使用次数统计 */
-    usageCount: number;
-    /** 工具最后使用时间 */
-    lastUsedTime: string;
-}
-/**
- * 统一服务器配置接口
- */
-interface UnifiedServerConfig {
-    name?: string;
-    enableLogging?: boolean;
-    logLevel?: string;
-    configs?: Record<string, MCPServiceConfig>;
-}
-/**
- * 统一服务器状态接口
- */
-interface UnifiedServerStatus {
-    isRunning: boolean;
-    serviceStatus: ManagerStatus;
-    transportCount: number;
-    activeConnections: number;
-    config: UnifiedServerConfig;
-    services?: Record<string, MCPServiceConnectionStatus>;
-    totalTools?: number;
-    availableTools?: string[];
-}
-/**
- * MCP 服务连接状态接口
- */
-interface MCPServiceConnectionStatus {
-    connected: boolean;
-    clientName: string;
-}
-/**
- * 管理器状态接口
- */
-interface ManagerStatus {
-    services: Record<string, MCPServiceConnectionStatus>;
-    totalTools: number;
-    availableTools: string[];
-}
-/**
- * 工具调用参数接口
- */
-interface ToolCallParams {
-    name: string;
-    arguments?: Record<string, unknown>;
-}
-/**
- * 验证后的工具调用参数
- */
-interface ValidatedToolCallParams {
-    name: string;
-    arguments?: Record<string, unknown>;
-}
-/**
- * 工具调用验证选项
- */
-interface ToolCallValidationOptions {
-    validateName?: boolean;
-    validateArguments?: boolean;
-    allowEmptyArguments?: boolean;
-    customValidator?: (params: ToolCallParams) => string | null;
-}
-/**
- * 工具调用错误码枚举
- */
-declare enum ToolCallErrorCode {
-    INVALID_PARAMS = -32602,
-    TOOL_NOT_FOUND = -32601,
-    SERVICE_UNAVAILABLE = -32001,
-    TIMEOUT = -32002,
-    TOOL_EXECUTION_ERROR = -32000
-}
-/**
- * 工具调用错误类
- */
-declare class ToolCallError extends Error {
-    code: ToolCallErrorCode;
-    data?: unknown | undefined;
-    constructor(code: ToolCallErrorCode, message: string, data?: unknown | undefined);
-}
-
-/**
- * MCP 连接管理模块
- *
- * 提供 MCPConnection 类，负责管理单个 MCP 服务的连接生命周期
- * 包括连接建立、工具列表管理、工具调用、心跳检测等功能
- *
- * @module connection
- */
-
-/**
- * MCP 连接类
- * 负责管理单个 MCP 服务的连接、工具管理和调用
- */
-declare class MCPConnection {
-    private name;
-    private config;
-    private client;
-    private transport;
-    private tools;
-    private connectionState;
-    private connectionTimeout;
-    private initialized;
-    private callbacks?;
-    private heartbeatTimer;
-    private heartbeatConfig?;
-    constructor(name: string, 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[];
-    /**
-     * 检测是否为会话过期错误
-     */
-    private isSessionExpiredError;
-    /**
-     * 自动重连
-     */
-    private reconnect;
-    /**
-     * 启动心跳检测
-     */
-    private startHeartbeat;
-    /**
-     * 执行一次心跳检查
-     */
-    private performHeartbeat;
-    /**
-     * 停止心跳检测
-     */
-    private stopHeartbeat;
-    /**
-     * 调用工具
-     */
-    callTool(name: string, arguments_: Record<string, unknown>): Promise<CompatibilityCallToolResult>;
-    /**
-     * 获取服务配置
-     */
-    getConfig(): MCPServiceConfig & {
-        name: string;
-    };
-    /**
-     * 获取服务状态
-     */
-    getStatus(): MCPServiceStatus;
-    /**
-     * 检查是否已连接
-     */
-    isConnected(): boolean;
-}
-
-/**
- * MCP 服务管理器
- * 提供简洁的 API 来管理多个 MCP 服务
- */
-
-/**
- * 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;
-    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'
-     *   }
-     * });
-     * ```
-     */
-    addServer(name: string, config: MCPServiceConfig): void;
-    /**
-     * 移除服务器配置
-     * @param name 服务器名称
-     */
-    removeServer(name: string): boolean;
-    /**
-     * 连接所有已添加的 MCP 服务
-     * 所有服务并行连接，单个服务失败不会影响其他服务
-     *
-     * @example
-     * ```typescript
-     * await manager.connect();
-     * ```
-     */
-    connect(): Promise<void>;
-    /**
-     * 断开所有 MCP 服务连接
-     *
-     * @example
-     * ```typescript
-     * await manager.disconnect();
-     * ```
-     */
-    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'
-     * });
-     * ```
-     */
-    callTool(serverName: string, toolName: string, args: Record<string, unknown>): Promise<CompatibilityCallToolResult>;
-    /**
-     * 列出所有可用的工具
-     * @returns 工具列表，格式为 [{ name, serverName, description, inputSchema }]
-     *
-     * @example
-     * ```typescript
-     * const tools = manager.listTools();
-     * console.log('可用工具:', tools.map(t => `${t.serverName}/${t.name}`));
-     * ```
-     */
-    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}`);
-     * }
-     * ```
-     */
-    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 }
-     * // }
-     * ```
-     */
-    getAllServerStatus(): Record<string, {
-        connected: boolean;
-        toolCount: number;
-    }>;
-    /**
-     * 检查服务是否已连接
-     * @param serverName 服务名称
-     *
-     * @example
-     * ```typescript
-     * if (manager.isConnected('datetime')) {
-     *   console.log('datetime 服务已连接');
-     * }
-     * ```
-     */
-    isConnected(serverName: string): boolean;
-    /**
-     * 获取已配置的服务列表
-     * @returns 服务名称数组
-     *
-     * @example
-     * ```typescript
-     * const servers = manager.getServerNames();
-     * console.log('已配置的服务:', servers);
-     * ```
-     */
-    getServerNames(): string[];
-    /**
-     * 获取已连接的服务列表
-     * @returns 已连接的服务名称数组
-     *
-     * @example
-     * ```typescript
-     * const connectedServers = manager.getConnectedServerNames();
-     * console.log('已连接的服务:', connectedServers);
-     * ```
-     */
-    getConnectedServerNames(): string[];
-}
-
-/**
- * MCP 传输层工厂模块
- *
- * 提供创建不同类型传输层实例的工厂函数
- * 支持 STDIO、SSE、StreamableHTTP 三种传输协议
- *
- * @module transport-factory
- */
-
-/**
- * 创建 transport 实例
- * @param config MCP 服务配置（包含 name）
- * @returns transport 实例
- */
-declare function createTransport(config: InternalMCPServiceConfig): MCPServerTransport;
-/**
- * 验证配置
- * 注意：name 验证已在 MCPConnection 构造函数中进行
- * @param config MCP 服务配置（包含 name）
- */
-declare function validateConfig(config: InternalMCPServiceConfig): void;
-/**
- * 获取支持的传输类型列表
- */
-declare function getSupportedTypes(): MCPTransportType[];
-/**
- * Transport 工厂对象（保持 API 兼容性）
- */
-declare const TransportFactory: {
-    create: typeof createTransport;
-    validateConfig: typeof validateConfig;
-    getSupportedTypes: typeof getSupportedTypes;
-};
-
-/**
- * MCP 服务器配置 Type 字段标准化工具
- * 支持将各种 type 字段格式转换为 MCP 官方标准格式
- *
- * @description
- * 标准格式与 MCP 官方保持一致：
- * - stdio: 本地进程通信
- * - sse: Server-Sent Events
- * - http: Streamable HTTP（推荐使用 http 而非 streamable-http）
- *
- * 向后兼容：自动转换各种变体格式
- */
-/**
- * MCP 服务器配置的基础接口
- * 定义包含可选 type 字段的配置对象结构
- */
-interface MCPBaseConfig {
-    type?: string;
-    [key: string]: unknown;
-}
-/**
- * MCP 服务器配置 Type 字段标准化工具类
- */
-declare namespace TypeFieldNormalizer {
-    /**
-     * 标准化 type 字段格式
-     *
-     * 支持的转换：
-     * - http 变体：http → http（标准值）
-     * - streamable-http → http
-     * - streamable_http → http
-     * - streamableHttp → http
-     * - sse 变体：sse → sse（标准值）
-     * - s_se → sse
-     * - s-se → sse
-     * - stdio 变体：stdio → stdio（标准值）
-     */
-    function normalizeTypeField<T extends MCPBaseConfig>(config: T): T;
-    function normalizeTypeField(config: unknown): unknown;
-    /**
-     * 标准化单个 type 值
-     */
-    function normalizeTypeValue(type: string): string;
-}
-/**
- * 导出便捷函数
- */
-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 服务配置
- * @param serviceName - 服务名称（用于日志输出）
- * @returns 完整的配置对象，包含推断出的类型
- */
-declare function inferTransportTypeFromConfig(config: MCPServiceConfig, serviceName?: string): MCPServiceConfig;
-/**
- * 验证工具调用参数
- * 对传入的参数进行完整性和格式验证
- *
- * @param params 待验证的参数
- * @param options 验证选项
- * @returns 验证后的参数
- * @throws ToolCallError 验证失败时抛出
- */
-declare function validateToolCallParams(params: unknown, options?: ToolCallValidationOptions): ValidatedToolCallParams;
-
-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 ToolCallValidationOptions, type ToolInfo, TransportFactory, TypeFieldNormalizer, type UnifiedServerConfig, type UnifiedServerStatus, type ValidatedToolCallParams, ensureToolJSONSchema, inferTransportTypeFromConfig, inferTransportTypeFromUrl, isValidToolJSONSchema, normalizeTypeField, validateToolCallParams };