@toolplex/client 0.1.24 → 0.1.26

package/dist/mcp-server/toolHandlers/installServerHandler.js

@@ -117,8 +117,24 @@ export async function handleInstallServer(params) {
         }
         // Validate server ID format
         validateServerIdOrThrow(server_id);
-        // Validate command is installed before proceeding
-        if (config.command) {
+        // Validate stdio transport configuration early to avoid timeouts
+        if (config.transport === "stdio") {
+            // Validate that command is provided
+            if (!config.command) {
+                throw new Error("Command is required for stdio transport");
+            }
+            // Validate command is installed
+            await RuntimeCheck.validateCommandOrThrow(config.command);
+            // Check that args is provided and not empty for package managers
+            // Package managers like npx, uvx, pnpm dlx, etc. require a package name as first arg
+            const command = config.command.toLowerCase();
+            const requiresPackageName = ["npx", "uvx", "pnpm", "yarn"].some((pm) => command.includes(pm));
+            if (requiresPackageName && (!config.args || config.args.length === 0)) {
+                throw new Error(`Package manager command '${config.command}' requires args to specify package name. Received args: ${config.args ? "[]" : "undefined"}`);
+            }
+        }
+        else if (config.command) {
+            // For non-stdio transports, still validate command if provided
             await RuntimeCheck.validateCommandOrThrow(config.command);
         }
         // Check if server is disallowed using policy enforcer

package/dist/mcp-server/toolHandlers/savePlaybookHandler.js

@@ -3,7 +3,8 @@ import Registry from "../registry.js";
 const logger = FileLogger;
 export async function handleSavePlaybook(params) {
     const startTime = Date.now();
-    await logger.info("Handling save playbook request");
+    const isValidationOnly = params.validate_only === true;
+    await logger.info(`Handling save playbook request${isValidationOnly ? " (validation only)" : ""}`);
     await logger.debug(`Playbook params: ${JSON.stringify(params)}`);
     const apiService = Registry.getToolplexApiService();
     const telemetryLogger = Registry.getTelemetryLogger();
@@ -19,19 +20,34 @@ export async function handleSavePlaybook(params) {
         if (clientContext.permissions.enable_read_only_mode) {
             throw new Error("Saving playbooks is disabled in read-only mode");
         }
-        // Enforce playbook policy before saving
+        // Enforce playbook policy before saving (runs in both validation and actual save)
         policyEnforcer.enforceSavePlaybookPolicy(params);
+        // If validation-only mode, return success without saving or logging telemetry
+        if (isValidationOnly) {
+            await logger.info("Playbook validation passed");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ validation: "passed" }),
+                    },
+                ],
+            };
+        }
         const { playbook_name, description, actions, domain, keywords, requirements, privacy, source_playbook_id, fork_reason, } = params;
         const response = await apiService.createPlaybook(playbook_name, description, actions, domain, keywords, requirements, privacy, source_playbook_id, fork_reason);
         await logger.info(`Playbook created successfully with ID: ${response.id}`);
-        await telemetryLogger.log("client_save_playbook", {
-            success: true,
-            log_context: {
-                playbook_id: response.id,
-                source_playbook_id: source_playbook_id,
-            },
-            latency_ms: Date.now() - startTime,
-        });
+        // Only log telemetry for actual saves (not validation-only calls)
+        if (!isValidationOnly) {
+            await telemetryLogger.log("client_save_playbook", {
+                success: true,
+                log_context: {
+                    playbook_id: response.id,
+                    source_playbook_id: source_playbook_id,
+                },
+                latency_ms: Date.now() - startTime,
+            });
+        }
         return {
             content: [
                 {
@@ -45,12 +61,15 @@ export async function handleSavePlaybook(params) {
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
-        await logger.error(`Failed to create playbook: ${errorMessage}`);
-        await telemetryLogger.log("client_save_playbook", {
-            success: false,
-            pii_sanitized_error_message: errorMessage,
-            latency_ms: Date.now() - startTime,
-        });
+        await logger.error(`Failed to ${isValidationOnly ? "validate" : "create"} playbook: ${errorMessage}`);
+        // Only log telemetry for actual saves (not validation-only calls)
+        if (!isValidationOnly) {
+            await telemetryLogger.log("client_save_playbook", {
+                success: false,
+                pii_sanitized_error_message: errorMessage,
+                latency_ms: Date.now() - startTime,
+            });
+        }
         return {
             isError: true,
             content: [

package/dist/server-manager/serverManager.d.ts

@@ -12,12 +12,17 @@ export declare class ServerManager {
     private config;
     private installationPromises;
     private configLock;
+    private static readonly MAX_STDERR_LINES;
     constructor();
     private loadConfig;
     private saveConfig;
     initialize(): Promise<InitializeResult>;
     getServerName(serverId: string): Promise<string>;
-    connectWithHandshakeTimeout(client: Client, transport: SSEClientTransport | StdioClientTransport, ms?: number): Promise<{
+    /**
+     * Helper to attach stderr listener as soon as transport starts
+     */
+    private attachStderrListener;
+    connectWithHandshakeTimeout(client: Client, transport: SSEClientTransport | StdioClientTransport, ms?: number, stderrBuffer?: string[], serverId?: string): Promise<{
         tools?: Tool[];
     }>;
     install(serverId: string, serverName: string, description: string, config: ServerConfig): Promise<void>;

package/dist/server-manager/serverManager.js

@@ -136,13 +136,51 @@ export class ServerManager {
         await logger.debug(`Getting name for server ${serverId}`);
         return this.serverNames.get(serverId) || serverId;
     }
-    async connectWithHandshakeTimeout(client, transport, ms = 60000) {
+    /**
+     * Helper to attach stderr listener as soon as transport starts
+     */
+    async attachStderrListener(transport, serverId, stderrBuffer, maxLines) {
+        // Poll for stderr availability (it becomes available after transport.start())
+        const maxAttempts = 100; // 1 second total
+        const pollInterval = 10; // 10ms between checks
+        for (let i = 0; i < maxAttempts; i++) {
+            if (transport.stderr) {
+                transport.stderr.on("data", (chunk) => {
+                    const lines = chunk
+                        .toString()
+                        .split("\n")
+                        .filter((l) => l.trim());
+                    stderrBuffer.push(...lines);
+                    // Keep only the last maxLines to prevent memory issues
+                    if (stderrBuffer.length > maxLines) {
+                        stderrBuffer.splice(0, stderrBuffer.length - maxLines);
+                    }
+                    // Also log stderr in real-time for debugging
+                    lines.forEach((line) => {
+                        logger.debug(`[${serverId} stderr] ${line}`);
+                    });
+                });
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        }
+        // If stderr never became available, that's okay (might be SSE transport)
+    }
+    async connectWithHandshakeTimeout(client, transport, ms = 60000, stderrBuffer, serverId) {
         let connectTimeout;
         let listToolsTimeout;
         try {
+            // Start stderr monitoring in parallel for stdio transports
+            const stderrMonitoring = transport instanceof StdioClientTransport && stderrBuffer && serverId
+                ? this.attachStderrListener(transport, serverId, stderrBuffer, ServerManager.MAX_STDERR_LINES)
+                : Promise.resolve();
             // Race connect() with timeout
             await Promise.race([
-                client.connect(transport),
+                (async () => {
+                    await client.connect(transport);
+                    // Ensure stderr listener is attached after connection starts
+                    await stderrMonitoring;
+                })(),
                 new Promise((_, reject) => {
                     connectTimeout = setTimeout(() => reject(new Error(`connect() timed out in ${ms} ms`)), ms);
                 }),
@@ -195,6 +233,7 @@ export class ServerManager {
             await this.removeServer(serverId);
         }
         let transport;
+        const stderrBuffer = [];
         if (config.transport === "sse") {
             if (!config.url)
                 throw new Error("URL is required for SSE transport");
@@ -226,7 +265,7 @@ export class ServerManager {
         }
         const client = new Client({ name: serverId, version: "1.0.0" }, { capabilities: { prompts: {}, resources: {}, tools: {} } });
         try {
-            const toolsResponse = await this.connectWithHandshakeTimeout(client, transport, 60000);
+            const toolsResponse = await this.connectWithHandshakeTimeout(client, transport, 60000, stderrBuffer, serverId);
             const tools = toolsResponse.tools || [];
             this.sessions.set(serverId, client);
             this.tools.set(serverId, tools);
@@ -258,7 +297,18 @@ export class ServerManager {
                     await logger.warn(`Failed to close transport during cleanup: ${closeErr}`);
                 }
             }
-            throw err;
+            // Enhance error message with stderr output if available
+            const baseError = err instanceof Error ? err.message : String(err);
+            let enhancedError = baseError;
+            if (stderrBuffer.length > 0) {
+                const stderrPreview = stderrBuffer.join("\n");
+                enhancedError = `${baseError}\n\nServer stderr output:\n${stderrPreview}`;
+                await logger.error(`Installation failed for ${serverId}. Error: ${baseError}. Stderr: ${stderrPreview}`);
+            }
+            else {
+                await logger.error(`Installation failed for ${serverId}: ${baseError}`);
+            }
+            throw new Error(enhancedError);
         }
     }
     async callTool(serverId, toolName, 
@@ -411,3 +461,5 @@ export class ServerManager {
         this.installationPromises.clear();
     }
 }
+// Maximum number of stderr lines to capture during installation
+ServerManager.MAX_STDERR_LINES = 50;

package/dist/shared/mcpServerTypes.d.ts

@@ -316,6 +316,7 @@ export declare const SavePlaybookParamsSchema: z.ZodObject<{
     privacy: z.ZodOptional<z.ZodEnum<["public", "private"]>>;
     source_playbook_id: z.ZodOptional<z.ZodString>;
     fork_reason: z.ZodOptional<z.ZodString>;
+    validate_only: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     description: string;
     playbook_name: string;
@@ -333,6 +334,7 @@ export declare const SavePlaybookParamsSchema: z.ZodObject<{
     privacy?: "public" | "private" | undefined;
     source_playbook_id?: string | undefined;
     fork_reason?: string | undefined;
+    validate_only?: boolean | undefined;
 }, {
     description: string;
     playbook_name: string;
@@ -350,6 +352,7 @@ export declare const SavePlaybookParamsSchema: z.ZodObject<{
     privacy?: "public" | "private" | undefined;
     source_playbook_id?: string | undefined;
     fork_reason?: string | undefined;
+    validate_only?: boolean | undefined;
 }>;
 export type SavePlaybookParams = z.infer<typeof SavePlaybookParamsSchema>;
 export declare const LogPlaybookUsageParamsSchema: z.ZodObject<{

package/dist/shared/mcpServerTypes.js

@@ -126,6 +126,9 @@ export const SavePlaybookParamsSchema = z.object({
     privacy: z.enum(["public", "private"]).optional(),
     source_playbook_id: z.string().optional(),
     fork_reason: z.string().optional(),
+    // Internal parameter for validation-only mode (not exposed to agent in tool definition)
+    // Use coerce to handle both boolean and string "true"/"false" from different LLM clients
+    validate_only: z.coerce.boolean().optional(),
 });
 // --------------------
 // LogPlaybookUsageParams

package/dist/src/shared/mcpServerTypes.js

@@ -126,6 +126,9 @@ export const SavePlaybookParamsSchema = z.object({
     privacy: z.enum(["public", "private"]).optional(),
     source_playbook_id: z.string().optional(),
     fork_reason: z.string().optional(),
+    // Internal parameter for validation-only mode (not exposed to agent in tool definition)
+    // Use coerce to handle both boolean and string "true"/"false" from different LLM clients
+    validate_only: z.coerce.boolean().optional(),
 });
 // --------------------
 // LogPlaybookUsageParams

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "0.1.24";
+export declare const version = "0.1.26";

package/dist/version.js

@@ -1 +1 @@
-export const version = '0.1.24';
+export const version = '0.1.26';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolplex/client",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "author": "ToolPlex LLC",
   "license": "SEE LICENSE IN LICENSE",
   "description": "The official ToolPlex client for AI agent tool discovery and execution",