@n0ts123/mcplink-core 0.0.1 → 0.0.3

package/README.md

@@ -1,49 +1,76 @@
-# @mcplink/core
+# @n0ts123/mcplink-core
 
-MCPLink 核心 SDK - AI Agent 工具调用框架
+MCPLink 核心 SDK - AI Agent 工具调用框架，让 AI 轻松调用 MCP 工具。
 
-## 安装
+[![npm version](https://img.shields.io/npm/v/@n0ts123/mcplink-core.svg)](https://www.npmjs.com/package/@n0ts123/mcplink-core)
+[![license](https://img.shields.io/npm/l/@n0ts123/mcplink-core.svg)](https://github.com/n0tssss/MCPLink/blob/master/LICENSE)
+[![GitHub](https://img.shields.io/badge/GitHub-n0tssss%2FMCPLink-blue)](https://github.com/n0tssss/MCPLink)
 
-```bash
-npm install @mcplink/core ai @ai-sdk/openai
-```
+## ✨ 特性
 
-根据你使用的模型，还需要安装对应的 AI SDK：
+- 🚀 **简单易用** - 几行代码即可让 AI 调用 MCP 工具
+- 🔄 **流式响应** - 支持实时流式输出，体验更流畅
+- 🤖 **多模型支持** - OpenAI GPT、Claude、Gemini、DeepSeek、Qwen、Llama 等
+- 🛠️ **MCP 协议** - 支持 stdio、SSE、Streamable HTTP 三种连接方式
+- ⚡ **并行调用** - 支持同时执行多个独立的工具调用
+- 💭 **思考过程** - 展示 AI 推理过程，支持 `<think>` 标签和原生 reasoning
+- 🎯 **即时结果** - 工具返回特定格式时立即推送（如卡片消息）
+- 🔀 **智能路由** - 根据模型自动选择原生或 Prompt-Based 模式
+- 📦 **TypeScript** - 完整的类型支持
 
-```bash
-# OpenAI (GPT-4, GPT-3.5)
-npm install @ai-sdk/openai
+## 📦 安装
 
-# Google (Gemini)
-npm install @ai-sdk/google
+```bash
+# npm
+npm install @n0ts123/mcplink-core
 
-# Anthropic (Claude)
-npm install @ai-sdk/anthropic
+# pnpm
+pnpm add @n0ts123/mcplink-core
 
-# 兼容 OpenAI 格式的模型 (DeepSeek, Qwen, 等)
-# 使用 @ai-sdk/openai 即可
+# yarn
+yarn add @n0ts123/mcplink-core
 ```
 
-## 快速开始
+> 💡 **内置 AI SDK**：本包已内置 `@ai-sdk/openai` 和 `@ai-sdk/anthropic`，无需额外安装即可直接使用。
+>
+> 如需使用 Google Gemini，需额外安装：`npm install @ai-sdk/google`
+
+## 🚀 快速开始
 
-### 最小示例
+### TypeScript / JavaScript (ESM)
 
 ```typescript
-import { MCPLink } from '@mcplink/core'
-import { createOpenAI } from '@ai-sdk/openai'
+import { MCPLink, createOpenAI } from '@n0ts123/mcplink-core'
 
 // 创建模型
-const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY })
+const openai = createOpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  baseURL: 'https://api.openai.com/v1',  // 可选
+})
 
 // 创建 Agent
 const agent = new MCPLink({
   model: openai('gpt-4o'),
+  systemPrompt: '你是一个智能助手',
+  maxIterations: 10,
+  parallelToolCalls: true,  // 启用并行工具调用
   mcpServers: {
+    // stdio 模式
     myTools: {
       type: 'stdio',
       command: 'node',
       args: ['./my-mcp-server.js'],
     },
+    // SSE 模式
+    remote: {
+      type: 'sse',
+      url: 'http://localhost:8080/mcp',
+    },
+    // Streamable HTTP 模式
+    streamable: {
+      type: 'streamable-http',
+      url: 'http://localhost:8080/mcp/stream',
+    },
   },
 })
 
@@ -54,23 +81,56 @@ console.log(result.content)
 await agent.close()
 ```
 
+### JavaScript (CommonJS)
+
+> ⚠️ 注意：本包是 ES Module，在 CommonJS 环境中需要使用动态 import
+
+```javascript
+async function main() {
+  const { MCPLink, createOpenAI } = await import('@n0ts123/mcplink-core')
+
+  const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY })
+
+  const agent = new MCPLink({
+    model: openai('gpt-4o'),
+    mcpServers: {
+      myTools: {
+        type: 'stdio',
+        command: 'node',
+        args: ['./my-mcp-server.js'],
+      },
+    },
+  })
+
+  await agent.initialize()
+  const result = await agent.chat('你好')
+  console.log(result.content)
+  await agent.close()
+}
+
+main()
+```
+
 ### 流式响应
 
 ```typescript
-import { MCPLink, MCPLinkEventType } from '@mcplink/core'
+import { MCPLink, MCPLinkEventType, createOpenAI } from '@n0ts123/mcplink-core'
+
+const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY })
 
 const agent = new MCPLink({
   model: openai('gpt-4o'),
-  systemPrompt: '你是一个智能助手',
-  maxIterations: 10,
   mcpServers: { /* ... */ },
 })
 
 await agent.initialize()
 
-// 流式处理
 for await (const event of agent.chatStream('帮我查询订单')) {
   switch (event.type) {
+    case MCPLinkEventType.ITERATION_START:
+      console.log(`📍 开始第 ${event.data.iteration} 轮迭代`)
+      break
+      
     case MCPLinkEventType.THINKING_START:
       console.log('💭 思考中...')
       break
@@ -79,10 +139,6 @@ for await (const event of agent.chatStream('帮我查询订单')) {
       process.stdout.write(event.data.content || '')
       break
       
-    case MCPLinkEventType.THINKING_END:
-      console.log('\n')
-      break
-      
     case MCPLinkEventType.TOOL_CALL_START:
       console.log(`🔧 调用工具: ${event.data.toolName}`)
       console.log(`   参数: ${JSON.stringify(event.data.toolArgs)}`)
@@ -92,21 +148,18 @@ for await (const event of agent.chatStream('帮我查询订单')) {
       const status = event.data.isError ? '❌' : '✅'
       console.log(`${status} 结果 (${event.data.duration}ms)`)
       break
-      
-    case MCPLinkEventType.TEXT_START:
-      console.log('📝 回复:')
+
+    case MCPLinkEventType.IMMEDIATE_RESULT:
+      // 即时结果，可用于渲染特殊 UI
+      console.log('🎯 即时结果:', event.data.immediateResult)
       break
       
     case MCPLinkEventType.TEXT_DELTA:
       process.stdout.write(event.data.content || '')
       break
       
-    case MCPLinkEventType.TEXT_END:
-      console.log('\n')
-      break
-      
     case MCPLinkEventType.COMPLETE:
-      console.log(`✅ 完成! 总耗时: ${event.data.totalDuration}ms`)
+      console.log(`\n✅ 完成! 耗时: ${event.data.totalDuration}ms, 迭代: ${event.data.totalIterations}`)
       break
       
     case MCPLinkEventType.ERROR:
@@ -116,50 +169,47 @@ for await (const event of agent.chatStream('帮我查询订单')) {
 }
 ```
 
-## 配置选项
+## ⚙️ 配置选项
 
 ### MCPLinkConfig
 
 ```typescript
 interface MCPLinkConfig {
-  /**
-   * AI 模型实例（必填）
-   * 使用 Vercel AI SDK 创建的模型
-   */
+  /** AI 模型实例（必填）*/
   model: LanguageModel
 
-  /**
-   * 模型名称
-   * 用于自动检测是否支持原生 function calling
-   * 如果不提供，会尝试从 model.modelId 获取
-   */
+  /** 模型名称，用于自动检测是否支持原生 function calling */
   modelName?: string
 
-  /**
-   * 系统提示词
-   * 定义 AI 的角色和行为
-   */
+  /** 系统提示词 */
   systemPrompt?: string
 
-  /**
-   * 最大迭代次数
-   * 防止无限循环，默认 10
-   */
+  /** 最大迭代次数（默认 10）*/
   maxIterations?: number
 
-  /**
-   * MCP 服务器配置
-   * key 是服务器 ID，value 是服务器配置
-   */
+  /** MCP 服务器配置 */
   mcpServers?: Record<string, MCPServerConfig>
 
-  /**
+  /** 是否并行执行工具调用（默认 true）*/
+  parallelToolCalls?: boolean
+
+  /** 
    * 是否强制使用 Prompt-Based 模式
    * - true: 强制使用 PromptBasedAgent
    * - false: 强制使用原生 Agent
-   * - 'auto' | undefined: 自动检测
+   * - 'auto': 自动检测（默认）
    */
   usePromptBasedTools?: boolean | 'auto'
+
+  /**
+   * 是否启用思考阶段（默认 true）
+   * 启用后每次迭代会先让 AI 思考分析，再执行工具调用
+   * 优点：Chain-of-Thought 效应，提高复杂任务准确性
+   */
+  enableThinkingPhase?: boolean
+
+  /** 即时结果匹配器，匹配时触发 IMMEDIATE_RESULT 事件 */
+  immediateResultMatchers?: Array<Record<string, unknown>>
 }
 ```
 
@@ -168,96 +218,94 @@ interface MCPLinkConfig {
 ```typescript
 // Stdio 模式（本地进程）
 interface MCPServerConfigStdio {
-  type: 'stdio'
-  command: string      // 启动命令
-  args?: string[]      // 命令参数
-  env?: Record<string, string>  // 环境变量
+  type?: 'stdio'
+  command: string
+  args?: string[]
+  env?: Record<string, string>
 }
 
 // SSE 模式（远程服务）
 interface MCPServerConfigSSE {
   type: 'sse'
-  url: string          // SSE 端点 URL
-  headers?: Record<string, string>  // 请求头
+  url: string
+  headers?: Record<string, string>
+}
+
+// Streamable HTTP 模式
+interface MCPServerConfigStreamableHTTP {
+  type: 'streamable-http'
+  url: string
+  headers?: Record<string, string>
 }
 ```
 
-## 多模型支持
+## 🤖 多模型支持
+
+MCPLink 会根据模型自动选择最佳的调用方式：
+
+| 模型 | 模式 | 说明 |
+|------|------|------|
+| GPT-4o, GPT-4, GPT-3.5 | 原生 | 使用 function calling |
+| Claude-3, Claude-3.5 | 原生 | 使用 function calling |
+| Gemini Flash/Pro | 原生 | 使用 function calling |
+| Mistral, Mixtral | 原生 | 使用 function calling |
+| DeepSeek | Prompt-Based | 使用 prompt 引导 |
+| Qwen, 通义千问 | Prompt-Based | 使用 prompt 引导 |
+| Llama, Yi, GLM | Prompt-Based | 使用 prompt 引导 |
 
 ### OpenAI
 
 ```typescript
-import { createOpenAI } from '@ai-sdk/openai'
+import { MCPLink, createOpenAI } from '@n0ts123/mcplink-core'
 
-const openai = createOpenAI({
-  apiKey: process.env.OPENAI_API_KEY,
-})
-
-const agent = new MCPLink({
-  model: openai('gpt-4o'),  // 或 gpt-4o-mini, gpt-3.5-turbo
-})
+const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY })
+const agent = new MCPLink({ model: openai('gpt-4o') })
 ```
 
-### Google Gemini
+### Anthropic Claude
 
 ```typescript
-import { createGoogleGenerativeAI } from '@ai-sdk/google'
+import { MCPLink, createAnthropic } from '@n0ts123/mcplink-core'
 
-const google = createGoogleGenerativeAI({
-  apiKey: process.env.GOOGLE_API_KEY,
-})
-
-const agent = new MCPLink({
-  model: google('gemini-1.5-flash'),  // 或 gemini-1.5-pro
-})
+const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY })
+const agent = new MCPLink({ model: anthropic('claude-3-5-sonnet-20241022') })
 ```
 
-### Anthropic Claude
+### Google Gemini
 
-```typescript
-import { createAnthropic } from '@ai-sdk/anthropic'
+> 需额外安装：`npm install @ai-sdk/google`
 
-const anthropic = createAnthropic({
-  apiKey: process.env.ANTHROPIC_API_KEY,
-})
+```typescript
+import { MCPLink } from '@n0ts123/mcplink-core'
+import { createGoogleGenerativeAI } from '@ai-sdk/google'
 
-const agent = new MCPLink({
-  model: anthropic('claude-3-5-sonnet-20241022'),
-})
+const google = createGoogleGenerativeAI({ apiKey: process.env.GOOGLE_API_KEY })
+const agent = new MCPLink({ model: google('gemini-1.5-flash') })
 ```
 
-### 兼容 OpenAI 的模型
-
-DeepSeek、Qwen、GLM 等兼容 OpenAI 格式的模型：
+### DeepSeek / 通义千问
 
 ```typescript
-import { createOpenAI } from '@ai-sdk/openai'
+import { MCPLink, createOpenAI } from '@n0ts123/mcplink-core'
 
 // DeepSeek
 const deepseek = createOpenAI({
   apiKey: process.env.DEEPSEEK_API_KEY,
   baseURL: 'https://api.deepseek.com/v1',
 })
-
-const agent = new MCPLink({
-  model: deepseek('deepseek-chat'),
-})
+const agent = new MCPLink({ model: deepseek('deepseek-chat') })
 
 // 通义千问
 const qwen = createOpenAI({
   apiKey: process.env.QWEN_API_KEY,
   baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
 })
-
-const agent = new MCPLink({
-  model: qwen('qwen-turbo'),
-})
+const agent = new MCPLink({ model: qwen('qwen-plus') })
 ```
 
-## 多轮对话
+## 💬 多轮对话
 
 ```typescript
-// 方式一：手动管理历史
 const history: Array<{ role: 'user' | 'assistant'; content: string }> = []
 
 // 第一轮
@@ -276,39 +324,41 @@ for await (const event of agent.chatStream('第一个订单的详情', { history
 }
 ```
 
-## 工具过滤
+## 🔧 工具过滤
 
 ```typescript
 // 只允许使用特定工具
 for await (const event of agent.chatStream('搜索产品', {
   allowedTools: ['search_products', 'get_product_details'],
 })) {
-  // 只会调用 search_products 和 get_product_details
+  // 只会调用指定的工具
 }
 ```
 
-## 手动工具管理
+## 🎯 即时结果
 
-```typescript
-// 获取所有可用工具
-const tools = agent.getTools()
-console.log(tools.map(t => t.name))
+当 MCP 工具返回特定格式数据时，可立即推送给前端：
 
-// 手动调用工具
-const result = await agent.callTool('search_products', {
-  keyword: 'APC6-01',
+```typescript
+const agent = new MCPLink({
+  model: openai('gpt-4o'),
+  mcpServers: { /* ... */ },
+  // 配置即时结果匹配器
+  immediateResultMatchers: [
+    { type: 'card' },           // 匹配 { type: "card", ... }
+    { type: 'product_list' },   // 匹配 { type: "product_list", ... }
+  ],
 })
 
-// 获取 MCP 服务器状态
-const statuses = agent.getMCPServerStatuses()
-console.log(statuses)
-
-// 手动控制 MCP 服务器
-await agent.startMCPServer('myServer')
-await agent.stopMCPServer('myServer')
+for await (const event of agent.chatStream('搜索产品')) {
+  if (event.type === MCPLinkEventType.IMMEDIATE_RESULT) {
+    // 立即展示卡片/特殊格式数据
+    showCard(event.data.immediateResult)
+  }
+}
 ```
 
-## 事件类型详解
+## 📋 事件类型
 
 | 事件 | 说明 | 数据 |
 |------|------|------|
@@ -317,108 +367,69 @@ await agent.stopMCPServer('myServer')
 | `thinking_start` | 思考开始 | `{}` |
 | `thinking_delta` | 思考内容 | `{ content }` |
 | `thinking_end` | 思考结束 | `{}` |
+| `thinking_content` | 完整思考内容 | `{ content }` |
 | `text_start` | 文本开始 | `{}` |
 | `text_delta` | 文本内容 | `{ content }` |
 | `text_end` | 文本结束 | `{}` |
 | `tool_call_start` | 工具调用开始 | `{ toolName, toolCallId, toolArgs }` |
+| `tool_call_delta` | 工具参数流式 | `{ toolCallId, argsTextDelta }` |
 | `tool_executing` | 工具执行中 | `{ toolName, toolCallId, toolArgs }` |
-| `tool_result` | 工具执行结果 | `{ toolName, toolResult, toolCallId, duration, isError }` |
-| `complete` | 任务完成 | `{ totalDuration, totalIterations }` |
-| `error` | 发生错误 | `{ error }` |
+| `tool_result` | 工具结果 | `{ toolName, toolResult, toolCallId, duration, isError }` |
+| `immediate_result` | 即时结果 | `{ toolName, toolCallId, immediateResult }` |
+| `complete` | 完成 | `{ totalDuration, totalIterations }` |
+| `error` | 错误 | `{ error }` |
 
-## 高级用法
-
-### 直接使用 Agent
-
-如果你只需要使用特定的 Agent 实现：
+## 🔧 手动工具管理
 
 ```typescript
-import { Agent, PromptBasedAgent, MCPManager } from '@mcplink/core'
-import { createOpenAI } from '@ai-sdk/openai'
-
-const openai = createOpenAI({ apiKey: '...' })
-const mcpManager = new MCPManager()
-
-// 添加 MCP 服务器
-mcpManager.addServer('myTools', {
-  type: 'stdio',
-  command: 'node',
-  args: ['./server.js'],
-})
-
-// 启动服务器
-await mcpManager.startAll()
-
-// 使用原生 Agent（适用于支持 function calling 的模型）
-const nativeAgent = new Agent(openai('gpt-4o'), mcpManager, {
-  systemPrompt: '你是一个智能助手',
-  maxIterations: 10,
-})
-
-// 使用 Prompt-Based Agent（适用于所有模型）
-const promptAgent = new PromptBasedAgent(openai('gpt-4o'), mcpManager, {
-  systemPrompt: '你是一个智能助手',
-  maxIterations: 10,
-})
-
-// 流式对话
-for await (const event of promptAgent.chatStream('你好')) {
-  console.log(event)
-}
-
-// 关闭
-await mcpManager.stopAll()
-```
-
-### 自定义 MCP 管理器
-
-```typescript
-import { MCPManager } from '@mcplink/core'
-
-const mcpManager = new MCPManager()
-
-// 添加多个服务器
-mcpManager.addServer('business', {
-  type: 'stdio',
-  command: 'node',
-  args: ['./business-server.js'],
-})
-
-mcpManager.addServer('database', {
-  type: 'sse',
-  url: 'http://localhost:8080/mcp',
-  headers: { Authorization: 'Bearer xxx' },
-})
-
-// 按需启动
-await mcpManager.startServer('business')
+// 获取所有可用工具
+const tools = agent.getTools()
 
-// 获取所有工具
-const tools = mcpManager.getAllTools()
+// 手动调用工具
+const result = await agent.callTool('search_products', { keyword: 'test' })
 
-// 调用工具
-const result = await mcpManager.callTool('search_products', { keyword: 'test' })
+// 获取 MCP 服务器状态
+const statuses = agent.getMCPServerStatuses()
 
-// 获取状态
-const statuses = mcpManager.getServerStatuses()
+// 手动控制 MCP 服务器
+await agent.startMCPServer('myServer')
+await agent.stopMCPServer('myServer')
 ```
 
-## TypeScript 类型
+## 📝 TypeScript 类型
 
 ```typescript
 import type {
   MCPLinkConfig,
   MCPServerConfig,
+  MCPServerConfigStdio,
+  MCPServerConfigSSE,
+  MCPServerConfigStreamableHTTP,
   MCPLinkEvent,
+  MCPLinkEventData,
   MCPTool,
   MCPServerStatus,
   ChatResult,
-} from '@mcplink/core'
+  ChatCallbacks,
+  ImmediateResultMatcher,
+} from '@n0ts123/mcplink-core'
 
-import { MCPLinkEventType } from '@mcplink/core'
+import { MCPLinkEventType } from '@n0ts123/mcplink-core'
 ```
 
-## 许可证
+## 📋 环境要求
+
+- **Node.js**: >= 18.0.0
+- **模块系统**: ES Module（推荐）或 CommonJS（需使用动态 import）
+
+## 🔗 相关链接
+
+- [GitHub 仓库](https://github.com/n0tssss/MCPLink)
+- [完整文档](https://github.com/n0tssss/MCPLink#readme)
+- [问题反馈](https://github.com/n0tssss/MCPLink/issues)
+- [MCP 协议规范](https://modelcontextprotocol.io/)
+- [Vercel AI SDK](https://sdk.vercel.ai/)
 
-MIT
+## 📄 许可证
 
+MIT License © [n0tssss](https://github.com/n0tssss)