@anyshift/mcp-proxy 0.3.4 → 0.3.6

package/dist/index.js

@@ -23,14 +23,15 @@ import { createJqTool } from './jq/index.js';
 import { truncateResponseIfNeeded } from './truncation/index.js';
 import { createFileWriter } from './fileWriter/index.js';
 import { generateToolId } from './utils/filename.js';
+import { PROXY_PARAMS } from './types/index.js';
 // ============================================================================
 // HELPER FUNCTIONS
 // ============================================================================
 /**
- * Inject 'description' parameter into a tool's inputSchema
- * This ensures LLMs explain why they're calling each tool
+ * Inject proxy-specific parameters into a tool's inputSchema
+ * Uses centralized PROXY_PARAMS definitions
  */
-function injectDescriptionParam(tool) {
+function injectProxyParams(tool) {
     // Clone the tool to avoid mutating the original
     const modifiedTool = { ...tool };
     if (!modifiedTool.inputSchema) {
@@ -43,15 +44,45 @@ function injectDescriptionParam(tool) {
     }
     // Clone properties
     modifiedTool.inputSchema.properties = { ...modifiedTool.inputSchema.properties };
-    // Only add if not already present
-    if (!modifiedTool.inputSchema.properties.description) {
-        modifiedTool.inputSchema.properties.description = {
-            type: 'string',
-            description: 'Brief explanation of why you are calling this tool and what you expect to learn/achieve'
-        };
+    // Inject all proxy params if not already present
+    for (const [key, value] of Object.entries(PROXY_PARAMS)) {
+        if (!modifiedTool.inputSchema.properties[key]) {
+            modifiedTool.inputSchema.properties[key] = value;
+        }
+    }
+    // Ensure isRetryAttempt is required (not optional)
+    if (!modifiedTool.inputSchema.required) {
+        modifiedTool.inputSchema.required = [];
+    }
+    if (!modifiedTool.inputSchema.required.includes('isRetryAttempt')) {
+        modifiedTool.inputSchema.required = [...modifiedTool.inputSchema.required, 'isRetryAttempt'];
     }
     return modifiedTool;
 }
+/**
+ * Add retry metadata to a unified response if present in tool args
+ */
+function addRetryMetadata(response, toolArgs) {
+    if (toolArgs.isRetryAttempt) {
+        response.isRetryAttempt = true;
+        if (toolArgs.originalToolId) {
+            response.originalToolId = toolArgs.originalToolId;
+        }
+    }
+    return response;
+}
+/**
+ * Create an error response with consistent structure
+ */
+function createErrorResponse(tool_id, error, toolArgs) {
+    return addRetryMetadata({ tool_id, wroteToFile: false, error }, toolArgs);
+}
+/**
+ * Create a success response with content (not written to file)
+ */
+function createContentResponse(tool_id, outputContent, toolArgs) {
+    return addRetryMetadata({ tool_id, wroteToFile: false, outputContent }, toolArgs);
+}
 /**
  * ENVIRONMENT VARIABLE CONTRACT
  * =============================
@@ -299,8 +330,8 @@ async function main() {
     // ------------------------------------------------------------------------
     // 5. REGISTER ALL TOOLS (CHILD + PROXY) WITH DESCRIPTION INJECTION
     // ------------------------------------------------------------------------
-    // Inject 'description' parameter into all child tools
-    const enhancedChildTools = childToolsResponse.tools.map(injectDescriptionParam);
+    // Inject proxy parameters (description, isRetryAttempt, originalToolId) into all child tools
+    const enhancedChildTools = childToolsResponse.tools.map(injectProxyParams);
     const allTools = [
         ...enhancedChildTools,
         ...(jqTool ? [jqTool.toolDefinition] : []) // JQ tool already has description param
@@ -323,6 +354,9 @@ async function main() {
             if (toolArgs.description) {
                 console.debug(`[mcp-proxy] Description: ${toolArgs.description}`);
             }
+            if (toolArgs.isRetryAttempt) {
+                console.debug(`[mcp-proxy] Retry of: ${toolArgs.originalToolId}`);
+            }
         }
         try {
             let result;
@@ -336,11 +370,7 @@ async function main() {
                 });
                 // JQ tool returns directly, wrap in unified format
                 const tool_id = generateToolId(toolName, toolArgs, fileWriterConfig.toolAbbreviations);
-                const unifiedResponse = {
-                    tool_id,
-                    wroteToFile: false,
-                    outputContent: result.content?.[0]?.text
-                };
+                const unifiedResponse = createContentResponse(tool_id, result.content?.[0]?.text, toolArgs);
                 return {
                     content: [{
                             type: 'text',
@@ -352,15 +382,10 @@ async function main() {
             // Forward all other tools to child MCP (if child exists)
             if (!childClient) {
                 const tool_id = generateToolId(toolName, toolArgs, fileWriterConfig.toolAbbreviations);
-                const errorResponse = {
-                    tool_id,
-                    wroteToFile: false,
-                    error: `Tool ${toolName} not available in standalone mode (no child MCP)`
-                };
                 return {
                     content: [{
                             type: 'text',
-                            text: JSON.stringify(errorResponse, null, 2)
+                            text: JSON.stringify(createErrorResponse(tool_id, `Tool ${toolName} not available in standalone mode (no child MCP)`, toolArgs), null, 2)
                         }],
                     isError: true
                 };
@@ -372,11 +397,27 @@ async function main() {
                 name: toolName,
                 arguments: toolArgs
             });
+            // Check if child MCP returned an error
+            const childReturnedError = !!result.isError;
             // Process result through file writer to get unified response
             if (result.content && Array.isArray(result.content) && result.content.length > 0) {
                 const item = result.content[0];
                 if (item.type === 'text' && typeof item.text === 'string') {
                     const originalLength = item.text.length;
+                    // If child returned error, pass through directly without file writing
+                    if (childReturnedError) {
+                        const tool_id = generateToolId(toolName, toolArgs, fileWriterConfig.toolAbbreviations);
+                        if (ENABLE_LOGGING) {
+                            console.debug(`[mcp-proxy] Child MCP returned error for ${toolName}: ${item.text.substring(0, 100)}...`);
+                        }
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: JSON.stringify(createErrorResponse(tool_id, item.text, toolArgs), null, 2)
+                                }],
+                            isError: true
+                        };
+                    }
                     // Get unified response from file writer
                     const unifiedResponse = await fileWriter.handleResponse(toolName, toolArgs, {
                         content: [{ type: 'text', text: item.text }]
@@ -408,7 +449,8 @@ async function main() {
                             }
                         }
                     }
-                    // Return unified response as JSON
+                    // Add retry metadata and return unified response as JSON
+                    addRetryMetadata(unifiedResponse, toolArgs);
                     return {
                         content: [{
                                 type: 'text',
@@ -420,30 +462,21 @@ async function main() {
             }
             // Fallback: return result with generated tool_id
             const tool_id = generateToolId(toolName, toolArgs, fileWriterConfig.toolAbbreviations);
-            const fallbackResponse = {
-                tool_id,
-                wroteToFile: false,
-                outputContent: result
-            };
             return {
                 content: [{
                         type: 'text',
-                        text: JSON.stringify(fallbackResponse, null, 2)
-                    }]
+                        text: JSON.stringify(createContentResponse(tool_id, result, toolArgs), null, 2)
+                    }],
+                isError: childReturnedError
             };
         }
         catch (error) {
             console.error(`[mcp-proxy] Error executing tool ${toolName}:`, error);
             const tool_id = generateToolId(toolName, toolArgs, fileWriterConfig.toolAbbreviations);
-            const errorResponse = {
-                tool_id,
-                wroteToFile: false,
-                error: `Error executing ${toolName}: ${error.message || String(error)}`
-            };
             return {
                 content: [{
                         type: 'text',
-                        text: JSON.stringify(errorResponse, null, 2)
+                        text: JSON.stringify(createErrorResponse(tool_id, `Error executing ${toolName}: ${error.message || String(error)}`, toolArgs), null, 2)
                     }],
                 isError: true
             };

package/dist/jq/index.d.ts

@@ -14,6 +14,18 @@ export declare function createJqTool(config: JqConfig): {
         inputSchema: {
             type: string;
             properties: {
+                description: {
+                    readonly type: "string";
+                    readonly description: "Brief explanation of why you are calling this tool and what you expect to learn/achieve";
+                };
+                isRetryAttempt: {
+                    readonly type: "boolean";
+                    readonly description: "Set to true if this call is a follow-up attempt after a previous failure. This includes: (1) exact retries for transient errors, (2) corrected attempts fixing typos or parameters based on error feedback. Any call attempting to achieve the same goal as a failed call is a retry.";
+                };
+                originalToolId: {
+                    readonly type: "string";
+                    readonly description: "The tool_id from the FIRST failed attempt in this retry chain. Always reference the original tool_id, not intermediate failures. Example: if tool_id_1 fails, tool_id_2 (retry) fails, tool_id_3 (retry) succeeds - both tool_id_2 and tool_id_3 should reference tool_id_1. Required when isRetryAttempt is true.";
+                };
                 jq_query: {
                     type: string;
                     description: string;
@@ -22,10 +34,6 @@ export declare function createJqTool(config: JqConfig): {
                     type: string;
                     description: string;
                 };
-                description: {
-                    type: string;
-                    description: string;
-                };
             };
             required: string[];
         };

package/dist/jq/tool.d.ts

@@ -1,19 +1,19 @@
 import { z } from 'zod';
 /**
  * Zod schema for JQ query execution
+ * Note: Proxy params (description, isRetryAttempt, originalToolId) are handled
+ * by the proxy layer, not validated here. They're defined in JQ_TOOL_DEFINITION's
+ * inputSchema for LLM visibility.
  */
 export declare const ExecuteJqQuerySchema: z.ZodObject<{
     jq_query: z.ZodString;
     file_path: z.ZodString;
-    description: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     jq_query: string;
     file_path: string;
-    description?: string | undefined;
 }, {
     jq_query: string;
     file_path: string;
-    description?: string | undefined;
 }>;
 /**
  * Tool definition for JQ query execution with enhanced prompts
@@ -25,6 +25,18 @@ export declare const JQ_TOOL_DEFINITION: {
     inputSchema: {
         type: string;
         properties: {
+            description: {
+                readonly type: "string";
+                readonly description: "Brief explanation of why you are calling this tool and what you expect to learn/achieve";
+            };
+            isRetryAttempt: {
+                readonly type: "boolean";
+                readonly description: "Set to true if this call is a follow-up attempt after a previous failure. This includes: (1) exact retries for transient errors, (2) corrected attempts fixing typos or parameters based on error feedback. Any call attempting to achieve the same goal as a failed call is a retry.";
+            };
+            originalToolId: {
+                readonly type: "string";
+                readonly description: "The tool_id from the FIRST failed attempt in this retry chain. Always reference the original tool_id, not intermediate failures. Example: if tool_id_1 fails, tool_id_2 (retry) fails, tool_id_3 (retry) succeeds - both tool_id_2 and tool_id_3 should reference tool_id_1. Required when isRetryAttempt is true.";
+            };
             jq_query: {
                 type: string;
                 description: string;
@@ -33,10 +45,6 @@ export declare const JQ_TOOL_DEFINITION: {
                 type: string;
                 description: string;
             };
-            description: {
-                type: string;
-                description: string;
-            };
         };
         required: string[];
     };

package/dist/jq/tool.js

@@ -1,6 +1,10 @@
 import { z } from 'zod';
+import { PROXY_PARAMS } from '../types/index.js';
 /**
  * Zod schema for JQ query execution
+ * Note: Proxy params (description, isRetryAttempt, originalToolId) are handled
+ * by the proxy layer, not validated here. They're defined in JQ_TOOL_DEFINITION's
+ * inputSchema for LLM visibility.
  */
 export const ExecuteJqQuerySchema = z.object({
     jq_query: z
@@ -9,10 +13,6 @@ export const ExecuteJqQuerySchema = z.object({
     file_path: z
         .string()
         .describe('Absolute path starting with "/" pointing to the JSON or JSONL file to process. Must be a valid, existing file with .json or .jsonl extension. The file will be validated for existence and readability before processing.'),
-    description: z
-        .string()
-        .optional()
-        .describe('Brief explanation of why you are calling this tool and what you expect to learn/achieve'),
 });
 /**
  * Tool definition for JQ query execution with enhanced prompts
@@ -111,11 +111,8 @@ export const JQ_TOOL_DEFINITION = {
                 type: 'string',
                 description: 'Absolute path starting with "/" pointing to the JSON or JSONL file to process. Must be a valid, existing file with .json or .jsonl extension. The file will be validated for existence and readability before processing.',
             },
-            description: {
-                type: 'string',
-                description: 'Brief explanation of why you are calling this tool and what you expect to learn/achieve',
-            },
+            ...PROXY_PARAMS,
         },
-        required: ['jq_query', 'file_path'],
+        required: ['jq_query', 'file_path', 'isRetryAttempt'],
     },
 };

package/dist/types/index.d.ts

@@ -1,3 +1,21 @@
+/**
+ * Centralized proxy parameter definitions
+ * Used by both injectProxyParams and JQ tool definitions
+ */
+export declare const PROXY_PARAMS: {
+    readonly description: {
+        readonly type: "string";
+        readonly description: "Brief explanation of why you are calling this tool and what you expect to learn/achieve";
+    };
+    readonly isRetryAttempt: {
+        readonly type: "boolean";
+        readonly description: "Set to true if this call is a follow-up attempt after a previous failure. This includes: (1) exact retries for transient errors, (2) corrected attempts fixing typos or parameters based on error feedback. Any call attempting to achieve the same goal as a failed call is a retry.";
+    };
+    readonly originalToolId: {
+        readonly type: "string";
+        readonly description: "The tool_id from the FIRST failed attempt in this retry chain. Always reference the original tool_id, not intermediate failures. Example: if tool_id_1 fails, tool_id_2 (retry) fails, tool_id_3 (retry) succeeds - both tool_id_2 and tool_id_3 should reference tool_id_1. Required when isRetryAttempt is true.";
+    };
+};
 /**
  * Configuration for the file writer module
  */
@@ -35,27 +53,6 @@ export interface FileWriterResult {
         text: string;
     }>;
 }
-/**
- * Schema analysis result for a JSON structure
- */
-export interface JsonSchema {
-    type: string;
-    properties?: Record<string, unknown>;
-    items?: unknown;
-    length?: number;
-    _hasNulls?: boolean;
-    _keysAreNumeric?: boolean;
-    _accessPattern?: string;
-}
-/**
- * Nullable fields extracted from schema
- */
-export interface NullableFields {
-    /** Fields that are always null */
-    alwaysNull: string[];
-    /** Fields that can be null (mixed types) */
-    nullable: string[];
-}
 /**
  * Unified response format for all tool calls
  * Provides a consistent structure for LLM consumption
@@ -73,4 +70,8 @@ export interface UnifiedToolResponse {
     outputContent?: unknown;
     /** Error message if the tool call failed */
     error?: string;
+    /** Whether this was a retry attempt */
+    isRetryAttempt?: boolean;
+    /** The original tool_id this call is retrying */
+    originalToolId?: string;
 }

package/dist/types/index.js

@@ -1 +1,18 @@
-export {};
+/**
+ * Centralized proxy parameter definitions
+ * Used by both injectProxyParams and JQ tool definitions
+ */
+export const PROXY_PARAMS = {
+    description: {
+        type: 'string',
+        description: 'Brief explanation of why you are calling this tool and what you expect to learn/achieve'
+    },
+    isRetryAttempt: {
+        type: 'boolean',
+        description: 'Set to true if this call is a follow-up attempt after a previous failure. This includes: (1) exact retries for transient errors, (2) corrected attempts fixing typos or parameters based on error feedback. Any call attempting to achieve the same goal as a failed call is a retry.'
+    },
+    originalToolId: {
+        type: 'string',
+        description: 'The tool_id from the FIRST failed attempt in this retry chain. Always reference the original tool_id, not intermediate failures. Example: if tool_id_1 fails, tool_id_2 (retry) fails, tool_id_3 (retry) succeeds - both tool_id_2 and tool_id_3 should reference tool_id_1. Required when isRetryAttempt is true.'
+    }
+};

package/dist/utils/filename.d.ts

@@ -6,11 +6,3 @@
  * @returns Tool ID like "1697834567123_met_qry_a3b4c5"
  */
 export declare const generateToolId: (toolName: string, args: Record<string, unknown>, toolAbbreviations?: Record<string, string>) => string;
-/**
- * Generate LLM-friendly compact filename
- * @param toolName - Name of the tool that generated the data
- * @param args - Arguments passed to the tool
- * @param toolAbbreviations - Optional custom abbreviations for tool names
- * @returns Compact filename like "1697834567123_met_qry_a3b4c5.json"
- */
-export declare const generateCompactFilename: (toolName: string, args: Record<string, unknown>, toolAbbreviations?: Record<string, string>) => string;

package/dist/utils/filename.js

@@ -40,13 +40,3 @@ export const generateToolId = (toolName, args, toolAbbreviations) => {
     const argsHash = hashArgs(args);
     return `${timestamp}_${toolAbbrev}_${argsHash}`;
 };
-/**
- * Generate LLM-friendly compact filename
- * @param toolName - Name of the tool that generated the data
- * @param args - Arguments passed to the tool
- * @param toolAbbreviations - Optional custom abbreviations for tool names
- * @returns Compact filename like "1697834567123_met_qry_a3b4c5.json"
- */
-export const generateCompactFilename = (toolName, args, toolAbbreviations) => {
-    return `${generateToolId(toolName, args, toolAbbreviations)}.json`;
-};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anyshift/mcp-proxy",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Generic MCP proxy that adds truncation, file writing, and JQ capabilities to any MCP server",
   "type": "module",
   "main": "dist/index.js",