npm package: @kagol/next-sdk-cursor
Description: 基于 MCP (Model Context Protocol) 协议的智能化开发套件，让 Web 应用轻松实现 AI 智能体操控。
Latest version: 0.0.1

# @opentiny/next-sdk

基于 MCP (Model Context Protocol) 协议的智能化开发套件，让 Web 应用轻松实现 AI 智能体操控。

## 特性

- 🚀 **简化开发**：将复杂的 MCP 协议封装成简单的 API
- 🔧 **工具注册**：轻松注册和管理 MCP 工具
- 📦 **资源管理**：支持图片、文档等资源的注册和更新
- 💬 **智能对话**：集成大模型采样功能
- 🔄 **长时间任务**：支持带进度反馈的长时间任务
- 👤 **用户引导**：内置用户信息收集功能
- 🔌 **自动连接**：自动处理传输连接和错误重连

## 安装

```bash
npm install @opentiny/next-sdk
```

## 快速开始

### 主页面设置

```typescript
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();
```

### 子页面设置

```typescript
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 工具。

```typescript
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 资源。

```typescript
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

采样管理器，用于与大模型进行对话。

```typescript
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

工具调用器，用于调用远程工具。

```typescript
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

```typescript
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