@anyshift/mcp-proxy 0.2.1 → 0.2.3-dev

package/README.md

@@ -133,39 +133,82 @@ npx @anyshift/mcp-proxy
 
 ## How It Works
 
+```mermaid
+graph TB
+    AI[🤖 AI Agent<br/>Claude]
+
+    AI -->|MCP Protocol| Proxy
+
+    subgraph Proxy["@anyshift/mcp-proxy"]
+        Start[Receive tool call]
+        CheckJQ{JQ tool?}
+        ExecuteJQ[Execute JQ locally]
+        Forward[Forward to child MCP]
+        GetResponse[Get response from child]
+        CheckSize{Size ≥ 1000 chars?}
+        WriteFile[📄 Write FULL data to file]
+        ReturnFile[Return file reference]
+        CheckTrunc{Size > 40K chars?}
+        Truncate[Truncate with notice]
+        ReturnDirect[Return response]
+
+        Start --> CheckJQ
+        CheckJQ -->|Yes| ExecuteJQ
+        CheckJQ -->|No| Forward
+        Forward --> GetResponse
+        ExecuteJQ --> CheckTrunc
+        GetResponse --> CheckSize
+        CheckSize -->|Yes| WriteFile
+        WriteFile --> ReturnFile
+        CheckSize -->|No| CheckTrunc
+        CheckTrunc -->|Yes| Truncate
+        CheckTrunc -->|No| ReturnDirect
+
+        ReturnFile -.->|📄 Small reference| AI
+        Truncate -.->|Truncated text| AI
+        ReturnDirect -.->|Full response| AI
+    end
+
+    Proxy -->|stdio + env vars| Child[Child MCP<br/>anyshift/datadog/grafana]
+    Child -.->|Response| Proxy
+
+    style AI fill:#e1f5ff
+    style Proxy fill:#fff4e1
+    style Child fill:#e8f5e9
+    style WriteFile fill:#c8e6c9
+    style ReturnFile fill:#c8e6c9
 ```
-┌─────────────┐
-│  AI Agent   │
-└──────┬──────┘
-       │ MCP Protocol (stdio)
-       ▼
-┌─────────────────────────────────┐
-│    @anyshift/mcp-proxy          │
-│                                 │
-│  1. Spawns child MCP            │
-│     with pass-through env vars  │
-│                                 │
-│  2. Discovers child tools       │
-│     + adds JQ tool              │
-│                                 │
-│  3. Forwards tool calls         │
-│                                 │
-│  4. Applies truncation          │
-│     if response > MAX_TOKENS    │
-│                                 │
-│  5. Writes to file              │
-│     if response > MIN_CHARS     │
-│                                 │
-│  6. Returns modified response   │
-│     to AI agent                 │
-└────────────┬────────────────────┘
-             │ Child process (stdio)
-             ▼
-      ┌──────────────┐
-      │  Child MCP   │  (mcp-grafana, custom-mcp, etc.)
-      │    Server    │  Gets env vars WITHOUT MCP_PROXY_ prefix
-      └──────────────┘
+
+### Response Handling Examples
+
+**Small responses (< 1,000 chars):**
+```
+Child: 500 chars → Proxy: Return directly → AI: 500 chars ✓
+```
+
+**Medium responses (1,000 - 40,000 chars):**
+```
+Child: 5,000 chars → Proxy: Write to file → AI: "📄 File: path/to/file.json" ✓
+```
+
+**Large responses (> 40,000 chars):**
+```
+Child: 100,000 chars → Proxy: Write FULL 100K to file → AI: "📄 File: ..." ✓
+Note: File contains complete data, not truncated!
+```
+
+**JQ tool queries:**
 ```
+AI: JQ query → Proxy: Execute locally → AI: Result (truncated if > 40K) ✓
+```
+
+### Key Design Principle
+
+**File writing happens BEFORE truncation.** This ensures:
+- Files always contain complete, untruncated data
+- Large responses are accessible via file references
+- AI receives small, manageable responses
+- No data loss due to context limits
 
 ## Integration Examples
 

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

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

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

@@ -0,0 +1,267 @@
+import { describe, it, expect } from '@jest/globals';
+import { generateQueryAssistSchema } from '../../fileWriter/schema.js';
+describe('Query-Assist Schema Generator', () => {
+    describe('Basic Structure Detection', () => {
+        it('should detect simple object structure', () => {
+            const data = {
+                id: '123',
+                name: 'Test',
+                count: 42
+            };
+            const schema = generateQueryAssistSchema(data, { maxDepth: 2, maxPaths: 20 });
+            expect(schema).toContain('📊 STRUCTURE GUIDE');
+            expect(schema).toContain('.id');
+            expect(schema).toContain('.name');
+            expect(schema).toContain('.count');
+            expect(schema).toContain('string');
+            expect(schema).toContain('number');
+        });
+        it('should detect array structure', () => {
+            const data = {
+                items: [
+                    { id: '1', price: 100 },
+                    { id: '2', price: 200 }
+                ]
+            };
+            // With maxDepth=3, we can see array item fields
+            const schema = generateQueryAssistSchema(data, { maxDepth: 3, maxPaths: 20 });
+            expect(schema).toContain('.items');
+            expect(schema).toContain('array[2]');
+            expect(schema).toContain('.items[].id');
+            expect(schema).toContain('.items[].price');
+        });
+        it('should detect nested object structure', () => {
+            const data = {
+                user: {
+                    profile: {
+                        name: 'Alice',
+                        age: 30
+                    }
+                }
+            };
+            const schema = generateQueryAssistSchema(data, { maxDepth: 2, maxPaths: 20 });
+            expect(schema).toContain('.user');
+            expect(schema).toContain('.user.profile');
+            expect(schema).toContain('object');
+        });
+    });
+    describe('Depth Limiting', () => {
+        it('should stop at max depth and show warning', () => {
+            const data = {
+                level1: {
+                    level2: {
+                        level3: {
+                            level4: 'too deep'
+                        }
+                    }
+                }
+            };
+            const schema = generateQueryAssistSchema(data, { maxDepth: 2, maxPaths: 20 });
+            // Should show paths up to depth 2
+            expect(schema).toContain('.level1.level2');
+            // Should show depth limit warning in consolidated format
+            expect(schema).toContain('⚠️  Limits: DEPTH (max: 2)');
+            // level3 can appear in exploration prompts, but not as a path entry
+            // Check that level3 is not shown as a separate path line
+            const lines = schema.split('\n');
+            const pathLines = lines.filter(l => l.includes('→') && l.includes('.level'));
+            expect(pathLines.some(l => l.includes('.level1.level2.level3') && l.includes(' → '))).toBe(false);
+        });
+        it('should show exploration prompts when depth limit hit', () => {
+            const data = {
+                deep: {
+                    nested: {
+                        value: 'hidden'
+                    }
+                }
+            };
+            const schema = generateQueryAssistSchema(data, { maxDepth: 1, maxPaths: 20 });
+            expect(schema).toContain('💡 EXPLORATION GUIDE');
+            expect(schema).toContain('⚠️  Limits: DEPTH (max: 1)');
+            expect(schema).toContain('View keys:');
+            expect(schema).toContain('Check type:');
+        });
+    });
+    describe('Key Limiting', () => {
+        it('should limit keys per object and show warning', () => {
+            const data = {};
+            for (let i = 0; i < 100; i++) {
+                data[`field_${i}`] = i;
+            }
+            const schema = generateQueryAssistSchema(data, { maxDepth: 2, maxPaths: 100, maxKeys: 20 });
+            expect(schema).toContain('💡 EXPLORATION GUIDE');
+            expect(schema).toContain('⚠️  Limits: KEYS (20 shown, 80 more)');
+        });
+        it('should show key exploration prompts when limit hit', () => {
+            const data = {};
+            for (let i = 0; i < 60; i++) {
+                data[`key${i}`] = `value${i}`;
+            }
+            const schema = generateQueryAssistSchema(data, { maxDepth: 2, maxPaths: 100, maxKeys: 30 });
+            expect(schema).toContain('💡 EXPLORATION GUIDE');
+            expect(schema).toContain('⚠️  Limits: KEYS (30 shown, 30 more)');
+            expect(schema).toContain('View keys:');
+            expect(schema).toContain('Count items:');
+        });
+    });
+    describe('Path Limiting', () => {
+        it('should limit total paths shown and prioritize important ones', () => {
+            // Create data with many fields to exceed path limit
+            const data = {
+                id: '123',
+                name: 'Test'
+            };
+            // Add many top-level fields
+            for (let i = 0; i < 20; i++) {
+                data[`field${i}`] = { nested: `value${i}` };
+            }
+            const schema = generateQueryAssistSchema(data, { maxDepth: 2, maxPaths: 10, maxKeys: 50 });
+            // Should show path limit warning in consolidated format
+            expect(schema).toContain('💡 EXPLORATION GUIDE');
+            expect(schema).toContain('PATHS (10 of');
+            // Should show some paths (prioritizes objects over primitives)
+            expect(schema).toContain('.field');
+            // Count number of path lines shown (should be exactly 10)
+            const pathLines = schema.split('\n').filter(l => l.includes(' → '));
+            expect(pathLines.length).toBeLessThanOrEqual(11); // 10 paths + root = 11
+        });
+        it('should show path exploration prompts when limit hit', () => {
+            const largeData = {};
+            for (let i = 0; i < 30; i++) {
+                largeData[`field${i}`] = { nested: 'value' };
+            }
+            const schema = generateQueryAssistSchema(largeData, { maxDepth: 2, maxPaths: 10, maxKeys: 50 });
+            expect(schema).toContain('💡 EXPLORATION GUIDE');
+            expect(schema).toContain('PATHS (10 of');
+            expect(schema).toContain('View keys:');
+            expect(schema).toContain('List all paths:');
+        });
+    });
+    describe('Mixed Schema Detection', () => {
+        it('should detect heterogeneous arrays', () => {
+            const data = {
+                items: [
+                    { type: 'book', pages: 200 },
+                    { type: 'video', duration: 120 },
+                    { type: 'audio', length: 180 }
+                ]
+            };
+            const schema = generateQueryAssistSchema(data, { maxDepth: 2, maxPaths: 20 });
+            expect(schema).toContain('💡 EXPLORATION GUIDE');
+            expect(schema).toContain('MIXED SCHEMAS');
+        });
+        it('should show mixed schema exploration prompts', () => {
+            const data = {
+                data: [
+                    { a: 1 },
+                    { b: 2 },
+                    { c: 3 }
+                ]
+            };
+            const schema = generateQueryAssistSchema(data, { maxDepth: 2, maxPaths: 20 });
+            expect(schema).toContain('💡 EXPLORATION GUIDE');
+            expect(schema).toContain('MIXED SCHEMAS');
+            expect(schema).toContain('Check variance:');
+        });
+    });
+    describe('Numeric Keys Detection', () => {
+        it('should detect numeric string keys and show representative structure', () => {
+            const data = {
+                '0': { name: 'Alice', age: 30 },
+                '1': { name: 'Bob', age: 25 },
+                '2': { name: 'Charlie', age: 35 }
+            };
+            const schema = generateQueryAssistSchema(data, { maxDepth: 3, maxPaths: 20 });
+            // Should detect numeric keys
+            expect(schema).toContain('object (numeric keys)');
+            expect(schema).toContain('(3 keys)');
+            // Should show representative structure with .[<idx>] notation
+            expect(schema).toContain('.[<idx>]');
+            // Should show nested structure of representative item
+            expect(schema).toContain('.[<idx>].name');
+            expect(schema).toContain('.[<idx>].age');
+            // Should show explanation note in exploration guide
+            expect(schema).toContain('💡 EXPLORATION GUIDE');
+            expect(schema).toContain('NUMERIC KEYS:');
+            expect(schema).toContain('.["0"], .["1"]');
+            expect(schema).toContain('.[0], .[1]');
+            // Should NOT enumerate individual keys
+            expect(schema).not.toContain('.0 ');
+            expect(schema).not.toContain('.1 ');
+            expect(schema).not.toContain('.2 ');
+        });
+    });
+    describe('Nullable Fields', () => {
+        it('should detect null values', () => {
+            const data = {
+                present: 'value',
+                missing: null,
+                empty: ''
+            };
+            const schema = generateQueryAssistSchema(data, { maxDepth: 2, maxPaths: 20 });
+            expect(schema).toContain('.missing');
+            expect(schema).toContain('null');
+            expect(schema).toContain('(nullable)');
+        });
+    });
+    describe('Schema Compactness', () => {
+        it('should not include common JQ patterns (moved to tool description)', () => {
+            const data = { simple: 'data' };
+            const schema = generateQueryAssistSchema(data, { maxDepth: 2, maxPaths: 20 });
+            // Common JQ patterns are now in the JQ tool description, not in every file reference
+            expect(schema).not.toContain('COMMON JQ PATTERNS:');
+            expect(schema).not.toContain('List all keys:');
+            // Schema should still contain the structure guide header
+            expect(schema).toContain('📊 STRUCTURE GUIDE');
+        });
+    });
+    describe('Size Constraints', () => {
+        it('should generate compact output for large structures', () => {
+            // Create a large nested structure
+            const data = {};
+            for (let i = 0; i < 100; i++) {
+                data[`key${i}`] = {
+                    nested: {
+                        deep: {
+                            value: i
+                        }
+                    }
+                };
+            }
+            const schema = generateQueryAssistSchema(data, {
+                maxDepth: 2,
+                maxPaths: 20,
+                maxKeys: 50
+            });
+            // Schema should be compact (under 5KB as designed)
+            expect(schema.length).toBeLessThan(5000);
+            // Should contain warnings about limits
+            expect(schema).toContain('⚠️');
+        });
+    });
+    describe('Empty Data Handling', () => {
+        it('should handle empty object', () => {
+            const data = {};
+            const schema = generateQueryAssistSchema(data, { maxDepth: 2, maxPaths: 20 });
+            expect(schema).toContain('📊 STRUCTURE GUIDE');
+            expect(schema).toContain('(root)');
+            expect(schema).toContain('object');
+            expect(schema).toContain('(0 keys)');
+        });
+        it('should handle empty array', () => {
+            const data = { items: [] };
+            const schema = generateQueryAssistSchema(data, { maxDepth: 2, maxPaths: 20 });
+            expect(schema).toContain('.items');
+            expect(schema).toContain('array[0]');
+        });
+    });
+    describe('Data Size Reporting', () => {
+        it('should report data size in characters', () => {
+            const data = { test: 'value' };
+            const schema = generateQueryAssistSchema(data, { maxDepth: 2, maxPaths: 20 });
+            expect(schema).toContain('Size:');
+            expect(schema).toContain('characters');
+            expect(schema).toMatch(/Size: \d+(,\d{3})* characters/);
+        });
+    });
+});

package/dist/fileWriter/index.d.ts

@@ -15,4 +15,4 @@ export declare function createFileWriter(config: FileWriterConfig): {
     handleResponse: (toolName: string, args: Record<string, unknown>, responseData: unknown) => Promise<FileWriterResult | unknown>;
 };
 export type { FileWriterConfig, FileWriterResult } from './types.js';
-export { analyzeJsonSchema, extractNullableFields } from './schema.js';
+export { generateQueryAssistSchema } from './schema.js';

package/dist/fileWriter/index.js

@@ -18,4 +18,4 @@ export function createFileWriter(config) {
         },
     };
 }
-export { analyzeJsonSchema, extractNullableFields } from './schema.js';
+export { generateQueryAssistSchema } from './schema.js';

package/dist/fileWriter/schema.d.ts

@@ -1,15 +1,42 @@
-import { JsonSchema, NullableFields } from '../types/index.js';
 /**
- * Analyze JSON structure and generate enhanced schema
- * @param obj - The object to analyze
- * @param path - Current path in the object (for debugging)
- * @returns Schema representation of the object
+ * Query-Assist Schema Generator
+ *
+ * Generates compact, LLM-friendly schemas optimized for crafting JQ queries.
+ * Uses JQ-style path notation (.items[].price) instead of JSON Schema.
+ * Includes exploration prompts when limits are reached.
  */
-export declare function analyzeJsonSchema(obj: unknown, path?: string): JsonSchema;
+export interface PathInfo {
+    path: string;
+    type: string;
+    depth: number;
+    nullable?: boolean;
+    arrayLength?: number;
+    keyCount?: number;
+    mixed?: boolean;
+}
+export interface LimitMetadata {
+    depthLimitHit: boolean;
+    keyLimitHit: boolean;
+    pathLimitHit: boolean;
+    mixedSchemasDetected: boolean;
+    maxDepth: number;
+    maxKeys: number;
+    maxPaths: number;
+    totalPathsFound: number;
+    deepestPathTruncated?: string;
+    truncatedKeyCount?: number;
+}
+export interface QueryAssistOptions {
+    maxDepth?: number;
+    maxPaths?: number;
+    maxKeys?: number;
+    dataSize?: number;
+}
 /**
- * Extract nullable and always-null fields from schema
- * @param schema - The schema to analyze
- * @param basePath - Base path for field names
- * @returns Object containing arrays of always-null and nullable field paths
+ * Generate query-assist schema for JSON data
+ * Main entry point for schema generation
+ * @param data - JSON data to analyze
+ * @param options - Configuration options
+ * @returns Compact text schema optimized for JQ queries
  */
-export declare function extractNullableFields(schema: unknown, basePath?: string): NullableFields;
+export declare function generateQueryAssistSchema(data: unknown, options?: QueryAssistOptions): string;

package/dist/fileWriter/schema.js

@@ -1,120 +1,270 @@
 /**
- * Analyze JSON structure and generate enhanced schema
- * @param obj - The object to analyze
- * @param path - Current path in the object (for debugging)
- * @returns Schema representation of the object
+ * Query-Assist Schema Generator
+ *
+ * Generates compact, LLM-friendly schemas optimized for crafting JQ queries.
+ * Uses JQ-style path notation (.items[].price) instead of JSON Schema.
+ * Includes exploration prompts when limits are reached.
  */
-export function analyzeJsonSchema(obj, path = 'root') {
-    if (obj === null)
-        return { type: 'null' };
-    if (obj === undefined)
-        return { type: 'undefined' };
-    const type = Array.isArray(obj) ? 'array' : typeof obj;
-    if (type === 'object') {
-        const properties = {};
-        const objRecord = obj;
-        const keys = Object.keys(objRecord);
-        // Detect numeric string keys (common in Cypher results)
-        const numericKeys = keys.filter((k) => /^\d+$/.test(k));
-        const hasNumericKeys = keys.length > 0 && numericKeys.length >= keys.length * 0.8;
-        for (const key in objRecord) {
-            if (Object.prototype.hasOwnProperty.call(objRecord, key)) {
-                properties[key] = analyzeJsonSchema(objRecord[key], `${path}.${key}`);
+/**
+ * Collect all paths from JSON data with limits applied
+ * @param data - The JSON data to analyze
+ * @param maxDepth - Maximum depth to traverse (default: 2)
+ * @param maxKeys - Maximum keys to analyze per object (default: 50)
+ * @returns Array of path information and limit metadata
+ */
+function collectPaths(data, maxDepth = 2, maxKeys = 50) {
+    const paths = [];
+    const limits = {
+        depthLimitHit: false,
+        keyLimitHit: false,
+        pathLimitHit: false,
+        mixedSchemasDetected: false,
+        maxDepth,
+        maxKeys,
+        maxPaths: 0, // Will be set later
+        totalPathsFound: 0
+    };
+    function traverse(val, path, depth) {
+        // Hard stop at max depth
+        if (depth > maxDepth) {
+            limits.depthLimitHit = true;
+            if (!limits.deepestPathTruncated) {
+                limits.deepestPathTruncated = path;
             }
+            return;
         }
-        const schema = { type: 'object', properties };
-        // Add metadata hints for numeric keys
-        if (hasNumericKeys) {
-            schema._keysAreNumeric = true;
-            schema._accessPattern = 'Use .["0"] not .[0]';
+        if (val === null) {
+            paths.push({ path, type: 'null', depth, nullable: true });
         }
-        return schema;
-    }
-    else if (type === 'array') {
-        const arr = obj;
-        if (arr.length === 0) {
-            return { type: 'array', items: { type: 'unknown' }, length: 0 };
+        else if (Array.isArray(val)) {
+            paths.push({ path, type: 'array', depth, arrayLength: val.length });
+            if (val.length === 0) {
+                return; // Empty array, nothing to explore
+            }
+            // Sample first 5 items to detect schema variance
+            const sample = val.slice(0, Math.min(5, val.length));
+            const types = new Set(sample.map(item => item === null
+                ? 'null'
+                : Array.isArray(item)
+                    ? 'array'
+                    : typeof item));
+            // Detect mixed schemas (heterogeneous arrays)
+            // Mixed if we have more than 1 distinct type
+            const mixed = types.size > 1;
+            if (mixed) {
+                limits.mixedSchemasDetected = true;
+            }
+            // Traverse first non-null item
+            const first = sample.find(v => v !== null);
+            if (first !== undefined) {
+                const arrayPath = `${path}[]`;
+                if (mixed) {
+                    // For mixed arrays, only show the mixed marker (don't traverse to avoid duplicate paths)
+                    paths.push({ path: arrayPath, type: 'mixed', depth: depth + 1, mixed: true });
+                }
+                else {
+                    // For uniform arrays, traverse to show the structure
+                    traverse(first, arrayPath, depth + 1);
+                }
+            }
+            // For objects in arrays, also check if they have different keys
+            if (types.has('object')) {
+                const objects = sample.filter(v => v && typeof v === 'object' && !Array.isArray(v));
+                if (objects.length >= 2) {
+                    const keySets = objects.map(o => new Set(Object.keys(o)));
+                    // Check if any two objects have different keys
+                    for (let i = 0; i < keySets.length - 1; i++) {
+                        const keys1 = Array.from(keySets[i]);
+                        const keys2 = Array.from(keySets[i + 1]);
+                        if (keys1.length !== keys2.length || !keys1.every(k => keySets[i + 1].has(k))) {
+                            limits.mixedSchemasDetected = true;
+                            break;
+                        }
+                    }
+                }
+            }
         }
-        // Analyze array items for mixed types and nulls
-        const itemTypes = new Set();
-        let hasNulls = false;
-        // Sample first 10 items to detect type variance
-        const sampled = arr.slice(0, Math.min(10, arr.length));
-        for (const item of sampled) {
-            if (item === null) {
-                hasNulls = true;
-                itemTypes.add('null');
+        else if (typeof val === 'object') {
+            const keys = Object.keys(val).sort();
+            // Check for numeric keys (common pattern - treat as collection like arrays)
+            const numericKeys = keys.filter(k => /^\d+$/.test(k));
+            const hasNumericKeys = keys.length > 0 && numericKeys.length >= keys.length * 0.8;
+            // Always show key count (including 0)
+            paths.push({
+                path,
+                type: hasNumericKeys ? 'object (numeric keys)' : 'object',
+                depth,
+                keyCount: keys.length
+            });
+            if (hasNumericKeys) {
+                // Treat as collection - show ONE representative item structure
+                // This avoids enumerating .0, .1, .2, ... which is repetitive and wastes space
+                const representativePath = path ? `${path}.[<idx>]` : `.[<idx>]`;
+                // Pick first key to show structure
+                if (keys.length > 0) {
+                    const firstKey = keys[0];
+                    traverse(val[firstKey], representativePath, depth + 1);
+                }
             }
             else {
-                itemTypes.add(Array.isArray(item) ? 'array' : typeof item);
+                // Normal object - traverse keys individually
+                const keysToAnalyze = keys.slice(0, maxKeys);
+                if (keys.length > maxKeys) {
+                    limits.keyLimitHit = true;
+                    limits.truncatedKeyCount = keys.length - maxKeys;
+                }
+                // Traverse child keys
+                for (const key of keysToAnalyze) {
+                    const childPath = path ? `${path}.${key}` : `.${key}`;
+                    traverse(val[key], childPath, depth + 1);
+                }
             }
         }
-        const schema = {
-            type: 'array',
-            items: itemTypes.size === 1 && !hasNulls
-                ? analyzeJsonSchema(arr[0], `${path}[0]`)
-                : { types: Array.from(itemTypes) },
-            length: arr.length,
-        };
-        // Add hints for null handling
-        if (hasNulls) {
-            schema._hasNulls = true;
+        else {
+            // Primitive types
+            paths.push({ path, type: typeof val, depth });
         }
-        return schema;
-    }
-    else {
-        return { type };
     }
+    traverse(data, '', 0);
+    limits.totalPathsFound = paths.length;
+    return { paths, limits };
 }
 /**
- * Extract nullable and always-null fields from schema
- * @param schema - The schema to analyze
- * @param basePath - Base path for field names
- * @returns Object containing arrays of always-null and nullable field paths
+ * Select top N most relevant paths using scoring
+ * @param paths - All collected paths
+ * @param maxPaths - Maximum paths to return
+ * @returns Prioritized subset of paths
  */
-export function extractNullableFields(schema, basePath = '') {
-    const alwaysNull = [];
-    const nullable = [];
-    function traverse(s, path) {
-        if (!s || typeof s !== 'object')
-            return;
-        const schemaObj = s;
-        // Check if this field is always null
-        if (schemaObj.type === 'null') {
-            alwaysNull.push(path);
-            return;
-        }
-        // Check if this field can be null (mixed types)
-        if (schemaObj.items && typeof schemaObj.items === 'object') {
-            const items = schemaObj.items;
-            if (items.types &&
-                Array.isArray(items.types) &&
-                items.types.includes('null')) {
-                nullable.push(path);
+function selectTopPaths(paths, maxPaths) {
+    // Score each path based on relevance
+    const scored = paths.map(p => ({
+        ...p,
+        score: (p.nullable ? 0 : 10) + // Non-null = higher priority
+            (3 - p.depth) * 5 + // Shallower = higher priority
+            (p.type === 'array' ? 5 : 0) + // Arrays = interesting
+            (p.type === 'object' || p.type === 'object (numeric keys)' ? 3 : 0) + // Objects = interesting
+            (p.mixed ? 2 : 0) // Mixed types = interesting
+    }));
+    // Sort by score (desc), then by path length (asc) for stability
+    return scored
+        .sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return a.path.length - b.path.length;
+    })
+        .slice(0, maxPaths);
+}
+/**
+ * Format paths as query-assist text with exploration prompts
+ * @param paths - Selected paths to display
+ * @param limits - Limit metadata for generating prompts
+ * @param dataSize - Size of original data in characters
+ * @returns Formatted text schema
+ */
+function formatQueryAssist(paths, limits, dataSize) {
+    let output = '📊 STRUCTURE GUIDE (for JQ queries)\n\n';
+    output += `Size: ${dataSize.toLocaleString()} characters\n\n`;
+    // Group paths by depth
+    const byDepth = {};
+    for (const p of paths) {
+        if (!byDepth[p.depth])
+            byDepth[p.depth] = [];
+        byDepth[p.depth].push(p);
+    }
+    // Format paths by depth levels
+    const depths = Object.keys(byDepth)
+        .map(Number)
+        .sort((a, b) => a - b);
+    for (const depth of depths) {
+        const depthPaths = byDepth[depth];
+        const label = depth === 0 ? 'ROOT' : depth === 1 ? 'TOP-LEVEL' : `NESTED (depth ${depth})`;
+        output += `${label}:\n`;
+        for (const p of depthPaths) {
+            const pathStr = p.path || '(root)';
+            output += `  ${pathStr.padEnd(35)}`;
+            output += ` → ${p.type}`;
+            if (p.arrayLength !== undefined) {
+                output += `[${p.arrayLength}]`;
             }
-        }
-        // Recurse into object properties
-        if (schemaObj.type === 'object' && schemaObj.properties) {
-            const props = schemaObj.properties;
-            for (const [key, value] of Object.entries(props)) {
-                const newPath = path ? `${path}.${key}` : key;
-                traverse(value, newPath);
+            if (p.keyCount !== undefined) {
+                output += ` (${p.keyCount} keys)`;
             }
+            if (p.nullable) {
+                output += ' (nullable)';
+            }
+            if (p.mixed) {
+                output += ' ⚠️ MIXED SCHEMAS';
+            }
+            if (depth === limits.maxDepth && (p.type === 'object' || p.type === 'object (numeric keys)' || p.type === 'array')) {
+                output += ' ⚠️ DEPTH LIMIT';
+            }
+            output += '\n';
         }
-        // Recurse into array items
-        if (schemaObj.type === 'array' &&
-            schemaObj.items &&
-            typeof schemaObj.items === 'object') {
-            const items = schemaObj.items;
-            if (items.type === 'object' && items.properties) {
-                const props = items.properties;
-                for (const [key, value] of Object.entries(props)) {
-                    const newPath = path ? `${path}[].${key}` : `[].${key}`;
-                    traverse(value, newPath);
-                }
+        output += '\n';
+    }
+    // Check if we have numeric-keyed objects in the output
+    const hasNumericKeys = paths.some(p => p.path.includes('.[<idx>]'));
+    // Build exploration guide if any limits were hit or special patterns detected
+    const hasLimits = limits.depthLimitHit || limits.keyLimitHit || limits.pathLimitHit || limits.mixedSchemasDetected;
+    if (hasNumericKeys || hasLimits) {
+        output += '💡 EXPLORATION GUIDE\n\n';
+        // Numeric keys note (data-specific, keep separate)
+        if (hasNumericKeys) {
+            output += 'NUMERIC KEYS: .[<idx>] represents structure shared by all numeric keys\n';
+            output += '  Access: .["0"], .["1"] or .[0], .[1] (array-style) | List: keys\n\n';
+        }
+        // Show which limits were hit
+        if (hasLimits) {
+            const limitWarnings = [];
+            if (limits.depthLimitHit) {
+                limitWarnings.push(`DEPTH (max: ${limits.maxDepth})`);
+            }
+            if (limits.keyLimitHit && limits.truncatedKeyCount) {
+                limitWarnings.push(`KEYS (${limits.maxKeys} shown, ${limits.truncatedKeyCount} more)`);
+            }
+            if (limits.pathLimitHit) {
+                limitWarnings.push(`PATHS (${limits.maxPaths} of ${limits.totalPathsFound})`);
+            }
+            if (limits.mixedSchemasDetected) {
+                limitWarnings.push('MIXED SCHEMAS');
             }
+            output += `⚠️  Limits: ${limitWarnings.join(' | ')}\n\n`;
+            // Generic JQ exploration patterns
+            output += 'Common JQ patterns:\n';
+            output += '  • View keys:        <path> | keys\n';
+            output += '  • Check type:       <path> | type\n';
+            output += '  • Count items:      <path> | length\n';
+            output += '  • Search keys:      keys | map(select(contains("term")))\n';
+            output += '  • List all paths:   paths(scalars) | map(join("."))\n';
+            output += '  • Filter arrays:    .[] | select(type == "object")\n';
+            if (limits.mixedSchemasDetected) {
+                output += '  • Check variance:   .[] | type  or  [:3] | map(keys)\n';
+            }
+            output += '\n';
         }
     }
-    traverse(schema, basePath);
-    return { alwaysNull, nullable };
+    return output;
+}
+/**
+ * Generate query-assist schema for JSON data
+ * Main entry point for schema generation
+ * @param data - JSON data to analyze
+ * @param options - Configuration options
+ * @returns Compact text schema optimized for JQ queries
+ */
+export function generateQueryAssistSchema(data, options = {}) {
+    const maxDepth = options.maxDepth ?? 2;
+    const maxPaths = options.maxPaths ?? 20;
+    const maxKeys = options.maxKeys ?? 50;
+    // Collect paths with limits
+    const { paths, limits } = collectPaths(data, maxDepth, maxKeys);
+    // Select top paths
+    const selectedPaths = selectTopPaths(paths, maxPaths);
+    // Update limit metadata
+    limits.maxPaths = maxPaths;
+    limits.pathLimitHit = paths.length > maxPaths;
+    // Calculate data size (use provided size if available to avoid re-stringifying)
+    const dataSize = options.dataSize ?? JSON.stringify(data).length;
+    // Format as text
+    return formatQueryAssist(selectedPaths, limits, dataSize);
 }

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;
 /**
@@ -160,8 +160,8 @@ const extractContentForFile = (responseData) => {
  * @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)
@@ -199,66 +199,28 @@ export async function handleToolResponse(config, toolName, args, responseData) {
         await fs.mkdir(config.outputPath, { recursive: true });
         // 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

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.1",
+  "version": "0.2.3-dev",
   "description": "Generic MCP proxy that adds truncation, file writing, and JQ capabilities to any MCP server",
   "type": "module",
   "main": "dist/index.js",