@opentiny/next 0.2.1 → 0.3.0

package/README.md

@@ -12,7 +12,7 @@ OpenTiny NEXT 是一个基于 Model Context Protocol（MCP）的 TypeScript 库
 npm install @opentiny/next
 ```
 
-## 客户端 API (client.js)
+## 客户端 API
 
 客户端 API 主要用于在浏览器环境中的 MCP 通信。
 
@@ -43,7 +43,7 @@ await client.connect(clientTransport);
 state.client = client;
 ```
 
-#### 在浏览器主线程与iframe、Web Worker等互相通信的场景
+#### 在浏览器主线程与 iframe、Web Worker 等互相通信的场景
 
 使用 `MessageChannelServerTransport` 和 `MessageChannelClientTransport` 创建用于监听的 Transport 服务端实例，以及用于连接的 Transport 客户端实例来进行通信。
 

package/index.d.ts

@@ -0,0 +1,325 @@
+import { JSONRPCMessage, RequestId } from '@modelcontextprotocol/sdk/types.js';
+import { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StreamableHTTPReconnectionOptions, StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { EventSourceInit } from 'eventsource';
+import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+import { OAuthClientMetadata, OAuthClientInformation, OAuthClientInformationFull, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+
+/**
+ * MessageChannelTransport 是一个用于在浏览器上下文之间传输消息的类。
+ * 它使用 MessageChannel API 来实现不同上下文（如 iframe、worker、标签页、窗口等）之间的通信。
+ * 该类提供了初始化、发送消息、关闭通道等功能。
+ */
+declare class MessageChannelTransport {
+    protected _port?: MessagePort;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage, extra?: {
+        authInfo?: AuthInfo;
+    }) => void;
+    sessionId?: string;
+    /**
+     * 构造函数，初始化 MessageChannelTransport。
+     *
+     * @param port - 用于通信的 MessagePort。
+     */
+    constructor(port?: MessagePort);
+    /**
+     * 初始化 MessageChannelTransport。
+     * 该方法会创建一个新的 MessageChannel，并将其端口传递给指定的全局对象。
+     * 如果传输已关闭，则抛出错误。
+     */
+    start(): Promise<void>;
+    /**
+     * 发送消息到 MessagePort。
+     * 如果传输已关闭，则抛出错误。
+     *
+     * @param message - 要发送的 JSON-RPC 消息。
+     */
+    send(message: JSONRPCMessage, options?: {
+        relatedRequestId?: RequestId;
+        authInfo?: AuthInfo;
+    }): Promise<void>;
+    /**
+     * 关闭 MessageChannelTransport。
+     * 该方法会关闭 MessagePort，并触发关闭回调。
+     * 如果传输已关闭，则不执行任何操作。
+     */
+    close(): Promise<void>;
+}
+/**
+ * 在浏览器端实现基于 MessageChannel API 的客户端传输类，
+ * 用于不同浏览器上下文（如 iframe、worker、标签页、窗口等）之间通信。
+ */
+declare class MessageChannelClientTransport extends MessageChannelTransport {
+    private _endpoint;
+    private _globalObject;
+    /**
+     * 创建一个监听通信的服务端实例。
+     *
+     * @param endpoint - 用于通信的端点。
+     * @param [globalObject] - 用于通信的全局对象（可选，默认当前全局对象）。
+     */
+    constructor(endpoint: string, globalObject?: object);
+}
+/**
+ * 在浏览器端实现基于 MessageChannel API 的服务端传输类，
+ * 用于不同浏览器上下文（如 iframe、worker、标签页、窗口等）之间通信。
+ */
+declare class MessageChannelServerTransport extends MessageChannelTransport {
+    private _endpoint;
+    private _globalObject;
+    private _listen;
+    /**
+     * 创建一个监听通信的服务端实例。
+     *
+     * @param endpoint - 用于通信的端点。
+     * @param [globalObject] - 用于通信的全局对象（可选，默认当前全局对象）。
+     */
+    constructor(endpoint: string, globalObject?: object);
+    /**
+     * 监听等待客户端连接。
+     * 该方法会返回一个 Promise，当客户端连接时解析。
+     */
+    listen(): Promise<void>;
+}
+/**
+ * 创建一对 MessageChannelTransport 实例，返回两个端口的传输实例。
+ * 这两个实例可以用于在不同的浏览器上下文之间进行通信。
+ *
+ * @returns 返回一对 MessageChannelTransport 实例。
+ */
+declare const createTransportPair: () => [MessageChannelTransport, MessageChannelTransport];
+
+declare module '@modelcontextprotocol/sdk/client/sse.js' {
+    interface SSEClientTransport {
+        sessionId: string;
+    }
+}
+interface WaitForOAuthCodeFunction {
+    (): Promise<unknown>;
+}
+interface sseInitOptions {
+    requestInit: {
+        headers: {
+            Authorization?: string;
+            'sse-session-id': string;
+        };
+        credentials?: RequestCredentials;
+    };
+    eventSourceInit: {
+        fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
+        withCredentials?: boolean;
+    };
+}
+/**
+ * 生成 SSEClientTransport 构造函数所需的第二个可选参数（传输配置）。
+ * 用于为 SSE 连接和 HTTP 请求统一设置认证头（Authorization）。
+ *
+ * @param token - 用于认证的 Bearer Token。
+ * @param sessionId - 可选的 sessionId，用于标识会话。
+ * @returns 返回传输配置对象，包含 requestInit 和 eventSourceInit 两部分：
+ *   - requestInit：fetch 请求的初始化配置，自动带上认证头。
+ *   - eventSourceInit：自定义 fetch 方法，确保 SSE 连接也带上认证头。
+ */
+declare const sseOptions: (token?: string, sessionId?: string) => sseInitOptions;
+/**
+ * Streamable HTTP 请求初始化配置接口
+ */
+interface streamInitOptions {
+    requestInit: {
+        headers: {
+            Authorization?: string;
+            'stream-session-id': string;
+        };
+        credentials?: RequestCredentials;
+    };
+}
+/**
+ * 生成 StreamableHTTPServerTransport 构造函数所需的第二个可选参数（传输配置）。
+ * 用于为 Streamable HTTP 连接和 HTTP 请求统一设置认证头（Authorization）。
+ *
+ * @param token - 用于认证的 Bearer Token。
+ * @param sessionId - 可选的 sessionId，用于标识会话。
+ * @returns 返回传输配置对象，包含以下内容：
+ *   - requestInit：fetch 请求的初始化配置，自动带上认证头，并设置 Streamable HTTP 代理的会话 ID。
+ */
+declare const streamOptions: (token?: string, sessionId?: string) => streamInitOptions;
+/**
+ * 代理选项接口
+ */
+interface ProxyOptions {
+    /**
+     * MCP 客户端实例
+     */
+    client: Client;
+    /**
+     * 代理服务器的 URL
+     */
+    url: string;
+    /**
+     * 可选的代理服务器的身份验证令牌
+     */
+    token?: string;
+    /**
+     * 可选的会话 ID，用于标识当前会话
+     */
+    sessionId?: string;
+    /**
+     * 可选的 OAuth 客户端提供者，用于身份验证
+     */
+    authProvider?: OAuthClientProvider;
+    /**
+     * 可选的事件源初始化选项，用于配置 SSE 的 EventSource
+     */
+    eventSourceInit?: EventSourceInit;
+    /**
+     * 可选的请求初始化选项，用于配置 HTTP 请求
+     */
+    requestInit?: RequestInit;
+    /**
+     * 可选的重连选项，用于配置 Streamable HTTP 的重连策略
+     */
+    reconnectionOptions?: StreamableHTTPReconnectionOptions;
+    /**
+     * 可选的函数，用于等待 OAuth 授权码
+     * 如果使用 authProvider，则需要提供此函数以获取授权码
+     */
+    waitForOAuthCode?: WaitForOAuthCodeFunction;
+}
+/**
+ * 尝试连接到 MCP 服务器，处理未授权错误并重试连接。
+ *
+ * @param client - MCP 客户端实例
+ * @param waitForOAuthCode - 函数，用于等待 OAuth 授权码
+ * @param createTransport - 函数，用于创建新的传输实例
+ * @returns 返回连接成功的传输实例
+ */
+declare const attemptConnection: (client: Client, waitForOAuthCode: WaitForOAuthCodeFunction, createTransport: () => SSEClientTransport | StreamableHTTPClientTransport) => Promise<SSEClientTransport | StreamableHTTPClientTransport>;
+/**
+ * 创建一个 SSE 客户端代理。
+ *
+ * @param options - 客户端代理选项
+ * @returns - 返回一个包含 transport 和 sessionId 的对象
+ */
+declare const createSseProxy: (options: ProxyOptions) => Promise<{
+    transport: SSEClientTransport;
+    sessionId: string;
+}>;
+/**
+ * 创建一个 Streamable HTTP 客户端代理。
+ *
+ * @param options - 客户端代理选项
+ * @returns - 返回一个包含 transport 和 sessionId 的对象
+ */
+declare const createStreamProxy: (options: ProxyOptions) => Promise<{
+    transport: StreamableHTTPClientTransport;
+    sessionId: string;
+}>;
+
+interface AuthClientProviderOptions {
+    clientMetadata: OAuthClientMetadata;
+    state?: string;
+    redirectCallback?: (url: URL) => Promise<void>;
+    getAuthCodeByState?: (url: string | URL, state: string) => Promise<Response>;
+    waitForOAuthCode?: () => Promise<void>;
+}
+declare class AuthClientProvider implements OAuthClientProvider {
+    waitForOAuthCode: () => Promise<unknown>;
+    private _clientInformation?;
+    private _tokens?;
+    private _codeVerifier?;
+    private _state;
+    private _redirectUrl;
+    private _clientMetadata;
+    private _redirectCallback;
+    private _getAuthCodeByState;
+    private _callBackPromise;
+    /**
+     * 重定向回调函数，用于处理 OAuth 鉴权后的重定向。
+     *
+     * @param redirectUrl 重定向的 URL
+     */
+    private redirectCallbackFunction;
+    /**
+     * 根据 state 获取 OAuth 鉴权码的函数。
+     *
+     * @param url  获取 code 的服务端 URL
+     * @param state  OAuth 鉴权的 state
+     * @returns 返回一个 Promise，当 OAuth 鉴权码可用时解析
+     */
+    private getAuthCodeByStateFunction;
+    /**
+     * 等待 OAuth 鉴权码的函数。
+     *
+     * @returns 返回一个 Promise，当 OAuth 鉴权码可用时解析
+     */
+    private waitForOAuthCodeFunction;
+    constructor(options: AuthClientProviderOptions);
+    /**
+     * 获取 OAuth 客户端的重定向 URL。
+     *
+     * @returns OAuth 客户端的重定向 URL
+     */
+    get redirectUrl(): string | URL;
+    /**
+     * 获取 OAuth 客户端的元数据。
+     *
+     * @returns OAuth 客户端的元数据
+     */
+    get clientMetadata(): OAuthClientMetadata;
+    /**
+     * 获取 OAuth 鉴权的 state。
+     *
+     * @returns OAuth 鉴权的 state
+     */
+    state?(): string;
+    /**
+     * 获取 OAuth 客户端的信息。
+     *
+     * @returns OAuth 客户端的信息
+     */
+    clientInformation(): OAuthClientInformation | undefined;
+    /**
+     * 保存 OAuth 客户端的信息。
+     *
+     * @param clientInformation  OAuth 客户端的信息
+     */
+    saveClientInformation(clientInformation: OAuthClientInformationFull): void;
+    /**
+     * 获取 OAuth 鉴权的访问令牌。
+     *
+     * @returns OAuth 鉴权的访问令牌
+     */
+    tokens(): OAuthTokens | undefined;
+    /**
+     * 保存 OAuth 鉴权的访问令牌。
+     *
+     * @param tokens  OAuth 鉴权的访问令牌
+     */
+    saveTokens(tokens: OAuthTokens): void;
+    /**
+     * 重定向到 OAuth 鉴权的授权 URL。
+     *
+     * @param authorizationUrl OAuth 鉴权的授权 URL
+     */
+    redirectToAuthorization(authorizationUrl: URL): void;
+    /**
+     * 保存用于 PKCE 流程的 code verifier。
+     *
+     * @param codeVerifier 用于 PKCE 流程的 code verifier
+     */
+    saveCodeVerifier(codeVerifier: string): void;
+    /**
+     * 获取用于 PKCE 流程的 code verifier。
+     *
+     * @returns 用于 PKCE 流程的 code verifier
+     * @throws 如果没有保存 code verifier，则抛出错误
+     */
+    codeVerifier(): string;
+}
+
+export { AuthClientProvider, MessageChannelClientTransport, MessageChannelServerTransport, MessageChannelTransport, attemptConnection, createSseProxy, createStreamProxy, createTransportPair, sseOptions, streamOptions };
+export type { AuthClientProviderOptions, ProxyOptions };