@convertcom/mcp-server 0.0.1-beta.3 → 0.0.1-beta.5

package/build/executor.js

@@ -0,0 +1,173 @@
+import { z, ZodError } from 'zod';
+import { jsonSchemaToZod } from 'json-schema-to-zod';
+import axios from 'axios';
+import { toolDefinitionMap } from './tools.js';
+import './api-config.js';
+export async function executeToolByName(toolName, toolArgs) {
+    const toolDefinition = toolDefinitionMap.get(toolName);
+    if (!toolDefinition) {
+        return { content: [{ type: 'text', text: 'Error: Unknown tool requested: ' + toolName }] };
+    }
+    return await executeApiTool(toolName, toolDefinition, toolArgs);
+}
+async function executeApiTool(toolName, definition, toolArgs) {
+    try {
+        let validatedArgs;
+        try {
+            const zodSchema = getZodSchemaFromJsonSchema(definition.inputSchema, toolName);
+            const argsToParse = (typeof toolArgs === 'object' && toolArgs !== null) ? toolArgs : {};
+            validatedArgs = zodSchema.parse(argsToParse);
+        }
+        catch (error) {
+            if (error instanceof ZodError) {
+                const validationErrorMessage = 'Invalid arguments. Common issue: Array parameters (like "include", "expand") must be passed as arrays, even for single values. Example: {"query": {"include": ["goals"]}} not {"query": {"include": "goals"}}. Details: ' + JSON.stringify(error.errors, null, 2);
+                return { content: [{ type: 'text', text: validationErrorMessage }] };
+            }
+            else {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                return { content: [{ type: 'text', text: 'Internal error during validation setup: ' + errorMessage }] };
+            }
+        }
+        let urlPath = definition.pathTemplate;
+        const queryParams = {};
+        const headers = { 'Accept': 'application/json' };
+        let requestBodyData = undefined;
+        // Apply basic authentication (Bearer token)
+        const bearerToken = process.env.BEARER_TOKEN || process.env.API_TOKEN;
+        if (bearerToken) {
+            headers['authorization'] = `Bearer ${bearerToken}`;
+        }
+        definition.executionParameters.forEach((param) => {
+            const value = validatedArgs[param.name];
+            if (typeof value !== 'undefined' && value !== null) {
+                if (param.in === 'path') {
+                    urlPath = urlPath.replace(`{${param.name}}`, encodeURIComponent(String(value)));
+                }
+                else if (param.in === 'query') {
+                    // Always keep arrays as arrays - we'll serialize them with bracket notation later
+                    // Note: OpenAPI spec says explode=false but Convert API requires bracket notation (explode=true behavior)
+                    queryParams[param.name] = value;
+                }
+                else if (param.in === 'header') {
+                    headers[param.name.toLowerCase()] = String(value);
+                }
+            }
+        });
+        if (urlPath.includes('{')) {
+            throw new Error(`Failed to resolve path parameters: ${urlPath}`);
+        }
+        // Build full URL with query string directly - don't rely on axios params serialization
+        let fullUrl = (process.env.API_BASE_URL || 'https://api.convert.com/api/v2') + urlPath;
+        if (Object.keys(queryParams).length > 0) {
+            // Serialize query params with bracket notation for arrays
+            const parts = [];
+            for (const [key, value] of Object.entries(queryParams)) {
+                if (Array.isArray(value)) {
+                    value.forEach((v) => {
+                        parts.push(`${key}[]=${encodeURIComponent(String(v))}`);
+                    });
+                }
+                else {
+                    parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+                }
+            }
+            fullUrl = fullUrl + '?' + parts.join('&');
+        }
+        if (definition.requestBodyContentType && typeof validatedArgs['requestBody'] !== 'undefined') {
+            requestBodyData = validatedArgs['requestBody'];
+            headers['content-type'] = definition.requestBodyContentType;
+        }
+        const config = {
+            method: (definition.method || 'get').toUpperCase(),
+            url: fullUrl,
+            // Don't pass params - query string is already in URL
+            headers,
+            ...(requestBodyData !== undefined && { data: requestBodyData }),
+        };
+        const response = await axios(config);
+        let responseText = '';
+        const contentType = response.headers['content-type']?.toLowerCase() || '';
+        if (contentType.includes('application/json') && typeof response.data === 'object' && response.data !== null) {
+            try {
+                responseText = JSON.stringify(response.data, null, 2);
+            }
+            catch {
+                responseText = '[Stringify Error]';
+            }
+        }
+        else if (typeof response.data === 'string') {
+            responseText = response.data;
+        }
+        else if (response.data !== undefined && response.data !== null) {
+            responseText = String(response.data);
+        }
+        else {
+            responseText = `(Status: ${response.status} - No body content)`;
+        }
+        return { content: [{ type: 'text', text: `API Response (Status: ${response.status}):\n${responseText}` }] };
+    }
+    catch (error) {
+        let errorMessage;
+        if (axios.isAxiosError(error)) {
+            errorMessage = formatApiError(error);
+        }
+        else if (error instanceof Error) {
+            errorMessage = error.message;
+        }
+        else {
+            errorMessage = `Unexpected error: ${String(error)}`;
+        }
+        console.error(`Error during execution: ${errorMessage}`);
+        return { content: [{ type: 'text', text: errorMessage }] };
+    }
+}
+function formatApiError(error) {
+    let message = 'API request failed.';
+    if (error.response) {
+        message = `API Error: Status ${error.response.status} (${error.response.statusText || 'Status text not available'}). `;
+        const responseData = error.response.data;
+        const MAX_LEN = 200;
+        if (typeof responseData === 'string') {
+            message += `Response: ${responseData.substring(0, MAX_LEN)}${responseData.length > MAX_LEN ? '...' : ''}`;
+        }
+        else if (responseData) {
+            try {
+                const jsonString = JSON.stringify(responseData);
+                message += `Response: ${jsonString.substring(0, MAX_LEN)}${jsonString.length > MAX_LEN ? '...' : ''}`;
+            }
+            catch {
+                message += 'Response: [Could not serialize data]';
+            }
+        }
+        else {
+            message += 'No response body received.';
+        }
+    }
+    else if (error.request) {
+        message = 'API Network Error: No response received from server.';
+        if (error.code)
+            message += ` (Code: ${error.code})`;
+    }
+    else {
+        message += `API Request Setup Error: ${error.message}`;
+    }
+    return message;
+}
+function getZodSchemaFromJsonSchema(jsonSchema, toolName) {
+    if (typeof jsonSchema !== 'object' || jsonSchema === null) {
+        return z.object({}).passthrough();
+    }
+    try {
+        const zodSchemaString = jsonSchemaToZod(jsonSchema);
+        const zodSchema = eval(zodSchemaString);
+        if (typeof zodSchema?.parse !== 'function') {
+            throw new Error('Eval did not produce a valid Zod schema.');
+        }
+        return zodSchema;
+    }
+    catch (err) {
+        console.error(`Failed to generate/evaluate Zod schema for '${toolName}':`, err);
+        return z.object({}).passthrough();
+    }
+}
+//# sourceMappingURL=executor.js.map

package/build/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"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"}

package/build/index.d.ts

@@ -10,3 +10,9 @@ import './api-config.js';
 export declare const SERVER_NAME = "convert-api";
 export declare const SERVER_VERSION = "2.0.0";
 export declare const API_BASE_URL = "https://api.convert.com/api/v2";
+/**
+ * Formats API errors for better readability
+ *
+ * @param error Axios error
+ * @returns Formatted error message
+ */

package/build/index.js

@@ -9,61 +9,114 @@ dotenv.config();
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { z, ZodError } from 'zod';
-import { jsonSchemaToZod } from 'json-schema-to-zod';
-import axios from 'axios';
+import { executeToolByName } from './executor.js';
+import { getNamespacedTools, executeNamespacedTool, isNamespace } from './namespaced.js';
+import { fileURLToPath } from 'node:url';
+import { resolve, dirname } from 'node:path';
+import { KbSearchService } from './kb-search.js';
 if (process.env.NODE_ENV === 'development') {
     import('mcps-logger/console');
 }
 import './api-config.js';
 import { toolDefinitionMap } from './tools.js';
-function getToolsForClient() {
-    const reportingTools = [
-        'getaccountslist',
-        'getaccountlivedata',
-        'getaccountactivecompletedexperienceslist',
-        'getprojectslist',
-        'getproject',
-        'getprojectlivedata',
-        'getexperienceslist',
-        'getexperience',
-        'getexperiencebykey',
-        'getexperiencelivedata',
-        'getexperienceaggregatedreport',
-        'getexperiencedailyreport',
-        'getexperiencedailytrafficallocation',
-        'getgoal',
-        'getgoalbykey',
-        'getlocation',
-        'getlocationslist',
-        'getaudienceslist',
-        'getaudience',
-        'getfeatureslist',
-        'getfeature',
-        'getfeaturebykey',
-    ];
-    const toolSet = process.env.TOOLS_FOR_CLIENT ?? 'reporting';
-    return Array.from(toolDefinitionMap.values())
-        .filter((def) => {
-        if (toolSet === 'readOnly') {
-            if (def.name.match(/^get/)) {
-                return true;
-            }
-            return false;
+import { DebugLogger } from './debug-log.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const knowledgeBasePath = resolve(__dirname, '..', 'data', 'convert-kb.json');
+const kbSearchService = new KbSearchService(knowledgeBasePath);
+const SERVER_INSTRUCTIONS = [
+    "You are an expert Convert Experiences assistant.",
+    "Always call 'searchKnowledgeBase' before using API namespaces so you understand required IDs,",
+    "terminology, or workflows.",
+    "The knowledge-base search is keyword based (MiniSearch)—focus on specific terms, such as product names,",
+    "URLs, or field labels, for best matches.",
+    "Whenever an API response returns raw IDs (goals, projects, audiences, etc.), immediately enrich those",
+    "IDs by calling the appropriate namespace tool so the final answer contains descriptive names and details—",
+    "the human should never have to resolve IDs manually. Example presenting 'Goal 10001068' is not acceptable,",
+    "you should call the goals namespace tool to get the name of the goal.",
+    "CRITICAL: When fetching resources with related data (e.g., experiences with goals), ALWAYS use BOTH 'include' AND 'expand'",
+    "query parameters together. 'include' alone only brings the related resource IDs into the response, but 'expand' provides",
+    "the full object data for those IDs. WITHOUT 'expand', you will only get useless numeric IDs instead of meaningful data.",
+    "For example: {\"query\": {\"include\": [\"goals\", \"variations\"], \"expand\": [\"goals\", \"variations\"]}} gives you complete goal and variation objects.",
+    "NEVER use 'include' without 'expand' - it will make the response useless with just IDs like 'goals: [10001068, 10001069]'.",
+    "Pay close attention to API response codes and any 'alerts' array in the payload; they describe what to do",
+    "next and must shape your follow-up actions.",
+    "When calling MCP tools, send arguments as strict JSON with double quotes (for example: {\"query\":",
+    "\"install convert on shopify\"}).",
+    "Combine what you learn with the available tools to craft accurate, fully explained API calls."
+].join(' ');
+const debugLogger = new DebugLogger(process.env.CONVERT_DEBUG_LOG === '1' || process.env.CONVERT_DEBUG_LOG?.toLowerCase() === 'true');
+function normalizeLooseJson(input) {
+    let output = input
+        .replace(/[`]/g, '"')
+        .replace(/[\u201C\u201D]/g, '"')
+        .replace(/[\u2018\u2019]/g, "'")
+        .replace(/(\{|\,)(\s*)([A-Za-z0-9_]+)(\s*):/g, (_, start, space, key, after) => `${start}${space}"${key}"${after}:`)
+        .replace(/:\s*'([^']*)'/g, ': "$1"')
+        .replace(/,\s*([}\]])/g, '$1');
+    return output;
+}
+function tryParseJsonLike(value) {
+    if (!value)
+        return undefined;
+    const attempts = [value, normalizeLooseJson(value)];
+    for (const candidate of attempts) {
+        try {
+            return JSON.parse(candidate);
         }
-        else if (toolSet === 'reporting') {
-            return reportingTools.indexOf(def.name) !== -1;
+        catch {
+            continue;
         }
-        return true;
-    })
-        .map((def) => {
-        return {
-            name: def.name,
-            description: def.description,
-            inputSchema: def.inputSchema,
-        };
-    })
-        .filter((tool) => tool !== null);
+    }
+    return undefined;
+}
+function extractQueryArgument(rawArgs) {
+    if (rawArgs === null || typeof rawArgs === 'undefined') {
+        return null;
+    }
+    if (typeof rawArgs === 'string') {
+        const trimmed = rawArgs.trim();
+        if (!trimmed) {
+            return null;
+        }
+        const parsed = tryParseJsonLike(trimmed);
+        if (parsed && typeof parsed?.query === 'string') {
+            return parsed.query.trim();
+        }
+        return trimmed;
+    }
+    if (typeof rawArgs === 'number' || typeof rawArgs === 'boolean') {
+        return String(rawArgs);
+    }
+    if (typeof rawArgs === 'object') {
+        const argsObj = rawArgs;
+        const direct = argsObj.query;
+        if (typeof direct === 'string') {
+            return direct.trim();
+        }
+        if (direct !== undefined && direct !== null) {
+            return String(direct);
+        }
+    }
+    return null;
+}
+const searchKnowledgeBaseTool = {
+    name: 'searchKnowledgeBase',
+    description: 'Searches the Convert experience knowledge base for concepts, terminology, and workflows before executing API actions.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Describe the topic or question you want to research (e.g., "install convert on shopify").'
+            }
+        },
+        required: ['query'],
+        additionalProperties: false
+    }
+};
+function getToolsForClient() {
+    const toolSet = process.env.TOOLS_FOR_CLIENT ?? 'reporting';
+    return [searchKnowledgeBaseTool, ...getNamespacedTools(toolSet)];
 }
 /**
  * Server configuration
@@ -74,149 +127,78 @@ export const API_BASE_URL = "https://api.convert.com/api/v2";
 /**
  * MCP Server instance
  */
-const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
-/**
- * Security schemes from the OpenAPI spec
- */
-const securitySchemes = {};
+const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, {
+    capabilities: { tools: {} },
+    instructions: SERVER_INSTRUCTIONS
+});
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return { tools: getToolsForClient() };
 });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name: toolName, arguments: toolArgs } = request.params;
-    const toolDefinition = toolDefinitionMap.get(toolName);
-    if (!toolDefinition) {
-        console.error(`Error: Unknown tool requested: ${toolName}`);
-        return { content: [{ type: "text", text: `Error: Unknown tool requested: ${toolName}` }] };
-    }
-    return await executeApiTool(toolName, toolDefinition, toolArgs ?? {}, securitySchemes);
-});
-/**
- * Executes an API tool with the provided arguments
- *
- * @param toolName Name of the tool to execute
- * @param definition Tool definition
- * @param toolArgs Arguments provided by the user
- * @param allSecuritySchemes Security schemes from the OpenAPI spec
- * @returns Call tool result
- */
-async function executeApiTool(toolName, definition, toolArgs, allSecuritySchemes) {
-    try {
-        // Validate arguments against the input schema
-        let validatedArgs;
+    debugLogger.log('callToolRequest', { toolName, arguments: toolArgs });
+    if (toolName === 'searchKnowledgeBase') {
         try {
-            const zodSchema = getZodSchemaFromJsonSchema(definition.inputSchema, toolName);
-            const argsToParse = (typeof toolArgs === 'object' && toolArgs !== null) ? toolArgs : {};
-            validatedArgs = zodSchema.parse(argsToParse);
-        }
-        catch (error) {
-            if (error instanceof ZodError) {
-                const validationErrorMessage = `Invalid arguments for tool '${toolName}': ${error.errors.map(e => `${e.path.join('.')} (${e.code}): ${e.message}`).join(', ')}`;
-                return { content: [{ type: 'text', text: validationErrorMessage }] };
+            const query = extractQueryArgument(toolArgs);
+            if (!query) {
+                debugLogger.log('searchKnowledgeBase.invalidArguments', { toolArgs });
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: "Error: The 'query' argument is required for searchKnowledgeBase." }],
+                    structuredContent: { error: "The 'query' argument is required for searchKnowledgeBase." }
+                };
             }
-            else {
-                const errorMessage = error instanceof Error ? error.message : String(error);
-                return { content: [{ type: 'text', text: `Internal error during validation setup: ${errorMessage}` }] };
-            }
-        }
-        // Prepare URL, query parameters, headers, and request body
-        let urlPath = definition.pathTemplate;
-        const queryParams = {};
-        const headers = { 'Accept': 'application/json' };
-        let requestBodyData = undefined;
-        // Apply parameters to the URL path, query, or headers
-        definition.executionParameters.forEach((param) => {
-            const value = validatedArgs[param.name];
-            if (typeof value !== 'undefined' && value !== null) {
-                if (param.in === 'path') {
-                    urlPath = urlPath.replace(`{${param.name}}`, encodeURIComponent(String(value)));
-                }
-                else if (param.in === 'query') {
-                    queryParams[param.name] = value;
-                }
-                else if (param.in === 'header') {
-                    headers[param.name.toLowerCase()] = String(value);
-                }
+            const results = kbSearchService.search(query, 5);
+            if (results.length === 0) {
+                debugLogger.log('searchKnowledgeBase.noResults', { query });
+                return {
+                    content: [{ type: 'text', text: `No knowledge base entries were found for the query: "${query}".` }],
+                    structuredContent: { query, results: [], message: `No knowledge base entries found for "${query}".` }
+                };
             }
-        });
-        // Ensure all path parameters are resolved
-        if (urlPath.includes('{')) {
-            throw new Error(`Failed to resolve path parameters: ${urlPath}`);
+            const structuredResults = results.map((result) => {
+                return {
+                    title: result.chunk.title,
+                    url: result.chunk.url,
+                    snippet: result.snippet,
+                    score: result.score
+                };
+            });
+            const textSummary = `Found ${structuredResults.length} relevant articles for "${query}":\n\n` +
+                structuredResults.map((result, index) => {
+                    const scoreText = Number.isFinite(result.score) ? ` (Relevance: ${(result.score * 100).toFixed(1)}%)` : '';
+                    return `${index + 1}. ${result.title}${scoreText}\n${result.url}\n${result.snippet}`;
+                }).join('\n\n---\n\n');
+            debugLogger.log('searchKnowledgeBase.success', { query, matchCount: results.length });
+            return {
+                content: [{ type: 'text', text: textSummary }],
+                structuredContent: { query, results: structuredResults }
+            };
         }
-        // Construct the full URL
-        const requestUrl = API_BASE_URL ? `${API_BASE_URL}${urlPath}` : urlPath;
-        // Handle request body if needed
-        if (definition.requestBodyContentType && typeof validatedArgs['requestBody'] !== 'undefined') {
-            requestBodyData = validatedArgs['requestBody'];
-            headers['content-type'] = definition.requestBodyContentType;
-        }
-        // Prepare the axios request configuration
-        const config = {
-            method: definition.method.toUpperCase(),
-            url: requestUrl,
-            params: queryParams,
-            headers: headers,
-            ...(requestBodyData !== undefined && { data: requestBodyData }),
-        };
-        // Log request info to stderr (doesn't affect MCP output)
-        console.error(`Executing tool "${toolName}": ${config.method} ${config.url}`);
-        // Execute the request
-        const response = await axios(config);
-        // Process and format the response
-        let responseText = '';
-        const contentType = response.headers['content-type']?.toLowerCase() || '';
-        // Handle JSON responses
-        if (contentType.includes('application/json') && typeof response.data === 'object' && response.data !== null) {
-            try {
-                responseText = JSON.stringify(response.data, null, 2);
-            }
-            catch (e) {
-                responseText = "[Stringify Error]";
-            }
-        }
-        // Handle string responses
-        else if (typeof response.data === 'string') {
-            responseText = response.data;
-        }
-        // Handle other response types
-        else if (response.data !== undefined && response.data !== null) {
-            responseText = String(response.data);
-        }
-        // Handle empty responses
-        else {
-            responseText = `(Status: ${response.status} - No body content)`;
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            debugLogger.log('searchKnowledgeBase.error', { toolArgs, error: message });
+            return {
+                isError: true,
+                content: [{ type: 'text', text: `Unexpected error during knowledge base search: ${message}` }],
+                structuredContent: { error: message }
+            };
         }
-        // Return formatted response
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `API Response (Status: ${response.status}):\n${responseText}`
-                }
-            ],
-        };
     }
-    catch (error) {
-        // Handle errors during execution
-        let errorMessage;
-        // Format Axios errors specially
-        if (axios.isAxiosError(error)) {
-            errorMessage = formatApiError(error);
-        }
-        // Handle standard errors
-        else if (error instanceof Error) {
-            errorMessage = error.message;
-        }
-        // Handle unexpected error types
-        else {
-            errorMessage = 'Unexpected error: ' + String(error);
-        }
-        // Log error to stderr
-        console.error(`Error during execution of tool '${toolName}':`, errorMessage);
-        // Return error message to client
-        return { content: [{ type: "text", text: errorMessage }] };
+    if (isNamespace(toolName)) {
+        const response = await executeNamespacedTool(toolName, toolArgs ?? {});
+        debugLogger.log('namespaceTool.success', { toolName, response });
+        return response;
     }
-}
+    if (toolDefinitionMap.has(toolName)) {
+        const response = await executeToolByName(toolName, (toolArgs ?? {}));
+        debugLogger.log('legacyTool.success', { toolName, response });
+        return response;
+    }
+    console.error(`Error: Unknown tool requested: ${toolName}`);
+    debugLogger.log('unknownTool', { toolName });
+    return { content: [{ type: 'text', text: `Error: Unknown tool requested: ${toolName}` }] };
+});
 /**
  * Main function to start the server
  */
@@ -253,60 +235,5 @@ main().catch((error) => {
  * @param error Axios error
  * @returns Formatted error message
  */
-function formatApiError(error) {
-    let message = 'API request failed.';
-    if (error.response) {
-        message = `API Error: Status ${error.response.status} (${error.response.statusText || 'Status text not available'}). `;
-        const responseData = error.response.data;
-        const MAX_LEN = 200;
-        if (typeof responseData === 'string') {
-            message += `Response: ${responseData.substring(0, MAX_LEN)}${responseData.length > MAX_LEN ? '...' : ''}`;
-        }
-        else if (responseData) {
-            try {
-                const jsonString = JSON.stringify(responseData);
-                message += `Response: ${jsonString.substring(0, MAX_LEN)}${jsonString.length > MAX_LEN ? '...' : ''}`;
-            }
-            catch {
-                message += 'Response: [Could not serialize data]';
-            }
-        }
-        else {
-            message += 'No response body received.';
-        }
-    }
-    else if (error.request) {
-        message = 'API Network Error: No response received from server.';
-        if (error.code)
-            message += ` (Code: ${error.code})`;
-    }
-    else {
-        message += `API Request Setup Error: ${error.message}`;
-    }
-    return message;
-}
-/**
- * Converts a JSON Schema to a Zod schema for runtime validation
- *
- * @param jsonSchema JSON Schema
- * @param toolName Tool name for error reporting
- * @returns Zod schema
- */
-function getZodSchemaFromJsonSchema(jsonSchema, toolName) {
-    if (typeof jsonSchema !== 'object' || jsonSchema === null) {
-        return z.object({}).passthrough();
-    }
-    try {
-        const zodSchemaString = jsonSchemaToZod(jsonSchema);
-        const zodSchema = eval(zodSchemaString);
-        if (typeof zodSchema?.parse !== 'function') {
-            throw new Error('Eval did not produce a valid Zod schema.');
-        }
-        return zodSchema;
-    }
-    catch (err) {
-        console.error(`Failed to generate/evaluate Zod schema for '${toolName}':`, err);
-        return z.object({}).passthrough();
-    }
-}
+// Removed legacy per-tool executor from index; execution handled by executor.ts and namespaced.ts
 //# sourceMappingURL=index.js.map