@opentiny/next 0.1.4 → 0.2.1

package/README.md

@@ -89,349 +89,6 @@ state.client = client;
 
 请注意：创建 `MessageChannelServerTransport` 实例必须在创建 `MessageChannelClientTransport` 实例之前，确保客户端连接之前服务端已经开始监听。由于 iframe、Web Worker 等代码运行通常在浏览器主线程之后，所以上述示例代码执行顺序一般是先创建 `MessageChannelServerTransport` 实例，后创建 `MessageChannelClientTransport` 实例。
 
-### SSE (Server-Sent Events) Client Proxy
-
-使用 `MessageChannel API` 创建的 `Client` 客户端实例运行在浏览器环境中，为了能够被后端服务的 AI 调用，需要借助 `createSseProxy` 方法创建该 `Client` 的代理。
-
-```typescript
-import { createSseProxy, ProxySSEClientTransport } from '@opentiny/next';
-import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
-
-// 定义页面的状态
-const state: {
-  sseTransport: ProxySSEClientTransport | undefined;
-  client: Client | undefined;
-} = {
-  sseTransport: undefined,
-  client: undefined
-};
-
-// 使用 SSE 代理连接到服务端
-const connectSseProxy = async () => {
-  if (!state.sseTransport) {
-    const { transport, sessionId } = await createSseProxy({
-      client: state.client as Client,
-      url: location + 'agent/sse',
-      token: process.env.USER_TOKEN as string
-    });
-
-    state.sseTransport = transport;
-  }
-};
-
-// 使用 SSE 代理调用工具方法
-const callSseProxy = async (question: string) => {
-  if (!state.sseTransport) {
-    console.error('You need to connect SSE Proxy first!');
-    return;
-  }
-
-  const sessionId = state.sseTransport.sessionId;
-  return await request('/question', { question, sessionId });
-};
-
-// 发送 HTTP 请求
-const request = async (url: string, data: string) => {
-  const response = await fetch(url, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      Authorization: `Bearer ${process.env.USER_TOKEN}`
-    },
-    body: JSON.stringify(data)
-  });
-
-  if (!response.ok) {
-    throw new Error(response.statusText);
-  }
-
-  return await response.json();
-};
-```
-
-请注意：在调用 `callSseProxy` 之前需要调用 `connectSseProxy`，只有代理连接成功后，后端服务的 AI 才能通过该代理调用浏览器环境下的 `Client` 客户端的工具方法。为了让后端服务能够找到当前浏览器的 `Client` 客户端连接，需要向后端服务传递 `sseTransport` 的 `sessionId`。
-
-### Streamable HTTP Client Proxy
-
-使用 `MessageChannel API` 创建的 `Client` 客户端实例运行在浏览器环境中，为了能够被后端服务的 AI 调用，需要借助 `createStreamProxy` 方法创建该 `Client` 的代理。
-
-```typescript
-import { createStreamProxy, ProxyStreamClientTransport } from '@opentiny/next';
-import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
-
-// 定义页面的状态
-const state: {
-  streamTransport: ProxyStreamClientTransport | undefined;
-  client: Client | undefined;
-} = {
-  streamTransport: undefined,
-  client: undefined
-};
-
-// 使用 Stream 代理连接到服务端
-const connectStreamProxy = async () => {
-  if (!state.streamTransport) {
-    const { transport, sessionId } = await createStreamProxy({
-      client: state.client as Client,
-      url: location + 'agent/mcp',
-      token: process.env.USER_TOKEN as string
-    });
-
-    state.streamTransport = transport;
-  }
-};
-
-// 使用 Streamable HTTP 代理调用工具方法
-const callStreamProxy = async (question: string) => {
-  if (!state.streamTransport) {
-    console.error('You need to connect Streamable HTTP Proxy first!');
-    return;
-  }
-
-  const sessionId = state.streamTransport.sessionId;
-  return await request('/question', { question, sessionId });
-};
-
-// 关闭 Streamable HTTP 代理连接
-const closeStreamProxy = async () => {
-  if (state.streamTransport) {
-    await state.streamTransport.terminateSession();
-    state.streamTransport = undefined;
-  }
-};
-
-// 在页面窗口装载时注册关闭 Streamable HTTP 连接的事件
-window.addEventListener('beforeunload', closeStreamProxy);
-
-// 在页面窗口卸载时移除注册关闭 Streamable HTTP 连接的事件
-window.removeEventListener('beforeunload', closeStreamProxy);
-```
-
-请注意：在调用 `callStreamProxy` 之前需要调用 `connectStreamProxy`，只有代理连接成功后，后端服务的 AI 才能通过该代理调用浏览器环境下的 `Client` 客户端的工具方法。为了让后端服务能够找到当前浏览器的 `Client` 客户端连接，需要向后端服务传递 `streamTransport` 的 `sessionId`。
-
-与 `SSE` 的连接可以自动关闭不同，`Streamable HTTP` 的连接需要手动关闭，即要调用 `streamTransport.terminateSession()` 方法来中断连接。
-
-## 服务端 API (server.js)
-
-服务端 API 主要用于在 Node.js 环境中创建 MCP 服务端，处理来自客户端的连接请求。
-
-### SSE (Server-Sent Events) Server Proxy
-
-以下是 Express 环境 Node.js 服务端连接代理的示例代码：
-
-```typescript
-import express from 'express';
-import session from 'express-session';
-import cors from 'cors';
-import { auth, useProxyHandles } from '@opentiny/next/server.js';
-import type { Request, Response } from 'express';
-import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
-
-const { handleSseProxy, handleSseInspector, handleSseMessage, clients } = useProxyHandles();
-
-const app = express();
-
-// 启用跨域资源共享
-app.use(cors());
-
-// 获取代理背后真实的 IP 地址
-app.set('trust proxy', 1);
-
-// 配置 session 中间件，支持会话管理
-app.use(
-  session({
-    secret: process.env.SECRET_KEY as string, // 会话密钥
-    cookie: { maxAge: 60000 }, // 会话有效期
-    resave: false,
-    saveUninitialized: true
-  })
-);
-
-// 获取所有客户端的 sessionId
-app.get('/list', async (req: Request, res: Response) => {
-  const sessions: Record<string, object> = {};
-  for (const sessionId in clients) {
-    const { user, device, type } = clients[sessionId];
-    sessions[sessionId] = { user, device, type };
-  }
-  res.json(sessions);
-});
-
-// 启用认证中间件
-app.use(auth({ secret: process.env.SECRET_KEY as string }));
-
-// MCP inspector url http://localhost:5173/agent/inspector?sessionId=
-app.get('/inspector', async (req: Request, res: Response) => {
-  try {
-    await handleSseInspector(req, res, '/agent/messages');
-  } catch (error) {
-    console.error('AI Agent inspector error:', (error as Error).message);
-  }
-});
-
-// SSE 端点，支持 inspector 和 proxy 两种模式，inspector url http://localhost:8001/sse?sessionId=
-app.get('/sse', async (req: Request, res: Response) => {
-  try {
-    if (req.query.sessionId) {
-      await handleSseInspector(req, res, '/messages');
-    } else {
-      await handleSseProxy(req, res, '/agent/messages');
-    }
-  } catch (error) {
-    console.error('AI Agent proxy error:', (error as Error).message);
-  }
-});
-
-// 消息转发端点，根据 sessionId 找到对应 transport 处理消息
-app.post('/messages', async (req: Request, res: Response) => {
-  try {
-    await handleSseMessage(req, res);
-  } catch (error) {
-    console.error('AI Agent message error:', (error as Error).message);
-  }
-});
-
-// 用户提问端点，支持带 sessionId 的上下文调用
-app.post('/question', express.json(), async (req: Request, res: Response) => {
-  try {
-    const sessionId = req.body.sessionId as string;
-    const client = clients[sessionId]?.client;
-    const question = req.body.question as string;
-    const answer = await ask(question, client); // 需自行实现 AI 调用 Client 的工具
-    res.json({ answer });
-  } catch (error) {
-    console.error('AI Agent question error:', (error as Error).message);
-  }
-});
-
-app.listen(8001, () => {
-  console.log('AI Agent listening on port 8001');
-});
-```
-
-### Streamable HTTP Server Proxy
-
-以下是 Express 环境 Node.js 服务端连接代理的示例代码：
-
-```typescript
-import express from 'express';
-import session from 'express-session';
-import cors from 'cors';
-import { auth, useProxyHandles } from '@opentiny/next/server.js';
-import type { Request, Response } from 'express';
-import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
-
-const { handleStreamRequest, handleStreamInspector, clients } = useProxyHandles();
-
-const app = express();
-
-// 启用跨域资源共享
-app.use(cors());
-
-// 获取代理背后真实的 IP 地址
-app.set('trust proxy', 1);
-
-// 配置 session 中间件，支持会话管理
-app.use(
-  session({
-    secret: process.env.SECRET_KEY as string, // 会话密钥
-    cookie: { maxAge: 60000 }, // 会话有效期
-    resave: false,
-    saveUninitialized: true
-  })
-);
-
-// 获取所有客户端的 sessionId
-app.get('/list', async (req: Request, res: Response) => {
-  const sessions: Record<string, object> = {};
-  for (const sessionId in clients) {
-    const { user, device, type } = clients[sessionId];
-    sessions[sessionId] = { user, device, type };
-  }
-  res.json(sessions);
-});
-
-// 启用认证中间件
-app.use(auth({ secret: process.env.SECRET_KEY as string }));
-
-// 处理 Streamable HTTP 服务端 POST/GET/DELETE 连接
-// 可以使用 MCP inspector 连接调试，方式与 SSE 连接相同，如下：
-// http://localhost:8001/mcp?sessionId= 或 http://localhost:5173/agent/mcp?sessionId=
-app.all('/mcp', express.json(), async (req: Request, res: Response) => {
-  try {
-    if (req.query.sessionId) {
-      await handleStreamInspector(req, res);
-    } else {
-      await handleStreamRequest(req, res);
-    }
-  } catch (error) {
-    console.error('AI Agent mcp error:', (error as Error).message);
-  }
-});
-
-// 用户提问端点，支持带 sessionId 的上下文调用
-app.post('/question', express.json(), async (req: Request, res: Response) => {
-  try {
-    const sessionId = req.body.sessionId as string;
-    const client = clients[sessionId]?.client;
-    const question = req.body.question as string;
-    const answer = await ask(question, client); // 需自行实现 AI 调用 Client 的工具
-    res.json({ answer });
-  } catch (error) {
-    console.error('AI Agent question error:', (error as Error).message);
-  }
-});
-
-app.listen(8001, () => {
-  console.log('AI Agent listening on port 8001');
-});
-```
-
-## Vite 工程配置示例
-
-以上示例代码均基于 Vite 工程配置运行，增加了环境变量以及代理转发等，以下是 `vite.config.ts` 示例：
-
-```typescript
-import { defineConfig } from 'vite';
-import vue from '@vitejs/plugin-vue';
-import dotenv from 'dotenv';
-import path from 'path';
-
-// Vite 配置文件
-export default defineConfig(() => {
-  // 加载 .env 文件中的环境变量
-  dotenv.config({ path: '.env' });
-
-  return {
-    // 注入环境变量到前端代码
-    define: {
-      'process.env': {
-        USER_TOKEN: process.env.USER_TOKEN
-      }
-    },
-    plugins: [vue()],
-    server: {
-      proxy: {
-        // 代理 /agent 开头的请求到本地 8001 端口（AI Agent 服务）
-        '/agent': {
-          target: 'http://localhost:8001',
-          changeOrigin: true,
-          rewrite: (path) => path.replace(/^\/agent/, '')
-        }
-      }
-    }
-  };
-});
-```
-
-## 注意事项
-
-1. 确保在服务端使用时安装 `express` 作为依赖
-2. 使用 JWT 令牌认证时，请保护好密钥
-3. 在生产环境中，应该设置适当的 CORS 配置
-4. SSE 连接会保持打开状态，请确保适当处理资源释放
-5. 使用 Streamable HTTP 时，记得在会话结束时调用 `terminateSession()` 方法关闭连接
-
 ## 许可证
 
 MIT

package/client.d.ts

@@ -1,8 +1,8 @@
 import { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
 import { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { SSEClientTransport, SSEClientTransportOptions } from '@modelcontextprotocol/sdk/client/sse.js';
-import { StreamableHTTPClientTransport, StreamableHTTPClientTransportOptions } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 
 /**
  * MessageChannelTransport 是一个用于在浏览器上下文之间传输消息的类。
@@ -94,69 +94,11 @@ declare class MessageChannelServerTransport extends MessageChannelTransport {
  */
 declare const createTransportPair: () => [MessageChannelTransport, MessageChannelTransport];
 
-/**
- * ProxySSEClientTransport（SSE 代理客户端传输类）
- * 该类用于通过 Server-Sent Events（SSE）协议从服务端接收消息，主要应用于浏览器等客户端环境，实现与服务端的实时消息通信。
- * 消息到达时会自动调用 forward.js 进行 method 分发交由代理处理。
- */
-declare class ProxySSEClientTransport extends SSEClientTransport {
-    _client: Client;
-    /**
-     * 构造函数
-     * @param url - SSE 服务端地址
-     * @param opts - 传输配置参数（如认证、请求头等）
-     * @param client - 客户端代理实例
-     */
-    constructor(url: URL, opts: SSEClientTransportOptions, client: Client);
-    /**
-     * 启动 SSE 连接或进行认证
-     * 重写父类方法，增加消息自动分发处理逻辑
-     *
-     * 收到 SSE 消息后，自动解析并转发到 forward.js 进行 method 分发。
-     * 若 forward 返回 undefined，则调用自定义 onmessage 回调。
-     */
-    _startOrAuth(): Promise<void>;
-    /**
-     * 获取当前会话 sessionId
-     */
-    get sessionId(): string;
-}
-
-/**
- * SSE 连接的启动或认证选项
- */
-interface StartSSEOptions {
-    resumptionToken?: string;
-    onresumptiontoken?: (token: string) => void;
-    replayMessageId?: string | number;
-}
-/**
- * ProxyStreamClientTransport（Streamable HTTP 代理客户端传输类）
- * 该类用于通过 Streamable HTTP 协议从服务端接收消息，主要应用于浏览器等客户端环境，实现与服务端的实时消息通信。
- * 消息到达时会自动调用 forward.js 进行 method 分发和业务处理。
- */
-declare class ProxyStreamClientTransport extends StreamableHTTPClientTransport {
-    _client: Client;
-    /**
-     * 构造函数
-     * @param url - Streamable HTTP 服务端地址
-     * @param opts - 传输配置参数（如认证、请求头等）
-     * @param client - 客户端代理实例
-     */
-    constructor(url: URL, opts: StreamableHTTPClientTransportOptions, client: Client);
-    /**
-     * 处理 SSE 数据流
-     * 重写父类方法，增加消息自动分发处理逻辑
-     *
-     * 收到 SSE 消息后，自动解析并转发到 forward.js 进行 method 分发。
-     * 若 forward 返回 undefined，则调用自定义 onmessage 回调。
-     *
-     * @param stream - SSE 可读数据流
-     * @param options - 启动 SSE 的配置参数
-     */
-    _handleSseStream(stream: ReadableStream, options: StartSSEOptions): void;
+declare module '@modelcontextprotocol/sdk/client/sse.js' {
+    interface SSEClientTransport {
+        sessionId: string;
+    }
 }
-
 /**
  * 客户端代理选项接口
  */
@@ -173,6 +115,10 @@ interface ClientProxyOption {
      * 代理服务器的身份验证令牌
      */
     token: string;
+    /**
+     * 可选的会话 ID，用于标识当前会话
+     */
+    sessionId?: string;
 }
 /**
  * 创建一个 SSE 客户端代理
@@ -181,7 +127,7 @@ interface ClientProxyOption {
  * @returns - 返回一个包含 transport 和 sessionId 的对象
  */
 declare const createSseProxy: (option: ClientProxyOption) => Promise<{
-    transport: ProxySSEClientTransport;
+    transport: SSEClientTransport;
     sessionId: string;
 }>;
 /**
@@ -191,7 +137,7 @@ declare const createSseProxy: (option: ClientProxyOption) => Promise<{
  * @returns - 返回一个包含 transport 和 sessionId 的对象
  */
 declare const createStreamProxy: (option: ClientProxyOption) => Promise<{
-    transport: ProxyStreamClientTransport;
+    transport: StreamableHTTPClientTransport;
     sessionId: string;
 }>;
 
@@ -200,21 +146,22 @@ declare const createStreamProxy: (option: ClientProxyOption) => Promise<{
  * 用于为 SSE 连接和 HTTP 请求统一设置认证头（Authorization）。
  *
  * @param token - 用于认证的 Bearer Token。
+ * @param sessionId - 可选的 sessionId，用于标识会话。
  * @returns 返回传输配置对象，包含 requestInit 和 eventSourceInit 两部分：
  *   - requestInit：fetch 请求的初始化配置，自动带上认证头。
  *   - eventSourceInit：自定义 fetch 方法，确保 SSE 连接也带上认证头。
  */
-declare const sseOptions: (token: string) => {
+declare const sseOptions: (token: string, sessionId?: string) => {
     requestInit: {
         headers: {
             Authorization: string;
+            "sse-session-id": string;
         };
     };
     eventSourceInit: {
         fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
     };
 };
-
 /**
  * 生成 StreamableHTTPServerTransport 构造函数所需的第二个可选参数（传输配置）。
  * 用于为 Streamable HTTP 连接和 HTTP 请求统一设置认证头（Authorization）。
@@ -224,7 +171,7 @@ declare const sseOptions: (token: string) => {
  * @returns 返回传输配置对象，包含以下内容：
  *   - requestInit：fetch 请求的初始化配置，自动带上认证头，并设置 Streamable HTTP 代理的会话 ID。
  */
-declare const streamOptions: (token: string, sessionId?: `${string}-${string}-${string}-${string}-${string}`) => {
+declare const streamOptions: (token: string, sessionId?: string) => {
     requestInit: {
         headers: {
             Authorization: string;
@@ -233,5 +180,12 @@ declare const streamOptions: (token: string, sessionId?: `${string}-${string}-${
     };
 };
 
-export { MessageChannelClientTransport, MessageChannelServerTransport, MessageChannelTransport, ProxySSEClientTransport, ProxyStreamClientTransport, createSseProxy, createStreamProxy, createTransportPair, sseOptions, streamOptions };
+/**
+ * 兼容安全策略的 UUID 生成方法，支持浏览器和 Node.js 环境
+ *
+ * @returns 返回一个 UUID 字符串
+ */
+declare const generateUUID: () => string;
+
+export { MessageChannelClientTransport, MessageChannelServerTransport, MessageChannelTransport, createSseProxy, createStreamProxy, createTransportPair, generateUUID, sseOptions, streamOptions };
 export type { ClientProxyOption };