@anyshift/mcp-proxy 0.3.4 → 0.3.5

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,26 @@ 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;
+        }
     }
     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;
+}
 /**
  * ENVIRONMENT VARIABLE CONTRACT
  * =============================
@@ -299,8 +311,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 +335,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 +351,11 @@ async function main() {
                 });
                 // JQ tool returns directly, wrap in unified format
                 const tool_id = generateToolId(toolName, toolArgs, fileWriterConfig.toolAbbreviations);
-                const unifiedResponse = {
+                const unifiedResponse = addRetryMetadata({
                     tool_id,
                     wroteToFile: false,
                     outputContent: result.content?.[0]?.text
-                };
+                }, toolArgs);
                 return {
                     content: [{
                             type: 'text',
@@ -352,11 +367,11 @@ 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 = {
+                const errorResponse = addRetryMetadata({
                     tool_id,
                     wroteToFile: false,
                     error: `Tool ${toolName} not available in standalone mode (no child MCP)`
-                };
+                }, toolArgs);
                 return {
                     content: [{
                             type: 'text',
@@ -372,11 +387,32 @@ 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);
+                        const errorResponse = addRetryMetadata({
+                            tool_id,
+                            wroteToFile: false,
+                            error: item.text
+                        }, toolArgs);
+                        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(errorResponse, 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 +444,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,26 +457,27 @@ async function main() {
             }
             // Fallback: return result with generated tool_id
             const tool_id = generateToolId(toolName, toolArgs, fileWriterConfig.toolAbbreviations);
-            const fallbackResponse = {
+            const fallbackResponse = addRetryMetadata({
                 tool_id,
                 wroteToFile: false,
                 outputContent: result
-            };
+            }, toolArgs);
             return {
                 content: [{
                         type: 'text',
                         text: JSON.stringify(fallbackResponse, 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 = {
+            const errorResponse = addRetryMetadata({
                 tool_id,
                 wroteToFile: false,
                 error: `Error executing ${toolName}: ${error.message || String(error)}`
-            };
+            }, toolArgs);
             return {
                 content: [{
                         type: 'text',

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

@@ -6,14 +6,20 @@ export declare const ExecuteJqQuerySchema: z.ZodObject<{
     jq_query: z.ZodString;
     file_path: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
+    isRetryAttempt: z.ZodOptional<z.ZodBoolean>;
+    originalToolId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     jq_query: string;
     file_path: string;
     description?: string | undefined;
+    isRetryAttempt?: boolean | undefined;
+    originalToolId?: string | undefined;
 }, {
     jq_query: string;
     file_path: string;
     description?: string | undefined;
+    isRetryAttempt?: boolean | undefined;
+    originalToolId?: string | undefined;
 }>;
 /**
  * Tool definition for JQ query execution with enhanced prompts
@@ -25,6 +31,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 +51,6 @@ export declare const JQ_TOOL_DEFINITION: {
                 type: string;
                 description: string;
             };
-            description: {
-                type: string;
-                description: string;
-            };
         };
         required: string[];
     };

package/dist/jq/tool.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { PROXY_PARAMS } from '../types/index.js';
 /**
  * Zod schema for JQ query execution
  */
@@ -9,10 +10,9 @@ 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'),
+    description: z.string().optional().describe(PROXY_PARAMS.description.description),
+    isRetryAttempt: z.boolean().optional().describe(PROXY_PARAMS.isRetryAttempt.description),
+    originalToolId: z.string().optional().describe(PROXY_PARAMS.originalToolId.description),
 });
 /**
  * Tool definition for JQ query execution with enhanced prompts
@@ -111,10 +111,7 @@ 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'],
     },

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
  */
@@ -73,4 +91,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/package.json

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