mcp-use 0.1.8 → 0.1.10

package/dist/examples/structured_output.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Structured Output Example - City Research with Playwright
+ *
+ * This example demonstrates intelligent structured output by researching Padova, Italy.
+ * The agent becomes schema-aware and will intelligently retry to gather missing
+ * information until all required fields can be populated.
+ */
+export {};
+//# sourceMappingURL=structured_output.d.ts.map

package/dist/examples/structured_output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured_output.d.ts","sourceRoot":"","sources":["../../examples/structured_output.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/examples/structured_output.js

@@ -0,0 +1,95 @@
+/**
+ * Structured Output Example - City Research with Playwright
+ *
+ * This example demonstrates intelligent structured output by researching Padova, Italy.
+ * The agent becomes schema-aware and will intelligently retry to gather missing
+ * information until all required fields can be populated.
+ */
+import { ChatOpenAI } from '@langchain/openai';
+import { config } from 'dotenv';
+import { z } from 'zod';
+import { MCPAgent, MCPClient } from '../index.js';
+// Load environment variables from .env file
+config();
+// Define the structured output schema using Zod
+const CityInfoSchema = z.object({
+    name: z.string().describe('Official name of the city'),
+    country: z.string().describe('Country where the city is located'),
+    region: z.string().describe('Region or state within the country'),
+    population: z.number().describe('Current population count'),
+    area_km2: z.number().describe('Area in square kilometers'),
+    foundation_date: z.string().describe('When the city was founded (approximate year or period)'),
+    mayor: z.string().describe('Current mayor or city leader'),
+    famous_landmarks: z.array(z.string()).describe('List of famous landmarks, monuments, or attractions'),
+    universities: z.array(z.string()).describe('List of major universities or educational institutions'),
+    economy_sectors: z.array(z.string()).describe('Main economic sectors or industries'),
+    sister_cities: z.array(z.string()).describe('Twin cities or sister cities partnerships'),
+    historical_significance: z.string().describe('Brief description of historical importance'),
+    climate_type: z.string().nullable().describe('Type of climate (e.g., Mediterranean, Continental)'),
+    elevation_meters: z.number().nullable().describe('Elevation above sea level in meters'),
+});
+async function main() {
+    const mcpConfig = {
+        mcpServers: {
+            playwright: {
+                command: 'npx',
+                args: ['@playwright/mcp@latest'],
+                env: {
+                    DISPLAY: ':1',
+                },
+            },
+        },
+    };
+    const client = new MCPClient(mcpConfig);
+    const llm = new ChatOpenAI({ model: 'gpt-4o' });
+    const agent = new MCPAgent({ llm, client, maxSteps: 50, memoryEnabled: true });
+    try {
+        // Use structured output with intelligent retry
+        // The agent will:
+        // 1. Know exactly what information it needs to collect
+        // 2. Attempt structured output at finish points
+        // 3. Continue execution if required information is missing
+        // 4. Only finish when all required fields can be populated
+        const result = await agent.run(`
+      Research comprehensive information about the city of Padova (also known as Padua) in Italy.
+      
+      Visit multiple reliable sources like Wikipedia, official city websites, tourism sites,
+      and university websites to gather detailed information including demographics, history,
+      governance, education, economy, landmarks, and international relationships.
+      `, 50, // maxSteps
+        true, // manageConnector
+        [], // externalHistory
+        CityInfoSchema);
+        // Now you have strongly-typed, validated data!
+        console.log(`Name: ${result.name}`);
+        console.log(`Country: ${result.country}`);
+        console.log(`Region: ${result.region}`);
+        console.log(`Population: ${result.population.toLocaleString()}`);
+        console.log(`Area: ${result.area_km2} km²`);
+        console.log(`Foundation: ${result.foundation_date}`);
+        console.log(`Mayor: ${result.mayor}`);
+        console.log(`Universities: ${result.universities.join(', ')}`);
+        console.log(`Economy: ${result.economy_sectors.join(', ')}`);
+        console.log(`Landmarks: ${result.famous_landmarks.join(', ')}`);
+        console.log(`Sister Cities: ${result.sister_cities.length > 0 ? result.sister_cities.join(', ') : 'None'}`);
+        console.log(`Historical Significance: ${result.historical_significance}`);
+        if (result.climate_type) {
+            console.log(`Climate: ${result.climate_type}`);
+        }
+        if (result.elevation_meters !== null) {
+            console.log(`Elevation: ${result.elevation_meters} meters`);
+        }
+    }
+    catch (error) {
+        console.error('Error:', error);
+    }
+    finally {
+        await agent.close();
+    }
+}
+// Handle unhandled promise rejections
+process.on('unhandledRejection', (reason, promise) => {
+    console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+    process.exit(1);
+});
+main().catch(console.error);

package/dist/src/agents/mcp_agent.d.ts

@@ -3,6 +3,7 @@ import type { BaseMessage } from '@langchain/core/messages';
 import type { StructuredToolInterface } from '@langchain/core/tools';
 import type { StreamEvent } from '@langchain/core/tracers/log_stream';
 import type { AgentStep } from 'langchain/agents';
+import type { z } from 'zod';
 import type { MCPClient } from '../client.js';
 import type { BaseConnector } from '../connectors/base.js';
 import { SystemMessage } from '@langchain/core/messages';
@@ -65,15 +66,28 @@ export declare class MCPAgent {
      * Runs the agent and returns a promise for the final result.
      */
     run(query: string, maxSteps?: number, manageConnector?: boolean, externalHistory?: BaseMessage[]): Promise<string>;
+    /**
+     * Runs the agent with structured output and returns a promise for the typed result.
+     */
+    run<T>(query: string, maxSteps?: number, manageConnector?: boolean, externalHistory?: BaseMessage[], outputSchema?: z.ZodSchema<T>): Promise<T>;
     /**
      * Runs the agent and yields intermediate steps as an async generator.
+     * If outputSchema is provided, returns structured output of type T.
      */
-    stream(query: string, maxSteps?: number, manageConnector?: boolean, externalHistory?: BaseMessage[]): AsyncGenerator<AgentStep, string, void>;
+    stream<T = string>(query: string, maxSteps?: number, manageConnector?: boolean, externalHistory?: BaseMessage[], outputSchema?: z.ZodSchema<T>): AsyncGenerator<AgentStep, string | T, void>;
     close(): Promise<void>;
     /**
      * Yields LangChain StreamEvent objects from the underlying streamEvents() method.
      * This provides token-level streaming and fine-grained event updates.
      */
     streamEvents(query: string, maxSteps?: number, manageConnector?: boolean, externalHistory?: BaseMessage[]): AsyncGenerator<StreamEvent, void, void>;
+    /**
+     * Attempt to create structured output from raw result with validation.
+     */
+    private _attemptStructuredOutput;
+    /**
+     * Enhance the query with schema information to make the agent aware of required fields.
+     */
+    private _enhanceQueryWithSchema;
 }
 //# sourceMappingURL=mcp_agent.d.ts.map

package/dist/src/agents/mcp_agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp_agent.d.ts","sourceRoot":"","sources":["../../../src/agents/mcp_agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mcp_agent.d.ts","sourceRoot":"","sources":["../../../src/agents/mcp_agent.ts"],"names":[],"mappings":"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"}

package/dist/src/agents/mcp_agent.js

@@ -211,23 +211,54 @@ export class MCPAgent {
             }
         }
     }
-    /**
-     * Runs the agent and returns a promise for the final result.
-     */
-    async run(query, maxSteps, manageConnector, externalHistory) {
-        const generator = this.stream(query, maxSteps, manageConnector, externalHistory);
+    async run(query, maxSteps, manageConnector, externalHistory, outputSchema) {
+        const generator = this.stream(query, maxSteps, manageConnector, externalHistory, outputSchema);
         return this._consumeAndReturn(generator);
     }
     /**
      * Runs the agent and yields intermediate steps as an async generator.
+     * If outputSchema is provided, returns structured output of type T.
      */
-    async *stream(query, maxSteps, manageConnector = true, externalHistory) {
+    async *stream(query, maxSteps, manageConnector = true, externalHistory, outputSchema) {
         let result = '';
         let initializedHere = false;
         const startTime = Date.now();
         const toolsUsedNames = [];
         let stepsTaken = 0;
         let success = false;
+        // Schema-aware setup for structured output
+        let structuredLlm = null;
+        let schemaDescription = '';
+        if (outputSchema) {
+            query = this._enhanceQueryWithSchema(query, outputSchema);
+            // Check if withStructuredOutput method exists
+            if ('withStructuredOutput' in this.llm && typeof this.llm.withStructuredOutput === 'function') {
+                structuredLlm = this.llm.withStructuredOutput(outputSchema);
+            }
+            else {
+                // Fallback: use the same LLM but we'll handle structure in our helper method
+                structuredLlm = this.llm;
+            }
+            // Get schema description for feedback
+            try {
+                const schemaType = outputSchema;
+                if (schemaType._def && schemaType._def.shape) {
+                    const fields = [];
+                    for (const [key, fieldSchema] of Object.entries(schemaType._def.shape)) {
+                        const field = fieldSchema;
+                        const isOptional = field.isOptional?.() ?? field._def?.typeName === 'ZodOptional';
+                        const isNullable = field.isNullable?.() ?? field._def?.typeName === 'ZodNullable';
+                        const description = field._def?.description || field.description || key;
+                        fields.push(`- ${key}: ${description} ${(isOptional || isNullable) ? '(optional)' : '(required)'}`);
+                    }
+                    schemaDescription = fields.join('\n');
+                }
+            }
+            catch (e) {
+                logger.warn(`Could not extract schema details: ${e}`);
+                schemaDescription = `Schema: ${outputSchema.constructor.name}`;
+            }
+        }
         try {
             if (manageConnector && !this._initialized) {
                 await this.initialize();
@@ -284,7 +315,46 @@ export class MCPAgent {
                     if (nextStepOutput.returnValues) {
                         logger.info(`✅ Agent finished at step ${stepNum + 1}`);
                         result = nextStepOutput.returnValues?.output ?? 'No output generated';
-                        break;
+                        // If structured output is requested, attempt to create it
+                        if (outputSchema && structuredLlm) {
+                            try {
+                                logger.info('🔧 Attempting structured output...');
+                                const structuredResult = await this._attemptStructuredOutput(result, structuredLlm, outputSchema, schemaDescription);
+                                // Add the final response to conversation history if memory is enabled
+                                if (this.memoryEnabled) {
+                                    this.addToHistory(new AIMessage(`Structured result: ${JSON.stringify(structuredResult)}`));
+                                }
+                                logger.info('✅ Structured output successful');
+                                success = true;
+                                return structuredResult;
+                            }
+                            catch (e) {
+                                logger.warn(`⚠️ Structured output failed: ${e}`);
+                                // Continue execution to gather missing information
+                                const missingInfoPrompt = `
+                The current result cannot be formatted into the required structure.
+                Error: ${String(e)}
+                
+                Current information: ${result}
+                
+                Please continue working to gather the missing information needed for:
+                ${schemaDescription}
+                
+                Focus on finding the specific missing details.
+                `;
+                                // Add this as feedback and continue the loop
+                                inputs.input = missingInfoPrompt;
+                                if (this.memoryEnabled) {
+                                    this.addToHistory(new HumanMessage(missingInfoPrompt));
+                                }
+                                logger.info('🔄 Continuing execution to gather missing information...');
+                                continue;
+                            }
+                        }
+                        else {
+                            // Regular execution without structured output
+                            break;
+                        }
                     }
                     const stepArray = nextStepOutput;
                     intermediateSteps.push(...stepArray);
@@ -333,11 +403,31 @@ export class MCPAgent {
                 logger.warn(`⚠️ Agent stopped after reaching max iterations (${steps})`);
                 result = `Agent stopped after reaching the maximum number of steps (${steps}).`;
             }
-            if (this.memoryEnabled) {
+            // If structured output was requested but not achieved, attempt one final time
+            if (outputSchema && structuredLlm && !success) {
+                try {
+                    logger.info('🔧 Final attempt at structured output...');
+                    const structuredResult = await this._attemptStructuredOutput(result, structuredLlm, outputSchema, schemaDescription);
+                    // Add the final response to conversation history if memory is enabled
+                    if (this.memoryEnabled) {
+                        this.addToHistory(new AIMessage(`Structured result: ${JSON.stringify(structuredResult)}`));
+                    }
+                    logger.info('✅ Final structured output successful');
+                    success = true;
+                    return structuredResult;
+                }
+                catch (e) {
+                    logger.error(`❌ Final structured output attempt failed: ${e}`);
+                    throw new Error(`Failed to generate structured output after ${steps} steps: ${e}`);
+                }
+            }
+            // Add the final response to conversation history if memory is enabled (regular case)
+            if (this.memoryEnabled && !outputSchema) {
                 this.addToHistory(new AIMessage(result));
             }
             logger.info('🎉 Agent execution complete');
             success = true;
+            // Return regular result
             return result;
         }
         catch (e) {
@@ -424,6 +514,7 @@ export class MCPAgent {
         let success = false;
         let eventCount = 0;
         let totalResponseLength = 0;
+        let finalResponse = '';
         try {
             // Initialize if needed
             if (manageConnector && !this._initialized) {
@@ -471,17 +562,21 @@ export class MCPAgent {
                     totalResponseLength += event.data.chunk.content.length;
                 }
                 yield event;
-                // Handle final message for history
+                // Capture final response from chain end event
                 if (event.event === 'on_chain_end' && event.data?.output) {
                     const output = event.data.output;
-                    if (typeof output === 'string' && this.memoryEnabled) {
-                        this.addToHistory(new AIMessage(output));
+                    if (typeof output === 'string') {
+                        finalResponse = output;
                     }
-                    else if (output?.output && typeof output.output === 'string' && this.memoryEnabled) {
-                        this.addToHistory(new AIMessage(output.output));
+                    else if (output?.output && typeof output.output === 'string') {
+                        finalResponse = output.output;
                     }
                 }
             }
+            // Add the final AI response to conversation history if memory is enabled
+            if (this.memoryEnabled && finalResponse) {
+                this.addToHistory(new AIMessage(finalResponse));
+            }
             logger.info(`🎉 StreamEvents complete - ${eventCount} events emitted`);
             success = true;
         }
@@ -532,4 +627,86 @@ export class MCPAgent {
             }
         }
     }
+    /**
+     * Attempt to create structured output from raw result with validation.
+     */
+    async _attemptStructuredOutput(rawResult, structuredLlm, outputSchema, schemaDescription) {
+        const formatPrompt = `
+    Please format the following information according to the specified schema.
+    Extract and structure the relevant information from the content below.
+    
+    Required schema fields:
+    ${schemaDescription}
+    
+    Content to format:
+    ${rawResult}
+    
+    Please provide the information in the requested structured format.
+    If any required information is missing, you must indicate this clearly.
+    `;
+        const structuredResult = await structuredLlm.invoke(formatPrompt);
+        // Validate that the result is complete (basic check)
+        try {
+            // Use Zod to validate the structured result
+            const validatedResult = outputSchema.parse(structuredResult);
+            // Additional validation for required fields
+            const schemaType = outputSchema;
+            if (schemaType._def && schemaType._def.shape) {
+                for (const [fieldName, fieldSchema] of Object.entries(schemaType._def.shape)) {
+                    const field = fieldSchema;
+                    const isOptional = field.isOptional?.() ?? field._def?.typeName === 'ZodOptional';
+                    const isNullable = field.isNullable?.() ?? field._def?.typeName === 'ZodNullable';
+                    if (!isOptional && !isNullable) {
+                        const value = validatedResult[fieldName];
+                        if (value === null || value === undefined
+                            || (typeof value === 'string' && !value.trim())
+                            || (Array.isArray(value) && value.length === 0)) {
+                            throw new Error(`Required field '${fieldName}' is missing or empty`);
+                        }
+                    }
+                }
+            }
+            return validatedResult;
+        }
+        catch (e) {
+            logger.debug(`Validation details: ${e}`);
+            throw e; // Re-raise to trigger retry logic
+        }
+    }
+    /**
+     * Enhance the query with schema information to make the agent aware of required fields.
+     */
+    _enhanceQueryWithSchema(query, outputSchema) {
+        const schemaFields = [];
+        try {
+            // Get field information from the schema
+            const schemaType = outputSchema;
+            if (schemaType._def && schemaType._def.shape) {
+                for (const [fieldName, fieldSchema] of Object.entries(schemaType._def.shape)) {
+                    const field = fieldSchema;
+                    const description = field._def?.description || field.description || fieldName;
+                    const isOptional = field.isOptional?.() ?? field._def?.typeName === 'ZodOptional';
+                    const isNullable = field.isNullable?.() ?? field._def?.typeName === 'ZodNullable';
+                    schemaFields.push(`- ${fieldName}: ${description} ${(isOptional || isNullable) ? '(optional)' : '(required)'}`);
+                }
+            }
+            const schemaDescription = schemaFields.join('\n');
+            // Enhance the query with schema awareness
+            const enhancedQuery = `
+      ${query}
+      
+      IMPORTANT: Your response must include sufficient information to populate the following structured output:
+      
+      ${schemaDescription}
+      
+      Make sure you gather ALL the required information during your task execution.
+      If any required information is missing, continue working to find it.
+      `;
+            return enhancedQuery;
+        }
+        catch (e) {
+            logger.warn(`Could not extract schema details: ${e}`);
+            return query;
+        }
+    }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-use",
   "type": "module",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "packageManager": "pnpm@10.6.1",
   "description": "A utility library for integrating Model Context Protocol (MCP) with LangChain, Zod, and related tools. Provides helpers for schema conversion, event streaming, and SDK usage.",
   "author": "Zane",
@@ -73,7 +73,8 @@
     "example:sandbox": "npm run build && node dist/examples/sandbox_everything.js",
     "example:oauth": "npm run build && node dist/examples/simple_oauth_example.js",
     "example:blender": "npm run build && node dist/examples/blender_use.js",
-    "example:add_server": "npm run build && node dist/examples/add_server_tool.js"
+    "example:add_server": "npm run build && node dist/examples/add_server_tool.js",
+    "example:structured": "npm run build && node dist/examples/structured_output.js"
   },
   "dependencies": {
     "@dmitryrechkin/json-schema-to-zod": "^1.0.1",