@anyshift/mcp-proxy 0.2.0 → 0.2.2

package/dist/fileWriter/writer.js

@@ -1,7 +1,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { generateCompactFilename } from '../utils/filename.js';
-import { analyzeJsonSchema, extractNullableFields } from './schema.js';
+import { generateQueryAssistSchema } from './schema.js';
 // Default minimum character count to trigger file writing
 const DEFAULT_MIN_CHARS = 1000;
 /**
@@ -104,6 +104,53 @@ const extractRawText = (response) => {
     }
     return null;
 };
+/**
+ * Extract the exact content that will be written to file
+ * This is used for both character counting AND file writing to ensure consistency
+ * @returns Object with contentToWrite and parsedForSchema (if applicable)
+ */
+const extractContentForFile = (responseData) => {
+    const rawText = extractRawText(responseData);
+    let contentToWrite;
+    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];
+            }
+            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;
+            contentToWrite = JSON.stringify(cleanData, null, 2);
+        }
+        catch {
+            // If parsing fails, write the raw text directly
+            contentToWrite = rawText;
+        }
+    }
+    else {
+        // Fallback: extract from display content or stringify the entire response
+        if (responseData &&
+            typeof responseData === 'object' &&
+            'content' in responseData &&
+            Array.isArray(responseData.content)) {
+            const textContent = responseData.content
+                .filter((item) => item.type === 'text')
+                .map((item) => item.text)
+                .join('\n');
+            contentToWrite = textContent;
+        }
+        else {
+            contentToWrite = JSON.stringify(responseData, null, 2);
+        }
+    }
+    return { contentToWrite, parsedForSchema };
+};
 /**
  * Centralized response handler with file writing capability
  * @param config - File writer configuration
@@ -113,8 +160,8 @@ const extractRawText = (response) => {
  * @returns Either the original response or a file reference response
  */
 export async function handleToolResponse(config, toolName, args, responseData) {
-    // JQ query tool should always return directly to AI (never write to file)
-    if (toolName === 'execute_jq_query') {
+    // Some tools should always return directly to AI (never write to file)
+    if (toolName === 'execute_jq_query' || toolName === 'get_label_schema') {
         return responseData;
     }
     // If there's an error, return proper MCP error response (never write errors to file)
@@ -134,26 +181,11 @@ export async function handleToolResponse(config, toolName, args, responseData) {
     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);
     // Check character count threshold - if response is too short, return directly
-    const rawText = extractRawText(responseData);
-    let contentLength = 0;
-    if (rawText) {
-        contentLength = rawText.length;
-    }
-    else if (responseData &&
-        typeof responseData === 'object' &&
-        'content' in responseData &&
-        Array.isArray(responseData.content)) {
-        const textContent = responseData.content
-            .filter((item) => item.type === 'text')
-            .map((item) => item.text)
-            .join('\n');
-        contentLength = textContent.length;
-    }
-    else {
-        contentLength = JSON.stringify(responseData).length;
-    }
-    // If content is shorter than threshold, return response directly instead of writing to file
+    const contentLength = contentToWrite.length;
     const minChars = config.minCharsForWrite ?? DEFAULT_MIN_CHARS;
     if (contentLength < minChars) {
         return responseData;
@@ -165,106 +197,30 @@ export async function handleToolResponse(config, toolName, args, responseData) {
         const filepath = path.join(config.outputPath, filename);
         // Ensure output directory exists
         await fs.mkdir(config.outputPath, { recursive: true });
-        // Extract the actual data from MCP response format
-        let contentToWrite;
-        let parsedForSchema;
-        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];
-                }
-                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;
-                contentToWrite = JSON.stringify(cleanData, null, 2);
-            }
-            catch {
-                // If parsing fails, write the raw text directly
-                contentToWrite = rawText;
-            }
-        }
-        else {
-            // Fallback: extract from display content or stringify the entire response
-            if (responseData &&
-                typeof responseData === 'object' &&
-                'content' in responseData &&
-                Array.isArray(responseData.content)) {
-                const textContent = responseData.content
-                    .filter((item) => item.type === 'text')
-                    .map((item) => item.text)
-                    .join('\n');
-                contentToWrite = textContent;
-            }
-            else {
-                contentToWrite = JSON.stringify(responseData, null, 2);
-            }
-        }
+        // Write the exact content we counted
         await fs.writeFile(filepath, contentToWrite);
-        // Try to generate schema if we have valid JSON
+        // Generate query-assist schema if we have valid JSON
         let schemaInfo = '';
-        let quickReference = '';
         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;
-            const schema = analyzeJsonSchema(cleanData);
-            const nullFields = extractNullableFields(schema);
-            const schemaObj = schema;
-            // Build quick reference section
-            quickReference += `\n\n🔍 UNDERSTAND THIS SCHEMA BEFORE WRITING JQ QUERIES:\n`;
-            // Structure hints
-            if (schemaObj._keysAreNumeric) {
-                quickReference += `   • Structure: Object with numeric keys ("0", "1", ...) - use .["0"]\n`;
-            }
-            else if (schemaObj.type === 'array') {
-                quickReference += `   • Structure: Array with ${schemaObj.length} items\n`;
-            }
-            else if (schemaObj.type === 'object' && schemaObj.properties) {
-                const props = schemaObj.properties;
-                const keys = Object.keys(props).slice(0, 5).join(', ');
-                quickReference += `   • Structure: Object with keys: ${keys}\n`;
-            }
-            // Always null fields
-            if (nullFields.alwaysNull.length > 0) {
-                const fieldList = nullFields.alwaysNull.slice(0, 5).join(', ');
-                const more = nullFields.alwaysNull.length > 5
-                    ? ` (+${nullFields.alwaysNull.length - 5} more)`
-                    : '';
-                quickReference += `   • Always null: ${fieldList}${more}\n`;
-            }
-            // Nullable fields
-            if (nullFields.nullable.length > 0) {
-                const fieldList = nullFields.nullable.slice(0, 5).join(', ');
-                const more = nullFields.nullable.length > 5
-                    ? ` (+${nullFields.nullable.length - 5} more)`
-                    : '';
-                quickReference += `   • Sometimes null: ${fieldList}${more}\n`;
-            }
-            // Suggest exploratory queries
-            if (schemaObj._keysAreNumeric) {
-                quickReference += `   • Explore: keys, .["0"] | keys, .["0"]\n`;
-            }
-            else if (schemaObj.type === 'array' && schemaObj.length > 0) {
-                quickReference += `   • Explore: length, .[0] | keys, .[0]\n`;
-            }
-            else {
-                quickReference += `   • Explore: keys, type\n`;
-            }
-            // Full schema
-            schemaInfo = `\n\nFull JSON Schema:\n${JSON.stringify(schema, null, 2)}`;
+            // Generate compact query-assist schema using config values
+            // Pass contentLength to avoid re-stringifying large payloads
+            schemaInfo = `\n\n${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, quick reference, and schema
+        // Return success message with file path, size, lines, and schema
         return {
             content: [
                 {
                     type: 'text',
-                    text: `📄 File: ${filepath}\nSize: ${contentToWrite.length} characters | Lines: ${lineCount}${quickReference}${schemaInfo}`,
+                    text: `📄 File: ${filepath}\nSize: ${contentToWrite.length} characters | Lines: ${lineCount}${schemaInfo}`,
                 },
             ],
         };

package/dist/index.js

@@ -95,6 +95,24 @@ const ENABLE_JQ = process.env.MCP_PROXY_ENABLE_JQ !== 'false'; // default true
  * Timeout in milliseconds for JQ query execution
  */
 const JQ_TIMEOUT_MS = parseInt(process.env.MCP_PROXY_JQ_TIMEOUT_MS || '30000');
+/**
+ * MCP_PROXY_SCHEMA_MAX_DEPTH (OPTIONAL, default: 3)
+ * Maximum depth to traverse when generating query-assist schemas
+ * Deeper structures will show exploration prompts instead
+ */
+const SCHEMA_MAX_DEPTH = parseInt(process.env.MCP_PROXY_SCHEMA_MAX_DEPTH || '3');
+/**
+ * MCP_PROXY_SCHEMA_MAX_PATHS (OPTIONAL, default: 20)
+ * Maximum number of paths to show in query-assist schemas
+ * Prioritizes non-null, shallow, and interesting paths
+ */
+const SCHEMA_MAX_PATHS = parseInt(process.env.MCP_PROXY_SCHEMA_MAX_PATHS || '20');
+/**
+ * MCP_PROXY_SCHEMA_MAX_KEYS (OPTIONAL, default: 50)
+ * Maximum number of object keys to analyze per object
+ * Objects with more keys will show a key limit warning
+ */
+const SCHEMA_MAX_KEYS = parseInt(process.env.MCP_PROXY_SCHEMA_MAX_KEYS || '50');
 /**
  * MCP_PROXY_ENABLE_LOGGING (OPTIONAL, default: false)
  * Enable debug logging for the proxy
@@ -228,7 +246,10 @@ async function main() {
         enabled: WRITE_TO_FILE,
         outputPath: OUTPUT_PATH,
         minCharsForWrite: MIN_CHARS_FOR_WRITE,
-        toolAbbreviations: {} // No service-specific abbreviations (generic proxy)
+        toolAbbreviations: {}, // No service-specific abbreviations (generic proxy)
+        schemaMaxDepth: SCHEMA_MAX_DEPTH,
+        schemaMaxPaths: SCHEMA_MAX_PATHS,
+        schemaMaxKeys: SCHEMA_MAX_KEYS
     };
     const fileWriter = createFileWriter(fileWriterConfig);
     // JQ tool configuration
@@ -263,56 +284,71 @@ async function main() {
             console.error(`[mcp-proxy] Tool call: ${toolName}`);
         }
         try {
+            let result;
             // Handle JQ tool locally (if enabled)
             if (toolName === 'execute_jq_query' && jqTool) {
                 if (ENABLE_LOGGING) {
                     console.error('[mcp-proxy] Executing JQ tool locally');
                 }
-                return await jqTool.handler({
+                result = await jqTool.handler({
                     params: { arguments: toolArgs }
                 });
             }
-            // 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.error(`[mcp-proxy] Forwarding to child MCP: ${toolName}`);
+            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.error(`[mcp-proxy] Forwarding to child MCP: ${toolName}`);
+                }
+                result = await childClient.callTool({
+                    name: toolName,
+                    arguments: toolArgs
+                });
             }
-            const result = await childClient.callTool({
-                name: toolName,
-                arguments: toolArgs
-            });
-            // Apply truncation and file writing to text responses
+            // Apply file writing and truncation to text responses
             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;
-                        // Step 1: Apply truncation
-                        item.text = truncateResponseIfNeeded(truncationConfig, item.text);
-                        if (item.text.length < originalLength && ENABLE_LOGGING) {
-                            console.error(`[mcp-proxy] Truncated response: ${originalLength} → ${item.text.length} chars`);
-                        }
-                        // Step 2: Apply file writing (if enabled)
+                        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') {
-                                item.text = fileResult.content[0].text;
-                                if (ENABLE_LOGGING) {
-                                    console.error(`[mcp-proxy] File writing applied for ${toolName}`);
+                                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.error(`[mcp-proxy] File writing applied for ${toolName} (${originalLength} chars written to file)`);
+                                    }
                                 }
                             }
                         }
+                        // 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.error(`[mcp-proxy] Truncated response: ${originalLength} → ${item.text.length} chars`);
+                            }
+                        }
                     }
                 }
             }

package/dist/jq/tool.js

@@ -73,6 +73,21 @@ export const JQ_TOOL_DEFINITION = {
         '\n2. **Incremental filtering**: Start with no filters, add conditions one by one' +
         '\n3. **Alternative null handling**: Use `// empty`, `select(. != null)`, or `try ... catch`' +
         '\n4. **Simplified queries**: Break complex queries into smaller, testable parts' +
+        '\n\n## COMMON JQ PATTERNS (Quick Reference):' +
+        '\n- **List all keys**: `keys` or `.[] | keys` (for nested)' +
+        '\n- **Check type**: `type` or `.field | type`' +
+        '\n- **Array length**: `.items | length` or `[.[]] | length`' +
+        '\n- **Filter array**: `.items[] | select(.price > 100)` or `select(.field == "value")`' +
+        '\n- **Extract field**: `.items[].id` or `.[] | .field`' +
+        '\n- **Get unique values**: `.items[].type | unique` or `[.[].field] | unique`' +
+        '\n- **Find nulls**: `.items[] | select(.field == null)` or `select(.field)` (non-null only)' +
+        '\n- **Count occurrences**: `group_by(.type) | map({type: .[0].type, count: length})`' +
+        '\n- **Sort**: `sort_by(.price)` or `sort_by(.price) | reverse` (descending)' +
+        '\n- **Map transform**: `[.[] | {id: .id, name: .name}]` (extract subset of fields)' +
+        '\n- **First N items**: `.[:5]` (array slice)' +
+        '\n- **Limit stream**: `limit(10; .[])` (stream processing)' +
+        '\n- **Default values**: `.field // "default"` or `.field // empty`' +
+        '\n- **Conditional**: `if .price > 100 then "expensive" else "cheap" end`' +
         '\n\n## COMPREHENSIVE EXAMPLES:' +
         '\n**Debugging sequence for Cypher results**:' +
         '\n- `keys` → ["0", "1", "2", ...] (shows object structure)' +

package/dist/types/index.d.ts

@@ -10,6 +10,12 @@ export interface FileWriterConfig {
     minCharsForWrite?: number;
     /** Custom abbreviations for tool names in filenames */
     toolAbbreviations?: Record<string, string>;
+    /** Maximum depth for schema generation (default: 2) */
+    schemaMaxDepth?: number;
+    /** Maximum paths to show in schema (default: 20) */
+    schemaMaxPaths?: number;
+    /** Maximum keys to analyze per object (default: 50) */
+    schemaMaxKeys?: number;
 }
 /**
  * Configuration for the JQ tool

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anyshift/mcp-proxy",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Generic MCP proxy that adds truncation, file writing, and JQ capabilities to any MCP server",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,11 @@
     "zod": "^3.24.2"
   },
   "devDependencies": {
+    "@jest/globals": "^30.2.0",
+    "@types/jest": "^30.0.0",
     "@types/node": "^22.0.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.5",
     "tsx": "^4.7.0",
     "typescript": "^5.3.3"
   },
@@ -27,6 +31,11 @@
   "scripts": {
     "build": "tsc",
     "start": "node dist/index.js",
-    "dev": "tsx src/index.ts"
+    "dev": "tsx src/index.ts",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:unit": "node --experimental-vm-modules node_modules/jest/bin/jest.js --testPathPattern=unit",
+    "test:integration": "node --experimental-vm-modules node_modules/jest/bin/jest.js --testPathPattern=integration",
+    "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
+    "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage"
   }
 }