@h1deya/langchain-mcp-tools 0.2.4 → 0.2.6

package/README.md

@@ -1,12 +1,18 @@
 # MCP To LangChain Tools Conversion Utility / TypeScript [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/hideya/langchain-mcp-tools-ts/blob/main/LICENSE) [![npm version](https://img.shields.io/npm/v/@h1deya/langchain-mcp-tools.svg)](https://www.npmjs.com/package/@h1deya/langchain-mcp-tools)
 
-## NOTE
+This is a simple, lightweight library intended to simplify the use of
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
+server tools with LangChain.
+
+Its simplicity and extra features for stdio MCP servers can make it useful as a basis for your own customizations.
+However, it only supports text results of tool calls and does not support MCP features other than tools.
 
-LangChain's official **LangChain.js MCP Adapters** library has been released at:
+LangChain's **official LangChain.js MCP Adapters** library,
+which supports comprehensive integration with LangChain, has been released at:
 - npmjs: https://www.npmjs.com/package/@langchain/mcp-adapters
-- github: https://github.com/langchain-ai/langchainjs-mcp-adapters
+- github: https://github.com/langchain-ai/langchainjs/tree/main/libs/langchain-mcp-adapters`
 
-You may want to consider using the above if you don't have specific needs for using this library...
+You may want to consider using the above if you don't have specific needs for this library.
 
 ## Introduction
 
@@ -14,23 +20,17 @@ This package is intended to simplify the use of
 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
 server tools with LangChain / TypeScript.
 
-[Model Context Protocol (MCP)](https://modelcontextprotocol.io/),
-an open standard
-[announced by Anthropic](https://www.anthropic.com/news/model-context-protocol),
-dramatically expands LLM's scope
-by enabling external tool and resource integration, including
-GitHub, Google Drive, Slack, Notion, Spotify, Docker, PostgreSQL, and more…
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is the de facto industry standard
+that dramatically expands the scope of LLMs by enabling the integration of external tools and resources,
+including DBs, GitHub, Google Drive, Docker, Slack, Notion, Spotify, and more.
 
-MCP is likely to become the de facto industry standard as 
-[OpenAI has announced its adoption](https://techcrunch.com/2025/03/26/openai-adopts-rival-anthropics-standard-for-connecting-ai-models-to-data).
-
-Over 2000 functional components available as MCP servers:
+There are quite a few useful MCP servers already available:
 
 - [MCP Server Listing on the Official Site](https://github.com/modelcontextprotocol/servers?tab=readme-ov-file#model-context-protocol-servers)
 - [MCP.so - Find Awesome MCP Servers and Clients](https://mcp.so/)
 - [Smithery: MCP Server Registry](https://smithery.ai/)
 
-The goal of this utility is to make these 2000+ MCP servers readily accessible from LangChain.
+This utility's goal is to make these massive numbers of MCP servers easily accessible from LangChain.
 
 It contains a utility function `convertMcpToLangchainTools()`.  
 This async function handles parallel initialization of specified multiple MCP servers
@@ -94,7 +94,7 @@ The returned tools can be used with LangChain, e.g.:
 
 ```ts
 // import { ChatAnthropic } from "@langchain/anthropic";
-const llm = new ChatAnthropic({ model: "claude-3-7-sonnet-latest" });
+const llm = new ChatAnthropic({ model: "claude-sonnet-4-0" });
 
 // import { createReactAgent } from "@langchain/langgraph/prebuilt";
 const agent = createReactAgent({
@@ -109,33 +109,134 @@ try [this LangChain application built with the utility](https://github.com/hidey
 For detailed information on how to use this library, please refer to the following document:  
 ["Supercharging LangChain: Integrating 2000+ MCP with ReAct"](https://medium.com/@h1deya/supercharging-langchain-integrating-450-mcp-with-react-d4e467cbf41a)
 
-## Experimental Features
+## Features
+
+### `stderr` Redirection for Local MCP Server 
+
+A new key `"stderr"` has been introduced to specify a file descriptor
+to which local (stdio) MCP server's stderr is redirected.  
+The key name `stderr` is derived from
+TypeScript SDK's [`StdioServerParameters`](https://github.com/modelcontextprotocol/typescript-sdk/blob/131776764536b5fdca642df51230a3746fb4ade0/src/client/stdio.ts#L32).
+
+```ts
+    const logPath = `mcp-server-${serverName}.log`;
+    const logFd = fs.openSync(logPath, "w");
+    mcpServers[serverName].stderr = logFd;
+```
+
+A usage example can be found [here](
+https://github.com/hideya/langchain-mcp-tools-ts-usage/blob/694b877ed5336bfcd5274d95d3f6d14bed0937a6/src/index.ts#L72-L83)
+
+### Working Directory Configuration for Local MCP Servers
+
+The working directory that is used when spawning a local (stdio) MCP server
+can be specified with the `"cwd"` key as follows:
+
+```ts
+    "local-server-name": {
+      command: "...",
+      args: [...],
+      cwd: "/working/directory"  // the working dir to be use by the server
+    },
+```
+
+The key name `cwd` is derived from
+TypeScript SDK's [`StdioServerParameters`](https://github.com/modelcontextprotocol/typescript-sdk/blob/131776764536b5fdca642df51230a3746fb4ade0/src/client/stdio.ts#L39).
+
 
 ### Remote MCP Server Support
 
-`mcp_servers` configuration for SSE and Websocket servers are as follows:
+`mcp_servers` configuration for Streamable HTTP, SSE and Websocket servers are as follows:
 
 ```ts
+    // Auto-detection: tries Streamable HTTP first, falls back to SSE on 4xx errors
+    "auto-detect-server": {
+        url: `http://${server_host}:${server_port}/...`
+    },
+
+    // Explicit Streamable HTTP
+    "streamable-http-server": {
+        url: `http://${server_host}:${server_port}/...`,
+        transport: "streamable_http"
+    },
+
+    // Explicit SSE
     "sse-server-name": {
-        url: `http://${sse_server_host}:${sse_server_port}/...`
+        url: `http://${sse_server_host}:${sse_server_port}/...`,
+        transport: "sse"
     },
 
+    // WebSocket
     "ws-server-name": {
         url: `ws://${ws_server_host}:${ws_server_port}/...`
     },
 ```
 
-Note that the key `"url"` may be changed in the future to match
-the MCP server configurations used by Claude for Desktop once
-it introduces remote server support.
+**Auto-detection behavior (default):**
+- For HTTP/HTTPS URLs without explicit `transport`, the library follows [MCP specification recommendations](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#backwards-compatibility)
+- First attempts Streamable HTTP transport
+- If Streamable HTTP fails with a 4xx error, automatically falls back to SSE transport
+- Non-4xx errors (network issues, etc.) are re-thrown without fallback
 
-A usage example can be found [here](
-https://github.com/hideya/langchain-mcp-tools-ts-usage/blob/694b877ed5336bfcd5274d95d3f6d14bed0937a6/src/index.ts#L26-L38)
+**Explicit transport selection:**
+- Set `transport: "streamable_http"` to force Streamable HTTP (no fallback)
+- Set `transport: "sse"` to force SSE transport
+- WebSocket URLs (`ws://` or `wss://`) always use WebSocket transport
+
+Streamable HTTP is the modern MCP transport that replaces the older HTTP+SSE transport. According to the [official MCP documentation](https://modelcontextprotocol.io/docs/concepts/transports):
+
+> "SSE as a standalone transport is deprecated as of protocol version 2024-11-05. It has been replaced by Streamable HTTP, which incorporates SSE as an optional streaming mechanism."
+
+Note that even when you specify the Streamable HTTP transport, you may see SSE activity in the logs, such as `Accept: text/event-stream`.
+This occurs when the MCP SDK chooses to use SSE for streaming server responses within the Streamable HTTP transport.
 
-### Authentication Support for SSE Connections
+### Authentication Support for Streamable HTTP Connections
 
-The library now supports authentication for SSE connections to MCP servers.
-This is particularly useful for accessing authenticated MCP servers that require OAuth.
+The library supports OAuth 2.1 authentication for Streamable HTTP connections:
+
+```ts
+import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+
+// Implement your own OAuth client provider
+class MyOAuthProvider implements OAuthClientProvider {
+  // Implementation details...
+}
+
+const mcpServers = {
+  "secure-streamable-server": {
+    url: "https://secure-mcp-server.example.com/mcp",
+    transport: "streamable_http",  // Optional: explicit transport
+    streamableHTTPOptions: {
+      // Provide an OAuth client provider
+      authProvider: new MyOAuthProvider(),
+      
+      // Optionally customize HTTP requests
+      requestInit: {
+        headers: {
+          'X-Custom-Header': 'custom-value'
+        }
+      },
+      
+      // Optionally configure reconnection behavior
+      reconnectionOptions: {
+        maxReconnectAttempts: 5,
+        reconnectDelay: 1000
+      }
+    }
+  }
+};
+```
+
+Test implementations are provided:
+
+- **Streamable HTTP Authentication Tests**:
+  - MCP client uses this library: [streamable-http-auth-test-client.ts](https://github.com/hideya/langchain-mcp-tools-ts/tree/main/testfiles/streamable-http-auth-test-client.ts)
+  - Test MCP Server:  [streamable-http-auth-test-server.ts](https://github.com/hideya/langchain-mcp-tools-ts/tree/main/testfiles/streamable-http-auth-test-server.ts)
+
+### Authentication Support for SSE Connections (Legacy)
+
+The library also supports authentication for SSE connections to MCP servers.
+Note that SSE transport is deprecated; Streamable HTTP is the recommended approach.
 
 To enable authentication, provide SSE options in your server configuration:
 
@@ -170,47 +271,11 @@ const mcpServers = {
 };
 ```
 
-A simple example showing how to implement an OAuth client provider can be found
-in [sse-auth-test-client.ts](https://github.com/hideya/langchain-mcp-tools-ts-usage/tree/main/src/sse-auth-test-client.ts)
-of [this usage examples repo](https://github.com/hideya/langchain-mcp-tools-ts-usage).
-
-For testing purposes, a sample MCP server with OAuth authentication support
-that works with the above client is provided
-in [sse-auth-test-server.ts](https://github.com/hideya/langchain-mcp-tools-ts-usage/tree/main/src/sse-auth-test-server.ts)
-of [this usage examples repo](https://github.com/hideya/langchain-mcp-tools-ts-usage).
-
-### Working Directory Configuration for Local MCP Servers
-
-The working directory that is used when spawning a local (stdio) MCP server
-can be specified with the `"cwd"` key as follows:
-
-```ts
-    "local-server-name": {
-      command: "...",
-      args: [...],
-      cwd: "/working/directory"  // the working dir to be use by the server
-    },
-```
-
-The key name `cwd` is derived from
-TypeScript SDK's [`StdioServerParameters`](https://github.com/modelcontextprotocol/typescript-sdk/blob/131776764536b5fdca642df51230a3746fb4ade0/src/client/stdio.ts#L39).
-
-
-### `stderr` Redirection for Local MCP Server 
-
-A new key `"stderr"` has been introduced to specify a file descriptor
-to which local (stdio) MCP server's stderr is redirected.  
-The key name `stderr` is derived from
-TypeScript SDK's [`StdioServerParameters`](https://github.com/modelcontextprotocol/typescript-sdk/blob/131776764536b5fdca642df51230a3746fb4ade0/src/client/stdio.ts#L32).
+Test implementations are provided:
 
-```ts
-    const logPath = `mcp-server-${serverName}.log`;
-    const logFd = fs.openSync(logPath, "w");
-    mcpServers[serverName].stderr = logFd;
-```
-
-A usage example can be found [here](
-https://github.com/hideya/langchain-mcp-tools-ts-usage/blob/694b877ed5336bfcd5274d95d3f6d14bed0937a6/src/index.ts#L72-L83)
+- **SSE Authentication Tests**:
+  - MCP client uses this library: [sse-auth-test-client.ts](https://github.com/hideya/langchain-mcp-tools-ts/tree/main/testfiles/sse-auth-test-client.ts)
+  - Test MCP Server: [sse-auth-test-server.ts](https://github.com/hideya/langchain-mcp-tools-ts/tree/main/testfiles/sse-auth-test-server.ts)
 
 ## Limitations
 

package/dist/langchain-mcp-tools.d.ts

@@ -1,6 +1,7 @@
 import { IOType } from "node:child_process";
 import { Stream } from "node:stream";
 import { StructuredTool } from "@langchain/core/tools";
+import { StreamableHTTPReconnectionOptions } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
 /**
  * Configuration for a command-line based MCP server.
@@ -10,6 +11,7 @@ import { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
  */
 export interface CommandBasedConfig {
     url?: never;
+    transport?: never;
     command: string;
     args?: string[];
     env?: Record<string, string>;
@@ -24,6 +26,7 @@ export interface CommandBasedConfig {
  */
 export interface UrlBasedConfig {
     url: string;
+    transport?: string;
     command?: never;
     args?: never;
     env?: never;
@@ -34,6 +37,12 @@ export interface UrlBasedConfig {
         eventSourceInit?: EventSourceInit;
         requestInit?: RequestInit;
     };
+    streamableHTTPOptions?: {
+        authProvider?: OAuthClientProvider;
+        requestInit?: RequestInit;
+        reconnectionOptions?: StreamableHTTPReconnectionOptions;
+        sessionId?: string;
+    };
 }
 /**
  * Configuration for an MCP server.

package/dist/langchain-mcp-tools.js

@@ -1,10 +1,12 @@
 import { DynamicStructuredTool } from "@langchain/core/tools";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { WebSocketClientTransport } from "@modelcontextprotocol/sdk/client/websocket.js";
 import { CallToolResultSchema, ListToolsResultSchema } from "@modelcontextprotocol/sdk/types.js";
 import { jsonSchemaToZod } from "@n8n/json-schema-to-zod";
+import { z } from "zod";
 import { Logger } from "./logger.js";
 // Custom error type for MCP server initialization failures
 /**
@@ -82,6 +84,278 @@ export async function convertMcpToLangchainTools(configs, options) {
     allTools.forEach((tool) => logger.debug(`- ${tool.name}`));
     return { tools: allTools, cleanup };
 }
+/**
+ * Sanitizes a JSON Schema to make it compatible with Google Gemini API.
+ *
+ * ⚠️  IMPORTANT: This is a temporary workaround to keep applications running.
+ *     The underlying schema compatibility issues should be fixed on the MCP server side
+ *     for proper Google LLM compatibility. This function will log warnings when
+ *     performing schema conversions to help track which servers need upstream fixes.
+ *
+ * Gemini supports only a limited subset of OpenAPI 3.0 Schema properties:
+ * - string: enum, format (only 'date-time' documented)
+ * - integer/number: format only
+ * - array: minItems, maxItems, items
+ * - object: properties, required, propertyOrdering, nullable
+ *
+ * This function removes known problematic properties while preserving
+ * as much validation as possible. When debug logging is enabled,
+ * it reports what schema changes were made for transparency.
+ *
+ * Reference: https://ai.google.dev/gemini-api/docs/structured-output#json-schemas
+ *
+ * @param schema - The JSON schema to sanitize
+ * @param logger - Optional logger for reporting sanitization actions
+ * @param toolName - Optional tool name for logging context
+ * @returns A sanitized schema compatible with all major LLM providers
+ *
+ * @internal This function is meant to be used internally by convertSingleMcpToLangchainTools
+ */
+function sanitizeSchemaForGemini(schema, logger, toolName) {
+    if (typeof schema !== 'object' || schema === null) {
+        return schema;
+    }
+    const sanitized = { ...schema };
+    const removedProperties = [];
+    const convertedProperties = [];
+    // Remove unsupported properties
+    if (sanitized.exclusiveMinimum !== undefined) {
+        removedProperties.push('exclusiveMinimum');
+        delete sanitized.exclusiveMinimum;
+    }
+    if (sanitized.exclusiveMaximum !== undefined) {
+        removedProperties.push('exclusiveMaximum');
+        delete sanitized.exclusiveMaximum;
+    }
+    // Convert exclusiveMinimum/Maximum to minimum/maximum if needed
+    if (schema.exclusiveMinimum !== undefined) {
+        sanitized.minimum = schema.exclusiveMinimum;
+        convertedProperties.push('exclusiveMinimum → minimum');
+    }
+    if (schema.exclusiveMaximum !== undefined) {
+        sanitized.maximum = schema.exclusiveMaximum;
+        convertedProperties.push('exclusiveMaximum → maximum');
+    }
+    // Remove unsupported string formats (Gemini only supports 'enum' and 'date-time')
+    if (sanitized.type === 'string' && sanitized.format) {
+        const supportedFormats = ['enum', 'date-time'];
+        if (!supportedFormats.includes(sanitized.format)) {
+            removedProperties.push(`format: ${sanitized.format}`);
+            delete sanitized.format;
+        }
+    }
+    // Log sanitization actions for this level
+    if (logger && toolName && (removedProperties.length > 0 || convertedProperties.length > 0)) {
+        const changes = [];
+        if (removedProperties.length > 0) {
+            changes.push(`removed: ${removedProperties.join(', ')}`);
+        }
+        if (convertedProperties.length > 0) {
+            changes.push(`converted: ${convertedProperties.join(', ')}`);
+        }
+        logger.warn(`MCP tool "${toolName}": schema sanitized for Gemini compatibility (${changes.join('; ')})`);
+    }
+    // Recursively process nested objects and arrays
+    if (sanitized.properties) {
+        sanitized.properties = Object.fromEntries(Object.entries(sanitized.properties).map(([key, value]) => [
+            key,
+            sanitizeSchemaForGemini(value, logger, toolName)
+        ]));
+    }
+    if (sanitized.anyOf) {
+        sanitized.anyOf = sanitized.anyOf.map((subSchema) => sanitizeSchemaForGemini(subSchema, logger, toolName));
+    }
+    if (sanitized.oneOf) {
+        sanitized.oneOf = sanitized.oneOf.map((subSchema) => sanitizeSchemaForGemini(subSchema, logger, toolName));
+    }
+    if (sanitized.allOf) {
+        sanitized.allOf = sanitized.allOf.map((subSchema) => sanitizeSchemaForGemini(subSchema, logger, toolName));
+    }
+    if (sanitized.items) {
+        sanitized.items = sanitizeSchemaForGemini(sanitized.items, logger, toolName);
+    }
+    if (sanitized.additionalProperties && typeof sanitized.additionalProperties === 'object') {
+        sanitized.additionalProperties = sanitizeSchemaForGemini(sanitized.additionalProperties, logger, toolName);
+    }
+    return sanitized;
+}
+/**
+ * Creates Streamable HTTP transport options from configuration.
+ * Consolidates repeated option configuration logic into a single reusable function.
+ *
+ * @param config - URL-based server configuration
+ * @param logger - Logger instance for recording authentication setup
+ * @param serverName - Server name for logging context
+ * @returns Configured StreamableHTTPClientTransportOptions or undefined if no options needed
+ *
+ * @internal This function is meant to be used internally by transport creation functions
+ */
+function createStreamableHttpOptions(config, logger, serverName) {
+    const options = {};
+    if (config.streamableHTTPOptions) {
+        if (config.streamableHTTPOptions.authProvider) {
+            options.authProvider = config.streamableHTTPOptions.authProvider;
+            logger.info(`MCP server "${serverName}": configuring Streamable HTTP with authentication provider`);
+        }
+        if (config.streamableHTTPOptions.requestInit) {
+            options.requestInit = config.streamableHTTPOptions.requestInit;
+        }
+        if (config.streamableHTTPOptions.reconnectionOptions) {
+            options.reconnectionOptions = config.streamableHTTPOptions.reconnectionOptions;
+        }
+        if (config.streamableHTTPOptions.sessionId) {
+            options.sessionId = config.streamableHTTPOptions.sessionId;
+        }
+    }
+    return Object.keys(options).length > 0 ? options : undefined;
+}
+/**
+ * Creates SSE transport options from configuration.
+ * Consolidates repeated option configuration logic into a single reusable function.
+ *
+ * @param config - URL-based server configuration
+ * @param logger - Logger instance for recording authentication setup
+ * @param serverName - Server name for logging context
+ * @returns Configured SSEClientTransportOptions or undefined if no options needed
+ *
+ * @internal This function is meant to be used internally by transport creation functions
+ */
+function createSseOptions(config, logger, serverName) {
+    const options = {};
+    if (config.sseOptions) {
+        if (config.sseOptions.authProvider) {
+            options.authProvider = config.sseOptions.authProvider;
+            logger.info(`MCP server "${serverName}": configuring SSE with authentication provider`);
+        }
+        if (config.sseOptions.eventSourceInit) {
+            options.eventSourceInit = config.sseOptions.eventSourceInit;
+        }
+        if (config.sseOptions.requestInit) {
+            options.requestInit = config.sseOptions.requestInit;
+        }
+    }
+    return Object.keys(options).length > 0 ? options : undefined;
+}
+/**
+ * Determines if an error represents a 4xx HTTP status code.
+ * Used to decide whether to fall back from Streamable HTTP to SSE transport.
+ *
+ * @param error - The error to check
+ * @returns true if the error represents a 4xx HTTP status
+ *
+ * @internal This function is meant to be used internally by createHttpTransportWithFallback
+ */
+function is4xxError(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    // Check for common error patterns that indicate 4xx responses
+    const errorObj = error;
+    // Check if it's a fetch Response error with status
+    if (errorObj.status && typeof errorObj.status === 'number') {
+        return errorObj.status >= 400 && errorObj.status < 500;
+    }
+    // Check if it's wrapped in a Response object
+    if (errorObj.response && errorObj.response.status && typeof errorObj.response.status === 'number') {
+        return errorObj.response.status >= 400 && errorObj.response.status < 500;
+    }
+    // Check for error messages that typically indicate 4xx errors
+    const message = errorObj.message || errorObj.toString();
+    if (typeof message === 'string') {
+        return /4[0-9]{2}/.test(message) ||
+            message.includes('Bad Request') ||
+            message.includes('Unauthorized') ||
+            message.includes('Forbidden') ||
+            message.includes('Not Found') ||
+            message.includes('Method Not Allowed');
+    }
+    return false;
+}
+/**
+ * Creates an HTTP transport with automatic fallback from Streamable HTTP to SSE.
+ * Follows the MCP specification recommendation to try Streamable HTTP first,
+ * then fall back to SSE if a 4xx error is encountered.
+ *
+ * See: https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#backwards-compatibility
+ *
+ * @param url - The URL to connect to
+ * @param config - URL-based server configuration
+ * @param logger - Logger instance for recording connection attempts
+ * @param serverName - Server name for logging context
+ * @returns A promise that resolves to a configured Transport
+ *
+ * @internal This function is meant to be used internally by convertSingleMcpToLangchainTools
+ */
+async function createHttpTransportWithFallback(url, config, logger, serverName) {
+    // If transport is explicitly specified, respect user's choice
+    if (config.transport === "streamable_http") {
+        logger.debug(`MCP server "${serverName}": using explicitly configured Streamable HTTP transport`);
+        const options = createStreamableHttpOptions(config, logger, serverName);
+        return new StreamableHTTPClientTransport(url, options);
+    }
+    if (config.transport === "sse") {
+        logger.debug(`MCP server "${serverName}": using explicitly configured SSE transport`);
+        const options = createSseOptions(config, logger, serverName);
+        return new SSEClientTransport(url, options);
+    }
+    // Auto-detection: try Streamable HTTP first, fall back to SSE on 4xx errors
+    logger.debug(`MCP server "${serverName}": attempting Streamable HTTP transport with SSE fallback`);
+    try {
+        const options = createStreamableHttpOptions(config, logger, serverName);
+        const transport = new StreamableHTTPClientTransport(url, options);
+        logger.info(`MCP server "${serverName}": successfully created Streamable HTTP transport`);
+        return transport;
+    }
+    catch (error) {
+        if (is4xxError(error)) {
+            logger.info(`MCP server "${serverName}": Streamable HTTP failed with 4xx error, falling back to SSE transport`);
+            const options = createSseOptions(config, logger, serverName);
+            return new SSEClientTransport(url, options);
+        }
+        // Re-throw non-4xx errors (network issues, etc.)
+        logger.error(`MCP server "${serverName}": Streamable HTTP transport creation failed with non-4xx error:`, error);
+        throw error;
+    }
+}
+/**
+ * Transforms a Zod schema to be compatible with OpenAI's Structured Outputs requirements.
+ *
+ * OpenAI's Structured Outputs feature requires that all optional fields must also be nullable.
+ * This function converts Zod schemas that use `.optional()` or `.default()` to also include
+ * `.nullable()`, ensuring compatibility with OpenAI models while maintaining compatibility
+ * with other LLM providers like Anthropic.
+ * See: https://platform.openai.com/docs/guides/structured-outputs?api-mode=responses#all-fields-must-be-required
+ *
+ * @param schema - The Zod object schema to transform
+ * @returns A new Zod schema with optional/default fields made nullable
+ *
+ * @example
+ * // Input schema: z.object({ name: z.string(), age: z.number().optional() })
+ * // Output schema: z.object({ name: z.string(), age: z.number().optional().nullable() })
+ *
+ * @see {@link https://platform.openai.com/docs/guides/structured-outputs | OpenAI Structured Outputs Documentation}
+ *
+ * @internal This function is meant to be used internally by convertSingleMcpToLangchainTools
+ */
+function makeZodSchemaOpenAICompatible(schema) {
+    const shape = schema.shape;
+    const newShape = {};
+    for (const [key, value] of Object.entries(shape)) {
+        if (value instanceof z.ZodOptional && !(value instanceof z.ZodNullable)) {
+            // Convert .optional() to .optional().nullable() for OpenAI compatibility
+            newShape[key] = value.nullable();
+        }
+        else if (value instanceof z.ZodDefault && !(value instanceof z.ZodNullable)) {
+            // Convert .default() to .default().nullable() for OpenAI compatibility
+            newShape[key] = value.nullable();
+        }
+        else {
+            // Keep existing fields unchanged (including already nullable fields)
+            newShape[key] = value;
+        }
+    }
+    return z.object(newShape);
+}
 /**
  * Initializes a single MCP server and converts its capabilities into LangChain tools.
  * Sets up a connection to the server, retrieves available tools, and creates corresponding
@@ -113,22 +387,67 @@ async function convertSingleMcpToLangchainTools(serverName, config, logger) {
             // Ignore
         }
         if (url?.protocol === "http:" || url?.protocol === "https:") {
-            // Extract SSE options from config if available
+            // Use the new auto-detection logic with fallback
             const urlConfig = config;
-            const sseOptions = {};
-            if (urlConfig.sseOptions) {
-                if (urlConfig.sseOptions.authProvider) {
-                    sseOptions.authProvider = urlConfig.sseOptions.authProvider;
-                    logger.info(`MCP server "${serverName}": configuring SSE with authentication provider`);
-                }
-                if (urlConfig.sseOptions.eventSourceInit) {
-                    sseOptions.eventSourceInit = urlConfig.sseOptions.eventSourceInit;
+            // Try to connect with Streamable HTTP first, fallback to SSE on 4xx errors
+            let connectionSucceeded = false;
+            // If transport is explicitly specified, respect user's choice (no fallback)
+            if (urlConfig.transport === "streamable_http" || urlConfig.transport === "sse") {
+                transport = await createHttpTransportWithFallback(url, urlConfig, logger, serverName);
+            }
+            else {
+                // Auto-detection with connection-level fallback
+                logger.debug(`MCP server "${serverName}": attempting Streamable HTTP transport with SSE fallback`);
+                try {
+                    // First attempt: Streamable HTTP
+                    const options = createStreamableHttpOptions(urlConfig, logger, serverName);
+                    transport = new StreamableHTTPClientTransport(url, options);
+                    logger.info(`MCP server "${serverName}": created Streamable HTTP transport, attempting connection`);
+                    // Try to connect with Streamable HTTP
+                    client = new Client({
+                        name: "mcp-client",
+                        version: "0.0.1",
+                    }, {
+                        capabilities: {},
+                    });
+                    await client.connect(transport);
+                    connectionSucceeded = true;
+                    logger.info(`MCP server "${serverName}": successfully connected using Streamable HTTP`);
                 }
-                if (urlConfig.sseOptions.requestInit) {
-                    sseOptions.requestInit = urlConfig.sseOptions.requestInit;
+                catch (error) {
+                    if (is4xxError(error)) {
+                        logger.info(`MCP server "${serverName}": Streamable HTTP failed with 4xx error, falling back to SSE transport`);
+                        // Cleanup failed transport and client
+                        if (transport) {
+                            try {
+                                await transport.close();
+                            }
+                            catch (cleanupError) {
+                                logger.debug(`MCP server "${serverName}": cleanup error during fallback:`, cleanupError);
+                            }
+                        }
+                        // Fallback to SSE
+                        const options = createSseOptions(urlConfig, logger, serverName);
+                        transport = new SSEClientTransport(url, options);
+                        logger.info(`MCP server "${serverName}": created SSE transport, attempting fallback connection`);
+                        // Create new client for SSE connection
+                        client = new Client({
+                            name: "mcp-client",
+                            version: "0.0.1",
+                        }, {
+                            capabilities: {},
+                        });
+                        await client.connect(transport);
+                        connectionSucceeded = true;
+                        logger.info(`MCP server "${serverName}": successfully connected using SSE fallback`);
+                    }
+                    else {
+                        // Re-throw non-4xx errors (network issues, etc.)
+                        logger.error(`MCP server "${serverName}": Streamable HTTP transport failed with non-4xx error:`, error);
+                        throw error;
+                    }
                 }
             }
-            transport = new SSEClientTransport(url, Object.keys(sseOptions).length > 0 ? sseOptions : undefined);
         }
         else if (url?.protocol === "ws:" || url?.protocol === "wss:") {
             transport = new WebSocketClientTransport(url);
@@ -150,57 +469,67 @@ async function convertSingleMcpToLangchainTools(serverName, config, logger) {
                 cwd: stdioServerConfig.cwd
             });
         }
-        client = new Client({
-            name: "mcp-client",
-            version: "0.0.1",
-        }, {
-            capabilities: {},
-        });
-        await client.connect(transport);
-        logger.info(`MCP server "${serverName}": connected`);
+        // Only create client if not already created during auto-detection fallback
+        if (!client) {
+            client = new Client({
+                name: "mcp-client",
+                version: "0.0.1",
+            }, {
+                capabilities: {},
+            });
+            await client.connect(transport);
+            logger.info(`MCP server "${serverName}": connected`);
+        }
         const toolsResponse = await client.request({ method: "tools/list" }, ListToolsResultSchema);
-        const tools = toolsResponse.tools.map((tool) => (new DynamicStructuredTool({
-            name: tool.name,
-            description: tool.description || "",
-            // FIXME
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            schema: jsonSchemaToZod(tool.inputSchema),
-            func: async function (input) {
-                logger.info(`MCP tool "${serverName}"/"${tool.name}" received input:`, input);
-                try {
-                    // Execute tool call
-                    const result = await client?.request({
-                        method: "tools/call",
-                        params: {
-                            name: tool.name,
-                            arguments: input,
-                        },
-                    }, CallToolResultSchema);
-                    // Handles null/undefined cases gracefully
-                    if (!result?.content) {
-                        logger.info(`MCP tool "${serverName}"/"${tool.name}" received null/undefined result`);
-                        return "";
+        const tools = toolsResponse.tools.map((tool) => {
+            // Apply sanitization for all LLMs (harmless for non-Gemini providers)
+            const sanitizedSchema = sanitizeSchemaForGemini(tool.inputSchema, logger, `${serverName}/${tool.name}`);
+            const baseSchema = jsonSchemaToZod(sanitizedSchema);
+            // Transforms a Zod schema to be compatible with OpenAI's Structured Outputs requirements.
+            const compatibleSchema = makeZodSchemaOpenAICompatible(baseSchema);
+            return new DynamicStructuredTool({
+                name: tool.name,
+                description: tool.description || "",
+                // FIXME
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                schema: compatibleSchema,
+                func: async function (input) {
+                    logger.info(`MCP tool "${serverName}"/"${tool.name}" received input:`, input);
+                    try {
+                        // Execute tool call
+                        const result = await client?.request({
+                            method: "tools/call",
+                            params: {
+                                name: tool.name,
+                                arguments: input,
+                            },
+                        }, CallToolResultSchema);
+                        // Handles null/undefined cases gracefully
+                        if (!result?.content) {
+                            logger.info(`MCP tool "${serverName}"/"${tool.name}" received null/undefined result`);
+                            return "";
+                        }
+                        const textContent = result.content
+                            .filter(content => content.type === "text")
+                            .map(content => content.text)
+                            .join("\n\n");
+                        // const textItems = result.content
+                        //   .filter(content => content.type === "text")
+                        //   .map(content => content.text)
+                        // const textContent = JSON.stringify(textItems);
+                        // Log rough result size for monitoring
+                        const size = new TextEncoder().encode(textContent).length;
+                        logger.info(`MCP tool "${serverName}"/"${tool.name}" received result (size: ${size})`);
+                        // If no text content, return a clear message describing the situation
+                        return textContent || "No text content available in response";
                     }
-                    const textContent = result.content
-                        .filter(content => content.type === "text")
-                        .map(content => content.text)
-                        .join("\n\n");
-                    // const textItems = result.content
-                    //   .filter(content => content.type === "text")
-                    //   .map(content => content.text)
-                    // const textContent = JSON.stringify(textItems);
-                    // Log rough result size for monitoring
-                    const size = new TextEncoder().encode(textContent).length;
-                    logger.info(`MCP tool "${serverName}"/"${tool.name}" received result (size: ${size})`);
-                    // If no text content, return a clear message describing the situation
-                    return textContent || "No text content available in response";
-                }
-                catch (error) {
-                    logger.warn(`MCP tool "${serverName}"/"${tool.name}" caused error: ${error}`);
-                    return `Error executing MCP tool: ${error}`;
-                }
-            },
-        })));
+                    catch (error) {
+                        logger.warn(`MCP tool "${serverName}"/"${tool.name}" caused error: ${error}`);
+                        return `Error executing MCP tool: ${error}`;
+                    }
+                },
+            });
+        });
         logger.info(`MCP server "${serverName}": ${tools.length} tool(s) available:`);
         tools.forEach((tool) => logger.info(`- ${tool.name}`));
         async function cleanup() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h1deya/langchain-mcp-tools",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "MCP To LangChain Tools Conversion Utility",
   "license": "MIT",
   "keywords": [
@@ -30,22 +30,39 @@
     "url": "git+https://github.com/hideya/langchain-mcp-tools-ts.git"
   },
   "scripts": {
+    "_comment_build": "# Build and development scripts",
     "build": "tsc",
     "prepare": "npm run build",
     "watch": "tsc --watch",
-    "simple-usage": "tsx testfiles/simple-usage.ts",
-    "direct-test": "tsx -- testfiles/direct-test.ts",
-    "sse-auth-test-client": "tsx testfiles/sse-auth-test-client.ts",
-    "sse-auth-test-server": "tsx testfiles/sse-auth-test-server.ts",
     "lint": "eslint src",
+    "clean": "git clean -fdxn -e .env && read -p 'OK?' && git clean -fdx -e .env",
+    
+    "_comment_test": "# Testing scripts",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "typedoc": "npx typedoc --options typedoc.json",
-    "deploy-docs": "npm run typedoc && ghp-import -n -p -f docs",
-    "clean": "git clean -fdxn -e .env && read -p 'OK?' && git clean -fdx -e .env",
-    "do-publish": "npm run clean && npm install && npm publish --access=public",
-    "test-publish": "npm run clean && npm install && npm publish --access=public --dry-run"
+    
+    "_comment_examples": "# Basic usage examples",
+    "example:simple": "tsx testfiles/simple-usage.ts",
+    
+    "_comment_streamable": "# Streamable HTTP transport tests",
+    "test:streamable:auth:server": "tsx testfiles/streamable-http-auth-test-server.ts",
+    "test:streamable:auth:client": "tsx testfiles/streamable-http-auth-test-client.ts",
+    "test:streamable:stateless:server": "tsx testfiles/streamable-http-stateless-test-server.ts",
+    "test:streamable:stateless:client": "tsx testfiles/streamable-http-stateless-test-client.ts",
+    "test:streamable:auto-detection": "tsx testfiles/streamable-http-auto-detection-test.ts",
+    
+    "_comment_sse": "# SSE transport tests (with authentication)",
+    "test:sse:server": "tsx testfiles/sse-auth-test-server.ts",
+    "test:sse:client": "tsx testfiles/sse-auth-test-client.ts",
+
+    "_comment_docs": "# Documentation scripts",
+    "docs:build": "npx typedoc --options typedoc.json",
+    "docs:deploy": "npm run docs:build && ghp-import -n -p -f docs",
+    
+    "_comment_publish": "# Publishing scripts",
+    "publish:test": "npm run clean && npm install && npm publish --access=public --dry-run",
+    "publish:do": "npm run clean && npm install && npm publish --access=public"
   },
   "dependencies": {
     "@langchain/core": "^0.3.27",
@@ -56,6 +73,7 @@
   "devDependencies": {
     "@eslint/js": "^9.17.0",
     "@langchain/anthropic": "^0.3.11",
+    "@langchain/google-genai": "^0.2.12",
     "@langchain/langgraph": "^0.2.36",
     "@langchain/openai": "^0.3.16",
     "@types/node": "^22.10.5",