@n0ts123/mcplink-core 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,456 @@
+import { LanguageModel } from 'ai';
+
+/** MCP 服务器配置 - stdio 模式 */
+interface MCPServerConfigStdio {
+    type?: 'stdio';
+    /** 启动命令 */
+    command: string;
+    /** 命令参数 */
+    args?: string[];
+    /** 环境变量 */
+    env?: Record<string, string>;
+}
+/** MCP 服务器配置 - SSE 模式 */
+interface MCPServerConfigSSE {
+    type: 'sse';
+    /** SSE 服务地址 */
+    url: string;
+    /** 请求头 */
+    headers?: Record<string, string>;
+}
+/** MCP 服务器配置 */
+type MCPServerConfig = MCPServerConfigStdio | MCPServerConfigSSE;
+/** MCPLink 配置 */
+interface MCPLinkConfig {
+    /** AI 模型实例 (Vercel AI SDK) */
+    model: LanguageModel;
+    /** 模型名称（用于自动检测是否支持原生工具调用） */
+    modelName?: string;
+    /** MCP 服务器配置 */
+    mcpServers?: Record<string, MCPServerConfig>;
+    /** 系统提示词 */
+    systemPrompt?: string;
+    /** 最大迭代次数 (防止无限循环) */
+    maxIterations?: number;
+    /** 是否允许并行工具调用 */
+    parallelToolCalls?: boolean;
+    /**
+     * 是否使用基于 Prompt 的工具调用
+     * - true: 使用 prompt 让模型输出特定格式来调用工具（支持所有模型）
+     * - false: 使用原生 function calling（需要模型支持）
+     * - 'auto': 自动检测（默认）
+     */
+    usePromptBasedTools?: boolean | 'auto';
+}
+/** 工具调用 */
+interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/** 工具结果 */
+interface ToolResult {
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+    isError?: boolean;
+    duration?: number;
+}
+/** 消息角色 */
+type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+/** 消息 */
+interface Message {
+    role: MessageRole;
+    content: string;
+    toolCalls?: ToolCall[];
+    toolResults?: ToolResult[];
+}
+/** 事件类型 */
+declare enum MCPLinkEventType {
+    /** AI 开始思考 */
+    THINKING_START = "thinking_start",
+    /** AI 思考内容 (流式) */
+    THINKING_DELTA = "thinking_delta",
+    /** AI 思考结束 */
+    THINKING_END = "thinking_end",
+    /** AI 思考内容（完整，用于工具调用时展示） */
+    THINKING_CONTENT = "thinking_content",
+    /** AI 开始回复 */
+    TEXT_START = "text_start",
+    /** AI 回复内容 (流式) */
+    TEXT_DELTA = "text_delta",
+    /** AI 回复结束 */
+    TEXT_END = "text_end",
+    /** 开始调用工具 */
+    TOOL_CALL_START = "tool_call_start",
+    /** 工具参数 (流式) */
+    TOOL_CALL_DELTA = "tool_call_delta",
+    /** 工具调用参数完成 */
+    TOOL_CALL_END = "tool_call_end",
+    /** 工具正在执行 */
+    TOOL_EXECUTING = "tool_executing",
+    /** 工具返回结果 */
+    TOOL_RESULT = "tool_result",
+    /** 开始新一轮迭代 */
+    ITERATION_START = "iteration_start",
+    /** 迭代结束 */
+    ITERATION_END = "iteration_end",
+    /** 全部完成 */
+    COMPLETE = "complete",
+    /** 发生错误 */
+    ERROR = "error",
+    /** TODO 列表开始 */
+    TODO_START = "todo_start",
+    /** 添加 TODO 项 */
+    TODO_ITEM_ADD = "todo_item_add",
+    /** 更新 TODO 项状态 */
+    TODO_ITEM_UPDATE = "todo_item_update",
+    /** TODO 列表完成 */
+    TODO_END = "todo_end"
+}
+/** 事件数据 */
+interface MCPLinkEventData {
+    content?: string;
+    toolName?: string;
+    toolArgs?: Record<string, unknown>;
+    toolResult?: unknown;
+    toolCallId?: string;
+    duration?: number;
+    iteration?: number;
+    maxIterations?: number;
+    totalIterations?: number;
+    totalDuration?: number;
+    argsTextDelta?: string;
+    isError?: boolean;
+    error?: Error;
+    todoId?: string;
+    todoTitle?: string;
+    todoItemId?: string;
+    todoItemContent?: string;
+    todoItemStatus?: TodoItemStatus;
+    todoItemResult?: string;
+}
+/** 事件 */
+interface MCPLinkEvent {
+    type: MCPLinkEventType;
+    timestamp: number;
+    data: MCPLinkEventData;
+}
+/** 对话回调选项 */
+interface ChatCallbacks {
+    /** AI 思考内容 */
+    onThinking?: (content: string) => void;
+    /** 开始调用工具 */
+    onToolCallStart?: (toolName: string, args: Record<string, unknown>) => void;
+    /** 工具返回结果 */
+    onToolResult?: (toolName: string, result: unknown, duration: number) => void;
+    /** AI 输出文本 (流式) */
+    onTextDelta?: (delta: string) => void;
+    /** 迭代开始 */
+    onIterationStart?: (iteration: number) => void;
+    /** 迭代结束 */
+    onIterationEnd?: (iteration: number) => void;
+    /** 发生错误 */
+    onError?: (error: Error) => void;
+    /** TODO 列表开始 */
+    onTodoStart?: (todoId: string, title: string) => void;
+    /** TODO 项添加 */
+    onTodoItemAdd?: (todoId: string, item: TodoItem) => void;
+    /** TODO 项更新 */
+    onTodoItemUpdate?: (todoId: string, itemId: string, status: TodoItemStatus, result?: string) => void;
+    /** TODO 列表完成 */
+    onTodoEnd?: (todoId: string) => void;
+}
+/** 对话结果 */
+interface ChatResult {
+    /** 最终回复内容 */
+    content: string;
+    /** 执行过的工具调用记录 */
+    toolCalls: Array<{
+        name: string;
+        arguments: Record<string, unknown>;
+        result: unknown;
+        duration: number;
+    }>;
+    /** 完整消息历史 */
+    messages: Message[];
+    /** Token 使用量 */
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    /** 总迭代次数 */
+    iterations: number;
+    /** 总耗时 (ms) */
+    duration: number;
+}
+/** MCP 工具定义 */
+interface MCPTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/** MCP 服务器状态 */
+interface MCPServerStatus {
+    id: string;
+    name: string;
+    config: MCPServerConfig;
+    status: 'stopped' | 'starting' | 'running' | 'error';
+    tools: MCPTool[];
+    error?: string;
+}
+/** TODO 项状态 */
+type TodoItemStatus = 'pending' | 'in_progress' | 'completed' | 'failed';
+/** TODO 项 */
+interface TodoItem {
+    /** 唯一标识 */
+    id: string;
+    /** 任务内容 */
+    content: string;
+    /** 当前状态 */
+    status: TodoItemStatus;
+    /** 完成后的结果摘要 */
+    result?: string;
+}
+/** TODO 列表 */
+interface TodoList {
+    /** 唯一标识 */
+    id: string;
+    /** 整体任务标题 */
+    title: string;
+    /** 任务项列表 */
+    items: TodoItem[];
+    /** 创建时间 */
+    createdAt: number;
+}
+
+/**
+ * MCPLink 主类
+ * AI Agent 工具调用框架的入口
+ */
+declare class MCPLink {
+    private model;
+    private mcpManager;
+    private agent;
+    private promptBasedAgent;
+    private config;
+    private initialized;
+    private detectedNativeSupport;
+    constructor(config: MCPLinkConfig);
+    /**
+     * 初始化 - 连接所有 MCP 服务器
+     */
+    initialize(): Promise<void>;
+    /**
+     * 关闭 - 断开所有 MCP 服务器连接
+     */
+    close(): Promise<void>;
+    /**
+     * 发起对话
+     */
+    chat(message: string, callbacks?: ChatCallbacks): Promise<ChatResult>;
+    /**
+     * 流式对话
+     * @param message 用户消息
+     * @param options 可选参数
+     * @param options.allowedTools 允许使用的工具名称列表
+     * @param options.history 历史消息列表
+     */
+    chatStream(message: string, options?: {
+        allowedTools?: string[];
+        history?: Array<{
+            role: 'user' | 'assistant';
+            content: string;
+        }>;
+    }): AsyncGenerator<MCPLinkEvent>;
+    /**
+     * 获取当前使用的模式
+     */
+    getToolCallingMode(): 'native' | 'prompt-based';
+    /**
+     * 添加 MCP 服务器
+     */
+    addMCPServer(id: string, config: MCPServerConfig): void;
+    /**
+     * 移除 MCP 服务器
+     */
+    removeMCPServer(id: string): Promise<void>;
+    /**
+     * 启动指定 MCP 服务器
+     */
+    startMCPServer(id: string): Promise<void>;
+    /**
+     * 停止指定 MCP 服务器
+     */
+    stopMCPServer(id: string): Promise<void>;
+    /**
+     * 获取所有 MCP 服务器状态
+     */
+    getMCPServerStatuses(): MCPServerStatus[];
+    /**
+     * 获取所有可用工具
+     */
+    getTools(): MCPTool[];
+    /**
+     * 手动调用工具
+     */
+    callTool(toolName: string, args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * 更新系统提示词
+     */
+    setSystemPrompt(prompt: string): void;
+    /**
+     * 更新 AI 模型
+     */
+    setModel(model: LanguageModel): void;
+}
+
+/**
+ * MCP 管理器
+ * 负责管理多个 MCP 服务器的连接、工具发现和调用
+ */
+declare class MCPManager {
+    private servers;
+    /**
+     * 添加 MCP 服务器配置
+     */
+    addServer(id: string, config: MCPServerConfig): void;
+    /**
+     * 启动 MCP 服务器
+     */
+    startServer(id: string): Promise<void>;
+    /**
+     * 停止 MCP 服务器
+     */
+    stopServer(id: string): Promise<void>;
+    /**
+     * 启动所有已配置的服务器
+     */
+    startAll(): Promise<void>;
+    /**
+     * 停止所有服务器
+     */
+    stopAll(): Promise<void>;
+    /**
+     * 获取所有可用的工具
+     */
+    getAllTools(): MCPTool[];
+    /**
+     * 调用工具
+     */
+    callTool(toolName: string, args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * 获取所有服务器状态
+     */
+    getServerStatuses(): MCPServerStatus[];
+    /**
+     * 移除服务器
+     */
+    removeServer(id: string): Promise<void>;
+}
+
+/**
+ * 默认用户提示词
+ * 这只是用户自定义的部分，核心工具调用逻辑已内置到代码中
+ */
+declare const DEFAULT_SYSTEM_PROMPT = "\u4F60\u662F\u4E00\u4E2A\u667A\u80FD\u52A9\u624B\uFF0C\u8BF7\u4F7F\u7528\u4E2D\u6587\u56DE\u590D\u3002";
+/**
+ * Agent 引擎
+ * 负责执行 AI 对话循环，处理工具调用
+ */
+declare class Agent {
+    private model;
+    private mcpManager;
+    private systemPrompt;
+    private maxIterations;
+    constructor(model: LanguageModel, mcpManager: MCPManager, options?: {
+        systemPrompt?: string;
+        maxIterations?: number;
+    });
+    /**
+     * 将 MCP 工具转换为 Vercel AI SDK 格式
+     */
+    private convertMCPToolsToAITools;
+    /**
+     * 简单的 JSON Schema 到 Zod 转换
+     */
+    private jsonSchemaToZod;
+    /**
+     * 执行对话
+     */
+    chat(userMessage: string, callbacks?: ChatCallbacks): Promise<ChatResult>;
+    /**
+     * 流式对话 - 返回事件生成器
+     * @param userMessage 用户消息
+     * @param options 可选参数
+     * @param options.allowedTools 允许使用的工具名称列表，为空或不传则使用所有工具
+     * @param options.history 历史消息列表
+     */
+    chatStream(userMessage: string, options?: {
+        allowedTools?: string[];
+        history?: Array<{
+            role: 'user' | 'assistant';
+            content: string;
+        }>;
+    }): AsyncGenerator<MCPLinkEvent>;
+}
+
+/**
+ * 基于 Prompt 的 Agent
+ * 通过 prompt 工程让任意模型支持工具调用和思考过程
+ *
+ * 设计原则：
+ * 1. 简洁 - 不做过多干预，让 AI 自己思考和决策
+ * 2. 通用 - 支持任何模型，不依赖特定 API
+ * 3. 可靠 - 稳定的状态机解析
+ */
+declare class PromptBasedAgent {
+    private model;
+    private mcpManager;
+    private systemPrompt;
+    private maxIterations;
+    constructor(model: LanguageModel, mcpManager: MCPManager, options?: {
+        systemPrompt?: string;
+        maxIterations?: number;
+    });
+    /**
+     * 生成工具列表描述
+     */
+    private generateToolsDescription;
+    /**
+     * 内置系统提示词 - 强调格式约束
+     */
+    private readonly BUILT_IN_PROMPT;
+    /**
+     * 构建完整的系统提示词
+     */
+    private buildSystemPrompt;
+    /**
+     * 解析工具调用
+     */
+    private parseToolCall;
+    /**
+     * 智能压缩历史消息
+     * - 用户消息完整保留
+     * - AI 回复保留关键信息（ID、名称、数量、价格等）
+     * - 去除冗长的 JSON 原始数据
+     */
+    private compressHistory;
+    /**
+     * 流式对话
+     */
+    chatStream(userMessage: string, options?: {
+        allowedTools?: string[];
+        history?: Array<{
+            role: 'user' | 'assistant';
+            content: string;
+        }>;
+    }): AsyncGenerator<MCPLinkEvent>;
+}
+
+export { Agent, type ChatCallbacks, type ChatResult, DEFAULT_SYSTEM_PROMPT, MCPLink, type MCPLinkConfig, type MCPLinkEvent, type MCPLinkEventData, MCPLinkEventType, MCPManager, type MCPServerConfig, type MCPServerConfigSSE, type MCPServerConfigStdio, type MCPServerStatus, type MCPTool, type Message, type MessageRole, PromptBasedAgent, type TodoItem, type TodoItemStatus, type TodoList, type ToolCall, type ToolResult };