@anyshift/mcp-proxy 0.3.0 → 0.3.1

package/dist/fileWriter/index.d.ts

@@ -1,4 +1,4 @@
-import { FileWriterConfig, FileWriterResult } from './types.js';
+import { FileWriterConfig, UnifiedToolResponse } from './types.js';
 /**
  * Create a file writer instance with the given configuration
  * @param config - File writer configuration
@@ -10,9 +10,9 @@ export declare function createFileWriter(config: FileWriterConfig): {
      * @param toolName - Name of the tool that generated the response
      * @param args - Arguments passed to the tool
      * @param responseData - The response data to potentially write to file
-     * @returns Either the original response or a file reference response
+     * @returns UnifiedToolResponse with consistent structure
      */
-    handleResponse: (toolName: string, args: Record<string, unknown>, responseData: unknown) => Promise<FileWriterResult | unknown>;
+    handleResponse: (toolName: string, args: Record<string, unknown>, responseData: unknown) => Promise<UnifiedToolResponse>;
 };
-export type { FileWriterConfig, FileWriterResult } from './types.js';
+export type { FileWriterConfig, FileWriterResult, UnifiedToolResponse } from './types.js';
 export { generateQueryAssistSchema } from './schema.js';

package/dist/fileWriter/index.js

@@ -11,7 +11,7 @@ export function createFileWriter(config) {
          * @param toolName - Name of the tool that generated the response
          * @param args - Arguments passed to the tool
          * @param responseData - The response data to potentially write to file
-         * @returns Either the original response or a file reference response
+         * @returns UnifiedToolResponse with consistent structure
          */
         handleResponse: async (toolName, args, responseData) => {
             return handleToolResponse(config, toolName, args, responseData);

package/dist/fileWriter/types.d.ts

@@ -1,4 +1,4 @@
 /**
  * Re-export FileWriterConfig and related types from the main types module
  */
-export type { FileWriterConfig, FileWriterResult } from '../types/index.js';
+export type { FileWriterConfig, FileWriterResult, UnifiedToolResponse } from '../types/index.js';

package/dist/fileWriter/writer.d.ts

@@ -1,10 +1,10 @@
-import { FileWriterConfig, FileWriterResult } from './types.js';
+import { FileWriterConfig, UnifiedToolResponse } from '../types/index.js';
 /**
  * Centralized response handler with file writing capability
  * @param config - File writer configuration
  * @param toolName - Name of the tool that generated the response
  * @param args - Arguments passed to the tool
  * @param responseData - The response data to potentially write to file
- * @returns Either the original response or a file reference response
+ * @returns UnifiedToolResponse with consistent structure
  */
-export declare function handleToolResponse(config: FileWriterConfig, toolName: string, args: Record<string, unknown>, responseData: unknown): Promise<FileWriterResult | unknown>;
+export declare function handleToolResponse(config: FileWriterConfig, toolName: string, args: Record<string, unknown>, responseData: unknown): Promise<UnifiedToolResponse>;

package/dist/fileWriter/writer.js

@@ -1,6 +1,6 @@
 import fs from 'fs/promises';
 import path from 'path';
-import { generateCompactFilename } from '../utils/filename.js';
+import { generateToolId } from '../utils/filename.js';
 import { generateQueryAssistSchema } from './schema.js';
 // Default minimum character count to trigger file writing
 const DEFAULT_MIN_CHARS = 1000;
@@ -115,14 +115,23 @@ const extractContentForFile = (responseData) => {
     let parsedForSchema = null;
     if (rawText) {
         try {
-            // Try to parse the raw text as JSON for prettier formatting
-            let jsonText = rawText;
-            // Extract JSON from common response patterns
-            const jsonMatch = rawText.match(/:\s*(\{.*\}|\[.*\])$/s);
-            if (jsonMatch) {
-                jsonText = jsonMatch[1];
+            // Try to parse the raw text directly as JSON first
+            let parsed;
+            try {
+                parsed = JSON.parse(rawText);
+            }
+            catch {
+                // If direct parsing fails, try extracting JSON from prefixed patterns
+                // like "Listed incidents: {...}" or "Queried metrics data: [...]"
+                // Only match colon at the START, before any JSON content
+                const prefixMatch = rawText.match(/^[^[{]*?:\s*(\{.*\}|\[.*\])$/s);
+                if (prefixMatch) {
+                    parsed = JSON.parse(prefixMatch[1]);
+                }
+                else {
+                    throw new Error('Could not parse as JSON');
+                }
             }
-            const parsed = JSON.parse(jsonText);
             parsedForSchema = parsed;
             // Remove pagination-related fields before writing
             const { pagination, has_more, next_page, previous_page, page, page_size, total_pages, ...cleanData } = parsed;
@@ -157,77 +166,87 @@ const extractContentForFile = (responseData) => {
  * @param toolName - Name of the tool that generated the response
  * @param args - Arguments passed to the tool
  * @param responseData - The response data to potentially write to file
- * @returns Either the original response or a file reference response
+ * @returns UnifiedToolResponse with consistent structure
  */
 export async function handleToolResponse(config, toolName, args, responseData) {
+    // Generate tool_id for all responses
+    const tool_id = generateToolId(toolName, args, config.toolAbbreviations);
     // Some tools should always return directly to AI (never write to file)
     if (toolName === 'execute_jq_query' || toolName === 'get_label_schema') {
-        return responseData;
+        const { contentToWrite, parsedForSchema } = extractContentForFile(responseData);
+        return {
+            tool_id,
+            wroteToFile: false,
+            outputContent: parsedForSchema ?? contentToWrite,
+        };
     }
-    // If there's an error, return proper MCP error response (never write errors to file)
+    // If there's an error, return error in unified format
     if (isErrorResponse(responseData)) {
         const errorMessage = extractErrorMessage(responseData);
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error: ${errorMessage}`,
-                },
-            ],
-            isError: true,
+            tool_id,
+            wroteToFile: false,
+            error: errorMessage,
         };
     }
-    // If file writing is disabled, just return the response
-    if (!config.enabled || !config.outputPath) {
-        return responseData;
-    }
     // Extract the content that will be written to file
     // This ensures we count the EXACT same content that will be written
     const { contentToWrite, parsedForSchema } = extractContentForFile(responseData);
+    // If file writing is disabled, return content directly
+    if (!config.enabled || !config.outputPath) {
+        return {
+            tool_id,
+            wroteToFile: false,
+            outputContent: parsedForSchema ?? contentToWrite,
+        };
+    }
     // Check character count threshold - if response is too short, return directly
     const contentLength = contentToWrite.length;
     const minChars = config.minCharsForWrite ?? DEFAULT_MIN_CHARS;
     if (contentLength < minChars) {
-        return responseData;
+        return {
+            tool_id,
+            wroteToFile: false,
+            outputContent: parsedForSchema ?? contentToWrite,
+        };
     }
     // Success case: write to file
     try {
-        // Create compact, LLM-friendly filename
-        const filename = generateCompactFilename(toolName, args, config.toolAbbreviations);
+        const filename = `${tool_id}.json`;
         const filepath = path.join(config.outputPath, filename);
         // Ensure output directory exists
         await fs.mkdir(config.outputPath, { recursive: true });
         // Write the exact content we counted
         await fs.writeFile(filepath, contentToWrite);
         // Generate query-assist schema if we have valid JSON
-        let schemaInfo = '';
+        let fileSchema;
         if (parsedForSchema) {
             // Use the clean data (without pagination) for schema analysis
             const { pagination, has_more, next_page, previous_page, page, page_size, total_pages, ...cleanData } = parsedForSchema;
             // Generate compact query-assist schema using config values
             // Pass contentLength to avoid re-stringifying large payloads
-            schemaInfo = `\n\n${generateQueryAssistSchema(cleanData, {
+            fileSchema = generateQueryAssistSchema(cleanData, {
                 maxDepth: config.schemaMaxDepth ?? 2,
                 maxPaths: config.schemaMaxPaths ?? 20,
                 maxKeys: config.schemaMaxKeys ?? 50,
                 dataSize: contentLength
-            })}`;
+            });
         }
-        // Count lines in the content
-        const lineCount = contentToWrite.split('\n').length;
-        // Return success message with file path, size, lines, and schema
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `📄 File: ${filepath}\nSize: ${contentToWrite.length} characters | Lines: ${lineCount}${schemaInfo}`,
-                },
-            ],
+            tool_id,
+            wroteToFile: true,
+            filePath: filepath,
+            fileSchema,
         };
     }
     catch (error) {
-        // If file writing fails, return the original response
+        // If file writing fails, return the content directly with error note
         console.error(`[handleToolResponse] Error writing file:`, error);
-        return responseData;
+        return {
+            tool_id,
+            wroteToFile: false,
+            outputContent: parsedForSchema ?? contentToWrite,
+            error: `File write failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
     }
 }

package/dist/index.js

@@ -22,6 +22,36 @@ import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprot
 import { createJqTool } from './jq/index.js';
 import { truncateResponseIfNeeded } from './truncation/index.js';
 import { createFileWriter } from './fileWriter/index.js';
+import { generateToolId } from './utils/filename.js';
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+/**
+ * Inject 'description' parameter into a tool's inputSchema
+ * This ensures LLMs explain why they're calling each tool
+ */
+function injectDescriptionParam(tool) {
+    // Clone the tool to avoid mutating the original
+    const modifiedTool = { ...tool };
+    if (!modifiedTool.inputSchema) {
+        modifiedTool.inputSchema = { type: 'object', properties: {} };
+    }
+    // Clone inputSchema
+    modifiedTool.inputSchema = { ...modifiedTool.inputSchema };
+    if (!modifiedTool.inputSchema.properties) {
+        modifiedTool.inputSchema.properties = {};
+    }
+    // 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'
+        };
+    }
+    return modifiedTool;
+}
 /**
  * ENVIRONMENT VARIABLE CONTRACT
  * =============================
@@ -267,11 +297,13 @@ async function main() {
         });
     }
     // ------------------------------------------------------------------------
-    // 5. REGISTER ALL TOOLS (CHILD + PROXY)
+    // 5. REGISTER ALL TOOLS (CHILD + PROXY) WITH DESCRIPTION INJECTION
     // ------------------------------------------------------------------------
+    // Inject 'description' parameter into all child tools
+    const enhancedChildTools = childToolsResponse.tools.map(injectDescriptionParam);
     const allTools = [
-        ...childToolsResponse.tools,
-        ...(jqTool ? [jqTool.toolDefinition] : [])
+        ...enhancedChildTools,
+        ...(jqTool ? [jqTool.toolDefinition] : []) // JQ tool already has description param
     ];
     console.debug(`[mcp-proxy] Exposing ${allTools.length} tools total (${childToolsResponse.tools.length} from child${jqTool ? ' + 1 JQ' : ''})`);
     // ------------------------------------------------------------------------
@@ -281,13 +313,16 @@ async function main() {
         return { tools: allTools };
     });
     // ------------------------------------------------------------------------
-    // 7. HANDLE TOOL CALL REQUESTS (WITH TRUNCATION & FILE WRITING)
+    // 7. HANDLE TOOL CALL REQUESTS (WITH UNIFIED RESPONSE FORMAT)
     // ------------------------------------------------------------------------
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const toolName = request.params.name;
         const toolArgs = request.params.arguments || {};
         if (ENABLE_LOGGING) {
             console.debug(`[mcp-proxy] Tool call: ${toolName}`);
+            if (toolArgs.description) {
+                console.debug(`[mcp-proxy] Description: ${toolArgs.description}`);
+            }
         }
         try {
             let result;
@@ -299,73 +334,116 @@ async function main() {
                 result = await jqTool.handler({
                     params: { arguments: toolArgs }
                 });
+                // 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
+                };
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(unifiedResponse, null, 2)
+                        }],
+                    isError: result.isError
+                };
             }
-            else {
-                // Forward all other tools to child MCP (if child exists)
-                if (!childClient) {
-                    return {
-                        content: [{
-                                type: 'text',
-                                text: `Error: Tool ${toolName} not available in standalone mode (no child MCP)`
-                            }],
-                        isError: true
-                    };
-                }
-                if (ENABLE_LOGGING) {
-                    console.debug(`[mcp-proxy] Forwarding to child MCP: ${toolName}`);
-                }
-                result = await childClient.callTool({
-                    name: toolName,
-                    arguments: toolArgs
-                });
+            // 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)
+                        }],
+                    isError: true
+                };
+            }
+            if (ENABLE_LOGGING) {
+                console.debug(`[mcp-proxy] Forwarding to child MCP: ${toolName}`);
             }
-            // Apply file writing and truncation to text responses
+            result = await childClient.callTool({
+                name: toolName,
+                arguments: toolArgs
+            });
+            // Process result through file writer to get unified response
             if (result.content && Array.isArray(result.content) && result.content.length > 0) {
-                for (let i = 0; i < result.content.length; i++) {
-                    const item = result.content[i];
-                    if (item.type === 'text' && typeof item.text === 'string') {
-                        const originalText = item.text;
-                        const originalLength = item.text.length;
-                        let fileWasWritten = false;
-                        // Step 1: Try file writing first (if enabled)
-                        // This writes the FULL original data to file
-                        if (fileWriterConfig.enabled) {
-                            const fileResult = await fileWriter.handleResponse(toolName, toolArgs, {
-                                content: [{ type: 'text', text: item.text }]
-                            });
-                            // Check if file was actually written (file reference returned)
-                            if (fileResult && fileResult.content && Array.isArray(fileResult.content) &&
-                                fileResult.content.length > 0 && fileResult.content[0].type === 'text') {
-                                const resultText = fileResult.content[0].text;
-                                // File reference contains "📄 File:" - this means file was written
-                                if (resultText.includes('📄 File:')) {
-                                    item.text = resultText;
-                                    fileWasWritten = true;
-                                    if (ENABLE_LOGGING) {
-                                        console.debug(`[mcp-proxy] File writing applied for ${toolName} (${originalLength} chars written to file)`);
-                                    }
-                                }
-                            }
+                const item = result.content[0];
+                if (item.type === 'text' && typeof item.text === 'string') {
+                    const originalLength = item.text.length;
+                    // Get unified response from file writer
+                    const unifiedResponse = await fileWriter.handleResponse(toolName, toolArgs, {
+                        content: [{ type: 'text', text: item.text }]
+                    });
+                    if (ENABLE_LOGGING) {
+                        if (unifiedResponse.wroteToFile) {
+                            console.debug(`[mcp-proxy] File written for ${toolName} (${originalLength} chars) → ${unifiedResponse.filePath}`);
                         }
-                        // Step 2: Apply truncation only if file was NOT written
-                        // (File references are small and don't need truncation)
-                        if (!fileWasWritten) {
-                            item.text = truncateResponseIfNeeded(truncationConfig, item.text);
-                            if (item.text.length < originalLength && ENABLE_LOGGING) {
-                                console.debug(`[mcp-proxy] Truncated response: ${originalLength} → ${item.text.length} chars`);
+                        else {
+                            console.debug(`[mcp-proxy] Response for ${toolName} (${originalLength} chars) returned directly`);
+                        }
+                    }
+                    // If not written to file, apply truncation to outputContent
+                    if (!unifiedResponse.wroteToFile && unifiedResponse.outputContent) {
+                        const contentStr = typeof unifiedResponse.outputContent === 'string'
+                            ? unifiedResponse.outputContent
+                            : JSON.stringify(unifiedResponse.outputContent);
+                        const truncated = truncateResponseIfNeeded(truncationConfig, contentStr);
+                        if (truncated.length < contentStr.length) {
+                            if (ENABLE_LOGGING) {
+                                console.debug(`[mcp-proxy] Truncated response: ${contentStr.length} → ${truncated.length} chars`);
+                            }
+                            // Re-parse if it was JSON, otherwise keep as string
+                            try {
+                                unifiedResponse.outputContent = JSON.parse(truncated);
+                            }
+                            catch {
+                                unifiedResponse.outputContent = truncated;
                             }
                         }
                     }
+                    // Return unified response as JSON
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify(unifiedResponse, null, 2)
+                            }],
+                        isError: !!unifiedResponse.error
+                    };
                 }
             }
-            return result;
+            // 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)
+                    }]
+            };
         }
         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: `Error executing ${toolName}: ${error.message || String(error)}`
+                        text: JSON.stringify(errorResponse, null, 2)
                     }],
                 isError: true
             };

package/dist/jq/tool.js

@@ -12,7 +12,7 @@ export const ExecuteJqQuerySchema = z.object({
     description: z
         .string()
         .optional()
-        .describe('Optional description; a short explanation of the purpose of the query'),
+        .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
@@ -113,7 +113,7 @@ export const JQ_TOOL_DEFINITION = {
             },
             description: {
                 type: 'string',
-                description: 'Optional description; a short explanation of the purpose of the query',
+                description: 'Brief explanation of why you are calling this tool and what you expect to learn/achieve',
             },
         },
         required: ['jq_query', 'file_path'],

package/dist/types/index.d.ts

@@ -56,3 +56,21 @@ export interface NullableFields {
     /** Fields that can be null (mixed types) */
     nullable: string[];
 }
+/**
+ * Unified response format for all tool calls
+ * Provides a consistent structure for LLM consumption
+ */
+export interface UnifiedToolResponse {
+    /** LLM-friendly unique identifier for this tool call */
+    tool_id: string;
+    /** Whether the response was written to a file */
+    wroteToFile: boolean;
+    /** Path to the file (only present if wroteToFile is true) */
+    filePath?: string;
+    /** Schema/structure guide for the data (only present if wroteToFile is true) */
+    fileSchema?: string;
+    /** The actual response content (only present if wroteToFile is false) */
+    outputContent?: unknown;
+    /** Error message if the tool call failed */
+    error?: string;
+}

package/dist/utils/filename.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Generate LLM-friendly tool ID (without file extension)
+ * @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 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

package/dist/utils/filename.js

@@ -28,15 +28,25 @@ const hashArgs = (args) => {
         .substring(0, 6);
 };
 /**
- * Generate LLM-friendly compact filename
+ * Generate LLM-friendly tool ID (without file extension)
  * @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"
+ * @returns Tool ID like "1697834567123_met_qry_a3b4c5"
  */
-export const generateCompactFilename = (toolName, args, toolAbbreviations) => {
+export const generateToolId = (toolName, args, toolAbbreviations) => {
     const timestamp = generateCompactTimestamp();
     const toolAbbrev = toolAbbreviations?.[toolName] || toolName.substring(0, 6);
     const argsHash = hashArgs(args);
-    return `${timestamp}_${toolAbbrev}_${argsHash}.json`;
+    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.0",
+  "version": "0.3.1",
   "description": "Generic MCP proxy that adds truncation, file writing, and JQ capabilities to any MCP server",
   "type": "module",
   "main": "dist/index.js",
@@ -13,7 +13,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.7.0",
+    "@modelcontextprotocol/sdk": "^1.24.0",
     "zod": "^3.24.2"
   },
   "devDependencies": {