@anyshift/mcp-proxy 0.3.0 → 0.3.2

package/dist/__tests__/unit/dynatrace.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/unit/dynatrace.test.js

@@ -0,0 +1,204 @@
+import { describe, it, expect } from '@jest/globals';
+import { parseDynatraceDqlResponse, isDynatraceDqlTool, } from '../../fileWriter/dynatrace.js';
+// Type guards for test assertions
+function isDqlSuccess(result) {
+    return (typeof result === 'object' &&
+        result !== null &&
+        'isDynatraceDql' in result &&
+        result.isDynatraceDql === true &&
+        'isError' in result &&
+        result.isError === false);
+}
+function isDqlError(result) {
+    return (typeof result === 'object' &&
+        result !== null &&
+        'isDynatraceDql' in result &&
+        result.isDynatraceDql === true &&
+        'isError' in result &&
+        result.isError === true);
+}
+describe('Dynatrace DQL Parser', () => {
+    describe('isDynatraceDqlTool', () => {
+        it('should return true for execute_dql tool', () => {
+            expect(isDynatraceDqlTool('execute_dql')).toBe(true);
+        });
+        it('should return false for other tools', () => {
+            expect(isDynatraceDqlTool('execute_jq_query')).toBe(false);
+            expect(isDynatraceDqlTool('get_metrics')).toBe(false);
+            expect(isDynatraceDqlTool('list_entities')).toBe(false);
+        });
+    });
+    describe('parseDynatraceDqlResponse - Success Responses', () => {
+        const successResponse = `📊 **DQL Query Results**
+
+- **Scanned Records:** 3,988,787
+- **Scanned Bytes:** 10.00 GB (Session total: 10.00 GB / 100 GB budget, 10.0% used)
+    💡 **Moderate Data Usage:** This query scanned 10.00 GB of data.
+- **⚠️ Sampling Used:** Yes (results may be approximate)
+
+📋 **Query Results**: (50 records):
+
+\`\`\`json
+[
+  {
+    "faas.name": "compassdigital-order-v1-root",
+    "logCount": "861021"
+  },
+  {
+    "faas.name": "cdl-shoppingcart-v1-root",
+    "logCount": "421993"
+  }
+]
+\`\`\``;
+        it('should parse a success response correctly', () => {
+            const result = parseDynatraceDqlResponse(successResponse);
+            expect(result.isDynatraceDql).toBe(true);
+            expect(isDqlSuccess(result)).toBe(true);
+            if (isDqlSuccess(result)) {
+                expect(result.metadata.scannedRecords).toBe(3988787);
+                expect(result.metadata.scannedBytes).toBe('10.00 GB');
+                expect(result.metadata.sessionTotal).toBe('10.00 GB');
+                expect(result.metadata.sessionBudget).toBe('100 GB');
+                expect(result.metadata.budgetUsedPercent).toBe('10.0%');
+                expect(result.metadata.samplingUsed).toBe(true);
+                expect(result.metadata.recordCount).toBe(50);
+                // dataUsageNote is optional, may or may not be present depending on formatting
+                expect(result.data).toBeInstanceOf(Array);
+                expect(result.data.length).toBe(2);
+                expect(result.data[0]['faas.name']).toBe('compassdigital-order-v1-root');
+            }
+        });
+        it('should parse response without sampling info', () => {
+            const responseNoSampling = `📊 **DQL Query Results**
+
+- **Scanned Records:** 1,000
+- **Scanned Bytes:** 100 MB (Session total: 100 MB / 100 GB budget, 0.1% used)
+
+📋 **Query Results**: (10 records):
+
+\`\`\`json
+[{"id": 1}]
+\`\`\``;
+            const result = parseDynatraceDqlResponse(responseNoSampling);
+            expect(result.isDynatraceDql).toBe(true);
+            if (isDqlSuccess(result)) {
+                expect(result.metadata.samplingUsed).toBeUndefined();
+                expect(result.metadata.recordCount).toBe(10);
+            }
+        });
+        it('should handle single record count', () => {
+            const responseSingleRecord = `📊 **DQL Query Results**
+
+- **Scanned Records:** 100
+- **Scanned Bytes:** 1 MB
+
+📋 **Query Results**: (1 record):
+
+\`\`\`json
+{"id": 1}
+\`\`\``;
+            const result = parseDynatraceDqlResponse(responseSingleRecord);
+            expect(result.isDynatraceDql).toBe(true);
+            if (isDqlSuccess(result)) {
+                expect(result.metadata.recordCount).toBe(1);
+            }
+        });
+    });
+    describe('parseDynatraceDqlResponse - Error Responses', () => {
+        const errorResponse = `Client Request Error: PARAMETER_MUST_NOT_BE_AN_AGGREGATION. exceptionType: "DQL-SYNTAX-ERROR". syntaxErrorPosition: {"start":{"column":113,"index":112,"line":1},"end":{"column":119,"index":118,"line":1}}. errorType: "PARAMETER_MUST_NOT_BE_AN_AGGREGATION". errorMessage: "Aggregations aren't allowed here, but \`count()\` is an aggregation function.". arguments: ["count()"]. queryString: "fetch logs, scanLimitGBytes: 10, samplingRatio: 100, from: now()-7d | summarize count(), by: {faas.name} | sort count() desc | limit 50". errorMessageFormatSpecifierTypes: ["INPUT_QUERY_PART"]. errorMessageFormat: "Aggregations aren't allowed here, but \`%1$s\` is an aggregation function.". queryId: "9be6a579-545c-4157-957f-5d8d39129a78" with HTTP status: 400.  (body: {"error":{"message":"PARAMETER_MUST_NOT_BE_AN_AGGREGATION","details":{"exceptionType":"DQL-SYNTAX-ERROR"}}})`;
+        it('should parse an error response correctly', () => {
+            const result = parseDynatraceDqlResponse(errorResponse);
+            expect(result.isDynatraceDql).toBe(true);
+            expect(isDqlError(result)).toBe(true);
+            if (isDqlError(result)) {
+                expect(result.errorMessage).toContain("Aggregations aren't allowed here");
+                expect(result.errorMessage).toContain('count()');
+                expect(result.errorMessage).toContain('Query:');
+                expect(result.errorMessage).toContain('HTTP 400');
+            }
+        });
+        it('should extract error type when no errorMessage field', () => {
+            const simpleError = `Client Request Error: INVALID_QUERY. exceptionType: "DQL-ERROR". with HTTP status: 400.`;
+            const result = parseDynatraceDqlResponse(simpleError);
+            expect(result.isDynatraceDql).toBe(true);
+            expect(isDqlError(result)).toBe(true);
+            if (isDqlError(result)) {
+                expect(result.errorMessage).toContain('INVALID_QUERY');
+                expect(result.errorMessage).toContain('HTTP 400');
+            }
+        });
+    });
+    describe('parseDynatraceDqlResponse - Non-Dynatrace Responses', () => {
+        it('should return isDynatraceDql: false for regular JSON', () => {
+            const regularJson = '{"status": "success", "data": [1, 2, 3]}';
+            const result = parseDynatraceDqlResponse(regularJson);
+            expect(result.isDynatraceDql).toBe(false);
+        });
+        it('should return isDynatraceDql: false for plain text', () => {
+            const plainText = 'This is just some plain text response';
+            const result = parseDynatraceDqlResponse(plainText);
+            expect(result.isDynatraceDql).toBe(false);
+        });
+        it('should return isDynatraceDql: false for other MCP tool outputs', () => {
+            const otherToolOutput = `Listed metrics:
+- metric.cpu.usage
+- metric.memory.used`;
+            const result = parseDynatraceDqlResponse(otherToolOutput);
+            expect(result.isDynatraceDql).toBe(false);
+        });
+    });
+    describe('Edge Cases', () => {
+        it('should handle malformed JSON in success response', () => {
+            const malformedJson = `📊 **DQL Query Results**
+
+- **Scanned Records:** 100
+
+📋 **Query Results**: (1 record):
+
+\`\`\`json
+{this is not valid json}
+\`\`\``;
+            const result = parseDynatraceDqlResponse(malformedJson);
+            expect(result.isDynatraceDql).toBe(true);
+            if (isDqlSuccess(result)) {
+                // Should still parse metadata
+                expect(result.metadata.scannedRecords).toBe(100);
+                // Data should be the raw text from code block since JSON parsing failed
+                expect(result.data).toBe('{this is not valid json}');
+            }
+        });
+        it('should handle empty JSON array', () => {
+            const emptyResults = `📊 **DQL Query Results**
+
+- **Scanned Records:** 0
+
+📋 **Query Results**: (0 records):
+
+\`\`\`json
+[]
+\`\`\``;
+            const result = parseDynatraceDqlResponse(emptyResults);
+            expect(result.isDynatraceDql).toBe(true);
+            if (isDqlSuccess(result)) {
+                expect(result.metadata.scannedRecords).toBe(0);
+                expect(result.metadata.recordCount).toBe(0);
+                expect(result.data).toEqual([]);
+            }
+        });
+        it('should handle response with no code block', () => {
+            const noCodeBlock = `📊 **DQL Query Results**
+
+- **Scanned Records:** 100
+
+📋 **Query Results**: (0 records):
+
+No data found.`;
+            const result = parseDynatraceDqlResponse(noCodeBlock);
+            expect(result.isDynatraceDql).toBe(true);
+            if (isDqlSuccess(result)) {
+                expect(result.metadata.scannedRecords).toBe(100);
+                expect(result.data).toBeNull();
+            }
+        });
+    });
+});

package/dist/fileWriter/dynatrace.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Dynatrace DQL Response Parser
+ *
+ * Parses Dynatrace DQL query responses to extract:
+ * - Metadata (scanned records, bytes, sampling info)
+ * - Data (the actual query results)
+ * - Errors (if the query failed)
+ */
+export interface DynatraceDqlMetadata {
+    scannedRecords?: number;
+    scannedBytes?: string;
+    sessionTotal?: string;
+    sessionBudget?: string;
+    budgetUsedPercent?: string;
+    dataUsageNote?: string;
+    samplingUsed?: boolean;
+    recordCount?: number;
+}
+export interface DynatraceDqlParsedResponse {
+    isDynatraceDql: true;
+    isError: false;
+    metadata: DynatraceDqlMetadata;
+    data: unknown;
+}
+export interface DynatraceDqlErrorResponse {
+    isDynatraceDql: true;
+    isError: true;
+    errorMessage: string;
+}
+export interface NotDynatraceDqlResponse {
+    isDynatraceDql: false;
+}
+export type DynatraceParseResult = DynatraceDqlParsedResponse | DynatraceDqlErrorResponse | NotDynatraceDqlResponse;
+/**
+ * Parse a Dynatrace DQL response
+ * @param text - The raw text response from Dynatrace
+ * @returns Parsed response with metadata/data or error, or indication that it's not a Dynatrace response
+ */
+export declare function parseDynatraceDqlResponse(text: string): DynatraceParseResult;
+/**
+ * Check if a tool name is a Dynatrace DQL tool
+ */
+export declare function isDynatraceDqlTool(toolName: string): boolean;

package/dist/fileWriter/dynatrace.js

@@ -0,0 +1,173 @@
+/**
+ * Dynatrace DQL Response Parser
+ *
+ * Parses Dynatrace DQL query responses to extract:
+ * - Metadata (scanned records, bytes, sampling info)
+ * - Data (the actual query results)
+ * - Errors (if the query failed)
+ */
+/**
+ * Detect if a text response is a Dynatrace DQL error
+ */
+function isDynatraceError(text) {
+    return text.includes('Client Request Error:') && text.includes('HTTP status:');
+}
+/**
+ * Detect if a text response is a Dynatrace DQL success response
+ */
+function isDynatraceSuccess(text) {
+    return text.includes('📊 **DQL Query Results**');
+}
+/**
+ * Parse a Dynatrace error response - keeps more context for debugging
+ */
+function parseErrorResponse(text) {
+    // The error format is:
+    // Client Request Error: ERROR_TYPE. exceptionType: "...". ... errorMessage: "...". ...
+    const parts = [];
+    // Extract error type
+    const errorTypeMatch = text.match(/Client Request Error:\s*([^.]+)/);
+    if (errorTypeMatch) {
+        parts.push(errorTypeMatch[1].trim());
+    }
+    // Extract the human-readable error message
+    const errorMessageMatch = text.match(/errorMessage:\s*"([^"]+)"/);
+    if (errorMessageMatch) {
+        parts.push(errorMessageMatch[1]);
+    }
+    // Extract the query string for context
+    const queryStringMatch = text.match(/queryString:\s*"([^"]+)"/);
+    if (queryStringMatch) {
+        parts.push(`Query: ${queryStringMatch[1]}`);
+    }
+    // Extract syntax error position if available
+    const positionMatch = text.match(/syntaxErrorPosition:\s*(\{[^}]+\})/);
+    if (positionMatch) {
+        try {
+            const pos = JSON.parse(positionMatch[1]);
+            if (pos.start) {
+                parts.push(`Position: line ${pos.start.line}, column ${pos.start.column}`);
+            }
+        }
+        catch {
+            // Ignore JSON parse errors
+        }
+    }
+    // Extract HTTP status
+    const httpStatusMatch = text.match(/HTTP status:\s*(\d+)/);
+    if (httpStatusMatch) {
+        parts.push(`HTTP ${httpStatusMatch[1]}`);
+    }
+    if (parts.length > 0) {
+        return parts.join('. ');
+    }
+    // Last fallback: return a truncated version of the raw error
+    const firstLine = text.split('\n')[0];
+    if (firstLine.length > 500) {
+        return firstLine.substring(0, 500) + '...';
+    }
+    return firstLine;
+}
+/**
+ * Parse metadata from a Dynatrace DQL success response
+ */
+function parseMetadata(text) {
+    const metadata = {};
+    // Parse scanned records: "- **Scanned Records:** 3,988,787"
+    const scannedRecordsMatch = text.match(/\*\*Scanned Records:\*\*\s*([\d,]+)/);
+    if (scannedRecordsMatch) {
+        metadata.scannedRecords = parseInt(scannedRecordsMatch[1].replace(/,/g, ''), 10);
+    }
+    // Parse scanned bytes: "- **Scanned Bytes:** 10.00 GB (Session total: 10.00 GB / 100 GB budget, 10.0% used)"
+    const scannedBytesMatch = text.match(/\*\*Scanned Bytes:\*\*\s*([^\n(]+)/);
+    if (scannedBytesMatch) {
+        metadata.scannedBytes = scannedBytesMatch[1].trim();
+    }
+    // Parse session total and budget from the parenthetical
+    const sessionMatch = text.match(/Session total:\s*([^/]+)\/\s*([^,]+)\s*budget,\s*([^)%]+)%\s*used/);
+    if (sessionMatch) {
+        metadata.sessionTotal = sessionMatch[1].trim();
+        metadata.sessionBudget = sessionMatch[2].trim();
+        metadata.budgetUsedPercent = sessionMatch[3].trim() + '%';
+    }
+    // Parse data usage note: "    💡 **Moderate Data Usage:** This query scanned 10.00 GB of data."
+    const dataUsageMatch = text.match(/\s*💡\s*\*\*([^*]+)\*\*:\s*([^\n]+)/);
+    if (dataUsageMatch) {
+        metadata.dataUsageNote = `${dataUsageMatch[1]}: ${dataUsageMatch[2].trim()}`;
+    }
+    // Parse sampling info: "- **⚠️ Sampling Used:** Yes"
+    const samplingMatch = text.match(/\*\*⚠️?\s*Sampling Used:\*\*\s*(Yes|No)/i);
+    if (samplingMatch) {
+        metadata.samplingUsed = samplingMatch[1].toLowerCase() === 'yes';
+    }
+    // Parse record count: "📋 **Query Results**: (50 records):"
+    const recordCountMatch = text.match(/\*\*Query Results\*\*[^(]*\((\d+)\s*records?\)/);
+    if (recordCountMatch) {
+        metadata.recordCount = parseInt(recordCountMatch[1], 10);
+    }
+    return metadata;
+}
+/**
+ * Extract JSON data from a Dynatrace DQL success response
+ */
+function extractData(text) {
+    // The JSON is in a code block: ```json\n[...]\n```
+    const jsonBlockMatch = text.match(/```json\s*\n([\s\S]*?)\n```/);
+    if (jsonBlockMatch) {
+        try {
+            return JSON.parse(jsonBlockMatch[1]);
+        }
+        catch {
+            // If JSON parsing fails, return the raw text from the block
+            return jsonBlockMatch[1];
+        }
+    }
+    // Fallback: try to find a JSON array or object anywhere after the header
+    const jsonMatch = text.match(/(\[[\s\S]*\]|\{[\s\S]*\})/);
+    if (jsonMatch) {
+        try {
+            return JSON.parse(jsonMatch[1]);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Parse a Dynatrace DQL response
+ * @param text - The raw text response from Dynatrace
+ * @returns Parsed response with metadata/data or error, or indication that it's not a Dynatrace response
+ */
+export function parseDynatraceDqlResponse(text) {
+    // Check if it's an error response
+    if (isDynatraceError(text)) {
+        return {
+            isDynatraceDql: true,
+            isError: true,
+            errorMessage: parseErrorResponse(text),
+        };
+    }
+    // Check if it's a success response
+    if (isDynatraceSuccess(text)) {
+        const metadata = parseMetadata(text);
+        const data = extractData(text);
+        return {
+            isDynatraceDql: true,
+            isError: false,
+            metadata,
+            data,
+        };
+    }
+    // Not a Dynatrace DQL response
+    return {
+        isDynatraceDql: false,
+    };
+}
+/**
+ * Check if a tool name is a Dynatrace DQL tool
+ */
+export function isDynatraceDqlTool(toolName) {
+    // The tool that executes DQL queries
+    return toolName === 'execute_dql';
+}

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,7 +1,8 @@
 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';
+import { parseDynatraceDqlResponse, isDynatraceDqlTool, } from './dynatrace.js';
 // Default minimum character count to trigger file writing
 const DEFAULT_MIN_CHARS = 1000;
 /**
@@ -115,14 +116,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;
@@ -151,83 +161,179 @@ const extractContentForFile = (responseData) => {
     }
     return { contentToWrite, parsedForSchema };
 };
+/**
+ * Handle Dynatrace DQL response - extracts metadata and data, writes structured file
+ * @param config - File writer configuration
+ * @param tool_id - Generated tool ID
+ * @param parsedDql - Parsed DQL response with metadata and data
+ * @returns UnifiedToolResponse or null if should fall through to default handling
+ */
+async function handleDynatraceDqlResponse(config, tool_id, parsedDql) {
+    // Build the structured content to write
+    const structuredContent = {
+        metadata: parsedDql.metadata,
+        data: parsedDql.data,
+    };
+    const contentToWrite = JSON.stringify(structuredContent, null, 2);
+    const contentLength = contentToWrite.length;
+    // If file writing is disabled, return null to fall through to default handling
+    if (!config.enabled || !config.outputPath) {
+        return null;
+    }
+    // Check character count threshold
+    const minChars = config.minCharsForWrite ?? DEFAULT_MIN_CHARS;
+    if (contentLength < minChars) {
+        return null;
+    }
+    // Write structured file
+    try {
+        const filename = `${tool_id}.json`;
+        const filepath = path.join(config.outputPath, filename);
+        await fs.mkdir(config.outputPath, { recursive: true });
+        await fs.writeFile(filepath, contentToWrite);
+        // Generate schema from the full structured content (metadata + data)
+        const fileSchema = generateQueryAssistSchema(structuredContent, {
+            maxDepth: config.schemaMaxDepth ?? 2,
+            maxPaths: config.schemaMaxPaths ?? 20,
+            maxKeys: config.schemaMaxKeys ?? 50,
+            dataSize: contentLength,
+        });
+        return {
+            tool_id,
+            wroteToFile: true,
+            filePath: filepath,
+            fileSchema,
+        };
+    }
+    catch (error) {
+        console.error(`[handleDynatraceDqlResponse] Error writing file:`, error);
+        return {
+            tool_id,
+            wroteToFile: false,
+            outputContent: structuredContent,
+            error: `File write failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
 /**
  * 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 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,
+        };
+    }
+    // Handle Dynatrace DQL responses specially
+    if (isDynatraceDqlTool(toolName)) {
+        const rawText = extractRawText(responseData);
+        if (rawText) {
+            const parsedDql = parseDynatraceDqlResponse(rawText);
+            if (parsedDql.isDynatraceDql) {
+                // If it's an error, return error directly
+                if (parsedDql.isError) {
+                    return {
+                        tool_id,
+                        wroteToFile: false,
+                        error: parsedDql.errorMessage,
+                    };
+                }
+                // Try to handle as structured Dynatrace response
+                const dqlResult = await handleDynatraceDqlResponse(config, tool_id, parsedDql);
+                if (dqlResult) {
+                    return dqlResult;
+                }
+                // If dqlResult is null, fall through to return the structured content directly
+                return {
+                    tool_id,
+                    wroteToFile: false,
+                    outputContent: {
+                        metadata: parsedDql.metadata,
+                        data: parsedDql.data,
+                    },
+                };
+            }
+        }
+        // If not a recognized Dynatrace DQL format, fall through to default handling
     }
-    // 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.2",
   "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": {