@toolplex/client 0.1.1

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

@@ -0,0 +1,81 @@
+import { FileLogger } from '../../shared/fileLogger.js';
+import { ListServersResultSchema } from '../../shared/serverManagerTypes.js';
+import Registry from '../registry.js';
+const logger = FileLogger;
+export async function handleListServers() {
+    const startTime = Date.now();
+    const serverManagerClients = Registry.getServerManagerClients();
+    const telemetryLogger = Registry.getTelemetryLogger();
+    const promptsCache = Registry.getPromptsCache();
+    const serversCache = Registry.getServersCache();
+    const policyEnforcer = Registry.getPolicyEnforcer();
+    try {
+        await logger.debug('Listing all installed servers');
+        let response = 'Currently installed MCP servers:\n\n';
+        // Collect all servers for updating the cache
+        const allServers = [];
+        for (const [runtime, client] of Object.entries(serverManagerClients)) {
+            const response_data = await client.sendRequest('list_servers', {});
+            if (response_data.error) {
+                continue;
+            }
+            const parsed = ListServersResultSchema.safeParse(response_data);
+            if (!parsed.success) {
+                await logger.error(`Invalid response from server manager: ${parsed.error}, runtime: ${runtime}`);
+                continue;
+            }
+            if (parsed.data.servers && parsed.data.servers.length > 0) {
+                // Filter out blocked servers
+                const filteredServers = policyEnforcer.filterBlockedMcpServers(parsed.data.servers, (server) => server.server_id);
+                filteredServers.forEach((server) => {
+                    response += `- Server ID: ${server.server_id}\n`;
+                    response += `  Name: ${server.server_name}\n`;
+                    response += `  Description: ${server.description}\n\n`;
+                    // Add to allServers for cache update
+                    allServers.push({
+                        server_id: server.server_id,
+                        server_name: server.server_name,
+                        description: server.description,
+                    });
+                });
+            }
+        }
+        // Update the servers cache with the fresh list
+        serversCache.updateServers(allServers);
+        if (response === 'Currently installed MCP servers:\n\n') {
+            response = promptsCache.getPrompt('list_servers_empty');
+        }
+        await logger.debug('Successfully retrieved servers list');
+        await telemetryLogger.log('client_list_servers', {
+            success: true,
+            latency_ms: Date.now() - startTime,
+        });
+        return {
+            role: 'system',
+            content: [
+                {
+                    type: 'text',
+                    text: response,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : promptsCache.getPrompt('unexpected_error');
+        await logger.error(`Failed to list servers: ${errorMessage}`);
+        await telemetryLogger.log('client_list_servers', {
+            success: false,
+            pii_sanitized_error_message: errorMessage,
+            latency_ms: Date.now() - startTime,
+        });
+        return {
+            role: 'system',
+            content: [
+                {
+                    type: 'text',
+                    text: promptsCache.getPrompt('unexpected_error').replace('{ERROR}', errorMessage),
+                },
+            ],
+        };
+    }
+}

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

@@ -0,0 +1,3 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { ListToolplexToolsParams } from '../../shared/mcpServerTypes.js';
+export declare function handleListTools(params: ListToolplexToolsParams): Promise<CallToolResult>;

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

@@ -0,0 +1,112 @@
+import { FileLogger } from '../../shared/fileLogger.js';
+import { findServerManagerClient } from './serverManagerUtils.js';
+import { ListToolsResultSchema, ListAllToolsResultSchema, } from '../../shared/serverManagerTypes.js';
+import Registry from '../registry.js';
+const logger = FileLogger;
+export async function handleListTools(params) {
+    const startTime = Date.now();
+    const serverManagerClients = Registry.getServerManagerClients();
+    const telemetryLogger = Registry.getTelemetryLogger();
+    const promptsCache = Registry.getPromptsCache();
+    const policyEnforcer = Registry.getPolicyEnforcer();
+    try {
+        const server_id = params.server_id;
+        let response = '';
+        if (server_id) {
+            // Check if server is blocked using policy enforcer
+            policyEnforcer.enforceUseServerPolicy(server_id);
+            await logger.debug(`Listing tools for specific server: ${server_id}`);
+            const client = await findServerManagerClient(server_id, serverManagerClients);
+            const response_data = await client.sendRequest('list_tools', { server_id: server_id });
+            if ('error' in response_data) {
+                throw new Error(`Failed to list tools for server_id ${server_id}, error message: ${response_data.error.message}`);
+            }
+            const parsed = ListToolsResultSchema.safeParse(response_data);
+            if (!parsed.success) {
+                throw new Error(`Invalid response from server manager: ${parsed.error}`);
+            }
+            response = promptsCache
+                .getPrompt('list_tools_server_header')
+                .replace('{SERVER_ID}', parsed.data.server_id)
+                .replace('{SERVER_NAME}', parsed.data.server_name);
+            if (!parsed.data.tools || parsed.data.tools.length === 0) {
+                response += promptsCache.getPrompt('list_tools_empty');
+            }
+            else {
+                parsed.data.tools.forEach((tool) => {
+                    response += `- ${tool.name}: ${tool.description}\n`;
+                    response += `  Input Schema: ${JSON.stringify(tool.inputSchema, null, 2)}\n\n`;
+                });
+            }
+        }
+        else {
+            await logger.debug('Listing tools from all installed servers');
+            response = promptsCache.getPrompt('list_tools_all_header');
+            for (const [runtime, client] of Object.entries(serverManagerClients)) {
+                const response_data = await client.sendRequest('list_all_tools', {});
+                if (response_data.error) {
+                    continue;
+                }
+                const parsed = ListAllToolsResultSchema.safeParse(response_data);
+                if (!parsed.success) {
+                    await logger.error(`Invalid response from server manager: ${parsed.error}, runtime: ${runtime}`);
+                    continue;
+                }
+                // Filter out blocked servers
+                const serverEntries = Object.entries(parsed.data.tools);
+                const filteredEntries = policyEnforcer.filterBlockedMcpServers(serverEntries, ([serverId]) => serverId);
+                for (const [serverId, serverTools] of filteredEntries) {
+                    if (serverTools && serverTools.length > 0) {
+                        response += `Server: ${serverId}\n`;
+                        serverTools.forEach((tool) => {
+                            response += `- ${tool.name}: ${tool.description}\n`;
+                            response += `  Input Schema: ${JSON.stringify(tool.inputSchema, null, 2)}\n\n`;
+                        });
+                        response += '\n';
+                    }
+                }
+            }
+            if (response === promptsCache.getPrompt('list_tools_all_header')) {
+                response += promptsCache.getPrompt('list_tools_empty');
+            }
+        }
+        await logger.debug('Successfully retrieved tools list');
+        await telemetryLogger.log('client_list_tools', {
+            success: true,
+            log_context: {
+                server_id: params.server_id,
+            },
+            latency_ms: Date.now() - startTime,
+        });
+        return {
+            role: 'system',
+            content: [
+                {
+                    type: 'text',
+                    text: response,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : promptsCache.getPrompt('unexpected_error');
+        await logger.error(`Failed to list tools: ${errorMessage}`);
+        await telemetryLogger.log('client_list_tools', {
+            success: false,
+            log_context: {
+                server_id: params.server_id,
+            },
+            pii_sanitized_error_message: errorMessage,
+            latency_ms: Date.now() - startTime,
+        });
+        return {
+            role: 'system',
+            content: [
+                {
+                    type: 'text',
+                    text: promptsCache.getPrompt('list_tools_failure').replace('{ERROR}', errorMessage),
+                },
+            ],
+        };
+    }
+}

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

@@ -0,0 +1,3 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { LogPlaybookUsageParams } from '../../shared/mcpServerTypes.js';
+export declare function handleLogPlaybookUsage(params: LogPlaybookUsageParams): Promise<CallToolResult>;

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

@@ -0,0 +1,65 @@
+import { FileLogger } from '../../shared/fileLogger.js';
+import Registry from '../registry.js';
+const logger = FileLogger;
+export async function handleLogPlaybookUsage(params) {
+    const startTime = Date.now();
+    await logger.debug(`Handling log playbook usage request with params: ${JSON.stringify(params)}`);
+    const { playbook_id, success, error_message } = params;
+    await logger.info(`Logging usage for playbook ${playbook_id}`);
+    const apiService = Registry.getToolplexApiService();
+    const telemetryLogger = Registry.getTelemetryLogger();
+    const promptsCache = Registry.getPromptsCache();
+    const policyEnforcer = Registry.getPolicyEnforcer();
+    const clientContext = Registry.getClientContext();
+    try {
+        // Check if the client is in restricted mode
+        if (clientContext.clientMode === 'restricted') {
+            throw new Error('Playbook functionality is disabled in restricted mode.');
+        }
+        // Enforce playbook usage logging policy
+        policyEnforcer.enforceLogPlaybookUsagePolicy();
+        await apiService.logPlaybookUsage(playbook_id, success, error_message);
+        await logger.info('Playbook usage logged successfully');
+        await telemetryLogger.log('client_log_playbook_usage', {
+            success: true,
+            log_context: {
+                playbook_id,
+                success: success,
+            },
+            latency_ms: Date.now() - startTime,
+        });
+        return {
+            role: 'system',
+            content: [
+                {
+                    type: 'text',
+                    text: promptsCache.getPrompt('log_playbook_usage_success'),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        await logger.error(`Failed to log playbook usage: ${errorMessage}`);
+        await telemetryLogger.log('client_log_playbook_usage', {
+            success: false,
+            log_context: {
+                playbook_id,
+                success: success,
+            },
+            pii_sanitized_error_message: errorMessage,
+            latency_ms: Date.now() - startTime,
+        });
+        return {
+            role: 'system',
+            content: [
+                {
+                    type: 'text',
+                    text: promptsCache
+                        .getPrompt('log_playbook_usage_failure')
+                        .replace('{ERROR}', errorMessage),
+                },
+            ],
+        };
+    }
+}

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

@@ -0,0 +1,3 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { LookupEntityParams } from '../../shared/mcpServerTypes.js';
+export declare function handleLookupEntityTool(params: LookupEntityParams): Promise<CallToolResult>;

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

@@ -0,0 +1,112 @@
+import { FileLogger } from '../../shared/fileLogger.js';
+import Registry from '../registry.js';
+import { annotateInstalledServer } from '../utils/resultAnnotators.js';
+const logger = FileLogger;
+export async function handleLookupEntityTool(params) {
+    const startTime = Date.now();
+    await logger.debug(`Handling lookup entity request for ${params.entity_type} with ID: ${params.entity_id}`);
+    const apiService = Registry.getToolplexApiService();
+    const telemetryLogger = Registry.getTelemetryLogger();
+    const promptsCache = Registry.getPromptsCache();
+    const serversCache = Registry.getServersCache();
+    const policyEnforcer = Registry.getPolicyEnforcer();
+    const clientContext = Registry.getClientContext();
+    try {
+        // Check if the client is in restricted mode
+        if (clientContext.clientMode === 'restricted') {
+            throw new Error('Lookup functionality is disabled in restricted mode.');
+        }
+        // Enforce blocked server policy if looking up a server
+        if (params.entity_type === 'server') {
+            policyEnforcer.enforceUseServerPolicy(params.entity_id);
+        }
+        let lookupResponse = await apiService.lookupEntity(params.entity_type, params.entity_id);
+        if (!lookupResponse) {
+            await logger.debug('No entity found');
+            await telemetryLogger.log('client_lookup_entity', {
+                success: true,
+                log_context: {
+                    entity_type: params.entity_type,
+                    entity_id: params.entity_id,
+                },
+                latency_ms: Date.now() - startTime,
+            });
+            return {
+                role: 'system',
+                content: [
+                    {
+                        type: 'text',
+                        text: promptsCache
+                            .getPrompt('lookup_entity_not_found')
+                            .replace('{entity_type}', params.entity_type)
+                            .replace('{entity_id}', params.entity_id),
+                    },
+                ],
+            };
+        }
+        // Use resultAnnotators to annotate if the server is installed
+        if (params.entity_type === 'server' && lookupResponse && typeof lookupResponse === 'object') {
+            try {
+                lookupResponse = annotateInstalledServer(lookupResponse, serversCache);
+            }
+            catch (err) {
+                await logger.warn(`Error annotating installed server: ${err}`);
+                // fallback: do not annotate
+            }
+        }
+        await logger.debug(`Found entity: ${JSON.stringify(lookupResponse)}`);
+        let response = `Found ${params.entity_type}:\n`;
+        response += JSON.stringify(lookupResponse, null, 2);
+        response += '\n';
+        await logger.debug('Lookup completed successfully');
+        await telemetryLogger.log('client_lookup_entity', {
+            success: true,
+            log_context: {
+                entity_type: params.entity_type,
+                entity_id: params.entity_id,
+            },
+            latency_ms: Date.now() - startTime,
+        });
+        const content = [
+            {
+                type: 'text',
+                text: response,
+            },
+        ];
+        if (params.entity_type === 'server') {
+            content.push({
+                type: 'text',
+                text: promptsCache.getPrompt('lookup_entity_install_guidance'),
+            });
+        }
+        return {
+            role: 'system',
+            content,
+        };
+    }
+    catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        await logger.error(`Error looking up entity: ${errorMessage}`);
+        await telemetryLogger.log('client_lookup_entity', {
+            success: false,
+            log_context: {
+                entity_type: params.entity_type,
+                entity_id: params.entity_id,
+            },
+            pii_sanitized_error_message: errorMessage,
+            latency_ms: Date.now() - startTime,
+        });
+        return {
+            role: 'system',
+            content: [
+                {
+                    type: 'text',
+                    text: promptsCache
+                        .getPrompt('lookup_entity_error')
+                        .replace('{entity_type}', params.entity_type)
+                        .replace('{ERROR}', errorMessage),
+                },
+            ],
+        };
+    }
+}

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

@@ -0,0 +1,3 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { SavePlaybookParams } from '../../shared/mcpServerTypes.js';
+export declare function handleSavePlaybook(params: SavePlaybookParams): Promise<CallToolResult>;

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

@@ -0,0 +1,65 @@
+import { FileLogger } from '../../shared/fileLogger.js';
+import Registry from '../registry.js';
+const logger = FileLogger;
+export async function handleSavePlaybook(params) {
+    const startTime = Date.now();
+    await logger.info('Handling save playbook request');
+    await logger.debug(`Playbook params: ${JSON.stringify(params)}`);
+    const apiService = Registry.getToolplexApiService();
+    const telemetryLogger = Registry.getTelemetryLogger();
+    const promptsCache = Registry.getPromptsCache();
+    const policyEnforcer = Registry.getPolicyEnforcer();
+    const clientContext = Registry.getClientContext();
+    try {
+        // Check if the client is in restricted mode
+        if (clientContext.clientMode === 'restricted') {
+            throw new Error('Playbook functionality is disabled in restricted mode.');
+        }
+        // Check if read-only mode is enabled
+        if (clientContext.permissions.enable_read_only_mode) {
+            throw new Error('Saving playbooks is disabled in read-only mode');
+        }
+        // Enforce playbook policy before saving
+        policyEnforcer.enforceSavePlaybookPolicy(params);
+        const { description, actions, domain, keywords, requirements, source_playbook_id, fork_reason, } = params;
+        const response = await apiService.createPlaybook(description, actions, domain, keywords, requirements, source_playbook_id, fork_reason);
+        await logger.info(`Playbook created successfully with ID: ${response.id}`);
+        await telemetryLogger.log('client_save_playbook', {
+            success: true,
+            log_context: {
+                playbook_id: response.id,
+                source_playbook_id: source_playbook_id,
+            },
+            latency_ms: Date.now() - startTime,
+        });
+        return {
+            role: 'system',
+            content: [
+                {
+                    type: 'text',
+                    text: promptsCache
+                        .getPrompt('save_playbook_success')
+                        .replace('{PLAYBOOK_ID}', response.id),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        await logger.error(`Failed to create playbook: ${errorMessage}`);
+        await telemetryLogger.log('client_save_playbook', {
+            success: false,
+            pii_sanitized_error_message: errorMessage,
+            latency_ms: Date.now() - startTime,
+        });
+        return {
+            role: 'system',
+            content: [
+                {
+                    type: 'text',
+                    text: promptsCache.getPrompt('save_playbook_failure').replace('{ERROR}', errorMessage),
+                },
+            ],
+        };
+    }
+}

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

@@ -0,0 +1,3 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { SearchParams } from '../../shared/mcpServerTypes.js';
+export declare function handleSearchTool(params: SearchParams): Promise<CallToolResult>;

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

@@ -0,0 +1,114 @@
+import { FileLogger } from '../../shared/fileLogger.js';
+import Registry from '../registry.js';
+import { annotateInstalledServers } from '../utils/resultAnnotators.js';
+const logger = FileLogger;
+export async function handleSearchTool(params) {
+    const startTime = Date.now();
+    await logger.info('Handling search request');
+    await logger.debug(`Search params: ${JSON.stringify(params)}`);
+    const apiService = Registry.getToolplexApiService();
+    const telemetryLogger = Registry.getTelemetryLogger();
+    const promptsCache = Registry.getPromptsCache();
+    const serversCache = Registry.getServersCache();
+    const clientContext = Registry.getClientContext();
+    const query = params.query;
+    const expandedKeywords = params.expanded_keywords || [];
+    const filter = params.filter || 'all';
+    const size = params.size || 10;
+    try {
+        // Check if the client is in restricted mode
+        if (clientContext.clientMode === 'restricted') {
+            throw new Error('Search functionality is disabled in restricted mode.');
+        }
+        const results = await apiService.search(query, expandedKeywords, filter, size);
+        // Log telemetry event
+        await telemetryLogger.log('client_search', {
+            success: true,
+            log_context: {
+                filter,
+                size,
+                num_expanded_keywords: expandedKeywords.length,
+                num_results: (results.mcp_servers?.length ?? -1) + (results.playbooks?.length ?? -1),
+            },
+            latency_ms: Date.now() - startTime,
+        });
+        const mcpServers = Array.isArray(results.mcp_servers) ? results.mcp_servers : [];
+        const playbooks = Array.isArray(results.playbooks) ? results.playbooks : [];
+        const totalResults = mcpServers.length + playbooks.length;
+        // Annotate installed servers using resultAnnotators
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let annotatedServers = [];
+        if (mcpServers.length > 0) {
+            try {
+                annotatedServers = annotateInstalledServers(mcpServers, serversCache);
+            }
+            catch (err) {
+                await logger.warn(`Error annotating installed servers: ${err}`);
+                annotatedServers = mcpServers;
+            }
+        }
+        if (totalResults === 0) {
+            await logger.info('No search results found');
+            return {
+                role: 'system',
+                content: [
+                    {
+                        type: 'text',
+                        text: promptsCache.getPrompt('search_no_results'),
+                    },
+                ],
+            };
+        }
+        await logger.debug(`Found ${totalResults} results`);
+        let response = promptsCache.getPrompt('search_results_header');
+        if ((annotatedServers.length ?? 0) > 0) {
+            response += '\n=== Servers ===\n';
+            response += JSON.stringify(annotatedServers, null, 2);
+            response += '\n';
+        }
+        else {
+            response += '\n(No servers found)\n';
+        }
+        if (playbooks.length > 0) {
+            response += '\n=== Playbooks ===\n';
+            response += JSON.stringify(playbooks, null, 2);
+            response += '\n';
+        }
+        else {
+            response += '\n(No playbooks found)\n';
+        }
+        await logger.info('Search completed successfully');
+        return {
+            role: 'system',
+            content: [
+                {
+                    type: 'text',
+                    text: response,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        await logger.error(`Search failed: ${errorMessage}`);
+        await telemetryLogger.log('client_search', {
+            success: false,
+            log_context: {
+                filter,
+                size,
+                num_expanded_keywords: expandedKeywords.length,
+            },
+            pii_sanitized_error_message: errorMessage,
+            latency_ms: Date.now() - startTime,
+        });
+        return {
+            role: 'system',
+            content: [
+                {
+                    type: 'text',
+                    text: promptsCache.getPrompt('unexpected_error').replace('{ERROR}', errorMessage),
+                },
+            ],
+        };
+    }
+}

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

@@ -0,0 +1,2 @@
+import { StdioServerManagerClient } from '../../shared/stdioServerManagerClient.js';
+export declare function findServerManagerClient(serverId: string, serverManagerClients: Record<string, StdioServerManagerClient>): Promise<StdioServerManagerClient>;

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

@@ -0,0 +1,20 @@
+export async function findServerManagerClient(serverId, serverManagerClients) {
+    for (const client of Object.values(serverManagerClients)) {
+        const response = await client.sendRequest('list_servers', {});
+        if ('error' in response) {
+            throw new Error(`Failed to list servers; error message: ${response.error.message}`);
+        }
+        // Handle both array and object responses
+        const serverList = Array.isArray(response) ? response : response.servers;
+        // Ensure serverList is an array and handle potential null/undefined
+        if (Array.isArray(serverList)) {
+            const hasServer = serverList.some((s) => 
+            // Handle both server_id and serverId properties
+            s.server_id === serverId || s.serverId === serverId);
+            if (hasServer) {
+                return client;
+            }
+        }
+    }
+    throw new Error(`Server ${serverId} not found`);
+}

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

@@ -0,0 +1,3 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { SubmitFeedbackParams } from '../../shared/mcpServerTypes.js';
+export declare function handleSubmitFeedback(params: SubmitFeedbackParams): Promise<CallToolResult>;