@toolplex/client 0.1.28 → 0.1.30

package/dist/mcp-server/index.js

@@ -13,6 +13,7 @@ const logLevel = process.env.LOG_LEVEL || "info";
 // These are provided by the host application (e.g., Electron desktop)
 const bundledDependencies = {
     node: process.env.TOOLPLEX_NODE_PATH,
+    npm: process.env.TOOLPLEX_NPM_PATH,
     npx: process.env.TOOLPLEX_NPX_PATH,
     python: process.env.TOOLPLEX_PYTHON_PATH,
     pip: process.env.TOOLPLEX_PIP_PATH,

package/dist/mcp-server/registry.d.ts

@@ -46,7 +46,7 @@ declare class Registry {
      * Get the path for a specific bundled dependency by name.
      * Returns undefined if the dependency is not available.
      */
-    static getBundledDependencyPath(depName: "node" | "python" | "git" | "uvx" | "npx"): string | undefined;
+    static getBundledDependencyPath(depName: "node" | "npm" | "python" | "git" | "uvx" | "npx"): string | undefined;
     /**
      * Set the server configuration (includes session resume history).
      */

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

@@ -20,7 +20,7 @@ export async function handleLookupEntityTool(params) {
         if (params.entity_type === "server") {
             policyEnforcer.enforceUseServerPolicy(params.entity_id);
         }
-        const lookupResponse = await apiService.lookupEntity(params.entity_type, params.entity_id);
+        const lookupResponse = await apiService.lookupEntity(params.entity_type, params.entity_id, params.include_readme);
         // Annotate installed server using resultAnnotators
         if (params.entity_type === "server" &&
             lookupResponse &&

package/dist/mcp-server/toolplexApi/service.d.ts

@@ -20,7 +20,7 @@ export declare class ToolplexApiService {
         eventType: LogTelemetryRequest["event_type"];
         data: Partial<Omit<LogTelemetryRequest, "event_type">>;
     }>): Promise<LogTelemetryBatchResponse>;
-    lookupEntity(entityType: "server" | "playbook" | "feedback", entityId: string): Promise<any>;
+    lookupEntity(entityType: "server" | "playbook" | "feedback", entityId: string, includeReadme?: boolean): Promise<any>;
     search(query: string, expandedKeywords?: string[], filter?: string, size?: number, scope?: string): Promise<SearchResponse>;
     createPlaybook(playbook_name: string, description: string, actions: Array<PlaybookAction>, domain?: string, keywords?: string[], requirements?: string[], privacy?: "public" | "private", sourcePlaybookId?: string, forkReason?: string): Promise<CreatePlaybookResponse>;
     logPlaybookUsage(playbookId: string, success: boolean, errorMessage?: string): Promise<LogPlaybookUsageResponse>;

package/dist/mcp-server/toolplexApi/service.js

@@ -93,7 +93,7 @@ export class ToolplexApiService {
             return { success: false };
         }
     }
-    async lookupEntity(entityType, entityId) {
+    async lookupEntity(entityType, entityId, includeReadme) {
         try {
             const response = await fetch(`${this.baseUrl}/lookup-entity`, {
                 method: "POST",
@@ -101,6 +101,7 @@ export class ToolplexApiService {
                 body: JSON.stringify({
                     entity_type: entityType,
                     entity_id: entityId,
+                    include_readme: includeReadme,
                 }),
             });
             return this.handleFetchResponse(response);

package/dist/mcp-server/toolplexServer.js

@@ -52,9 +52,42 @@ export async function serve(config) {
         },
     });
     // Initialize server manager clients
+    // Use bundled node if available, otherwise fall back to system "node"
+    // Pass bundled dependency paths so the server-manager can initialize its Registry
     await logger.info("Initializing server manager clients");
+    const nodeCommand = config.bundledDependencies?.node || "node";
     const serverManagerClients = {
-        node: new StdioServerManagerClient("node", [path.join(__dirname, "..", "server-manager", "index.js")], { LOG_LEVEL: config.logLevel }),
+        node: new StdioServerManagerClient(nodeCommand, [path.join(__dirname, "..", "server-manager", "index.js")], {
+            LOG_LEVEL: config.logLevel,
+            // Pass the current PATH which includes bundled bin directories
+            PATH: process.env.PATH,
+            // Pass all bundled dependency paths to server-manager
+            // These are critical for proper command resolution (e.g., npx -> node + npx-cli.js)
+            ...(config.bundledDependencies?.node && {
+                TOOLPLEX_NODE_PATH: config.bundledDependencies.node,
+            }),
+            ...(config.bundledDependencies?.npm && {
+                TOOLPLEX_NPM_PATH: config.bundledDependencies.npm,
+            }),
+            ...(config.bundledDependencies?.npx && {
+                TOOLPLEX_NPX_PATH: config.bundledDependencies.npx,
+            }),
+            ...(config.bundledDependencies?.python && {
+                TOOLPLEX_PYTHON_PATH: config.bundledDependencies.python,
+            }),
+            ...(config.bundledDependencies?.pip && {
+                TOOLPLEX_PIP_PATH: config.bundledDependencies.pip,
+            }),
+            ...(config.bundledDependencies?.uv && {
+                TOOLPLEX_UV_PATH: config.bundledDependencies.uv,
+            }),
+            ...(config.bundledDependencies?.uvx && {
+                TOOLPLEX_UVX_PATH: config.bundledDependencies.uvx,
+            }),
+            ...(config.bundledDependencies?.git && {
+                TOOLPLEX_GIT_PATH: config.bundledDependencies.git,
+            }),
+        }),
     };
     // Start all server manager clients
     await logger.info("Starting server manager clients");

package/dist/mcp-server/utils/runtimeCheck.d.ts

@@ -1,12 +1,30 @@
+/**
+ * Result of resolving a command, which may need to be invoked via node
+ * if it's a .js script (e.g., bundled npm/npx on Unix).
+ */
+export interface ResolvedCommand {
+    command: string;
+    prependArgs: string[];
+}
 export declare class RuntimeCheck {
+    /**
+     * Resolve a dependency and return both the command and any prepended args needed.
+     * This handles the case where bundled npm/npx on Unix are .js scripts that
+     * need to be invoked via node.
+     *
+     * @param commandName - The command to resolve (e.g., "npx", "node", "uvx")
+     * @returns ResolvedCommand with command and prependArgs
+     * @throws Error if the command is not available
+     */
+    static resolveCommandWithArgs(commandName: string): ResolvedCommand;
     /**
      * Resolve a dependency path with priority order:
      * 1. Bundled dependencies (if provided by host application like ToolPlex Desktop)
      * 2. System PATH (fallback for standalone @client usage)
      * 3. Error if neither available
      *
-     * This allows ToolPlex Desktop to provide reliable bundled dependencies while
-     * still supporting standalone users who have system dependencies installed.
+     * NOTE: This returns just the path. For npm/npx which may be .js files on Unix,
+     * use resolveCommandWithArgs() instead to get the proper invocation.
      *
      * @param commandName - The command to resolve
      * @returns The full path to the command executable

package/dist/mcp-server/utils/runtimeCheck.js

@@ -8,12 +8,14 @@ const INSTALL_HINTS = {
     python: "Install Python: https://www.python.org/downloads/. Or check if you have `python3` installed.",
     python3: "Install Python: https://www.python.org/downloads/. Or check if you have `python` installed.",
     node: "Install Node.js: https://nodejs.org/en/download/",
+    npm: "Install npm (comes with Node.js): https://nodejs.org/en/download/",
     npx: "Install npx (comes with Node.js): https://nodejs.org/en/download/",
     git: "Install Git: https://git-scm.com/downloads",
 };
 // Commands that should use bundled dependencies (required)
 const BUNDLED_DEPENDENCY_COMMANDS = [
     "node",
+    "npm",
     "python",
     "python3",
     "git",
@@ -22,44 +24,54 @@ const BUNDLED_DEPENDENCY_COMMANDS = [
 ];
 export class RuntimeCheck {
     /**
-     * Resolve a dependency path with priority order:
-     * 1. Bundled dependencies (if provided by host application like ToolPlex Desktop)
-     * 2. System PATH (fallback for standalone @client usage)
-     * 3. Error if neither available
-     *
-     * This allows ToolPlex Desktop to provide reliable bundled dependencies while
-     * still supporting standalone users who have system dependencies installed.
+     * Resolve a dependency and return both the command and any prepended args needed.
+     * This handles the case where bundled npm/npx on Unix are .js scripts that
+     * need to be invoked via node.
      *
-     * @param commandName - The command to resolve
-     * @returns The full path to the command executable
-     * @throws Error if the command is not available in bundled deps or system PATH
+     * @param commandName - The command to resolve (e.g., "npx", "node", "uvx")
+     * @returns ResolvedCommand with command and prependArgs
+     * @throws Error if the command is not available
      */
-    static resolveDependency(commandName) {
-        // Check if this is a known bundled dependency type
+    static resolveCommandWithArgs(commandName) {
         const isBundledDep = BUNDLED_DEPENDENCY_COMMANDS.includes(commandName);
         if (isBundledDep) {
-            // Priority 1: Try bundled dependency first (preferred for ToolPlex Desktop)
+            // Priority 1: Try bundled dependency first
             const bundledPath = Registry.getBundledDependencyPath(commandName);
             if (bundledPath && fs.existsSync(bundledPath)) {
-                return bundledPath;
+                // Check if this is a .js file that needs to be invoked via node
+                if (bundledPath.endsWith(".js")) {
+                    const nodePath = Registry.getBundledDependencyPath("node");
+                    if (nodePath && fs.existsSync(nodePath)) {
+                        return {
+                            command: nodePath,
+                            prependArgs: [bundledPath],
+                        };
+                    }
+                    // Fallback to system node if bundled node not available
+                    return {
+                        command: "node",
+                        prependArgs: [bundledPath],
+                    };
+                }
+                return { command: bundledPath, prependArgs: [] };
             }
-            // Handle python3 -> python mapping for bundled deps
+            // Handle python3 -> python mapping
             if (commandName === "python3") {
                 const pythonPath = Registry.getBundledDependencyPath("python");
                 if (pythonPath && fs.existsSync(pythonPath)) {
-                    return pythonPath;
+                    return { command: pythonPath, prependArgs: [] };
                 }
             }
-            // Priority 2: Fall back to system PATH (for standalone @client usage)
+            // Priority 2: Fall back to system PATH
             const enhancedPath = getEnhancedPath();
             const resolved = which.sync(commandName, {
                 path: enhancedPath,
                 nothrow: true,
             });
             if (resolved) {
-                return resolved;
+                return { command: resolved, prependArgs: [] };
             }
-            // Priority 3: Neither bundled nor system available - error
+            // Priority 3: Error
             const hint = INSTALL_HINTS[commandName];
             throw new Error(`Missing required command: '${commandName}'.\n` +
                 `This command is not available in bundled dependencies or system PATH.\n` +
@@ -78,7 +90,28 @@ export class RuntimeCheck {
             }
             throw new Error(`Command '${commandName}' not found in enhanced PATH. Please install it manually or check your config.`);
         }
-        return resolved;
+        return { command: resolved, prependArgs: [] };
+    }
+    /**
+     * Resolve a dependency path with priority order:
+     * 1. Bundled dependencies (if provided by host application like ToolPlex Desktop)
+     * 2. System PATH (fallback for standalone @client usage)
+     * 3. Error if neither available
+     *
+     * NOTE: This returns just the path. For npm/npx which may be .js files on Unix,
+     * use resolveCommandWithArgs() instead to get the proper invocation.
+     *
+     * @param commandName - The command to resolve
+     * @returns The full path to the command executable
+     * @throws Error if the command is not available in bundled deps or system PATH
+     */
+    static resolveDependency(commandName) {
+        const resolved = this.resolveCommandWithArgs(commandName);
+        // If there are prepend args, the first one is the actual script path
+        if (resolved.prependArgs.length > 0) {
+            return resolved.prependArgs[0];
+        }
+        return resolved.command;
     }
     /**
      * Validate that a command is available (either bundled or in system PATH).

package/dist/server-manager/index.js

@@ -1,6 +1,34 @@
 import { ServerManagerProtocol } from "./stdioServer.js";
 import { FileLogger } from "../shared/fileLogger.js";
+import Registry from "../mcp-server/registry.js";
 FileLogger.initialize("server-manager");
+// Initialize bundled dependencies from environment variables.
+// These are passed from the MCP server process which received them from Electron.
+// This is critical for proper command resolution (e.g., npx -> node + npx-cli.js).
+//
+// NOTE: We do NOT call Registry.init() here because that does heavy initialization
+// (API services, caches, etc.) that the server-manager doesn't need. We only need
+// the bundled dependency paths for command resolution.
+function initializeBundledDeps() {
+    const bundledDependencies = {
+        node: process.env.TOOLPLEX_NODE_PATH,
+        npm: process.env.TOOLPLEX_NPM_PATH,
+        npx: process.env.TOOLPLEX_NPX_PATH,
+        python: process.env.TOOLPLEX_PYTHON_PATH,
+        pip: process.env.TOOLPLEX_PIP_PATH,
+        uv: process.env.TOOLPLEX_UV_PATH,
+        uvx: process.env.TOOLPLEX_UVX_PATH,
+        git: process.env.TOOLPLEX_GIT_PATH,
+    };
+    // Only set if we have at least one bundled dep
+    const hasAnyBundledDep = Object.values(bundledDependencies).some(Boolean);
+    if (hasAnyBundledDep) {
+        Registry.setBundledDependencies(bundledDependencies);
+        FileLogger.debug(`Server-manager initialized with bundled deps: ${JSON.stringify(bundledDependencies)}`);
+    }
+}
+// Initialize bundled deps and start
+initializeBundledDeps();
 const protocol = new ServerManagerProtocol();
 protocol.start().catch((error) => {
     console.error("Failed to start server:", error);

package/dist/server-manager/serverManager.js

@@ -242,18 +242,35 @@ export class ServerManager {
         else if (config.transport === "stdio") {
             if (!config.command)
                 throw new Error("Command is required for stdio transport");
-            // Use RuntimeCheck to resolve the command, which prioritizes bundled dependencies
-            const { RuntimeCheck } = await import("../mcp-server/utils/runtimeCheck.js");
-            // Extract command name first (handles paths with spaces correctly)
-            const commandName = RuntimeCheck.extractCommandName(config.command);
-            const resolvedCommand = RuntimeCheck.resolveDependency(commandName);
-            const enhancedPath = getEnhancedPath();
+            // Use the inherited PATH from the parent process (MCP server -> Electron).
+            // This PATH already includes bundled bin directories prepended, so commands
+            // like "npx", "uvx", "git" will resolve to bundled versions first.
+            // We use process.env.PATH directly instead of rebuilding with getEnhancedPath()
+            // to preserve the bundled directories that were set up by Electron.
+            const inheritedPath = process.env.PATH || getEnhancedPath();
+            // For the command itself, resolve it properly handling the case where
+            // bundled npm/npx on Unix are .js scripts that need to be invoked via node.
+            let resolvedCommand = config.command;
+            let prependArgs = [];
+            if (!config.command.startsWith("/") &&
+                !/^[A-Za-z]:[\\/]/.test(config.command)) {
+                // It's a relative command name (like "npx"), resolve via RuntimeCheck
+                const { RuntimeCheck } = await import("../mcp-server/utils/runtimeCheck.js");
+                const commandName = RuntimeCheck.extractCommandName(config.command);
+                const resolved = RuntimeCheck.resolveCommandWithArgs(commandName);
+                resolvedCommand = resolved.command;
+                prependArgs = resolved.prependArgs;
+            }
+            // Combine prependArgs with config.args
+            // e.g., if npx is a .js file: command="node", prependArgs=["/path/to/npx-cli.js"]
+            // then args become ["/path/to/npx-cli.js", "-y", "@wonderwhy-er/desktop-commander"]
+            const finalArgs = [...prependArgs, ...(config.args || [])];
             const serverParams = {
                 command: resolvedCommand,
-                args: config.args || [],
+                args: finalArgs,
                 env: {
                     ...process.env,
-                    PATH: enhancedPath,
+                    PATH: inheritedPath,
                     ...(config.env || {}),
                 },
                 stderr: "pipe",

package/dist/shared/mcpServerTypes.d.ts

@@ -4,9 +4,14 @@ export type LogLevel = "error" | "warn" | "info" | "debug";
 /**
  * Paths to bundled dependencies provided by the host application (e.g., Electron).
  * These dependencies are required for MCP server installations and execution.
+ *
+ * NOTE: On Unix systems, npm/npx paths point to the actual CLI .js files
+ * (e.g., lib/node_modules/npm/bin/npx-cli.js) because electron-builder dereferences
+ * symlinks during packaging. These must be invoked via `node <script>`.
  */
 export interface BundledDependencies {
     node?: string;
+    npm?: string;
     npx?: string;
     python?: string;
     pip?: string;
@@ -140,12 +145,15 @@ export type SearchParams = z.infer<typeof SearchParamsSchema>;
 export declare const LookupEntityParamsSchema: z.ZodObject<{
     entity_type: z.ZodEnum<["server", "playbook", "feedback"]>;
     entity_id: z.ZodString;
+    include_readme: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     entity_type: "server" | "playbook" | "feedback";
     entity_id: string;
+    include_readme?: boolean | undefined;
 }, {
     entity_type: "server" | "playbook" | "feedback";
     entity_id: string;
+    include_readme?: boolean | undefined;
 }>;
 export type LookupEntityParams = z.infer<typeof LookupEntityParamsSchema>;
 export declare const InstallParamsSchema: z.ZodObject<{

package/dist/shared/mcpServerTypes.js

@@ -51,6 +51,7 @@ export const SearchParamsSchema = z.object({
 export const LookupEntityParamsSchema = z.object({
     entity_type: z.enum(["server", "playbook", "feedback"]),
     entity_id: z.string(),
+    include_readme: z.boolean().optional(),
 });
 // --------------------
 // InstallParams

package/dist/src/mcp-server/toolplexApi/service.js

@@ -93,7 +93,7 @@ export class ToolplexApiService {
             return { success: false };
         }
     }
-    async lookupEntity(entityType, entityId) {
+    async lookupEntity(entityType, entityId, includeReadme) {
         try {
             const response = await fetch(`${this.baseUrl}/lookup-entity`, {
                 method: "POST",
@@ -101,6 +101,7 @@ export class ToolplexApiService {
                 body: JSON.stringify({
                     entity_type: entityType,
                     entity_id: entityId,
+                    include_readme: includeReadme,
                 }),
             });
             return this.handleFetchResponse(response);

package/dist/src/mcp-server/utils/runtimeCheck.js

@@ -8,12 +8,14 @@ const INSTALL_HINTS = {
     python: "Install Python: https://www.python.org/downloads/. Or check if you have `python3` installed.",
     python3: "Install Python: https://www.python.org/downloads/. Or check if you have `python` installed.",
     node: "Install Node.js: https://nodejs.org/en/download/",
+    npm: "Install npm (comes with Node.js): https://nodejs.org/en/download/",
     npx: "Install npx (comes with Node.js): https://nodejs.org/en/download/",
     git: "Install Git: https://git-scm.com/downloads",
 };
 // Commands that should use bundled dependencies (required)
 const BUNDLED_DEPENDENCY_COMMANDS = [
     "node",
+    "npm",
     "python",
     "python3",
     "git",
@@ -22,44 +24,54 @@ const BUNDLED_DEPENDENCY_COMMANDS = [
 ];
 export class RuntimeCheck {
     /**
-     * Resolve a dependency path with priority order:
-     * 1. Bundled dependencies (if provided by host application like ToolPlex Desktop)
-     * 2. System PATH (fallback for standalone @client usage)
-     * 3. Error if neither available
-     *
-     * This allows ToolPlex Desktop to provide reliable bundled dependencies while
-     * still supporting standalone users who have system dependencies installed.
+     * Resolve a dependency and return both the command and any prepended args needed.
+     * This handles the case where bundled npm/npx on Unix are .js scripts that
+     * need to be invoked via node.
      *
-     * @param commandName - The command to resolve
-     * @returns The full path to the command executable
-     * @throws Error if the command is not available in bundled deps or system PATH
+     * @param commandName - The command to resolve (e.g., "npx", "node", "uvx")
+     * @returns ResolvedCommand with command and prependArgs
+     * @throws Error if the command is not available
      */
-    static resolveDependency(commandName) {
-        // Check if this is a known bundled dependency type
+    static resolveCommandWithArgs(commandName) {
         const isBundledDep = BUNDLED_DEPENDENCY_COMMANDS.includes(commandName);
         if (isBundledDep) {
-            // Priority 1: Try bundled dependency first (preferred for ToolPlex Desktop)
+            // Priority 1: Try bundled dependency first
             const bundledPath = Registry.getBundledDependencyPath(commandName);
             if (bundledPath && fs.existsSync(bundledPath)) {
-                return bundledPath;
+                // Check if this is a .js file that needs to be invoked via node
+                if (bundledPath.endsWith(".js")) {
+                    const nodePath = Registry.getBundledDependencyPath("node");
+                    if (nodePath && fs.existsSync(nodePath)) {
+                        return {
+                            command: nodePath,
+                            prependArgs: [bundledPath],
+                        };
+                    }
+                    // Fallback to system node if bundled node not available
+                    return {
+                        command: "node",
+                        prependArgs: [bundledPath],
+                    };
+                }
+                return { command: bundledPath, prependArgs: [] };
             }
-            // Handle python3 -> python mapping for bundled deps
+            // Handle python3 -> python mapping
             if (commandName === "python3") {
                 const pythonPath = Registry.getBundledDependencyPath("python");
                 if (pythonPath && fs.existsSync(pythonPath)) {
-                    return pythonPath;
+                    return { command: pythonPath, prependArgs: [] };
                 }
             }
-            // Priority 2: Fall back to system PATH (for standalone @client usage)
+            // Priority 2: Fall back to system PATH
             const enhancedPath = getEnhancedPath();
             const resolved = which.sync(commandName, {
                 path: enhancedPath,
                 nothrow: true,
             });
             if (resolved) {
-                return resolved;
+                return { command: resolved, prependArgs: [] };
             }
-            // Priority 3: Neither bundled nor system available - error
+            // Priority 3: Error
             const hint = INSTALL_HINTS[commandName];
             throw new Error(`Missing required command: '${commandName}'.\n` +
                 `This command is not available in bundled dependencies or system PATH.\n` +
@@ -78,7 +90,28 @@ export class RuntimeCheck {
             }
             throw new Error(`Command '${commandName}' not found in enhanced PATH. Please install it manually or check your config.`);
         }
-        return resolved;
+        return { command: resolved, prependArgs: [] };
+    }
+    /**
+     * Resolve a dependency path with priority order:
+     * 1. Bundled dependencies (if provided by host application like ToolPlex Desktop)
+     * 2. System PATH (fallback for standalone @client usage)
+     * 3. Error if neither available
+     *
+     * NOTE: This returns just the path. For npm/npx which may be .js files on Unix,
+     * use resolveCommandWithArgs() instead to get the proper invocation.
+     *
+     * @param commandName - The command to resolve
+     * @returns The full path to the command executable
+     * @throws Error if the command is not available in bundled deps or system PATH
+     */
+    static resolveDependency(commandName) {
+        const resolved = this.resolveCommandWithArgs(commandName);
+        // If there are prepend args, the first one is the actual script path
+        if (resolved.prependArgs.length > 0) {
+            return resolved.prependArgs[0];
+        }
+        return resolved.command;
     }
     /**
      * Validate that a command is available (either bundled or in system PATH).

package/dist/src/shared/mcpServerTypes.js

@@ -51,6 +51,7 @@ export const SearchParamsSchema = z.object({
 export const LookupEntityParamsSchema = z.object({
     entity_type: z.enum(["server", "playbook", "feedback"]),
     entity_id: z.string(),
+    include_readme: z.boolean().optional(),
 });
 // --------------------
 // InstallParams

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "0.1.28";
+export declare const version = "0.1.30";

package/dist/version.js

@@ -1 +1 @@
-export const version = '0.1.28';
+export const version = '0.1.30';

package/package.json

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