mcp-use 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 zane
+
+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,130 @@
+<h1 align="center">Unified MCP Client Library</h1>
+
+[![](https://img.shields.io/npm/dw/@modelcontextprotocol/mcp-client.svg)](https://www.npmjs.com/package/@modelcontextprotocol/mcp-client)
+[![npm version](https://img.shields.io/npm/v/@modelcontextprotocol/mcp-client.svg)](https://www.npmjs.com/package/@modelcontextprotocol/mcp-client)
+[![License](https://img.shields.io/github/license/zandko/mcp-use)](https://github.com/zandko/mcp-use/blob/main/LICENSE)
+[![Code style: ESLint](https://img.shields.io/badge/code%20style-eslint-4B32C3.svg)](https://eslint.org)
+[![GitHub stars](https://img.shields.io/github/stars/zandko/mcp-use?style=social)](https://github.com/zandko/mcp-use/stargazers)
+
+🌐 **MCP Client** is the open-source way to connect **any LLM to any MCP server** in TypeScript/Node.js, letting you build custom agents with tool access without closed-source dependencies.
+
+💡 Let developers easily connect any LLM via LangChain.js to tools like web browsing, file operations, 3D modeling, and more.
+
+---
+
+## ✨ Key Features
+
+| Feature                         | Description                                                                |
+| ------------------------------- | -------------------------------------------------------------------------- |
+| 🔄 **Ease of use**              | Create an MCP-capable agent in just a few lines of TypeScript.             |
+| 🤖 **LLM Flexibility**          | Works with any LangChain.js-supported LLM that supports tool calling.      |
+| 🌐 **HTTP Support**             | Direct SSE/HTTP connection to MCP servers.                                 |
+| ⚙️ **Dynamic Server Selection** | Agents select the right MCP server from a pool on the fly.                 |
+| 🧩 **Multi-Server Support**     | Use multiple MCP servers in one agent.                                     |
+| 🛡️ **Tool Restrictions**        | Restrict unsafe tools like filesystem or network.                          |
+| 🔧 **Custom Agents**            | Build your own agents with LangChain.js adapter or implement new adapters. |
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Install from npm
+npm install mcp-use
+# LangChain.js and your LLM provider (e.g., OpenAI)
+npm install langchain @langchain/openai dotenv
+```
+
+Create a `.env`:
+
+```ini
+OPENAI_API_KEY=your_api_key
+```
+
+### Basic Usage
+
+```ts
+import { ChatOpenAI } from '@langchain/openai'
+import { MCPAgent, MCPClient } from 'mcp-use'
+import 'dotenv/config'
+
+async function main() {
+  // 1. Configure MCP servers
+  const config = {
+    mcpServers: {
+      playwright: { command: 'npx', args: ['@playwright/mcp@latest'] }
+    }
+  }
+  const client = MCPClient.fromDict(config)
+
+  // 2. Create LLM
+  const llm = new ChatOpenAI({ modelName: 'gpt-4o' })
+
+  // 3. Instantiate agent
+  const agent = new MCPAgent({ llm, client, maxSteps: 20 })
+
+  // 4. Run query
+  const result = await agent.run('Find the best restaurant in Tokyo using Google Search')
+  console.log('Result:', result)
+}
+
+main().catch(console.error)
+```
+
+---
+
+## 📂 Configuration File
+
+You can store servers in a JSON file:
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+Load it:
+
+```ts
+import { MCPClient } from 'mcp-use'
+const client = MCPClient.fromConfigFile('./mcp-config.json')
+```
+
+---
+
+## 🔄 Multi-Server Example
+
+```ts
+const config = {
+  mcpServers: {
+    airbnb: { command: 'npx', args: ['@openbnb/mcp-server-airbnb'] },
+    playwright: { command: 'npx', args: ['@playwright/mcp@latest'] }
+  }
+}
+const client = MCPClient.fromDict(config)
+const agent = new MCPAgent({ llm, client, useServerManager: true })
+await agent.run('Search Airbnb in Barcelona, then Google restaurants nearby')
+```
+
+---
+
+## 🔒 Tool Access Control
+
+```ts
+const agent = new MCPAgent({
+  llm,
+  client,
+  disallowedTools: ['file_system', 'network']
+})
+```
+
+## 📜 License
+
+MIT © [Zane](https://github.com/zandko)

package/dist/index.js

@@ -0,0 +1,10 @@
+import { MCPAgent } from './src/agents/mcp_agent.js';
+import { MCPClient } from './src/client.js';
+import { loadConfigFile } from './src/config.js';
+import { BaseConnector } from './src/connectors/base.js';
+import { HttpConnector } from './src/connectors/http.js';
+import { StdioConnector } from './src/connectors/stdio.js';
+import { WebSocketConnector } from './src/connectors/websocket.js';
+import { Logger, logger } from './src/logging.js';
+import { MCPSession } from './src/session.js';
+export { BaseConnector, HttpConnector, loadConfigFile, Logger, logger, MCPAgent, MCPClient, MCPSession, StdioConnector, WebSocketConnector };

package/dist/src/adapters/base.js

@@ -0,0 +1,124 @@
+import { logger } from '../logging.js';
+/**
+ * Abstract base class for converting MCP tools to other framework formats.
+ *
+ * This class defines the common interface that all adapter implementations
+ * should follow to ensure consistency across different frameworks.
+ */
+export class BaseAdapter {
+    /**
+     * List of tool names that should not be available.
+     */
+    disallowedTools;
+    /**
+     * Internal cache that maps a connector instance to the list of tools
+     * generated for it.
+     */
+    connectorToolMap = new Map();
+    constructor(disallowedTools) {
+        this.disallowedTools = disallowedTools ?? [];
+    }
+    /**
+     * Create tools from an MCPClient instance.
+     *
+     * This is the recommended way to create tools from an MCPClient, as it handles
+     * session creation and connector extraction automatically.
+     *
+     * @param client          The MCPClient to extract tools from.
+     * @param disallowedTools Optional list of tool names to exclude.
+     * @returns               A promise that resolves with a list of converted tools.
+     */
+    static async createTools(client, disallowedTools) {
+        // Create the adapter
+        const adapter = new this(disallowedTools);
+        // Ensure we have active sessions
+        if (!client.activeSessions || Object.keys(client.activeSessions).length === 0) {
+            logger.info('No active sessions found, creating new ones...');
+            await client.createAllSessions();
+        }
+        // Get all active sessions
+        const sessions = client.getAllActiveSessions();
+        // Extract connectors from sessions
+        const connectors = Object.values(sessions).map(session => session.connector);
+        // Create tools from connectors
+        return adapter.createToolsFromConnectors(connectors);
+    }
+    /**
+     * Dynamically load tools for a specific connector.
+     *
+     * @param connector The connector to load tools for.
+     * @returns         The list of tools that were loaded in the target framework's format.
+     */
+    async loadToolsForConnector(connector) {
+        // Return cached tools if we already processed this connector
+        if (this.connectorToolMap.has(connector)) {
+            const cached = this.connectorToolMap.get(connector);
+            logger.debug(`Returning ${cached.length} existing tools for connector`);
+            return cached;
+        }
+        const connectorTools = [];
+        // Make sure the connector is initialized and has tools
+        const success = await this.ensureConnectorInitialized(connector);
+        if (!success) {
+            return [];
+        }
+        // Convert and collect tools
+        for (const tool of connector.tools) {
+            const converted = this.convertTool(tool, connector);
+            if (converted) {
+                connectorTools.push(converted);
+            }
+        }
+        // Cache the tools for this connector
+        this.connectorToolMap.set(connector, connectorTools);
+        // Log for debugging purposes
+        logger.debug(`Loaded ${connectorTools.length} new tools for connector: ${connectorTools
+            .map((t) => t?.name ?? String(t))
+            .join(', ')}`);
+        return connectorTools;
+    }
+    /**
+     * Create tools from MCP tools in all provided connectors.
+     *
+     * @param connectors List of MCP connectors to create tools from.
+     * @returns         A promise that resolves with all converted tools.
+     */
+    async createToolsFromConnectors(connectors) {
+        const tools = [];
+        for (const connector of connectors) {
+            const connectorTools = await this.loadToolsForConnector(connector);
+            tools.push(...connectorTools);
+        }
+        logger.debug(`Available tools: ${tools.length}`);
+        return tools;
+    }
+    /**
+     * Check if a connector is initialized and has tools.
+     *
+     * @param connector The connector to check.
+     * @returns         True if the connector is initialized and has tools, false otherwise.
+     */
+    checkConnectorInitialized(connector) {
+        return Boolean(connector.tools && connector.tools.length);
+    }
+    /**
+     * Ensure a connector is initialized.
+     *
+     * @param connector The connector to initialize.
+     * @returns         True if initialization succeeded, false otherwise.
+     */
+    async ensureConnectorInitialized(connector) {
+        if (!this.checkConnectorInitialized(connector)) {
+            logger.debug('Connector doesn\'t have tools, initializing it');
+            try {
+                await connector.initialize();
+                return true;
+            }
+            catch (err) {
+                logger.error(`Error initializing connector: ${err}`);
+                return false;
+            }
+        }
+        return true;
+    }
+}

package/dist/src/adapters/index.js

@@ -0,0 +1,2 @@
+export { BaseAdapter } from './base.js';
+export { LangChainAdapter } from './langchain_adapter.js';

package/dist/src/adapters/langchain_adapter.js

@@ -0,0 +1,105 @@
+import { JSONSchemaToZod } from '@dmitryrechkin/json-schema-to-zod';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { logger } from '../logging.js';
+import { BaseAdapter } from './base.js';
+function schemaToZod(schema) {
+    /** Recursively normalise `type: [T, U]` → `anyOf: [{type:T},{type:U}]`. */
+    // const fixSchema = (s: any): any => {
+    //   if (s && typeof s === 'object') {
+    //     if (Array.isArray(s.type)) {
+    //       s.anyOf = s.type.map((t: any) => ({ type: t }))
+    //       delete s.type
+    //     }
+    //     for (const [k, v] of Object.entries(s)) {
+    //       s[k] = fixSchema(v)
+    //     }
+    //   }
+    //   return s
+    // }
+    try {
+        // const normalised = fixSchema(structuredClone(schema))
+        const zodSchema = JSONSchemaToZod.convert(schema);
+        return zodSchema;
+    }
+    catch (err) {
+        logger.warn(`Failed to convert JSON schema to Zod: ${err}`);
+        return z.any();
+    }
+}
+function parseMcpToolResult(toolResult) {
+    if (toolResult.isError) {
+        throw new Error(`Tool execution failed: ${toolResult.content}`);
+    }
+    if (!toolResult.content || toolResult.content.length === 0) {
+        throw new Error('Tool execution returned no content');
+    }
+    let decoded = '';
+    for (const item of toolResult.content) {
+        switch (item.type) {
+            case 'text': {
+                decoded += item.text;
+                break;
+            }
+            case 'image': {
+                decoded += item.data;
+                break;
+            }
+            case 'resource': {
+                const res = item.resource;
+                if (res?.text !== undefined) {
+                    decoded += res.text;
+                }
+                else if (res?.blob !== undefined) {
+                    // eslint-disable-next-line node/prefer-global/buffer
+                    decoded += res.blob instanceof Uint8Array || res.blob instanceof Buffer
+                        // eslint-disable-next-line node/prefer-global/buffer
+                        ? Buffer.from(res.blob).toString('base64')
+                        : String(res.blob);
+                }
+                else {
+                    throw new Error(`Unexpected resource type: ${res?.type}`);
+                }
+                break;
+            }
+            default:
+                throw new Error(`Unexpected content type: ${item.type}`);
+        }
+    }
+    return decoded;
+}
+export class LangChainAdapter extends BaseAdapter {
+    constructor(disallowedTools = []) {
+        super(disallowedTools);
+    }
+    /**
+     * Convert a single MCP tool specification into a LangChainJS structured tool.
+     */
+    convertTool(mcpTool, connector) {
+        // Filter out disallowed tools early.
+        if (this.disallowedTools.includes(mcpTool.name)) {
+            return null;
+        }
+        // Derive a strict Zod schema for the tool's arguments.
+        const argsSchema = mcpTool.inputSchema
+            ? schemaToZod(mcpTool.inputSchema)
+            : z.object({}).optional();
+        const tool = new DynamicStructuredTool({
+            name: mcpTool.name ?? 'NO NAME',
+            description: mcpTool.description ?? '', // Blank is acceptable but discouraged.
+            schema: argsSchema,
+            func: async (input) => {
+                logger.debug(`MCP tool \"${mcpTool.name}\" received input: ${JSON.stringify(input)}`);
+                try {
+                    const result = await connector.callTool(mcpTool.name, input);
+                    return parseMcpToolResult(result);
+                }
+                catch (err) {
+                    logger.error(`Error executing MCP tool: ${err}`);
+                    return `Error executing MCP tool: ${String(err)}`;
+                }
+            },
+        });
+        return tool;
+    }
+}

package/dist/src/agents/base.js

@@ -0,0 +1,9 @@
+export class BaseAgent {
+    session;
+    /**
+     * @param session MCP session used for tool invocation
+     */
+    constructor(session) {
+        this.session = session;
+    }
+}

package/dist/src/agents/index.js

@@ -0,0 +1,3 @@
+export { BaseAgent } from './base.js';
+export { MCPAgent } from './mcp_agent.js';
+export { ServerManager } from './server_manager.js';