@toolplex/client 0.1.1

package/dist/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/mcp-server/policy/policyEnforcer.d.ts

@@ -0,0 +1,57 @@
+import { ClientContext } from '../clientContext.js';
+import CallToolObserver from './callToolObserver.js';
+import InstallObserver from './installObserver.js';
+import { SavePlaybookParams, SubmitFeedbackParams } from '../../shared/mcpServerTypes.js';
+export declare class PolicyEnforcer {
+    private playbookPolicy;
+    private feedbackPolicy;
+    private serverPolicy;
+    private callToolObserver;
+    private installObserver;
+    constructor();
+    /**
+     * Initialize the policy enforcer with the client context
+     */
+    init(clientContext: ClientContext): void;
+    /**
+     * Enforce playbook policy validation before saving.
+     * Throws if the playbook does not pass policy.
+     */
+    enforceSavePlaybookPolicy(playbook: SavePlaybookParams): void;
+    /**
+     * Enforce feedback policy validation.
+     * Throws if the feedback does not pass policy.
+     */
+    enforceFeedbackPolicy(feedback: SubmitFeedbackParams): void;
+    /**
+     * Enforce server call tool policy validation.
+     * Throws if attempting to call a tool on a blocked server.
+     */
+    enforceCallToolPolicy(serverId: string): void;
+    /**
+     * Enforce server config policy validation.
+     * Throws if attempting to use a blocked or disallowed server.
+     */
+    enforceUseServerPolicy(serverId: string): void;
+    /**
+     * Enforce playbook usage logging policy validation.
+     * Throws if read-only mode is enabled.
+     */
+    enforceLogPlaybookUsagePolicy(): void;
+    /**
+     * 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<T>(servers: T[], getServerId: (item: T) => string): T[];
+    /**
+     * Get a reference to the CallToolObserver instance.
+     */
+    getCallToolObserver(): CallToolObserver;
+    /**
+     * Get a reference to the InstallObserver instance.
+     */
+    getInstallObserver(): InstallObserver;
+}

package/dist/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/mcp-server/policy/serverPolicy.d.ts

@@ -0,0 +1,39 @@
+import { ClientContext } from '../clientContext.js';
+export declare class ServerPolicy {
+    private clientContext;
+    private blockedMcpServersSet;
+    constructor(clientContext: ClientContext);
+    /**
+     * Validates that a server is not blocked.
+     *
+     * @throws Error if attempting to use a blocked server
+     */
+    enforceBlockedServerPolicy(serverId: string): void;
+    /**
+     * Validates that a server is allowed.
+     *
+     * @throws Error if attempting to use a server not in the allowed list
+     */
+    enforceAllowedServerPolicy(serverId: string): void;
+    /**
+     * 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: string): void;
+    /**
+     * Validates that a server can be used.
+     *
+     * @throws Error if attempting to use a blocked or disallowed server
+     */
+    enforceUseServerPolicy(serverId: string): void;
+    /**
+     * 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<T>(servers: T[], getServerId: (item: T) => string): T[];
+}

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

@@ -0,0 +1,61 @@
+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/mcp-server/promptsCache.d.ts

@@ -0,0 +1,25 @@
+export declare class PromptsCache {
+    private _prompts;
+    private _version;
+    constructor();
+    /**
+     * Initialize prompts cache with prompts from init response
+     */
+    init(prompts: Record<string, string>): void;
+    /**
+     * Get a specific prompt by key from the cache
+     */
+    getPrompt(key: string): string;
+    /**
+     * Get the version of the current prompts
+     */
+    getVersion(): string;
+    /**
+     * Check if the cache is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Reset the cache
+     */
+    reset(): void;
+}

package/dist/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/mcp-server/registry.d.ts

@@ -0,0 +1,34 @@
+import { ClientContext } from './clientContext.js';
+import { ToolplexApiService } from './toolplexApi/service.js';
+import { StdioServerManagerClient } from '../shared/stdioServerManagerClient.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.
+ */
+declare class Registry {
+    private static _clientContext;
+    private static _toolplexApiService;
+    private static _serverManagerClients;
+    private static _telemetryLogger;
+    private static _promptsCache;
+    private static _toolDefinitionsCache;
+    private static _serversCache;
+    private static _policyEnforcer;
+    static init(clientContext: ClientContext): Promise<void>;
+    static getClientContext(): ClientContext;
+    static getToolplexApiService(): ToolplexApiService;
+    static getServerManagerClients(): Record<string, StdioServerManagerClient>;
+    static setServerManagerClients(clients: Record<string, StdioServerManagerClient>): void;
+    static getTelemetryLogger(): TelemetryLogger;
+    static getPromptsCache(): PromptsCache;
+    static getToolDefinitionsCache(): ToolDefinitionsCache;
+    static getServersCache(): ServersCache;
+    static getPolicyEnforcer(): PolicyEnforcer;
+    static reset(): void;
+}
+export default Registry;

package/dist/mcp-server/registry.js

@@ -0,0 +1,109 @@
+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;
+    }
+    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;
+    }
+}
+Registry._clientContext = null;
+Registry._toolplexApiService = null;
+Registry._serverManagerClients = null;
+Registry._telemetryLogger = null;
+Registry._promptsCache = null;
+Registry._toolDefinitionsCache = null;
+Registry._serversCache = null;
+Registry._policyEnforcer = null;
+export default Registry;

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

@@ -0,0 +1,53 @@
+import { StdioServerManagerClient } from '../shared/stdioServerManagerClient.js';
+type ServerInfo = {
+    server_id: string;
+    server_name: string;
+    description: string;
+};
+/**
+ * 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 declare class ServersCache {
+    private _serverIds;
+    constructor();
+    /**
+     * Initialize the cache with a list of servers, e.g. from initialize() succeeded list.
+     * Only tracks server IDs.
+     */
+    init(servers: ServerInfo[]): void;
+    /**
+     * 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: ServerInfo[]): void;
+    /**
+     * Returns true if the server is installed (present in the cache).
+     * Throws an error if the cache is not initialized.
+     */
+    isInstalled(serverId: string): boolean;
+    /**
+     * Get all cached server IDs.
+     */
+    getServerIds(): string[];
+    /**
+     * 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)
+     */
+    refreshCache(serverManagerClients: Record<string, StdioServerManagerClient>): Promise<void>;
+    /**
+     * Check if the cache is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Reset the cache
+     */
+    reset(): void;
+}
+export {};