@h1deya/langchain-mcp-tools 0.2.9 → 0.3.1

package/README.md

@@ -1,18 +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)
+# 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) [![network dependents](https://dependents.info/hideya/langchain-mcp-tools-ts/badge)](https://dependents.info/hideya/langchain-mcp-tools-ts)
 
 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.
+Its simplicity and extra features, such as
+[tools schema adjustments for LLM compatibility](https://github.com/hideya/langchain-mcp-tools-ts/blob/main/README.md#llm-provider-schema-compatibility)
+and [tools invocation logging](https://github.com/hideya/langchain-mcp-tools-ts/blob/main/README.md#debugging-and-logging),
+make it a useful basis for your experiments and 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,
-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/tree/main/libs/langchain-mcp-adapters`
-
-You may want to consider using the above if you don't have specific needs for this library.
+[LangChain's **official LangChain.js MCP Adapters** library](https://www.npmjs.com/package/@langchain/mcp-adapters),
+which supports comprehensive integration with LangChain, has been released.
+You may want to consider using it if you don't have specific needs for this library.
 
 ## Introduction
 
@@ -22,24 +22,20 @@ server tools with LangChain / TypeScript.
 
 [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.
-
-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/)
-
-This utility's goal is to make these massive numbers of MCP servers easily accessible from LangChain.
+including DBs, Cloud Storages, GitHub, Docker, Slack, and more.
+There are [quite a few useful MCP servers already available.
+See [MCP Server Listing on the Official Site](https://github.com/modelcontextprotocol/servers?tab=readme-ov-file#model-context-protocol-servers).
 
+This utility's goal is to make these numerous MCP servers easily accessible from LangChain.  
 It contains a utility function `convertMcpToLangchainTools()`.  
 This async function handles parallel initialization of specified multiple MCP servers
 and converts their available tools into an array of LangChain-compatible tools.
+It also performs LLM provider-specific schema transformations
+to prevent [schema compatibility issues](https://github.com/hideya/langchain-mcp-tools-ts/blob/main/README.md#llm-provider-schema-compatibility)
 
 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)
-
-A python equivalent of this utility is available
+["Supercharging LangChain: Integrating 2000+ MCP with ReAct"](https://medium.com/@h1deya/supercharging-langchain-integrating-450-mcp-with-react-d4e467cbf41a).  
+A Python equivalent of this utility is available
 [here](https://pypi.org/project/langchain-mcp-tools)
 
 ## Prerequisites
@@ -86,7 +82,14 @@ const mcpServers: McpServersConfig = {
   },
 };
 
-const { tools, cleanup } = await convertMcpToLangchainTools(mcpServers);
+const { tools, cleanup } = await convertMcpToLangchainTools(
+  mcpServers, {
+    // Perform provider-specific JSON schema transformations to prevent schema compatibility issues
+    llmProvider: "google_gemini"
+    // llmProvider: "openai"
+    // llmProvider: "anthropic"
+  }
+);
 ```
 
 This utility function initializes all specified MCP servers in parallel,
@@ -94,14 +97,20 @@ and returns LangChain Tools
 ([`tools: StructuredTool[]`](https://api.js.langchain.com/classes/_langchain_core.tools.StructuredTool.html))
 by gathering available MCP tools from the servers,
 and by wrapping them into LangChain tools.
+
+When `llmProvider` option is specified, it performs LLM provider-specific schema transformations
+for MCP tools to prevent schema compatibility issues.
+Set this option when you enconter schema related warnings/errors while execution.  
+[See below](https://github.com/hideya/langchain-mcp-tools-ts/blob/main/README.md#llm-provider-schema-compatibility) for details.
+
 It also returns an async callback function (`cleanup: McpServerCleanupFn`)
 to be invoked to close all MCP server sessions when finished.
 
 The returned tools can be used with LangChain, e.g.:
 
 ```ts
-// import { ChatAnthropic } from "@langchain/anthropic";
-const llm = new ChatAnthropic({ model: "claude-sonnet-4-0" });
+// import { ChatGoogleGenerativeAI } from "@langchain/google-genai";
+const llm = new ChatGoogleGenerativeAI({ model: "gemini-2.5-flash" });
 
 // import { createReactAgent } from "@langchain/langgraph/prebuilt";
 const agent = createReactAgent({
@@ -110,17 +119,35 @@ const agent = createReactAgent({
 });
 ```
 
+A minimal but complete working usage example can be found
+[in this example in the langchain-mcp-tools-ts-usage repo](https://github.com/hideya/langchain-mcp-tools-ts-usage/blob/main/src/index.ts)
+
 For hands-on experimentation with MCP server integration,
-try [this LangChain application built with the utility](https://github.com/hideya/mcp-client-langchain-ts)
+try [this MCP Client CLI tool built with this library](https://www.npmjs.com/package/@h1deya/mcp-client-cli)
 
-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)
+## Building from Source
+
+See [README_DEV.md](https://github.com/hideya/langchain-mcp-tools-ts/blob/main/README_DEV.md) for details.
 
 ## MCP Protocol Support
 
 This library supports **MCP Protocol version 2025-03-26** and maintains backwards compatibility with version 2024-11-05.
 It follows the [official MCP specification](https://modelcontextprotocol.io/specification/2025-03-26/) for transport selection and backwards compatibility.
 
+### Limitations
+
+- **Tool Return Types**: Currently, only text results of tool calls are supported.
+The library uses LangChain's `response_format: 'content'` (the default), which only supports text strings.
+While MCP tools can return multiple content types (text, images, etc.), this library currently filters and uses only text content.
+- **MCP Features**: Only MCP [Tools](https://modelcontextprotocol.io/docs/concepts/tools) are supported. Other MCP features like Resources, Prompts, and Sampling are not implemented.
+
+### Notes:
+
+- **LLM Compatibility and Schema Transformations**: The library can perform schema transformations for LLM compatibility.
+  [See below](https://github.com/hideya/langchain-mcp-tools-ts/blob/main/README.md#llm-provider-schema-compatibility) for details.
+- **Passing PATH Env Variable**: The library automatically adds the `PATH` environment variable to stdio server configrations if not explicitly provided to ensure servers can find required executables.
+
+
 ## Features
 
 ### `stderr` Redirection for Local MCP Server 
@@ -155,8 +182,6 @@ can be specified with the `"cwd"` key as follows:
 The key name `cwd` is derived from
 TypeScript SDK's [`StdioServerParameters`](https://github.com/modelcontextprotocol/typescript-sdk/blob/131776764536b5fdca642df51230a3746fb4ade0/src/client/stdio.ts#L39).
 
-**Note:** The library automatically adds the `PATH` environment variable to stdio servers if not explicitly provided to ensure servers can find required executables.
-
 ### Transport Selection Priority
 
 The library selects transports using the following priority order:
@@ -243,7 +268,8 @@ class MyOAuthProvider implements OAuthClientProvider {
 const mcpServers = {
   "secure-streamable-server": {
     url: "https://secure-mcp-server.example.com/mcp",
-    transport: "streamable_http",  // Optional: explicit transport
+    // To avoid auto protocol fallback, specify the protocol explicitly when using authentication
+    transport: "streamable_http",  // or `type: "http",`
     streamableHTTPOptions: {
       // Provide an OAuth client provider
       authProvider: new MyOAuthProvider(),
@@ -271,57 +297,6 @@ Test implementations are provided:
   - 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:
-
-```ts
-import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
-
-// Implement your own OAuth client provider
-class MyOAuthProvider implements OAuthClientProvider {
-  // Implementation details...
-}
-
-const mcpServers = {
-  "secure-server": {
-    url: "https://secure-mcp-server.example.com",
-    sseOptions: {
-      // Provide an OAuth client provider
-      authProvider: new MyOAuthProvider(),
-      
-      // Optionally customize the initial SSE request
-      eventSourceInit: {
-        // Custom options
-      },
-      
-      // Optionally customize recurring POST requests
-      requestInit: {
-        headers: {
-          'X-Custom-Header': 'custom-value'
-        }
-      }
-    }
-  }
-};
-```
-
-Test implementations are provided:
-
-- **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
-
-- **Tool Return Types**: Currently, only text results of tool calls are supported.
-The library uses LangChain's `response_format: 'content'` (the default), which only supports text strings.
-While MCP tools can return multiple content types (text, images, etc.), this library currently filters and uses only text content.
-- **MCP Features**: Only MCP [Tools](https://modelcontextprotocol.io/docs/concepts/tools) are supported. Other MCP features like Resources, Prompts, and Sampling are not implemented.
-
 ## Change Log
 
 Can be found [here](https://github.com/hideya/langchain-mcp-tools-ts/blob/main/CHANGELOG.md)
@@ -330,76 +305,90 @@ Can be found [here](https://github.com/hideya/langchain-mcp-tools-ts/blob/main/C
 
 ### Troubleshooting
 
-#### Common Configuration Errors
+1. **Enable debug logging**: Set `logLevel: "debug"` to see detailed connection and execution logs
+2. **Check server stderr**: For stdio MCP servers, use `stderr` redirection to capture server error output
+3. **Test explicit transports**: Try forcing specific transport types to isolate auto-detection issues
+4. **Verify server independently**: Test the MCP server with other clients (e.g., MCP Inspector)
+
+### LLM Provider Schema Compatibility
 
-**McpInitializationError: Cannot specify both 'command' and 'url'**
-- Remove either the `command` field (for URL-based servers) or the `url` field (for local stdio servers)
-- Use `command` for local MCP servers, `url` for remote servers
+Different LLM providers have incompatible JSON Schema requirements for function calling:
 
-**McpInitializationError: URL protocol to be http: or https:**
-- Check that your URL starts with `http://` or `https://` when using HTTP transport
-- For WebSocket servers, use `ws://` or `wss://` URLs
+- **OpenAI requires**: Optional fields must be nullable (`.optional()` + `.nullable()`)
+  for function calling (based on Structured Outputs API requirements,
+  strict enforcement coming in future SDK versions)"
+- **Google Gemini API**: Rejects nullable fields and `$defs` references, requires strict OpenAPI 3.0 subset compliance
+- **Anthropic Claude**: Very relaxed schema requirements with no documented restrictions
 
-**McpInitializationError: command to be specified**
-- Add a `command` field when using stdio transport
-- Ensure the command path is correct and the executable exists
+**Note**: Google Vertex AI provides OpenAI-compatible endpoints that support nullable fields.
 
-#### Transport Detection Issues
+#### Real-World Impact
 
-**Transport detection failed**
-- Server may not support the MCP protocol correctly
-- Try specifying an explicit transport type (`transport: "streamable_http"` or `transport: "sse"`)
-- Check server documentation for supported transport types
+This creates challenges for developers trying to create universal schemas across providers.
 
-**Connection timeout or network errors**
-- Verify the server URL and port are correct
-- Check that the server is running and accessible
-- Ensure firewall/network settings allow the connection
+Many MCP servers generate schemas that don't satisfy all providers' requirements.  
+For example, the official Notion MCP server [@notionhq/notion-mcp-server](https://www.npmjs.com/package/@notionhq/notion-mcp-server) (as of Jul 2, 2025) produces:
 
-#### Tool Execution Problems
+**OpenAI Warnings:**
+```
+Zod field at `#/definitions/API-get-users/properties/start_cursor` uses `.optional()` without `.nullable()` which is not supported by the API. See: https://platform.openai.com/docs/guides/structured-outputs?api-mode=responses#all-fields-must-be-required
+... followed by many more
+```
 
-**Schema sanitization warnings for Gemini compatibility**
-- These are informational and generally safe to ignore
-- Consider updating the MCP server to use Gemini-compatible schemas
-- Warnings help identify servers that may need upstream fixes
+**Gemini Errors:**
+```
+GoogleGenerativeAIFetchError: [GoogleGenerativeAI Error]: Error fetching from https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent: [400 Bad Request] * GenerateContentRequest.tools[0].function_declarations[0].parameters.properties[children].items.properties[paragraph].properties[rich_text].items.properties[mention].any_of[0].required: only allowed for OBJECT type
+... followed by many more
+```
 
-**Tool calls returning empty results**
-- Check server logs (use `stderr` redirection to capture them)
-- Verify tool parameters match the expected schema
-- Enable debug logging to see detailed tool execution information
+#### Solution
 
-#### Debug Steps
+The new option, `llmProvider`, has been introduced for performing provider-specific JSON schema transformations:
 
-1. **Enable debug logging**: Set `logLevel: "debug"` to see detailed connection and execution logs
-2. **Check server stderr**: For stdio MCP servers, use `stderr` redirection to capture server error output
-3. **Test explicit transports**: Try forcing specific transport types to isolate auto-detection issues
-4. **Verify server independently**: Test the MCP server with other clients (e.g., MCP Inspector)
+```typescript
+const { tools, cleanup } = await convertMcpToLangchainTools(
+  mcpServers, {
+    llmProvider: "openai"        // Makes optional fields nullable
+    // llmProvider: "google_gemini" // Applies Gemini's strict validation rules  
+    // llmProvider: "anthropic"     // No transformations needed
+  }
+);
+```
+
+**Features:**
+- Generates INFO-level logs when transformations are applied
+- Helps users identify potential MCP server schema improvements
+- Falls back to original schema when no `llmProvider` is specified
 
-#### Configuration Validation
+#### Provider-Specific Transformations
 
-The library validates server configurations and will throw `McpInitializationError` for invalid configurations:
+| Provider | Transformations Applied |
+|----------|------------------------|
+| `openai` | Makes optional fields nullable, handles union types |
+| `google_gemini` | Filters invalid required fields, fixes anyOf variants, removes unsupported features |
+| `anthropic` | Accepts schemas as-is, but handles them efficiently |
 
-- **Cannot specify both `url` and `command`**: Use `command` for local servers or `url` for remote servers
-- **Transport type must match URL protocol**: e.g., `transport: "http"` requires `http:` or `https:` URL
-- **Transport requires appropriate configuration**: HTTP/WS transports need URLs, stdio transport needs command
+For other providers, try without specifying the option:
 
-### LLM Compatibility
+```typescript
+const { tools, cleanup } = await convertMcpToLangchainTools(
+  mcpServers
+);
+```
 
-The library automatically handles schema compatibility for different LLM providers:
+#### References
 
-- **Google Gemini**: Sanitizes schemas to remove unsupported properties (logs warnings when changes are made)
-- **OpenAI Structured Outputs**: Makes optional fields nullable as required by OpenAI's specification
-- **Anthropic Claude**: Works with schemas as-is
-- **Other providers**: Generally compatible with standard JSON schemas
+- [OpenAI Function Calling](https://platform.openai.com/docs/guides/function-calling)
+- [Gemini API Schema Requirements](https://ai.google.dev/api/caching#Schema)
+- [Anthropic Tool Use](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview)
 
-Schema transformations are applied automatically and logged at the `warn` level when changes are made, helping you identify which MCP servers might need upstream schema fixes for optimal compatibility.
 
 ### Resource Management
 
 The returned `cleanup` function properly handles resource cleanup:
 
 - Closes all MCP server connections concurrently
-- Logs any cleanup failures without throwing errors
+- Logs any cleanup failures
 - Continues cleanup of remaining servers even if some fail
 - Should always be called when done using the tools
 
@@ -440,3 +429,8 @@ const { tools, cleanup } = await convertMcpToLangchainTools(
 ```
 
 Available log levels: `"fatal" | "error" | "warn" | "info" | "debug" | "trace"`
+
+### For Developers
+
+See [README_DEV.md](https://github.com/hideya/langchain-mcp-tools-ts/blob/main/README.md)
+for more information about development and testing.

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

@@ -80,6 +80,13 @@ export type SingleMcpServerConfig = CommandBasedConfig | UrlBasedConfig;
 export interface McpServersConfig {
     [key: string]: SingleMcpServerConfig;
 }
+/**
+ * Logger interface for MCP tools operations.
+ * Provides structured logging capabilities for debugging and monitoring
+ * MCP server connections and tool executions.
+ *
+ * @public
+ */
 export interface McpToolsLogger {
     debug(...args: unknown[]): void;
     info(...args: unknown[]): void;
@@ -88,12 +95,42 @@ export interface McpToolsLogger {
 }
 /**
  * Options for configuring logging behavior.
+ * Controls the verbosity level of logging output during MCP operations.
  *
  * @public
  */
 export interface LogOptions {
+    /** Log verbosity level. Higher levels include all lower levels (e.g., "debug" includes "info", "warn", "error", "fatal") */
     logLevel?: "fatal" | "error" | "warn" | "info" | "debug" | "trace";
 }
+/**
+ * Supported LLM providers for schema transformations.
+ * Each provider has specific JSON schema requirements that may conflict with MCP tool schemas.
+ *
+ * @public
+ */
+export type LlmProvider = "openai" | "google_gemini" | "google_genai" | "anthropic" | "none";
+/**
+ * Configuration options for converting MCP servers to LangChain tools.
+ * Extends LogOptions to include provider-specific schema transformations and custom logging.
+ *
+ * @public
+ */
+export interface ConvertMcpToLangchainOptions extends LogOptions {
+    /** Custom logger implementation. If not provided, uses default Logger with specified logLevel */
+    logger?: McpToolsLogger;
+    /** LLM provider for schema compatibility transformations. Performs provider-specific JSON schema modifications to prevent compatibility issues */
+    llmProvider?: LlmProvider;
+}
+/**
+ * Cleanup function returned by convertMcpToLangchainTools.
+ * Properly terminates all MCP server connections and cleans up resources.
+ *
+ * @public
+ */
+export interface McpServerCleanupFn {
+    (): Promise<void>;
+}
 /**
  * Error interface for MCP-related errors.
  * Extends the standard Error interface with MCP-specific properties.
@@ -104,9 +141,6 @@ export interface McpError extends Error {
     serverName: string;
     details?: unknown;
 }
-export interface McpServerCleanupFn {
-    (): Promise<void>;
-}
 /**
  * Error thrown when an MCP server initialization fails.
  * Contains details about the server that failed to initialize.
@@ -127,6 +161,10 @@ export declare class McpInitializationError extends Error implements McpError {
  * @param options.logLevel - Log verbosity level ("fatal" | "error" | "warn" | "info" | "debug" | "trace")
  * @param options.logger - Custom logger implementation that follows the McpToolsLogger interface.
  *                        If provided, overrides the default Logger instance.
+ * @param options.llmProvider - LLM provider for schema compatibility transformations.
+ *                             Performs provider-specific JSON schema modifications to prevent compatibility issues.
+ *                             Set to "openai" for OpenAI models, "google_gemini"/"google_genai" for Google models,
+ *                             "anthropic" for Claude models, or "none" for no transformation.
  *
  * @returns A promise that resolves to:
  *          - tools: Array of StructuredTool instances ready for use with LangChain
@@ -138,17 +176,19 @@ export declare class McpInitializationError extends Error implements McpError {
  * @remarks
  * - Servers are initialized concurrently for better performance
  * - Configuration is validated and will throw errors for conflicts (e.g., both url and command specified)
+ * - Schema transformations are applied based on llmProvider to ensure compatibility
  * - The cleanup function continues with remaining servers even if some cleanup operations fail
  *
  * @example
  * const { tools, cleanup } = await convertMcpToLangchainTools({
  *   filesystem: { command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "."] },
  *   fetch: { command: "uvx", args: ["mcp-server-fetch"] }
+ * }, {
+ *   llmProvider: "openai",
+ *   logLevel: "debug"
  * });
  */
-export declare function convertMcpToLangchainTools(configs: McpServersConfig, options?: LogOptions & {
-    logger?: McpToolsLogger;
-}): Promise<{
+export declare function convertMcpToLangchainTools(configs: McpServersConfig, options?: ConvertMcpToLangchainOptions): Promise<{
     tools: StructuredTool[];
     cleanup: McpServerCleanupFn;
 }>;