@opentiny/next-sdk

基于 MCP (Model Context Protocol) 协议的智能化开发套件，让 Web 应用轻松实现 AI 智能体操控。

特性

• 🚀 简化开发：将复杂的 MCP 协议封装成简单的 API
• 🔧 工具注册：轻松注册和管理 MCP 工具
• 📦 资源管理：支持图片、文档等资源的注册和更新
• 💬 智能对话：集成大模型采样功能
• 🔄 长时间任务：支持带进度反馈的长时间任务
• 👤 用户引导：内置用户信息收集功能
• 🔌 自动连接：自动处理传输连接和错误重连

安装

npm install @opentiny/next-sdk

快速开始

主页面设置

import { NextSDK } from '@opentiny/next-sdk';

// 初始化主页面
const sdk = await NextSDK.initMainPage({
  name: 'ECS Console',
  clientId: 'ecs-console-client',
  redirectUris: ['http://localhost:8001/auth/callback']
});

// 连接到流代理
await sdk.connectProxy('http://localhost:3000/mcp');

// 获取传输对，传递给子页面
const { transport, clientTransport } = sdk.getTransportPair();

子页面设置

import { NextSDK } from '@opentiny/next-sdk';
import { z } from 'zod';

// 初始化子页面
const sdk = await NextSDK.initSubPage(serverTransport, {
  name: 'Advanced Config'
});

// 注册工具
const toolRegistry = sdk.getToolRegistry();
toolRegistry.registerTool({
  name: 'get-discount',
  description: '根据配置总费用获取优惠价格',
  paramsSchema: z.object({
    totalPrice: z.number().describe('配置总费用')
  }),
  callback: async ({ totalPrice }) => {
    const discountPrice = totalPrice * 0.9;
    return { content: [{ type: 'text', text: String(discountPrice) }] };
  }
});

API 文档

NextSDK

主要的 SDK 类，提供完整的 MCP 功能。

静态方法

• NextSDK.initMainPage(config) - 初始化主页面
• NextSDK.initSubPage(serverTransport, config) - 初始化子页面

实例方法

• initClient() - 初始化客户端
• initServer(serverTransport) - 初始化服务端
• connectProxy(url, sessionId) - 连接到流代理
• getToolRegistry() - 获取工具注册器
• getResourceRegistry() - 获取资源注册器
• getSamplingManager() - 获取采样管理器
• getToolCaller() - 获取工具调用器
• cleanup() - 清理资源

ToolRegistry

工具注册器，用于注册和管理 MCP 工具。

const toolRegistry = sdk.getToolRegistry();

// 注册简单工具
const tool = toolRegistry.registerTool({
  name: 'calculate',
  description: '计算功能',
  paramsSchema: z.object({
    a: z.number(),
    b: z.number()
  }),
  callback: async ({ a, b }) => {
    return { content: [{ type: 'text', text: String(a + b) }] };
  }
});

// 注册长时间任务
const longTask = toolRegistry.registerLongTask({
  name: 'process-data',
  description: '处理数据',
  onProgress: (progress, total, message) => {
    console.log(`进度: ${progress}/${total} - ${message}`);
  },
  callback: async (params, context) => {
    const { sendNotification, signal } = context;
    
    for (let i = 1; i <= 10; i++) {
      if (signal.aborted) break;
      
      await sendNotification({
        method: 'notifications/progress',
        params: {
          progress: i,
          total: 10,
          message: `处理步骤 ${i}`
        }
      });
      
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
    
    return { content: [{ type: 'text', text: '处理完成' }] };
  }
});

ResourceRegistry

资源注册器，用于注册和管理 MCP 资源。

const resourceRegistry = sdk.getResourceRegistry();

// 注册图片资源
const imageResource = resourceRegistry.registerResource({
  name: 'images',
  template: 'file:///images/{name}.png',
  list: ['logo', 'icon'],
  complete: {
    name: () => ['logo', 'icon']
  },
  callback: async (uri, { name }) => ({
    contents: [{
      uri: uri.href,
      mimeType: 'image/png',
      text: `<img src="${name}.png" />`
    }]
  })
});

// 注册提示
const prompt = resourceRegistry.registerPrompt({
  name: 'help-prompt',
  messages: [{
    role: 'assistant',
    content: { type: 'text', text: '我可以帮助您配置系统参数' }
  }]
});

// 注册用户引导
const elicitation = resourceRegistry.registerElicitation({
  name: 'collect-info',
  title: '收集信息',
  description: '收集用户基本信息',
  schema: {
    type: 'object',
    properties: {
      name: { type: 'string', title: '姓名' },
      email: { type: 'string', title: '邮箱' }
    },
    required: ['name', 'email']
  },
  message: '请提供您的个人信息',
  onAccept: (data) => console.log('用户信息:', data),
  onDecline: () => console.log('用户拒绝提供信息')
});

SamplingManager

采样管理器，用于与大模型进行对话。

const samplingManager = sdk.getSamplingManager();

// 简单采样
const response = await samplingManager.simpleSampling('什么是人工智能？', {
  model: 'claude-3-sonnet',
  maxTokens: 200
});

// 自定义采样
const customResponse = await samplingManager.createSampling({
  messages: [{
    role: 'user',
    content: { type: 'text', text: '请解释机器学习' }
  }],
  modelPreferences: {
    hints: [{ name: 'claude-3-sonnet' }],
    intelligencePriority: 0.8,
    speedPriority: 0.5
  },
  systemPrompt: '你是一个专业的AI助手',
  maxTokens: 300
});

ToolCaller

工具调用器，用于调用远程工具。

const toolCaller = sdk.getToolCaller();

// 调用工具
const result = await toolCaller.callTool('calculate', {
  a: 10,
  b: 20
});

// 启动长时间任务
const { promise, controller, cancel } = await toolCaller.startLongTask('process-data', {
  data: 'some data'
}, {
  onProgress: (progress) => {
    console.log(`进度: ${progress.progress}/${progress.total}`);
  },
  onCancel: (reason) => {
    console.log(`任务被取消: ${reason}`);
  }
});

// 取消任务
cancel('用户取消了任务');

配置选项

NextSDKConfig

interface NextSDKConfig {
  name?: string;                    // SDK 名称
  version?: string;                 // SDK 版本
  clientId?: string;               // 客户端 ID
  redirectUris?: string[];         // 重定向 URI
  capabilities?: any;              // MCP 能力配置
  onError?: (error: Error) => void; // 错误处理函数
  onReconnect?: () => void;        // 重连处理函数
}

完整示例

查看 src/examples.ts 文件中的完整使用示例。

许可证

MIT