@h1deya/langchain-mcp-tools 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hideya
+
+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,71 @@
+# MCP Server To LangChain Tools Conversion Utility [![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)
+
+This package is intended to simplify the use of MCP server tools within LangChain.
+
+It contains a utility function `convertMCPServersToLangChainTools()`
+that initializes specified MCP servers,
+and returns [LangChain Tools](https://js.langchain.com/docs/how_to/tool_calling/)
+that wrap all the available MCP server tools.
+
+## Installation
+
+```bash
+npm i @h1deya/langchain-mcp-tool
+```
+
+## Quick Start
+
+`convertMCPServersToLangChainTools()` utility function accepts MCP server configuration
+in pretty much the same format as a JS Object interpretation of the JSON format used by
+[Claude for Desktop](https://modelcontextprotocol.io/quickstart/user)
+(it just needs the contents of the `mcpServers` property).
+e.g.:
+
+```ts
+const mcpServers: MCPServersConfig = {
+  filesystem: {
+    command: 'npx',
+    args: [
+      '-y',
+      '@modelcontextprotocol/server-filesystem',
+      '/Users/username/Desktop'  // path to a directory to allow access to
+    ]
+  },
+  fetch: {
+    command: 'uvx',
+    args: [
+      'mcp-server-fetch'
+    ]
+  }
+};
+
+const { tools, cleanup } = await convertMCPServersToLangChainTools(mcpServers);
+```
+
+The utility function initializes all the MCP server connections concurrently,
+and returns LangChain Tools (`tools: DynamicStructuredTool[]`)
+by gathering all the available MCP server tools,
+and by wrapping them into [LangChain Tools](https://js.langchain.com/docs/how_to/tool_calling/).
+It also returns `cleanup` callback function
+which is used to close all the connections to the MCP servers when finished.
+
+The returned tools can be used with LangChain, e.g.:
+
+```ts
+const llm = new ChatAnthropic({ model: 'claude-3-5-haiku-latest' });
+
+// import { createReactAgent } from '@langchain/langgraph/prebuilt';
+const agent = createReactAgent({
+  llm,
+  tools
+});
+```
+A simple and experimentable usage example can be found
+[here](https://github.com/hideya/langchain-mcp-tools-ts-usage/blob/main/src/index.ts)
+
+A more realistic usage example can be found
+[here](https://github.com/hideya/langchain-mcp-client-ts)
+
+## Limitations
+
+Currently, only text results of tool calls are supported.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./langchain-mcp-tools.js";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./langchain-mcp-tools.js";

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

@@ -0,0 +1,20 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+interface MCPServerConfig {
+    command: string;
+    args: readonly string[];
+    env?: Readonly<Record<string, string>>;
+}
+export interface MCPServersConfig {
+    [key: string]: MCPServerConfig;
+}
+interface LogOptions {
+    logLevel?: 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
+}
+export interface MCPServerCleanupFunction {
+    (): Promise<void>;
+}
+export declare function convertMCPServersToLangChainTools(configs: MCPServersConfig, options?: LogOptions): Promise<{
+    tools: DynamicStructuredTool[];
+    cleanup: MCPServerCleanupFunction;
+}>;
+export {};

package/dist/langchain-mcp-tools.js

@@ -0,0 +1,133 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { CallToolResultSchema, ListToolsResultSchema } from '@modelcontextprotocol/sdk/types.js';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { jsonSchemaToZod } from '@n8n/json-schema-to-zod';
+import { Logger } from './logger.js';
+// Custom error type for MCP server initialization failures
+class MCPInitializationError extends Error {
+    serverName;
+    details;
+    constructor(serverName, message, details) {
+        super(message);
+        this.serverName = serverName;
+        this.details = details;
+        this.name = 'MCPInitializationError';
+    }
+}
+// Primary function to convert multiple MCP servers to LangChain tools
+export async function convertMCPServersToLangChainTools(configs, options) {
+    const allTools = [];
+    const cleanupCallbacks = [];
+    const logger = new Logger({ level: options?.logLevel || 'info' });
+    const serverInitPromises = Object.entries(configs).map(async ([name, config]) => {
+        const result = await convertMCPServerToLangChainTools(name, config, logger);
+        return { name, result };
+    });
+    // Track server names alongside their promises
+    const serverNames = Object.keys(configs);
+    // Concurrently initialize all the MCP servers
+    const results = await Promise.allSettled(serverInitPromises);
+    // Process successful initializations and log failures
+    results.forEach((result, index) => {
+        if (result.status === 'fulfilled') {
+            const { result: { tools, cleanup } } = result.value;
+            allTools.push(...tools);
+            cleanupCallbacks.push(cleanup);
+        }
+        else {
+            logger.error(`MCP server "${serverNames[index]}": failed to initialize: ${result.reason.details}`);
+            throw result.reason;
+        }
+    });
+    async function cleanup() {
+        // Concurrently execute all the callbacks
+        const results = await Promise.allSettled(cleanupCallbacks.map(callback => callback()));
+        // Log any cleanup failures
+        const failures = results.filter(result => result.status === 'rejected');
+        failures.forEach((failure, index) => {
+            logger.error(`MCP server "${serverNames[index]}": failed to close: ${failure.reason}`);
+        });
+    }
+    logger.info(`MCP servers initialized: ${allTools.length} tool(s) available in total`);
+    allTools.forEach((tool) => logger.debug(`- ${tool.name}`));
+    return { tools: allTools, cleanup };
+}
+// Convert a single MCP server into LangChain tools
+async function convertMCPServerToLangChainTools(serverName, config, logger) {
+    let transport = null;
+    let client = null;
+    logger.info(`MCP server "${serverName}": initializing with: ${JSON.stringify(config)}`);
+    // NOTE: Some servers (e.g. Brave) seem to require PATH to be set.
+    // To avoid confusion, it was decided to automatically append it to the env
+    // if not explicitly set by the config.
+    const env = { ...config.env };
+    if (!env.PATH) {
+        env.PATH = process.env.PATH || '';
+    }
+    try {
+        transport = new StdioClientTransport({
+            command: config.command,
+            args: config.args,
+            env: env,
+        });
+        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 (input) => {
+                logger.info(`MCP Tool "${tool.name}" received input:`, input);
+                // Execute tool call
+                const result = await client?.request({
+                    method: "tools/call",
+                    params: {
+                        name: tool.name,
+                        arguments: input,
+                    },
+                }, CallToolResultSchema);
+                const roughLength = JSON.stringify(result).length;
+                logger.info(`MCP Tool "${tool.name}" received result (length: ${roughLength})`);
+                logger.debug('result:', result);
+                const filteredResult = result?.content
+                    .filter(content => content.type === 'text')
+                    .map(content => content.text)
+                    .join('\n\n');
+                return filteredResult;
+                // return JSON.stringify(result.content);
+            },
+        })));
+        logger.info(`MCP server "${serverName}": ${tools.length} tool(s) available:`);
+        tools.forEach((tool) => logger.info(`- ${tool.name}`));
+        async function cleanup() {
+            if (transport) {
+                await transport.close();
+                logger.info(`MCP server "${serverName}": connection closed`);
+            }
+        }
+        return { tools, cleanup };
+    }
+    catch (error) {
+        // Proper cleanup in case of initialization error
+        if (transport) {
+            try {
+                await transport.close();
+            }
+            catch (cleanupError) {
+                // Log cleanup error but don't let it override the original error
+                logger.error(`Failed to cleanup during initialization error: ${cleanupError}`);
+            }
+        }
+        throw new MCPInitializationError(serverName, `Failed to initialize MCP server: ${error instanceof Error ? error.message : String(error)}`, error);
+    }
+}

package/dist/logger.d.ts

@@ -0,0 +1,27 @@
+type LogLevelString = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+declare enum LogLevel {
+    TRACE = 0,
+    DEBUG = 1,
+    INFO = 2,
+    WARN = 3,
+    ERROR = 4,
+    FATAL = 5
+}
+declare class Logger {
+    private readonly level;
+    private static readonly RESET;
+    constructor({ level }?: {
+        level?: LogLevelString | LogLevel;
+    });
+    private parseLogLevel;
+    private log;
+    private formatValue;
+    private createLogMethod;
+    trace: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    fatal: (...args: unknown[]) => void;
+}
+export { Logger, LogLevel, LogLevelString };

package/dist/logger.js

@@ -0,0 +1,62 @@
+// Simple logger
+var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["TRACE"] = 0] = "TRACE";
+    LogLevel[LogLevel["DEBUG"] = 1] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 2] = "INFO";
+    LogLevel[LogLevel["WARN"] = 3] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 4] = "ERROR";
+    LogLevel[LogLevel["FATAL"] = 5] = "FATAL";
+})(LogLevel || (LogLevel = {}));
+const LOG_COLORS = {
+    [LogLevel.TRACE]: '\x1b[90m', // Gray
+    [LogLevel.DEBUG]: '\x1b[90m', // Gray
+    [LogLevel.INFO]: '\x1b[90m', // Gray
+    [LogLevel.WARN]: '\x1b[1;93m', // Bold bright yellow
+    [LogLevel.ERROR]: '\x1b[1;91m', // Bold bright red
+    [LogLevel.FATAL]: '\x1b[1;101m', // Red background, Bold text
+};
+const LOG_LEVEL_MAP = {
+    trace: LogLevel.TRACE,
+    debug: LogLevel.DEBUG,
+    info: LogLevel.INFO,
+    warn: LogLevel.WARN,
+    error: LogLevel.ERROR,
+    fatal: LogLevel.FATAL
+};
+class Logger {
+    level;
+    static RESET = '\x1b[0m';
+    constructor({ level = LogLevel.INFO } = {}) {
+        this.level = this.parseLogLevel(level);
+    }
+    parseLogLevel(level) {
+        if (typeof level === 'number')
+            return level;
+        return LOG_LEVEL_MAP[level.toLowerCase()];
+    }
+    log(level, ...args) {
+        if (level < this.level)
+            return;
+        const color = LOG_COLORS[level];
+        const levelStr = `[${LogLevel[level].toLowerCase()}]`;
+        console.log(`${color}${levelStr}${Logger.RESET}`, ...args.map(this.formatValue));
+    }
+    formatValue(value) {
+        if (value === null)
+            return 'null';
+        if (value === undefined)
+            return 'undefined';
+        return typeof value === 'object' ? JSON.stringify(value, null, 2) : String(value);
+    }
+    createLogMethod(level) {
+        return (...args) => this.log(level, ...args);
+    }
+    trace = this.createLogMethod(LogLevel.TRACE);
+    debug = this.createLogMethod(LogLevel.DEBUG);
+    info = this.createLogMethod(LogLevel.INFO);
+    warn = this.createLogMethod(LogLevel.WARN);
+    error = this.createLogMethod(LogLevel.ERROR);
+    fatal = this.createLogMethod(LogLevel.FATAL);
+}
+export { Logger, LogLevel };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@h1deya/langchain-mcp-tools",
+  "version": "0.1.0",
+  "description": "A utility that wraps MCP servers into LangChain tools",
+  "license": "MIT",
+  "keywords": [
+    "modelcontextprotocol",
+    "mcp",
+    "mcp-client",
+    "langchain",
+    "tool-calling",
+    "typescript"
+  ],
+  "author": "hideya kawahara",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hideya/langchain-mcp-tools-ts.git"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "clean": "rm -rf dist coverage"
+  },
+  "dependencies": {
+    "@langchain/core": "^0.3.27",
+    "@modelcontextprotocol/sdk": "^1.1.0",
+    "@n8n/json-schema-to-zod": "^1.1.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@types/node": "^22.10.5",
+    "@typescript-eslint/eslint-plugin": "^8.19.0",
+    "@typescript-eslint/parser": "^8.19.0",
+    "@vitest/coverage-v8": "^2.1.8",
+    "eslint": "^9.17.0",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.19.0",
+    "vitest": "^2.1.8"
+  }
+}