@alvin0/ai-agent-sdk-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alvin0 (chaulamdinhai) <chaulamdinhai@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @alvin0/ai-agent-sdk-mcp
+
+Runtime: **Universal** (Edge/Worker, browser, Deno, Bun, and Node).
+
+```sh
+pnpm add @alvin0/ai-agent-sdk-core @alvin0/ai-agent-sdk-mcp
+```
+
+Universal MCP client for Fetch-shaped HTTP runtimes. It connects remote MCP
+servers to the SDK as a versioned `ToolSource`.
+
+```ts
+import { createAgentRuntime } from '@alvin0/ai-agent-sdk-core'
+import { connectMcpHttp } from '@alvin0/ai-agent-sdk-mcp'
+
+const runtime = await createAgentRuntime({ providers: [modelProvider] })
+let connection: Awaited<ReturnType<typeof connectMcpHttp>> | undefined
+try {
+  connection = await connectMcpHttp({
+    serverName: 'tools',
+    url: 'https://tools.example.com/mcp',
+    logger: runtime.logger({ fields: { integration: 'mcp-http' } }),
+  })
+  const agent = runtime.agent({ model, toolSources: [connection] })
+  await agent.generate('Use the connected tools when needed.')
+} finally {
+  try {
+    await runtime.close()
+  } finally {
+    await connection?.closeWithReport()
+  }
+}
+```
+
+The normal root and `/client` route contain no server, stdio, filesystem,
+`node:http`, or process lifecycle integration. Use `@alvin0/ai-agent-sdk-mcp-node` for
+the Node stdio client, and a dedicated server package for hosting.
+
+HTTP endpoints are host-selected. HTTPS, public-network-only access, and no
+redirects are the defaults; local development must opt out explicitly. Use
+`allowedOrigins`, the async `validateEndpoint` hook, a DNS-pinning custom fetch
+or network egress policy, response/catalog/result bounds, and operation deadlines
+according to the application's trust boundary. OAuth credential persistence and
+redirect handling remain caller-owned.
+
+Composition: `runtime-agent.toolSources`. Lifecycle: `connected-caller-owned`;
+create the runtime first, pass `runtime.logger(...)` while connecting, close the
+runtime to quiesce runs, then inspect `connection.closeWithReport()`.

package/dist/client-ChEdrVJ_.d.ts

@@ -0,0 +1,310 @@
+import { ToolCatalog, ToolCatalogSnapshot, ToolFilter, ToolSource, ToolSourceSnapshotOptions } from "@alvin0/ai-agent-sdk-core/tools";
+import { JsonObject, JsonValue, SdkLogger, SupportSafeError } from "@alvin0/ai-agent-sdk-core";
+//#region src/client/public-types.d.ts
+/** Protocol-selection surface owned by the SDK so Web consumers do not inherit Node ambient types. */
+type McpVersionNegotiationMode = 'legacy' | 'auto' | {
+  readonly pin: string;
+};
+interface McpBearerAuthProvider {
+  token(): Promise<string | undefined>;
+  onUnauthorized?(context: {
+    readonly response: Response;
+    readonly resourceMetadataUrl?: URL;
+  }): Promise<void>;
+}
+/**
+ * OAuth providers intentionally remain structural. The MCP protocol package accepts richer
+ * provider objects; this boundary keeps them portable without copying that package's full API.
+ */
+type McpAuthenticationProvider = McpBearerAuthProvider | object;
+type McpFetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
+interface McpStreamableHttpReconnectionOptions {
+  readonly maxReconnectionDelay: number;
+  readonly initialReconnectionDelay: number;
+  readonly reconnectionDelayGrowFactor: number;
+  readonly maxRetries: number;
+}
+interface McpStreamableHttpTransportOptions {
+  readonly authProvider?: McpAuthenticationProvider;
+  readonly skipIssuerMetadataValidation?: boolean;
+  readonly requestInit?: RequestInit;
+  readonly fetch?: McpFetch;
+  readonly reconnectionOptions?: McpStreamableHttpReconnectionOptions;
+  readonly reconnectionScheduler?: (reconnect: () => void, delay: number, attemptCount: number) => (() => void) | void;
+  readonly sessionId?: string;
+  readonly protocolVersion?: string;
+  readonly onInsufficientScope?: 'reauthorize' | 'throw';
+  readonly maxStepUpRetries?: number;
+}
+interface McpSseTransportOptions {
+  readonly authProvider?: McpAuthenticationProvider;
+  readonly skipIssuerMetadataValidation?: boolean;
+  readonly eventSourceInit?: {
+    readonly fetch?: McpFetch;
+  };
+  readonly requestInit?: RequestInit;
+  readonly fetch?: McpFetch;
+}
+interface McpTransport {
+  start(): Promise<void>;
+  send(...args: never[]): Promise<void>;
+  close(): Promise<void>;
+  readonly hasPerRequestStream?: boolean;
+  onclose?: (() => void) | undefined;
+  onerror?: ((error: Error) => void) | undefined;
+  onmessage?: ((...args: never[]) => void) | undefined;
+}
+interface McpRemoteToolDefinition {
+  readonly name: string;
+  readonly description?: string;
+  readonly inputSchema?: JsonObject;
+  readonly outputSchema?: JsonObject;
+  readonly annotations?: JsonObject;
+}
+interface McpCallToolResult {
+  readonly [key: string]: unknown;
+  readonly content: readonly unknown[];
+  readonly structuredContent?: unknown;
+  readonly isError?: boolean | undefined;
+}
+/** Common raw-protocol operations available without importing the upstream declaration graph. */
+interface McpProtocolClient {
+  callTool(params: {
+    readonly name: string;
+    readonly arguments?: JsonObject;
+  }, options?: {
+    readonly signal?: AbortSignal;
+    readonly timeout?: number;
+    readonly toolDefinition?: McpRemoteToolDefinition;
+  }): Promise<McpCallToolResult>;
+  listTools(params?: JsonObject, options?: object): Promise<{
+    readonly tools: readonly McpRemoteToolDefinition[];
+    readonly nextCursor?: string;
+  }>;
+  listResources(params?: JsonObject, options?: object): Promise<JsonObject>;
+  readResource(params: {
+    readonly uri: string;
+    readonly _meta?: JsonObject;
+  }, options?: object): Promise<JsonObject>;
+  listPrompts(params?: JsonObject, options?: object): Promise<JsonObject>;
+  getPrompt(params: {
+    readonly name: string;
+    readonly arguments?: JsonObject;
+  }, options?: object): Promise<JsonObject>;
+  ping(options?: object): Promise<JsonObject>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/client/api-types.d.ts
+interface McpReconnectOptions {
+  readonly enabled?: boolean;
+  readonly initialDelayMs?: number;
+  readonly maxDelayMs?: number;
+  readonly maxAttempts?: number;
+}
+interface ResolvedMcpReconnectOptions {
+  readonly enabled: boolean;
+  readonly initialDelayMs: number;
+  readonly maxDelayMs: number;
+  readonly maxAttempts: number;
+}
+type McpClientStatus = 'idle' | 'connecting' | 'authorization-required' | 'authentication-required' | 'authentication-failed' | 'oauth-authorization-required' | 'scope-authorization-required' | 'ready' | 'reconnecting' | 'failed' | 'closed';
+type McpAuthenticationKind = 'none' | 'bearer' | 'oauth' | 'unknown';
+type McpTransportKind = 'streamable-http' | 'sse' | 'custom';
+interface McpAuthorizationState {
+  readonly kind: McpAuthenticationKind;
+  readonly reason: 'credentials-required' | 'invalid-credentials' | 'authorization-code-required' | 'insufficient-scope';
+  readonly requiredScope?: string;
+}
+interface McpProtocolState {
+  readonly era: 'modern' | 'legacy';
+  readonly version?: string;
+  readonly transport: McpTransportKind;
+  readonly fallback: boolean;
+}
+interface McpClientState {
+  readonly status: McpClientStatus;
+  readonly serverName: string;
+  readonly attempt: number;
+  readonly error?: Error;
+  readonly authorization?: McpAuthorizationState;
+  readonly protocol?: McpProtocolState;
+  readonly catalogRevision: number;
+  readonly supportError?: SupportSafeError;
+}
+interface McpClientLifecycleOptions {
+  readonly serverName: string;
+  readonly logger?: SdkLogger;
+  readonly clientName?: string;
+  readonly clientVersion?: string;
+  readonly protocol?: McpVersionNegotiationMode;
+  readonly reconnect?: McpReconnectOptions | false;
+  readonly toolFilter?: ToolFilter;
+  readonly prefixToolNames?: boolean;
+  readonly toolCallTimeoutMs?: number;
+  readonly operationTimeoutMs?: number;
+  readonly closeTimeoutMs?: number;
+  readonly maxTools?: number;
+  readonly maxCatalogBytes?: number;
+  readonly maxToolResultBytes?: number;
+  readonly trustReadOnlyAnnotations?: boolean;
+  readonly onStateChange?: (state: McpClientState) => void;
+  readonly signal?: AbortSignal;
+}
+interface McpHttpClientOptions extends McpClientLifecycleOptions {
+  readonly url: string | URL;
+  readonly fetch?: typeof globalThis.fetch;
+  readonly headers?: RequestInit['headers'];
+  readonly allowedOrigins?: readonly string[];
+  readonly requireHttps?: boolean;
+  readonly allowPrivateNetwork?: boolean;
+  readonly allowRedirects?: boolean;
+  /**
+   * Final host policy hook, awaited immediately before every request and
+   * redirect under the operation's absolute deadline. The signal is cancelled
+   * on caller abort or timeout. A server can resolve DNS here; pair it with a
+   * fetch/egress layer that pins the validated address to eliminate
+   * validation/connect races.
+   */
+  readonly validateEndpoint?: (url: URL, signal: AbortSignal) => void | Promise<void>;
+  readonly maxTransportBytes?: number;
+  readonly transport?: Omit<McpStreamableHttpTransportOptions, 'requestInit'> & {
+    readonly requestInit?: RequestInit;
+  };
+  readonly legacySse?: false | {
+    readonly url?: string | URL;
+    readonly transport?: McpSseTransportOptions;
+  };
+}
+type McpToolResultValue = JsonObject & {
+  readonly content: readonly JsonValue[];
+  readonly structuredContent?: JsonValue;
+};
+type McpTransportFactory = () => McpTransport;
+interface McpClientRuntimeOptions {
+  readonly authenticationKind?: McpAuthenticationKind;
+  readonly fallbackTransportFactory?: McpTransportFactory;
+  /** Internal transport family supplied by the official HTTP/stdio factories. */
+  readonly integrationFamily?: 'mcp-http-client' | 'mcp-stdio-client';
+}
+interface McpOAuthCallbackOptions {
+  readonly expectedState: string;
+  readonly signal?: AbortSignal;
+}
+interface McpCloseReport {
+  readonly state: 'closed';
+  readonly deadlineReached: boolean;
+  readonly unsettledOperations: number;
+  readonly error?: SupportSafeError;
+}
+interface McpConnectionPublicShape {
+  readonly serverName: string;
+  readonly tools: ToolCatalog;
+}
+//#endregion
+//#region src/client/result.d.ts
+declare class McpRemoteToolError extends Error {
+  readonly result: McpCallToolResult;
+  constructor(serverName: string, toolName: string, result: McpCallToolResult);
+}
+type McpConnectionStage = 'transport' | 'authentication' | 'handshake' | 'catalog' | 'unknown';
+declare class McpConnectionError extends Error {
+  readonly stage: McpConnectionStage;
+  readonly failure: SupportSafeError;
+  readonly cleanup: McpCloseReport;
+  readonly code: 'MCP_CONNECT_FAILED';
+  constructor(stage: McpConnectionStage, failure: SupportSafeError, cleanup: McpCloseReport, cause: unknown);
+}
+//#endregion
+//#region src/client/runtime-helpers.d.ts
+declare function resolveMcpReconnectOptions(input: McpReconnectOptions | false | undefined): ResolvedMcpReconnectOptions;
+//#endregion
+//#region src/client/connection.d.ts
+/**
+ * Owns one MCP server connection across transport generations.
+ *
+ * The ToolCatalog object is stable for the lifetime of this connection. A
+ * successful list refresh swaps its registrations synchronously; a failed
+ * refresh leaves the last-known-good catalog intact.
+ */
+declare class McpClientConnection implements ToolSource {
+  readonly kind: 'tool-source';
+  readonly apiVersion: 1;
+  readonly id: string;
+  readonly serverName: string;
+  readonly tools: ToolCatalog;
+  private readonly options;
+  private readonly transportFactory;
+  private readonly fallbackTransportFactory;
+  private readonly authenticationKind;
+  private readonly integrationFamily;
+  private readonly toolCallTimeoutMs;
+  private readonly operationTimeoutMs;
+  private readonly closeTimeoutMs;
+  private readonly maxTools;
+  private readonly maxCatalogBytes;
+  private readonly maxToolResultBytes;
+  private readonly reconnect;
+  private readonly registry;
+  private toolDisposers;
+  private current;
+  private pendingAuthorization;
+  private connecting;
+  private syncTail;
+  private pendingToolSyncs;
+  private reconnectTimer;
+  private reconnectAttempts;
+  private catalogRevision;
+  private connectedAt;
+  private closed;
+  private closeTask;
+  private currentState;
+  constructor(options: McpClientLifecycleOptions, transportFactory: McpTransportFactory, runtime?: McpClientRuntimeOptions);
+  get state(): McpClientState;
+  snapshot(options: ToolSourceSnapshotOptions): ToolCatalogSnapshot;
+  /**
+   * Use the currently owned protocol client for resources, prompts, or other
+   * MCP operations that do not map to the SDK ToolCatalog.
+   */
+  withClient<T>(operation: (client: McpProtocolClient, signal: AbortSignal) => Promise<T>): Promise<T>;
+  withClient<TClient, T>(operation: (client: TClient, signal: AbortSignal) => Promise<T>): Promise<T>;
+  /** Connect, negotiate capabilities, and publish the first tool snapshot. */
+  connect(): Promise<void>;
+  /** Force a fresh tools/list and atomically replace the published snapshot. */
+  refreshTools(options?: {
+    readonly signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+   * Validate an OAuth callback, exchange its authorization code on the pending
+   * HTTP transport, then reconnect with a fresh transport generation.
+   */
+  finishOAuth(callbackParams: URLSearchParams, options: McpOAuthCallbackOptions): Promise<void>;
+  /** Stop reconnecting, close the live generation, and unregister its tools. */
+  close(): Promise<void>;
+  closeWithReport(options?: {
+    readonly signal?: AbortSignal;
+  }): Promise<McpCloseReport>;
+  private performClose;
+  private connectGeneration;
+  private createGeneration;
+  private clientOptions;
+  private generationDown;
+  private scheduleReconnect;
+  private enqueueToolSync;
+  private swapTools;
+  private bridgeTool;
+  private clearTools;
+  private bumpCatalogRevision;
+  private logAuthenticationFailure;
+  private closeGeneration;
+  private publish;
+}
+//#endregion
+//#region src/client/http-client.d.ts
+/** Construct an HTTP client without opening the connection yet. */
+declare function createMcpHttpClient(options: McpHttpClientOptions): McpClientConnection;
+/** Construct and fully initialize an HTTP client. */
+declare function connectMcpHttp(options: McpHttpClientOptions): Promise<McpClientConnection>;
+//#endregion
+export { McpStreamableHttpReconnectionOptions as A, McpAuthenticationProvider as C, McpProtocolClient as D, McpFetch as E, McpTransport as M, McpVersionNegotiationMode as N, McpRemoteToolDefinition as O, ResolvedMcpReconnectOptions as S, McpCallToolResult as T, McpProtocolState as _, McpConnectionError as a, McpTransportFactory as b, McpAuthorizationState as c, McpClientState as d, McpClientStatus as f, McpOAuthCallbackOptions as g, McpHttpClientOptions as h, resolveMcpReconnectOptions as i, McpStreamableHttpTransportOptions as j, McpSseTransportOptions as k, McpClientLifecycleOptions as l, McpConnectionPublicShape as m, createMcpHttpClient as n, McpRemoteToolError as o, McpCloseReport as p, McpClientConnection as r, McpAuthenticationKind as s, connectMcpHttp as t, McpClientRuntimeOptions as u, McpReconnectOptions as v, McpBearerAuthProvider as w, McpTransportKind as x, McpToolResultValue as y };
+//# sourceMappingURL=client-ChEdrVJ_.d.ts.map

package/dist/client-ChEdrVJ_.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-ChEdrVJ_.d.ts","names":[],"sources":["../src/client/public-types.ts","../src/client/api-types.ts","../src/client/result.ts","../src/client/runtime-helpers.ts","../src/client/connection.ts","../src/client/http-client.ts"],"mappings":"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"}