@opentiny/agent 0.3.2 → 0.3.4

package/README.md

@@ -1,13 +1,107 @@
-# OpenTiny Agent
+# OpenTiny NEXT
 
-OpenTiny Agent Server
+OpenTiny NEXT 是一个基于 Model Context Protocol（MCP）的 TypeScript 库，提供了多种传输方式来支持 MCP 客户端与服务端的通信。本库支持三种主要的传输方式：
+
+1. MessageChannel API - 用于浏览器内部不同上下文之间的通信
+2. SSE (Server-Sent Events) Client Proxy - 基于 HTTP 长连接实现单向数据推送的 Client 连接代理
+3. Streamable HTTP Client Proxy - 通过分块传输编码实现任意数据的流式传输的 Client 连接代理
 
 ## 安装
 
 ```bash
-npm install @opentiny/agent
+npm install @opentiny/next
 ```
 
+## 客户端 API (client.js)
+
+客户端 API 主要用于在浏览器环境中的 MCP 通信。
+
+### MessageChannel API
+
+#### 在同一浏览器窗口内互相通信的场景
+
+使用 `createTransportPair` 创建一对可互通的 Transport 服务的和客户端实例来进行通信。
+
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { createTransportPair } from '@opentiny/next';
+
+// 创建一对可互通的 Transport 实例
+const [serverTransport, clientTransport] = createTransportPair();
+
+// 创建 MCP 服务端和客户端实例
+const serverCapabilities = {
+  prompts: { listChanged: true },
+  resources: { subscribe: true, listChanged: true },
+  tools: { listChanged: true },
+  completions: {},
+  logging: {}
+};
+const clientCapabilities = { roots: { listChanged: true }, sampling: {}, elicitation: {} };
+const server = new McpServer({ name: 'mcp-server', version: '1.0.0' }, { capabilities: serverCapabilities });
+const client = new Client({ name: 'mcp-client', version: '1.0.0' }, { capabilities: clientCapabilities });
+
+// 建立服务端和客户端的通信连接
+await server.connect(serverTransport);
+await client.connect(clientTransport);
+
+// 将客户端实例存储到状态中
+state.client = client;
+```
+
+#### 在浏览器主线程与iframe、Web Worker等互相通信的场景
+
+使用 `MessageChannelServerTransport` 和 `MessageChannelClientTransport` 创建用于监听的 Transport 服务端实例，以及用于连接的 Transport 客户端实例来进行通信。
+
+以下是在浏览器主线程的代码：
+
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { MessageChannelServerTransport } from '@opentiny/next';
+
+// 创建用于监听的 Transport 服务端实例
+const serverTransport = new MessageChannelServerTransport('endpoint');
+
+// 创建 MCP 服务端实例
+const capabilities = {
+  prompts: { listChanged: true },
+  resources: { subscribe: true, listChanged: true },
+  tools: { listChanged: true },
+  completions: {},
+  logging: {}
+};
+const server = new McpServer({ name: 'mcp-server', version: '1.0.0' }, { capabilities });
+
+// 监听 endpoint 端点，等待客户端连接
+await serverTransport.listen();
+
+// 建立服务端和客户端的通信连接
+await server.connect(serverTransport);
+```
+
+以下是在 iframe、Web Worker 的代码：
+
+```typescript
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { MessageChannelClientTransport } from '@opentiny/next';
+
+// 创建用于连接的 Transport 客户端实例
+const clientTransport = new MessageChannelClientTransport('endpoint');
+
+// 创建 MCP 客户端实例
+const capabilities = { roots: { listChanged: true }, sampling: {}, elicitation: {} };
+const client = new Client({ name: 'mcp-client', version: '1.0.0' }, { capabilities });
+
+// 建立服务端和客户端的通信连接
+await client.connect(clientTransport);
+
+// 将客户端实例存储到状态中
+state.client = client;
+```
+
+请注意：创建 `MessageChannelServerTransport` 实例必须在创建 `MessageChannelClientTransport` 实例之前，确保客户端连接之前服务端已经开始监听。由于 iframe、Web Worker 等代码运行通常在浏览器主线程之后，所以上述示例代码执行顺序一般是先创建 `MessageChannelServerTransport` 实例，后创建 `MessageChannelClientTransport` 实例。
+
 ## 许可证
 
 MIT

package/index.d.ts

@@ -2,6 +2,9 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import WebSocket from 'ws';
 import { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
 import { Response, RequestHandler, Request, NextFunction } from 'express';
 import { JwtPayload } from 'jsonwebtoken';
@@ -9,6 +12,22 @@ import { OAuthClientInformationFull, OAuthTokens, OAuthTokenRevocationRequest }
 import { AuthorizationParams, OAuthServerProvider } from '@modelcontextprotocol/sdk/server/auth/provider.js';
 import { OAuthRegisteredClientsStore } from '@modelcontextprotocol/sdk/server/auth/clients.js';
 import { AuthRouterOptions } from '@modelcontextprotocol/sdk/server/auth/router.js';
+import { CorsOptions } from 'cors';
+
+/**
+ * Server transport for WebSocket: this will listen to clients over the WebSocket protocol.
+ */
+declare class WebSocketServerTransport implements Transport {
+    private _socket?;
+    sessionId?: string;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    constructor(socket: WebSocket);
+    start(): Promise<void>;
+    close(): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
+}
 
 declare const ACCESS_TOKEN_EXPIRES_IN: number;
 declare const REFRESH_TOKEN_EXPIRES_IN: number;
@@ -349,12 +368,13 @@ declare const createAuthCallbackRouter: (callbackEndpoint: string, ...middleware
 /**
  * 创建 OAuth 认证元数据路由。
  *
- * @param authServerProvider 认证服务器提供者
+ * @param authProvider 认证服务器提供者
  * @param authUrl 认证 URL
  * @param resourceUrl 资源 URL
+ * @param issuerUrl 签发者 URL，可选
  * @returns Express 路由处理器
  */
-declare const createAuthMetadataRouter: (authServerProvider: AuthServerProvider, authUrl: string, resourceUrl: string) => RequestHandler;
+declare const createAuthMetadataRouter: (authProvider: AuthServerProvider, authUrl: string, resourceUrl: string, issuerUrl?: string) => RequestHandler;
 /**
  * 创建 OAuth 认证路由。
  *
@@ -362,6 +382,15 @@ declare const createAuthMetadataRouter: (authServerProvider: AuthServerProvider,
  * @returns Express 路由处理器
  */
 declare const createAuthRouter: (options: AuthRouterOptions) => RequestHandler;
+/**
+ * 创建锁定 CORS 头中间件
+ * 配置的 CORS 规则，并锁定 Access-Control-Allow-Origin,
+ * 防止后续中间件（如第三方库）修改它。
+ *
+ * @param options CORS 选项
+ * @returns Express 中间件函数
+ */
+declare const lockCors: (options: CorsOptions) => (req: Request, res: Response, next: NextFunction) => void;
 
 /**
  * 客户端连接的信息，包括客户端实例、用户信息和 Transport 类型。
@@ -374,7 +403,7 @@ interface ClientInfo {
     /**
      * 客户端连接的 Transport 实例
      */
-    transport: SSEServerTransport | StreamableHTTPServerTransport;
+    transport: SSEServerTransport | StreamableHTTPServerTransport | WebSocketServerTransport;
     /**
      * 连接的用户信息
      */
@@ -403,7 +432,7 @@ interface ClientInfo {
     /**
      * 客户端连接的 Transport 类型
      */
-    type: 'SSE' | 'StreamableHTTP';
+    type: 'SSE' | 'StreamableHTTP' | 'WebSocket';
 }
 /**
  * 遥控端连接的信息，包括服务端实例、用户信息和 Transport 类型。
@@ -462,7 +491,7 @@ interface ClientError {
     /**
      * 客户端连接的 Transport 实例
      */
-    transport: SSEServerTransport | StreamableHTTPServerTransport;
+    transport: SSEServerTransport | StreamableHTTPServerTransport | WebSocketServerTransport;
     /**
      * 错误信息
      */
@@ -470,7 +499,7 @@ interface ClientError {
     /**
      * 服务端连接的 Transport 类型
      */
-    type: 'SSE' | 'StreamableHTTP';
+    type: 'SSE' | 'StreamableHTTP' | 'WebSocket';
 }
 /**
  * RemoterError 接口，在遥控端连接或处理过程中发生的错误。
@@ -516,6 +545,14 @@ declare module 'express' {
 declare const auth: ({ secret }: {
     secret: string;
 }) => (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * 请求认证，用于校验 JWT Token。
+ *
+ * 检查 request.query 中的 token 字段。
+ * 校验通过后，将解码后的用户信息挂载到 req.user
+ * 校验失败或缺失 token 时，抛出异常。
+ */
+declare const jwtAuth: (req: Request, secret: string) => void;
 /**
  * SSE 与 Streamable HTTP 连接的处理函数，同时返回所有客户端代理实例。
  */
@@ -525,6 +562,7 @@ declare const useProxyHandles: () => {
     handleSseMessage: (req: Request, res: Response) => Promise<void>;
     handleStreamRequest: (req: Request, res: Response) => Promise<void>;
     handleStreamInspector: (req: Request, res: Response) => Promise<void>;
+    handleWebSocket: (socket: WebSocket, req: Request) => Promise<void>;
     clients: Record<string, ClientInfo>;
     remoters: Record<string, RemoterInfo>;
     transports: Record<string, any>;
@@ -538,5 +576,5 @@ declare const useProxyHandles: () => {
     onRemoterError: (onError: (error: RemoterError) => void) => void;
 };
 
-export { ACCESS_TOKEN_EXPIRES_IN, AuthServerProvider, MemoryAccessTokensStore, MemoryAuthorizationCodeStore, MemoryClientsStore, MemoryRefreshTokensStore, REFRESH_TOKEN_EXPIRES_IN, auth, createAuthCallbackRouter, createAuthMetadataRouter, createAuthMiddleware, createAuthRouter, useProxyHandles };
+export { ACCESS_TOKEN_EXPIRES_IN, AuthServerProvider, MemoryAccessTokensStore, MemoryAuthorizationCodeStore, MemoryClientsStore, MemoryRefreshTokensStore, REFRESH_TOKEN_EXPIRES_IN, WebSocketServerTransport, auth, createAuthCallbackRouter, createAuthMetadataRouter, createAuthMiddleware, createAuthRouter, jwtAuth, lockCors, useProxyHandles };
 export type { AuthServerProviderOptions, ClientError, ClientInfo, OAuthAccessTokensStore, OAuthAuthorizationCodeStore, OAuthRefreshTokensStore, RemoterError, RemoterInfo };