@opentiny/agent 0.3.3 → 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

@@ -12,6 +12,7 @@ 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.
@@ -367,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 认证路由。
  *
@@ -380,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 类型。
@@ -565,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, WebSocketServerTransport, auth, createAuthCallbackRouter, createAuthMetadataRouter, createAuthMiddleware, createAuthRouter, jwtAuth, 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 };