@toolplex/client 0.1.18 → 0.1.20

package/dist/mcp-server/index.js

@@ -9,6 +9,17 @@ const apiKey = process.env.TOOLPLEX_API_KEY;
 const clientMode = process.env.TOOLPLEX_CLIENT_MODE || "standard";
 const clientName = process.env.CLIENT_NAME || "unknown";
 const logLevel = process.env.LOG_LEVEL || "info";
+// Read bundled dependency paths from environment variables
+// These are provided by the host application (e.g., Electron desktop)
+const bundledDependencies = {
+    node: process.env.TOOLPLEX_NODE_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,
+};
 if (!apiKey) {
     process.exit(1);
 }
@@ -18,6 +29,7 @@ const config = {
     clientMode,
     clientName,
     logLevel,
+    bundledDependencies,
 };
 serve(config).catch(() => {
     process.exit(1);

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

@@ -6,6 +6,7 @@ import { PromptsCache } from "./promptsCache.js";
 import { ToolDefinitionsCache } from "./toolDefinitionsCache.js";
 import { ServersCache } from "./serversCache.js";
 import { PolicyEnforcer } from "./policy/policyEnforcer.js";
+import { BundledDependencies } from "../shared/mcpServerTypes.js";
 /**
  * In-memory global registry for the ToolPlex client.
  * Maintains singleton instances of core services and clients used throughout the application.
@@ -19,6 +20,7 @@ declare class Registry {
     private static _toolDefinitionsCache;
     private static _serversCache;
     private static _policyEnforcer;
+    private static _bundledDependencies;
     static init(clientContext: ClientContext): Promise<void>;
     static getClientContext(): ClientContext;
     static getToolplexApiService(): ToolplexApiService;
@@ -29,6 +31,21 @@ declare class Registry {
     static getToolDefinitionsCache(): ToolDefinitionsCache;
     static getServersCache(): ServersCache;
     static getPolicyEnforcer(): PolicyEnforcer;
+    /**
+     * Set bundled dependencies (paths to Node, Python, Git, etc.)
+     * provided by the host application (e.g., Electron desktop app).
+     */
+    static setBundledDependencies(deps: BundledDependencies): void;
+    /**
+     * Get bundled dependencies (paths to required executables).
+     * Returns a copy of the bundled dependencies object.
+     */
+    static getBundledDependencies(): BundledDependencies;
+    /**
+     * 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 reset(): void;
 }
 export default Registry;

package/dist/mcp-server/registry.js

@@ -80,6 +80,27 @@ class Registry {
         }
         return this._policyEnforcer;
     }
+    /**
+     * Set bundled dependencies (paths to Node, Python, Git, etc.)
+     * provided by the host application (e.g., Electron desktop app).
+     */
+    static setBundledDependencies(deps) {
+        this._bundledDependencies = deps;
+    }
+    /**
+     * Get bundled dependencies (paths to required executables).
+     * Returns a copy of the bundled dependencies object.
+     */
+    static getBundledDependencies() {
+        return { ...this._bundledDependencies };
+    }
+    /**
+     * Get the path for a specific bundled dependency by name.
+     * Returns undefined if the dependency is not available.
+     */
+    static getBundledDependencyPath(depName) {
+        return this._bundledDependencies[depName];
+    }
     static reset() {
         this._clientContext = null;
         this._toolplexApiService = null;
@@ -98,6 +119,7 @@ class Registry {
             this._serversCache = null;
         }
         this._policyEnforcer = null;
+        this._bundledDependencies = {};
     }
 }
 Registry._clientContext = null;
@@ -108,4 +130,5 @@ Registry._promptsCache = null;
 Registry._toolDefinitionsCache = null;
 Registry._serversCache = null;
 Registry._policyEnforcer = null;
+Registry._bundledDependencies = {};
 export default Registry;

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

@@ -45,6 +45,7 @@ export async function handleCallTool(params) {
             content.push({
                 type: "text",
                 text: promptsCache.getPrompt("tool_call_next_steps"),
+                _meta: { role: "system" },
             });
         }
         await logger.debug("Tool called successfully");

package/dist/mcp-server/toolHandlers/initHandler.d.ts

@@ -1,3 +1,12 @@
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { InitializeToolplexParams } from "../../shared/mcpServerTypes.js";
+/**
+ * Helper to resolve dependency path with fallback:
+ * 1. Bundled dependency (if available)
+ * 2. System PATH (fallback)
+ * 3. "not available" if neither exists
+ *
+ * Exported for testing purposes.
+ */
+export declare function resolveDependencyForInit(bundledPath: string | undefined, commandName: string): string;
 export declare function handleInitialize(params: InitializeToolplexParams): Promise<CallToolResult>;

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

@@ -3,7 +3,39 @@ import os from "os";
 import { initServerManagersOnly } from "../utils/initServerManagers.js";
 import Registry from "../registry.js";
 import envPaths from "env-paths";
+import which from "which";
+import { getEnhancedPath } from "../../shared/enhancedPath.js";
+import * as fs from "fs";
 const logger = FileLogger;
+/**
+ * Helper to resolve dependency path with fallback:
+ * 1. Bundled dependency (if available)
+ * 2. System PATH (fallback)
+ * 3. "not available" if neither exists
+ *
+ * Exported for testing purposes.
+ */
+export function resolveDependencyForInit(bundledPath, commandName) {
+    // Check bundled first
+    if (bundledPath && fs.existsSync(bundledPath)) {
+        return bundledPath;
+    }
+    // Fall back to system PATH
+    try {
+        const enhancedPath = getEnhancedPath();
+        const systemPath = which.sync(commandName, {
+            path: enhancedPath,
+            nothrow: true,
+        });
+        if (systemPath) {
+            return `${systemPath} (system)`;
+        }
+    }
+    catch {
+        // Ignore errors, will return "not available"
+    }
+    return "not available";
+}
 export async function handleInitialize(params) {
     const startTime = Date.now();
     await logger.info("Initializing ToolPlex");
@@ -23,6 +55,8 @@ export async function handleInitialize(params) {
             ? "Windows"
             : platform.charAt(0).toUpperCase() + platform.slice(1);
     const paths = envPaths("ToolPlex", { suffix: "" });
+    // Get bundled dependency information
+    const bundledDeps = Registry.getBundledDependencies();
     const systemInfo = {
         os: `${osName} ${os.release()}`,
         arch: os.arch(),
@@ -35,6 +69,14 @@ export async function handleInitialize(params) {
             month: "long",
             day: "numeric",
         }),
+        // Resolve dependency paths with bundled > system > not available priority
+        nodePath: resolveDependencyForInit(bundledDeps.node, "node"),
+        npxPath: resolveDependencyForInit(bundledDeps.npx, "npx"),
+        pythonPath: resolveDependencyForInit(bundledDeps.python, platform === "win32" ? "python" : "python3"),
+        pipPath: resolveDependencyForInit(bundledDeps.pip, platform === "win32" ? "pip" : "pip3"),
+        uvPath: resolveDependencyForInit(bundledDeps.uv, "uv"),
+        uvxPath: resolveDependencyForInit(bundledDeps.uvx, "uvx"),
+        gitPath: resolveDependencyForInit(bundledDeps.git, "git"),
     };
     await logger.debug("Initializing server managers and API service");
     const [serverManagerInitResults, toolplexApiInitResponse] = await Promise.all([
@@ -76,7 +118,14 @@ export async function handleInitialize(params) {
                     .replace("{ARGS.memory}", systemInfo.memory)
                     .replace("{ARGS.cpuCores}", systemInfo.cpuCores.toString())
                     .replace("{ARGS.workDir}", systemInfo.workDir)
-                    .replace("{ARGS.date}", systemInfo.date),
+                    .replace("{ARGS.date}", systemInfo.date)
+                    .replace("{ARGS.nodePath}", systemInfo.nodePath)
+                    .replace("{ARGS.npxPath}", systemInfo.npxPath)
+                    .replace("{ARGS.pythonPath}", systemInfo.pythonPath)
+                    .replace("{ARGS.pipPath}", systemInfo.pipPath)
+                    .replace("{ARGS.uvPath}", systemInfo.uvPath)
+                    .replace("{ARGS.uvxPath}", systemInfo.uvxPath)
+                    .replace("{ARGS.gitPath}", systemInfo.gitPath),
             },
         ],
     };

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

@@ -89,6 +89,7 @@ export async function handleLookupEntityTool(params) {
             content.push({
                 type: "text",
                 text: promptsCache.getPrompt("lookup_entity_install_guidance"),
+                _meta: { role: "system" },
             });
         }
         return {

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

@@ -121,10 +121,10 @@ export async function handleSearchTool(params) {
                 type: "text",
                 text: JSON.stringify(responseData),
             },
-            // Second: Followup instructions
             {
                 type: "text",
                 text: promptsCache.getPrompt("search_results_footer"),
+                _meta: { role: "system" },
             },
         ];
         await logger.info("Search completed successfully");

package/dist/mcp-server/toolplexServer.js

@@ -34,6 +34,11 @@ export async function serve(config) {
     clientContext.clientName = config.clientName;
     clientContext.clientVersion = clientVersion;
     await Registry.init(clientContext);
+    // Store bundled dependencies in Registry for use throughout the application
+    if (config.bundledDependencies) {
+        Registry.setBundledDependencies(config.bundledDependencies);
+        await logger.debug(`Bundled dependencies registered: ${JSON.stringify(config.bundledDependencies)}`);
+    }
     await logger.info(`Starting Toolplex server in ${config.dev ? "development" : "production"} mode`);
     const server = new Server({
         name: "toolplex-server",

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

@@ -1,4 +1,22 @@
 export declare 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.
+     *
+     * @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: string): string;
+    /**
+     * Validate that a command is available (either bundled or in system PATH).
+     * Throws an error if the command is not found.
+     */
     static validateCommandOrThrow(rawCommand: string): void;
     static extractCommandName(command: string): string;
 }

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

@@ -1,5 +1,7 @@
 import { getEnhancedPath } from "../../shared/enhancedPath.js";
 import which from "which";
+import Registry from "../registry.js";
+import * as fs from "fs";
 const INSTALL_HINTS = {
     uvx: "Install uvx: https://docs.astral.sh/uv/getting-started/installation/",
     uv: "Install uv: https://docs.astral.sh/uv/getting-started/installation/",
@@ -7,22 +9,84 @@ const INSTALL_HINTS = {
     python3: "Install Python: https://www.python.org/downloads/. Or check if you have `python` installed.",
     node: "Install 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",
+    "python",
+    "python3",
+    "git",
+    "npx",
+    "uvx",
+];
 export class RuntimeCheck {
-    static validateCommandOrThrow(rawCommand) {
-        const command = this.extractCommandName(rawCommand);
+    /**
+     * 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.
+     *
+     * @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) {
+        // Check if this is a known bundled dependency type
+        const isBundledDep = BUNDLED_DEPENDENCY_COMMANDS.includes(commandName);
+        if (isBundledDep) {
+            // Priority 1: Try bundled dependency first (preferred for ToolPlex Desktop)
+            const bundledPath = Registry.getBundledDependencyPath(commandName);
+            if (bundledPath && fs.existsSync(bundledPath)) {
+                return bundledPath;
+            }
+            // Handle python3 -> python mapping for bundled deps
+            if (commandName === "python3") {
+                const pythonPath = Registry.getBundledDependencyPath("python");
+                if (pythonPath && fs.existsSync(pythonPath)) {
+                    return pythonPath;
+                }
+            }
+            // Priority 2: Fall back to system PATH (for standalone @client usage)
+            const enhancedPath = getEnhancedPath();
+            const resolved = which.sync(commandName, {
+                path: enhancedPath,
+                nothrow: true,
+            });
+            if (resolved) {
+                return resolved;
+            }
+            // Priority 3: Neither bundled nor system available - 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` +
+                (hint ? `👉 ${hint}` : ""));
+        }
+        // For non-bundled dependencies, only check system PATH
         const enhancedPath = getEnhancedPath();
-        const resolved = which.sync(command, {
+        const resolved = which.sync(commandName, {
             path: enhancedPath,
             nothrow: true,
         });
         if (!resolved) {
-            const hint = INSTALL_HINTS[command];
+            const hint = INSTALL_HINTS[commandName];
             if (hint) {
-                throw new Error(`Missing required command: '${command}'.\n👉 ${hint}`);
+                throw new Error(`Missing required command: '${commandName}'.\n👉 ${hint}`);
             }
-            throw new Error(`Command '${command}' not found in enhanced PATH. Please install it manually or check your config.`);
+            throw new Error(`Command '${commandName}' not found in enhanced PATH. Please install it manually or check your config.`);
         }
+        return resolved;
+    }
+    /**
+     * Validate that a command is available (either bundled or in system PATH).
+     * Throws an error if the command is not found.
+     */
+    static validateCommandOrThrow(rawCommand) {
+        const command = this.extractCommandName(rawCommand);
+        this.resolveDependency(command);
     }
     static extractCommandName(command) {
         return command.trim().split(/\s+/)[0];

package/dist/server-manager/serverManager.js

@@ -3,7 +3,6 @@ import { StdioClientTransport, } from "@modelcontextprotocol/sdk/client/stdio.js
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import * as fs from "fs/promises";
 import * as path from "path";
-import which from "which";
 import { FileLogger } from "../shared/fileLogger.js";
 import envPaths from "env-paths";
 import { getEnhancedPath } from "../shared/enhancedPath.js";
@@ -204,15 +203,10 @@ 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");
+            const resolvedCommand = RuntimeCheck.resolveDependency(config.command);
             const enhancedPath = getEnhancedPath();
-            let resolvedCommand = which.sync(config.command, {
-                path: enhancedPath,
-                nothrow: true,
-            });
-            if (!resolvedCommand) {
-                // Fallback to supplied command
-                resolvedCommand = config.command;
-            }
             const serverParams = {
                 command: resolvedCommand,
                 args: config.args || [],

package/dist/shared/enhancedPath.js

@@ -1,5 +1,5 @@
 import * as path from "path";
-import { existsSync } from "fs";
+import * as fs from "fs";
 import { homedir } from "os";
 import { glob } from "glob";
 /**
@@ -18,14 +18,14 @@ export function getEnhancedPath() {
         if (extraPath.includes("*")) {
             const matches = glob.sync(extraPath);
             for (const match of matches) {
-                if (existsSync(match) && !seen.has(match)) {
+                if (fs.existsSync(match) && !seen.has(match)) {
                     seen.add(match);
                     allPaths.unshift(match);
                 }
             }
         }
         else {
-            if (existsSync(extraPath) && !seen.has(extraPath)) {
+            if (fs.existsSync(extraPath) && !seen.has(extraPath)) {
                 seen.add(extraPath);
                 allPaths.unshift(extraPath);
             }

package/dist/shared/mcpServerTypes.d.ts

@@ -1,12 +1,26 @@
 import { z } from "zod";
 export type ClientMode = "standard" | "restricted";
 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.
+ */
+export interface BundledDependencies {
+    node?: string;
+    npx?: string;
+    python?: string;
+    pip?: string;
+    uv?: string;
+    uvx?: string;
+    git?: string;
+}
 export interface ToolplexServerConfig {
     dev: boolean;
     apiKey: string;
     clientMode: ClientMode;
     clientName: string;
     logLevel: LogLevel;
+    bundledDependencies?: BundledDependencies;
 }
 export declare const TransportTypeSchema: z.ZodEnum<["stdio", "sse"]>;
 export type TransportType = z.infer<typeof TransportTypeSchema>;

package/dist/src/mcp-server/clientContext.js

@@ -0,0 +1,118 @@
+/**
+ * Maintains client context for the ToolPlex server
+ */
+export class ClientContext {
+    constructor() {
+        this._sessionId = null;
+        this._dev = null;
+        this._apiKey = null;
+        this._clientMode = null;
+        this._llmContext = null;
+        this._clientVersion = null;
+        this._permissions = null;
+        this._flags = null;
+        this._isOrgUser = null;
+        this._clientName = null;
+    }
+    get sessionId() {
+        if (!this._sessionId) {
+            throw new Error("Session ID not set - ToolPlex not initialized");
+        }
+        return this._sessionId;
+    }
+    set sessionId(id) {
+        this._sessionId = id;
+    }
+    get dev() {
+        if (this._dev === null) {
+            throw new Error("Dev mode not set - ToolPlex not initialized");
+        }
+        return this._dev;
+    }
+    set dev(isDev) {
+        this._dev = isDev;
+    }
+    get apiKey() {
+        if (!this._apiKey) {
+            throw new Error("API key not set - ToolPlex not initialized");
+        }
+        return this._apiKey;
+    }
+    set apiKey(key) {
+        this._apiKey = key;
+    }
+    get clientMode() {
+        if (!this._clientMode) {
+            throw new Error("Client mode not set - ToolPlex not initialized");
+        }
+        return this._clientMode;
+    }
+    set clientMode(mode) {
+        this._clientMode = mode;
+    }
+    get clientName() {
+        if (!this._clientName) {
+            throw new Error("Client name not set - ToolPlex not initialized");
+        }
+        return this._clientName;
+    }
+    set clientName(name) {
+        this._clientName = name;
+    }
+    get llmContext() {
+        if (!this._llmContext) {
+            throw new Error("LLM context not set - ToolPlex not initialized");
+        }
+        return this._llmContext;
+    }
+    set llmContext(context) {
+        this._llmContext = context;
+    }
+    get clientVersion() {
+        if (!this._clientVersion) {
+            throw new Error("Client version not set - ToolPlex not initialized");
+        }
+        return this._clientVersion;
+    }
+    set clientVersion(version) {
+        this._clientVersion = version;
+    }
+    get permissions() {
+        if (!this._permissions) {
+            throw new Error("Permissions not set - ToolPlex not initialized");
+        }
+        return this._permissions;
+    }
+    set permissions(perms) {
+        this._permissions = perms;
+    }
+    get flags() {
+        if (!this._flags) {
+            throw new Error("Consts not set - ToolPlex not initialized");
+        }
+        return this._flags;
+    }
+    set flags(consts) {
+        this._flags = consts;
+    }
+    get isOrgUser() {
+        if (this._isOrgUser === null) {
+            throw new Error("Organization user status not set - ToolPlex not initialized");
+        }
+        return this._isOrgUser;
+    }
+    set isOrgUser(isOrgUser) {
+        this._isOrgUser = isOrgUser;
+    }
+    isInitialized() {
+        return !!(this._sessionId &&
+            this._apiKey &&
+            this._clientMode &&
+            this._llmContext &&
+            this._clientVersion &&
+            this._permissions &&
+            this._flags &&
+            this._isOrgUser !== null &&
+            this._clientName);
+    }
+}

package/dist/src/mcp-server/logging/telemetryLogger.js

@@ -0,0 +1,54 @@
+import Registry from "../registry.js";
+import { FileLogger } from "../../shared/fileLogger.js";
+const logger = FileLogger;
+export class TelemetryLogger {
+    constructor() {
+        this.eventQueue = [];
+        this.flushTimeout = null;
+        this.BATCH_SIZE = 10;
+        this.FLUSH_INTERVAL = 30000;
+        this.scheduleFlush();
+    }
+    /**
+     * Log a telemetry event
+     */
+    async log(eventType, data) {
+        this.eventQueue.push({ eventType, data });
+        if (this.eventQueue.length >= this.BATCH_SIZE) {
+            await this.flush();
+        }
+    }
+    async flush() {
+        if (this.eventQueue.length === 0)
+            return;
+        try {
+            const apiService = Registry.getToolplexApiService();
+            const events = [...this.eventQueue];
+            this.eventQueue = [];
+            await logger.debug(`Flushing ${events.length} telemetry events`);
+            await apiService.logTelemetryEvents(events);
+        }
+        catch (err) {
+            await logger.error(`Error flushing telemetry events: ${err}`);
+            this.eventQueue.unshift(...this.eventQueue);
+        }
+    }
+    scheduleFlush() {
+        if (this.flushTimeout) {
+            clearTimeout(this.flushTimeout);
+        }
+        this.flushTimeout = setTimeout(async () => {
+            await this.flush();
+            this.scheduleFlush();
+        }, this.FLUSH_INTERVAL);
+    }
+    /**
+     * Clean up resources - should be called when shutting down
+     */
+    async dispose() {
+        if (this.flushTimeout) {
+            clearTimeout(this.flushTimeout);
+        }
+        await this.flush();
+    }
+}

package/dist/src/mcp-server/policy/callToolObserver.js

@@ -0,0 +1,27 @@
+class CallToolObserver {
+    constructor() {
+        this.serverToolCalls = new Map();
+    }
+    // Record a call to a tool on a server
+    recordCall(serverId, toolName) {
+        if (!this.serverToolCalls.has(serverId)) {
+            this.serverToolCalls.set(serverId, new Set());
+        }
+        this.serverToolCalls.get(serverId).add(toolName);
+    }
+    // Check if a server was called at all
+    wasServerCalled(serverId) {
+        return (this.serverToolCalls.has(serverId) &&
+            this.serverToolCalls.get(serverId).size > 0);
+    }
+    // Check if a specific tool was called on a server
+    wasToolCalled(serverId, toolName) {
+        return (this.serverToolCalls.has(serverId) &&
+            this.serverToolCalls.get(serverId).has(toolName));
+    }
+    // Optionally, clear all records (for testing or reset)
+    clear() {
+        this.serverToolCalls.clear();
+    }
+}
+export default CallToolObserver;