@toolplex/client 0.1.18 → 0.1.19

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

@@ -0,0 +1,35 @@
+class InstallObserver {
+    constructor() {
+        this.serverInstallActions = new Map();
+    }
+    // Record an install action on a server
+    recordInstall(serverId) {
+        this.recordAction(serverId, "install");
+    }
+    // Record an uninstall action on a server
+    recordUninstall(serverId) {
+        this.recordAction(serverId, "uninstall");
+    }
+    // Check if a server has been installed
+    wasServerInstalled(serverId) {
+        return (this.serverInstallActions.has(serverId) &&
+            this.serverInstallActions.get(serverId).has("install"));
+    }
+    // Check if a server has been uninstalled
+    wasServerUninstalled(serverId) {
+        return (this.serverInstallActions.has(serverId) &&
+            this.serverInstallActions.get(serverId).has("uninstall"));
+    }
+    // Optionally, clear all records (for testing or reset)
+    clear() {
+        this.serverInstallActions.clear();
+    }
+    // Private method to record an action
+    recordAction(serverId, action) {
+        if (!this.serverInstallActions.has(serverId)) {
+            this.serverInstallActions.set(serverId, new Set());
+        }
+        this.serverInstallActions.get(serverId).add(action);
+    }
+}
+export default InstallObserver;

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

@@ -0,0 +1,81 @@
+import Registry from "../registry.js";
+export class PlaybookPolicy {
+    constructor(clientContext, callToolObserver) {
+        this.callToolObserver = callToolObserver;
+        this.clientContext = clientContext;
+        this.blockedMcpServersSet = new Set(clientContext.flags.blocked_mcp_servers || []);
+    }
+    /**
+     * Validates a playbook before saving by checking that:
+     * - Referenced servers and tools have been used
+     * - No blocked servers are referenced
+     * - Private playbooks are only created when enabled
+     *
+     * For each action with a 'call' property, verifies that:
+     * - Any referenced server has been connected to
+     * - Any referenced server/tool combination has been executed
+     * - The server is not in the blocked servers list
+     *
+     * @throws Error if a referenced server or tool has not been used in the current session,
+     * if a blocked server is referenced, or if trying to create a private playbook when disabled
+     */
+    enforceSavePlaybookPolicy(playbook) {
+        if (!Array.isArray(playbook.actions)) {
+            throw new Error("Playbook actions must be an array");
+        }
+        for (const [idx, action] of playbook.actions.entries()) {
+            if (!action.call)
+                continue;
+            // Parse the call string
+            // Supported formats:
+            // - "mcp_server_id:<server_id>::<tool_name>"
+            // - "mcp_server_id:<server_id>"
+            // - "playbook_id:<playbook_id>"
+            const call = action.call.trim();
+            if (call.startsWith("mcp_server_id:")) {
+                // Could be with or without tool_name
+                // e.g. mcp_server_id:abc123::toolX or mcp_server_id:abc123
+                const match = call.match(/^mcp_server_id:([^:]+)(?:::([^:]+))?$/);
+                if (!match) {
+                    throw new Error(`Invalid call format in action ${idx + 1}: "${call}"`);
+                }
+                const serverId = match[1];
+                const toolName = match[2];
+                // Check if server is blocked
+                if (this.blockedMcpServersSet.has(serverId)) {
+                    throw new Error(`Playbook action ${idx + 1} references blocked server "${serverId}"`);
+                }
+                if (toolName) {
+                    // Must have called this tool on this server
+                    if (!this.callToolObserver.wasToolCalled(serverId, toolName)) {
+                        throw new Error(`Playbook action ${idx + 1} references tool "${toolName}" on server "${serverId}" which has not been used in this session.`);
+                    }
+                }
+                else {
+                    // Only server referenced, must have called any tool on this server
+                    if (!this.callToolObserver.wasServerCalled(serverId)) {
+                        throw new Error(`Playbook action ${idx + 1} references server "${serverId}" which has not been used in this session.`);
+                    }
+                }
+            }
+            else if (call.startsWith("playbook_id:")) {
+                // For playbook references, we could skip or add logic if needed
+                // For now, we do not validate playbook_id usage
+                continue;
+            }
+            else {
+                throw new Error(`Playbook action ${idx + 1} has an unrecognized call format: "${call}"`);
+            }
+        }
+    }
+    /**
+     * Validates if playbook usage logging is allowed based on read-only mode
+     * @throws Error if read-only mode is enabled
+     */
+    enforceLogPlaybookUsagePolicy() {
+        if (this.clientContext.permissions.enable_read_only_mode) {
+            const promptsCache = Registry.getPromptsCache();
+            throw new Error(promptsCache.getPrompt("log_playbook_usage_disabled"));
+        }
+    }
+}

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

@@ -0,0 +1,105 @@
+import { PlaybookPolicy } from "./playbookPolicy.js";
+import { FeedbackPolicy } from "./feedbackPolicy.js";
+import CallToolObserver from "./callToolObserver.js";
+import InstallObserver from "./installObserver.js";
+import { ServerPolicy } from "./serverPolicy.js";
+export class PolicyEnforcer {
+    constructor() {
+        this.playbookPolicy = null;
+        this.feedbackPolicy = null;
+        this.serverPolicy = null;
+        this.callToolObserver = null;
+        this.installObserver = null;
+    }
+    /**
+     * Initialize the policy enforcer with the client context
+     */
+    init(clientContext) {
+        this.callToolObserver = new CallToolObserver();
+        this.installObserver = new InstallObserver();
+        this.playbookPolicy = new PlaybookPolicy(clientContext, this.callToolObserver);
+        this.feedbackPolicy = new FeedbackPolicy(clientContext, this.callToolObserver, this.installObserver);
+        this.serverPolicy = new ServerPolicy(clientContext);
+    }
+    /**
+     * Enforce playbook policy validation before saving.
+     * Throws if the playbook does not pass policy.
+     */
+    enforceSavePlaybookPolicy(playbook) {
+        if (!this.playbookPolicy) {
+            throw new Error("PolicyEnforcer not initialized");
+        }
+        this.playbookPolicy.enforceSavePlaybookPolicy(playbook);
+    }
+    /**
+     * Enforce feedback policy validation.
+     * Throws if the feedback does not pass policy.
+     */
+    enforceFeedbackPolicy(feedback) {
+        if (!this.feedbackPolicy) {
+            throw new Error("PolicyEnforcer not initialized");
+        }
+        this.feedbackPolicy.enforceFeedbackPolicy(feedback);
+    }
+    /**
+     * Enforce server call tool policy validation.
+     * Throws if attempting to call a tool on a blocked server.
+     */
+    enforceCallToolPolicy(serverId) {
+        if (!this.serverPolicy) {
+            throw new Error("PolicyEnforcer not initialized");
+        }
+        this.serverPolicy.enforceCallToolPolicy(serverId);
+    }
+    /**
+     * Enforce server config policy validation.
+     * Throws if attempting to use a blocked or disallowed server.
+     */
+    enforceUseServerPolicy(serverId) {
+        if (!this.serverPolicy) {
+            throw new Error("PolicyEnforcer not initialized");
+        }
+        this.serverPolicy.enforceUseServerPolicy(serverId);
+    }
+    /**
+     * Enforce playbook usage logging policy validation.
+     * Throws if read-only mode is enabled.
+     */
+    enforceLogPlaybookUsagePolicy() {
+        if (!this.playbookPolicy) {
+            throw new Error("PolicyEnforcer not initialized");
+        }
+        this.playbookPolicy.enforceLogPlaybookUsagePolicy();
+    }
+    /**
+     * Filters out blocked servers from a list of objects.
+     *
+     * @param servers List of objects containing server IDs
+     * @param getServerId Function that extracts the server ID from an object
+     * @returns Filtered list with blocked servers removed
+     */
+    filterBlockedMcpServers(servers, getServerId) {
+        if (!this.serverPolicy) {
+            throw new Error("PolicyEnforcer not initialized");
+        }
+        return this.serverPolicy.filterBlockedMcpServers(servers, getServerId);
+    }
+    /**
+     * Get a reference to the CallToolObserver instance.
+     */
+    getCallToolObserver() {
+        if (!this.callToolObserver) {
+            throw new Error("PolicyEnforcer not initialized");
+        }
+        return this.callToolObserver;
+    }
+    /**
+     * Get a reference to the InstallObserver instance.
+     */
+    getInstallObserver() {
+        if (!this.installObserver) {
+            throw new Error("PolicyEnforcer not initialized");
+        }
+        return this.installObserver;
+    }
+}

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

@@ -0,0 +1,63 @@
+export class ServerPolicy {
+    constructor(clientContext) {
+        this.clientContext = clientContext;
+        this.blockedMcpServersSet = new Set(clientContext.flags.blocked_mcp_servers || []);
+    }
+    /**
+     * Validates that a server is not blocked.
+     *
+     * @throws Error if attempting to use a blocked server
+     */
+    enforceBlockedServerPolicy(serverId) {
+        if (this.blockedMcpServersSet.has(serverId)) {
+            throw new Error(`Cannot use blocked server "${serverId}. Questions? Contact support@toolplex.ai"`);
+        }
+    }
+    /**
+     * Validates that a server is allowed.
+     *
+     * @throws Error if attempting to use a server not in the allowed list
+     */
+    enforceAllowedServerPolicy(serverId) {
+        const allowedServers = this.clientContext.permissions.allowed_mcp_servers;
+        if (allowedServers &&
+            allowedServers.length > 0 &&
+            !allowedServers.includes(serverId)) {
+            throw new Error(`Server "${serverId}" is not allowed for your account. Please adjust the Allowed MCP Servers permissions on the ToolPlex Dashboard if this is a mistake.`);
+        }
+    }
+    /**
+     * Validates that a server is not blocked before calling a tool on it.
+     * Also checks if desktop commander is enabled when calling tools on the desktop commander server.
+     *
+     * @throws Error if attempting to call a tool on a blocked server or if desktop commander is disabled
+     */
+    enforceCallToolPolicy(serverId) {
+        this.enforceBlockedServerPolicy(serverId);
+        this.enforceAllowedServerPolicy(serverId);
+        // Check if desktop commander is disabled and this is the desktop commander server
+        if (!this.clientContext.permissions.use_desktop_commander &&
+            serverId === this.clientContext.flags.desktop_commander_server_id) {
+            throw new Error("Desktop Commander is disabled for your account");
+        }
+    }
+    /**
+     * Validates that a server can be used.
+     *
+     * @throws Error if attempting to use a blocked or disallowed server
+     */
+    enforceUseServerPolicy(serverId) {
+        this.enforceBlockedServerPolicy(serverId);
+        this.enforceAllowedServerPolicy(serverId);
+    }
+    /**
+     * Filters out blocked servers from a list of objects.
+     *
+     * @param servers List of objects containing server IDs
+     * @param getServerId Function that extracts the server ID from an object
+     * @returns Filtered list with blocked servers removed
+     */
+    filterBlockedMcpServers(servers, getServerId) {
+        return servers.filter((server) => !this.blockedMcpServersSet.has(getServerId(server)));
+    }
+}

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

@@ -0,0 +1,51 @@
+export class PromptsCache {
+    constructor() {
+        this._prompts = null;
+        this._version = null;
+        this._prompts = null;
+        this._version = null;
+    }
+    /**
+     * Initialize prompts cache with prompts from init response
+     */
+    init(prompts) {
+        // Allow re-init.
+        this._prompts = prompts;
+        this._version = prompts._version;
+    }
+    /**
+     * Get a specific prompt by key from the cache
+     */
+    getPrompt(key) {
+        if (!this._prompts) {
+            throw new Error("PromptsCache not initialized");
+        }
+        const prompt = this._prompts[key];
+        if (!prompt) {
+            throw new Error(`Prompt "${key}" not found in cache`);
+        }
+        return prompt;
+    }
+    /**
+     * Get the version of the current prompts
+     */
+    getVersion() {
+        if (!this._version) {
+            throw new Error("PromptsCache not initialized");
+        }
+        return this._version;
+    }
+    /**
+     * Check if the cache is initialized
+     */
+    isInitialized() {
+        return this._prompts !== null;
+    }
+    /**
+     * Reset the cache
+     */
+    reset() {
+        this._prompts = null;
+        this._version = null;
+    }
+}

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

@@ -0,0 +1,134 @@
+import { ToolplexApiService } from "./toolplexApi/service.js";
+import { TelemetryLogger } from "./logging/telemetryLogger.js";
+import { PromptsCache } from "./promptsCache.js";
+import { ToolDefinitionsCache } from "./toolDefinitionsCache.js";
+import { ServersCache } from "./serversCache.js";
+import { PolicyEnforcer } from "./policy/policyEnforcer.js";
+/**
+ * In-memory global registry for the ToolPlex client.
+ * Maintains singleton instances of core services and clients used throughout the application.
+ */
+class Registry {
+    static async init(clientContext) {
+        if (this._clientContext ||
+            this._toolplexApiService ||
+            this._serverManagerClients) {
+            throw new Error("Registry already initialized");
+        }
+        this._clientContext = clientContext;
+        this._toolplexApiService = new ToolplexApiService(clientContext);
+        this._serverManagerClients = {};
+        this._telemetryLogger = new TelemetryLogger();
+        this._promptsCache = new PromptsCache();
+        this._toolDefinitionsCache = new ToolDefinitionsCache();
+        this._serversCache = new ServersCache();
+        this._policyEnforcer = new PolicyEnforcer();
+        // Tool definitions must be initialized early to use tools like initialize_toolplex.
+        await this._toolDefinitionsCache.init(this._toolplexApiService, clientContext);
+    }
+    static getClientContext() {
+        if (!this._clientContext) {
+            throw new Error("ClientContext not initialized in Registry");
+        }
+        return this._clientContext;
+    }
+    static getToolplexApiService() {
+        if (!this._toolplexApiService) {
+            throw new Error("ToolplexApiService not initialized in Registry");
+        }
+        return this._toolplexApiService;
+    }
+    static getServerManagerClients() {
+        if (!this._serverManagerClients) {
+            throw new Error("ServerManagerClients not initialized in Registry");
+        }
+        return this._serverManagerClients;
+    }
+    static setServerManagerClients(clients) {
+        if (!this._serverManagerClients) {
+            throw new Error("Registry not initialized");
+        }
+        this._serverManagerClients = clients;
+    }
+    static getTelemetryLogger() {
+        if (!this._telemetryLogger) {
+            throw new Error("TelemetryLogger not initialized in Registry");
+        }
+        return this._telemetryLogger;
+    }
+    static getPromptsCache() {
+        if (!this._promptsCache) {
+            throw new Error("PromptsCache not initialized in Registry");
+        }
+        return this._promptsCache;
+    }
+    static getToolDefinitionsCache() {
+        if (!this._toolDefinitionsCache) {
+            throw new Error("ToolDefinitionsCache not initialized in Registry");
+        }
+        return this._toolDefinitionsCache;
+    }
+    static getServersCache() {
+        if (!this._serversCache) {
+            throw new Error("ServersCache not initialized in Registry");
+        }
+        return this._serversCache;
+    }
+    static getPolicyEnforcer() {
+        if (!this._policyEnforcer) {
+            throw new Error("PolicyEnforcer not initialized in 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;
+        this._serverManagerClients = null;
+        this._telemetryLogger = null;
+        if (this._promptsCache) {
+            this._promptsCache.reset();
+            this._promptsCache = null;
+        }
+        if (this._toolDefinitionsCache) {
+            this._toolDefinitionsCache.reset();
+            this._toolDefinitionsCache = null;
+        }
+        if (this._serversCache) {
+            this._serversCache.reset();
+            this._serversCache = null;
+        }
+        this._policyEnforcer = null;
+        this._bundledDependencies = {};
+    }
+}
+Registry._clientContext = null;
+Registry._toolplexApiService = null;
+Registry._serverManagerClients = null;
+Registry._telemetryLogger = null;
+Registry._promptsCache = null;
+Registry._toolDefinitionsCache = null;
+Registry._serversCache = null;
+Registry._policyEnforcer = null;
+Registry._bundledDependencies = {};
+export default Registry;

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

@@ -0,0 +1,100 @@
+import { ListServersResultSchema } from "../shared/serverManagerTypes.js";
+import { FileLogger } from "../shared/fileLogger.js";
+const logger = FileLogger;
+/**
+ * An in-memory cache that tracks currently installed servers.
+ * Maintains a set of server IDs for quick lookup of installed servers.
+ * Can be refreshed by querying server manager clients for their current server lists.
+ */
+export class ServersCache {
+    constructor() {
+        this._serverIds = null;
+        this._serverIds = null;
+    }
+    /**
+     * Initialize the cache with a list of servers, e.g. from initialize() succeeded list.
+     * Only tracks server IDs.
+     */
+    init(servers) {
+        this._serverIds = new Set(servers.map((s) => s.server_id));
+    }
+    /**
+     * Update the cache with a new list of servers, e.g. after calling listServersHandler.
+     * This does not imply initialization, but is meant to refresh the cache with the latest list.
+     * Only tracks server IDs.
+     */
+    updateServers(servers) {
+        this._serverIds = new Set(servers.map((s) => s.server_id));
+    }
+    /**
+     * Returns true if the server is installed (present in the cache).
+     * Throws an error if the cache is not initialized.
+     */
+    isInstalled(serverId) {
+        if (!this.isInitialized()) {
+            throw new Error("ServersCache not initialized");
+        }
+        if (!serverId) {
+            throw new Error(`Invalid serverId: "${serverId}"`);
+        }
+        return this._serverIds.has(serverId);
+    }
+    /**
+     * Get all cached server IDs.
+     */
+    getServerIds() {
+        if (!this._serverIds) {
+            throw new Error("ServersCache not initialized");
+        }
+        return Array.from(this._serverIds);
+    }
+    /**
+     * Refresh the cache by calling list_servers on all server manager clients.
+     * This follows the pattern in handleListServers (listServersHandler.ts):
+     * - Use sendRequest('list_servers', {}) on each client.
+     * - Validate/parse the response with ListServersResultSchema.
+     * - Collect all servers from all runtimes.
+     * @param serverManagerClients - Record of server manager clients (e.g. from Registry)
+     */
+    async refreshCache(serverManagerClients) {
+        const allServerIds = new Set();
+        for (const [runtime, client] of Object.entries(serverManagerClients)) {
+            try {
+                const response_data = await client.sendRequest("list_servers", {});
+                if (response_data.error) {
+                    await logger.warn(`Error from server manager client "${runtime}": ${response_data.error}`);
+                    continue;
+                }
+                const parsed = ListServersResultSchema.safeParse(response_data);
+                if (!parsed.success) {
+                    await logger.warn(`Failed to parse list_servers response from "${runtime}": ${JSON.stringify(response_data)}`);
+                    continue;
+                }
+                if (parsed.data.servers && parsed.data.servers.length > 0) {
+                    for (const server of parsed.data.servers) {
+                        if (server && typeof server.server_id === "string") {
+                            allServerIds.add(server.server_id);
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                await logger.warn(`Exception while refreshing cache from server manager client "${runtime}": ${err instanceof Error ? err.message : String(err)}`);
+                // Continue to next client
+            }
+        }
+        this._serverIds = allServerIds;
+    }
+    /**
+     * Check if the cache is initialized
+     */
+    isInitialized() {
+        return this._serverIds !== null;
+    }
+    /**
+     * Reset the cache
+     */
+    reset() {
+        this._serverIds = null;
+    }
+}

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

@@ -0,0 +1,67 @@
+export class ToolDefinitionsCache {
+    constructor() {
+        this._tools = null;
+        this._version = null;
+        this._tools = null;
+        this._version = null;
+    }
+    /**
+     * Initialize tools cache by fetching tools from API
+     * Handles errors if fetching fails, but does not rethrow.
+     */
+    async init(service, _clientContext) {
+        try {
+            const toolsResponse = await service.getTools();
+            this._tools = toolsResponse.tools;
+            this._version = toolsResponse._version;
+        }
+        catch {
+            this._tools = null;
+            this._version = null;
+        }
+    }
+    /**
+     * Get all cached tool definitions
+     */
+    getTools() {
+        if (!this._tools) {
+            throw new Error("ToolDefinitionsCache not initialized");
+        }
+        return this._tools;
+    }
+    /**
+     * Get a specific tool by name from the cache
+     */
+    getTool(name) {
+        if (!this._tools) {
+            throw new Error("ToolDefinitionsCache not initialized");
+        }
+        const tool = this._tools.find((t) => t.name === name);
+        if (!tool) {
+            throw new Error(`Tool "${name}" not found in cache`);
+        }
+        return tool;
+    }
+    /**
+     * Get the version of the current tools
+     */
+    getVersion() {
+        if (!this._version) {
+            throw new Error("ToolDefinitionsCache not initialized");
+        }
+        return this._version;
+    }
+    /**
+     * Check if the cache is initialized
+     */
+    isInitialized() {
+        return this._tools !== null;
+    }
+    /**
+     * Reset the cache
+     */
+    reset() {
+        this._tools = null;
+        this._version = null;
+    }
+}