json-explorer-mcp 1.0.0 → 1.0.2

package/README.md

@@ -8,13 +8,19 @@ An MCP (Model Context Protocol) server for efficiently exploring large JSON file
 - **Smart truncation** - Large values are automatically summarized
 - **Caching** - Parsed JSON is cached with file modification checks
 - **Schema inference** - Understand structure without reading all data
-- **Aggregate statistics** - Get counts, distributions, and numeric stats
+- **Schema validation** - Validate data against JSON Schema with `$ref` resolution
+- **Aggregate statistics** - Get counts, distributions, and numeric stats for arrays
 
 ## Installation
 
 ```bash
-npm install
-npm run build
+npm install -g json-explorer-mcp
+```
+
+Or use directly with npx:
+
+```bash
+npx json-explorer-mcp
 ```
 
 ## Usage
@@ -27,8 +33,8 @@ Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/
 {
   "mcpServers": {
     "json-explorer": {
-      "command": "node",
-      "args": ["/path/to/json-explorer-mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "json-explorer-mcp"]
     }
   }
 }
@@ -42,8 +48,8 @@ Add to `.mcp.json` in your project:
 {
   "mcpServers": {
     "json-explorer": {
-      "command": "node",
-      "args": ["dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "json-explorer-mcp"]
     }
   }
 }
@@ -55,11 +61,12 @@ Add to `.mcp.json` in your project:
 
 Get an overview of a JSON file including size, structure type, and a depth-limited preview.
 
-```
+```typescript
 json_inspect(file: "/path/to/data.json")
 ```
 
 Returns:
+
 ```json
 {
   "file": "/path/to/data.json",
@@ -77,18 +84,19 @@ Returns:
 
 List all keys (for objects) or indices (for arrays) at a given path with type info and previews.
 
-```
+```typescript
 json_keys(file: "/path/to/data.json", path: "$.users")
 ```
 
 Returns:
+
 ```json
 {
   "path": "$.users",
   "type": "array",
   "keys": [
-    { "key": "[0]", "type": "object", "preview": "{\"id\": 1, \"name\": \"Alice\", ...}", "path": "$.users[0]" },
-    { "key": "[1]", "type": "object", "preview": "{\"id\": 2, \"name\": \"Bob\", ...}", "path": "$.users[1]" }
+    { "key": "[0]", "type": "object", "preview": "{\"id\": 1, ...}", "path": "$.users[0]" },
+    { "key": "[1]", "type": "object", "preview": "{\"id\": 2, ...}", "path": "$.users[1]" }
   ],
   "totalCount": 1000
 }
@@ -98,7 +106,7 @@ Returns:
 
 Retrieve the value at a specific path. Large values are automatically truncated.
 
-```
+```typescript
 json_get(file: "/path/to/data.json", path: "$.users[0]")
 ```
 
@@ -106,11 +114,12 @@ json_get(file: "/path/to/data.json", path: "$.users[0]")
 
 Infer the JSON schema/structure at a path. For arrays, samples items to determine the item schema.
 
-```
+```typescript
 json_schema(file: "/path/to/data.json", path: "$.users")
 ```
 
 Returns:
+
 ```json
 {
   "path": "$.users",
@@ -128,11 +137,66 @@ Returns:
 }
 ```
 
+### json_validate
+
+Validate JSON data against a JSON Schema. Schema can be provided inline or as a path to a schema file.
+
+**Features:**
+- Automatic resolution of local file `$ref` references
+- Optional network `$ref` resolution (disabled by default)
+- Validates that referenced files are actual JSON Schemas
+- Error limiting (default 10) to avoid huge error lists
+
+```typescript
+json_validate(
+  file: "/path/to/data.json",
+  schema: { "type": "object", "properties": { "id": { "type": "integer" } }, "required": ["id"] },
+  path: "$.users[0]"
+)
+```
+
+Or with a schema file (local `$ref`s are automatically resolved):
+
+```typescript
+json_validate(
+  file: "/path/to/data.json",
+  schema: "/path/to/schema.json"
+)
+```
+
+With options:
+
+```typescript
+json_validate(
+  file: "/path/to/data.json",
+  schema: "/path/to/schema.json",
+  path: "$.users",
+  errorLimit: 5,              // Max errors to return (default: 10)
+  resolveLocalRefs: true,     // Resolve local file $refs (default: true)
+  resolveNetworkRefs: false   // Resolve HTTP $refs (default: false)
+)
+```
+
+Returns:
+
+```json
+{
+  "valid": false,
+  "errorCount": 15,
+  "truncatedErrorCount": 5,
+  "errors": [
+    { "path": "/id", "message": "must be integer", "keyword": "type", "params": {} },
+    { "path": "", "message": "must have required property 'name'", "keyword": "required", "params": {} }
+  ],
+  "resolvedRefs": ["/path/to/definitions.json"]
+}
+```
+
 ### json_search
 
 Search for keys or values matching a pattern (regex supported).
 
-```
+```typescript
 json_search(file: "/path/to/data.json", query: "email", searchType: "key")
 json_search(file: "/path/to/data.json", query: "@example.com", searchType: "value")
 ```
@@ -141,7 +205,7 @@ json_search(file: "/path/to/data.json", query: "@example.com", searchType: "valu
 
 Get sample items from an array. Supports first, last, random, or range-based sampling.
 
-```
+```typescript
 json_sample(file: "/path/to/data.json", path: "$.users", count: 5, mode: "random")
 ```
 
@@ -149,16 +213,14 @@ json_sample(file: "/path/to/data.json", path: "$.users", count: 5, mode: "random
 
 Get aggregate statistics for array fields. If no path provided, discovers and analyzes all arrays of objects in the file.
 
-```
+```typescript
 json_stats(file: "/path/to/data.json")
 ```
 
 Returns:
+
 ```json
 {
-  "arrays": [
-    { "path": "$.users", "length": 1000, "itemType": "object", "fields": ["id", "name", "status"], "fieldCount": 10 }
-  ],
   "stats": [
     {
       "path": "$.users",
@@ -173,7 +235,8 @@ Returns:
 ```
 
 With a specific path:
-```
+
+```typescript
 json_stats(file: "/path/to/data.json", path: "$.users", fields: ["status", "created_at"])
 ```
 
@@ -188,6 +251,48 @@ All path parameters support JSONPath syntax:
 - `$.users[*]` - All array items (in search results)
 - `$["special-key"]` - Bracket notation for special characters
 
+## Security
+
+### Schema Validation
+
+All referenced schemas (both local files and network URLs) are validated before use. The tool checks that fetched content is a valid JSON Schema object containing appropriate keywords (`type`, `properties`, `$ref`, etc.), rejecting arrays, primitives, or unrelated JSON files.
+
+### Network Schema Resolution
+
+By default, `json_validate` only resolves local file `$ref` references. Network (HTTP/HTTPS) resolution is disabled by default for security.
+
+To enable network refs for a specific validation:
+
+```typescript
+json_validate(file: "data.json", schema: "schema.json", resolveNetworkRefs: true)
+```
+
+### Disabling Network Resolution Completely
+
+For security-conscious environments, you can completely disable network schema resolution using an environment variable:
+
+```bash
+JSON_EXPLORER_NO_NETWORK=1
+```
+
+When set to `1`, this overrides any `resolveNetworkRefs: true` option, ensuring schemas are never fetched from the network.
+
+**Claude Desktop config with network disabled:**
+
+```json
+{
+  "mcpServers": {
+    "json-explorer": {
+      "command": "npx",
+      "args": ["-y", "json-explorer-mcp"],
+      "env": {
+        "JSON_EXPLORER_NO_NETWORK": "1"
+      }
+    }
+  }
+}
+```
+
 ## Development
 
 ```bash
@@ -197,6 +302,9 @@ npm install
 # Build
 npm run build
 
+# Run tests
+npm test
+
 # Run in development mode
 npm run dev
 ```

package/dist/index.js

@@ -123,13 +123,20 @@ server.tool("json_schema", "Infer the JSON schema/structure at a path. For array
     }
 });
 // Tool: json_validate - Validate against JSON Schema
-server.tool("json_validate", "Validate JSON data against a JSON Schema. Schema can be provided inline or as a path to a schema file.", {
+server.tool("json_validate", "Validate JSON data against a JSON Schema. Schema can be provided inline or as a path to a schema file. Automatically resolves local file $refs. Use resolveNetworkRefs to also fetch remote schemas.", {
     file: z.string().describe("Absolute path to the JSON file to validate"),
     schema: z.union([z.string(), z.object({}).passthrough()]).describe("JSON Schema object or path to schema file"),
     path: z.string().optional().describe("JSONPath to validate. Defaults to root."),
-}, { readOnlyHint: true }, async ({ file, schema, path }) => {
+    errorLimit: z.number().optional().describe("Maximum number of errors to return. Defaults to 10."),
+    resolveLocalRefs: z.boolean().optional().describe("Resolve $ref to local files. Defaults to true."),
+    resolveNetworkRefs: z.boolean().optional().describe("Resolve $ref to HTTP URLs. Defaults to false for security."),
+}, { readOnlyHint: true }, async ({ file, schema, path, errorLimit, resolveLocalRefs, resolveNetworkRefs }) => {
     try {
-        const result = await jsonValidate(file, schema, path);
+        const result = await jsonValidate(file, schema, path, {
+            errorLimit,
+            resolveLocalRefs,
+            resolveNetworkRefs,
+        });
         return {
             content: [
                 {

package/dist/tools/query.d.ts

@@ -39,16 +39,57 @@ export interface FieldStats {
 export interface ArrayInfo {
     path: string;
     length: number;
-    itemType: string;
+    itemType: "object" | "string" | "number" | "mixed";
     fields?: string[];
     fieldCount?: number;
 }
+export interface PrimitiveArrayStats {
+    path: string;
+    arrayLength: number;
+    itemType: "string" | "number" | "mixed";
+    typeBreakdown?: Record<string, number>;
+    nullCount: number;
+    uniqueCount?: number;
+    stringStats?: {
+        count: number;
+        uniqueCount: number;
+        lengthStats: {
+            min: number;
+            max: number;
+            avg: number;
+            median: number;
+        };
+        distribution?: Record<string, number>;
+    };
+    lengthStats?: {
+        min: number;
+        max: number;
+        avg: number;
+        median: number;
+    };
+    distribution?: Record<string, number>;
+    numericStats?: {
+        count?: number;
+        min: number;
+        max: number;
+        avg: number;
+        median: number;
+        stdDev: number;
+        percentiles: {
+            p25: number;
+            p50: number;
+            p75: number;
+            p90: number;
+            p99: number;
+        };
+    };
+}
 export interface StatsResult {
     path: string;
     arrayLength: number;
     fields: FieldStats[];
 }
 export interface MultiStatsResult {
-    stats: StatsResult[];
+    stats: (StatsResult | PrimitiveArrayStats)[];
 }
-export declare function jsonStats(filePath: string, path?: string, fields?: string[]): Promise<StatsResult | MultiStatsResult>;
+export declare function jsonStats(filePath: string, path?: string, fields?: string[]): Promise<StatsResult | PrimitiveArrayStats | MultiStatsResult>;

package/dist/tools/query.js

@@ -118,13 +118,13 @@ export async function jsonSample(filePath, path, count = 5, mode = "first", rang
         hasMore: arrayLength > count,
     };
 }
-function findArraysOfObjects(data, currentPath = "$", maxDepth = 5, depth = 0) {
+function findArrays(data, currentPath = "$", maxDepth = 5, depth = 0) {
     const results = [];
     if (depth > maxDepth)
         return results;
     if (Array.isArray(data) && data.length > 0) {
         const firstItem = data[0];
-        // Only include arrays of objects (not primitives or nested arrays)
+        // Arrays of objects
         if (typeof firstItem === "object" && firstItem !== null && !Array.isArray(firstItem)) {
             const fields = Object.keys(firstItem);
             results.push({
@@ -152,29 +152,69 @@ function findArraysOfObjects(data, currentPath = "$", maxDepth = 5, depth = 0) {
                 }
             }
         }
+        // Arrays of primitives (strings, numbers, or mixed)
+        else if (typeof firstItem === "string" || typeof firstItem === "number") {
+            // Check if array has mixed types
+            const types = new Set(data.map((item) => typeof item).filter((t) => t === "string" || t === "number"));
+            if (types.size > 1) {
+                results.push({
+                    path: currentPath,
+                    length: data.length,
+                    itemType: "mixed",
+                });
+            }
+            else if (typeof firstItem === "string") {
+                results.push({
+                    path: currentPath,
+                    length: data.length,
+                    itemType: "string",
+                });
+            }
+            else {
+                results.push({
+                    path: currentPath,
+                    length: data.length,
+                    itemType: "number",
+                });
+            }
+        }
     }
     else if (typeof data === "object" && data !== null) {
         for (const key of Object.keys(data)) {
             const childPath = /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(key)
                 ? `${currentPath}.${key}`
                 : `${currentPath}["${key}"]`;
-            results.push(...findArraysOfObjects(data[key], childPath, maxDepth, depth + 1));
+            results.push(...findArrays(data[key], childPath, maxDepth, depth + 1));
         }
     }
     return results;
 }
 export async function jsonStats(filePath, path, fields) {
     const data = await loadJson(filePath);
-    // If no path provided, compute stats for all arrays of objects
+    // If no path provided, compute stats for all arrays
     if (!path) {
-        const arrays = findArraysOfObjects(data);
+        const arrays = findArrays(data);
         const allStats = [];
         for (const arr of arrays) {
             try {
                 const value = getValueAtPath(data, arr.path);
                 if (Array.isArray(value) && value.length > 0) {
-                    const stats = computeArrayStats(value, arr.path, fields);
-                    allStats.push(stats);
+                    if (arr.itemType === "object") {
+                        const stats = computeObjectArrayStats(value, arr.path, fields);
+                        allStats.push(stats);
+                    }
+                    else if (arr.itemType === "string") {
+                        const stats = computeStringArrayStats(value, arr.path);
+                        allStats.push(stats);
+                    }
+                    else if (arr.itemType === "number") {
+                        const stats = computeNumberArrayStats(value, arr.path);
+                        allStats.push(stats);
+                    }
+                    else if (arr.itemType === "mixed") {
+                        const stats = computeMixedArrayStats(value, arr.path);
+                        allStats.push(stats);
+                    }
                 }
             }
             catch {
@@ -187,9 +227,27 @@ export async function jsonStats(filePath, path, fields) {
     if (!Array.isArray(value)) {
         throw new Error(`Path "${path}" is not an array. Got: ${getValueType(value)}`);
     }
-    return computeArrayStats(value, path, fields);
+    // Determine array type
+    if (value.length === 0) {
+        return { path, arrayLength: 0, fields: [] };
+    }
+    const firstItem = value[0];
+    // Check for mixed primitive types
+    if (typeof firstItem === "string" || typeof firstItem === "number") {
+        const types = new Set(value.map((item) => typeof item).filter((t) => t === "string" || t === "number"));
+        if (types.size > 1) {
+            return computeMixedArrayStats(value, path);
+        }
+    }
+    if (typeof firstItem === "string") {
+        return computeStringArrayStats(value, path);
+    }
+    else if (typeof firstItem === "number") {
+        return computeNumberArrayStats(value, path);
+    }
+    return computeObjectArrayStats(value, path, fields);
 }
-function computeArrayStats(value, path, fields) {
+function computeObjectArrayStats(value, path, fields) {
     if (value.length === 0) {
         return { path, arrayLength: 0, fields: [] };
     }
@@ -247,3 +305,183 @@ function computeArrayStats(value, path, fields) {
         fields: fieldStats,
     };
 }
+function computeStringArrayStats(value, path) {
+    const strings = value.filter((v) => typeof v === "string");
+    const nullCount = value.length - strings.length;
+    // Compute length stats
+    const lengths = strings.map((s) => s.length);
+    const sortedLengths = [...lengths].sort((a, b) => a - b);
+    const lengthStats = lengths.length > 0 ? {
+        min: Math.min(...lengths),
+        max: Math.max(...lengths),
+        avg: Math.round(lengths.reduce((a, b) => a + b, 0) / lengths.length * 100) / 100,
+        median: sortedLengths[Math.floor(sortedLengths.length / 2)],
+    } : undefined;
+    // Compute value distribution (if reasonable number of unique values)
+    const distribution = {};
+    for (const s of strings) {
+        distribution[s] = (distribution[s] || 0) + 1;
+    }
+    const uniqueCount = Object.keys(distribution).length;
+    // Only include distribution if <= 50 unique values
+    const result = {
+        path,
+        arrayLength: value.length,
+        itemType: "string",
+        nullCount,
+        uniqueCount,
+        lengthStats,
+    };
+    if (uniqueCount <= 50) {
+        // Sort by count descending
+        const sortedDistribution = {};
+        Object.entries(distribution)
+            .sort(([, a], [, b]) => b - a)
+            .slice(0, 20) // Top 20 values
+            .forEach(([k, v]) => { sortedDistribution[k] = v; });
+        result.distribution = sortedDistribution;
+    }
+    return result;
+}
+function computeNumberArrayStats(value, path) {
+    const numbers = value.filter((v) => typeof v === "number" && !isNaN(v));
+    const nullCount = value.length - numbers.length;
+    if (numbers.length === 0) {
+        return {
+            path,
+            arrayLength: value.length,
+            itemType: "number",
+            nullCount,
+            uniqueCount: 0,
+        };
+    }
+    const sorted = [...numbers].sort((a, b) => a - b);
+    const sum = numbers.reduce((a, b) => a + b, 0);
+    const avg = sum / numbers.length;
+    // Standard deviation
+    const squaredDiffs = numbers.map((n) => Math.pow(n - avg, 2));
+    const avgSquaredDiff = squaredDiffs.reduce((a, b) => a + b, 0) / numbers.length;
+    const stdDev = Math.sqrt(avgSquaredDiff);
+    // Percentile helper
+    const percentile = (p) => {
+        const index = (p / 100) * (sorted.length - 1);
+        const lower = Math.floor(index);
+        const upper = Math.ceil(index);
+        if (lower === upper)
+            return sorted[lower];
+        return sorted[lower] + (index - lower) * (sorted[upper] - sorted[lower]);
+    };
+    // Unique values
+    const uniqueCount = new Set(numbers).size;
+    const result = {
+        path,
+        arrayLength: value.length,
+        itemType: "number",
+        nullCount,
+        uniqueCount,
+        numericStats: {
+            min: sorted[0],
+            max: sorted[sorted.length - 1],
+            avg: Math.round(avg * 1000) / 1000,
+            median: percentile(50),
+            stdDev: Math.round(stdDev * 1000) / 1000,
+            percentiles: {
+                p25: Math.round(percentile(25) * 1000) / 1000,
+                p50: Math.round(percentile(50) * 1000) / 1000,
+                p75: Math.round(percentile(75) * 1000) / 1000,
+                p90: Math.round(percentile(90) * 1000) / 1000,
+                p99: Math.round(percentile(99) * 1000) / 1000,
+            },
+        },
+    };
+    // If there are few unique values, include distribution
+    if (uniqueCount <= 20) {
+        const distribution = {};
+        for (const n of numbers) {
+            const key = String(n);
+            distribution[key] = (distribution[key] || 0) + 1;
+        }
+        result.distribution = distribution;
+    }
+    return result;
+}
+function computeMixedArrayStats(value, path) {
+    // Count types
+    const typeBreakdown = {};
+    for (const item of value) {
+        const t = item === null ? "null" : typeof item;
+        typeBreakdown[t] = (typeBreakdown[t] || 0) + 1;
+    }
+    const nullCount = typeBreakdown["null"] || 0 + (typeBreakdown["undefined"] || 0);
+    const result = {
+        path,
+        arrayLength: value.length,
+        itemType: "mixed",
+        typeBreakdown,
+        nullCount,
+    };
+    // Compute string stats if there are strings
+    const strings = value.filter((v) => typeof v === "string");
+    if (strings.length > 0) {
+        const lengths = strings.map((s) => s.length);
+        const sortedLengths = [...lengths].sort((a, b) => a - b);
+        const stringDistribution = {};
+        for (const s of strings) {
+            stringDistribution[s] = (stringDistribution[s] || 0) + 1;
+        }
+        const stringUniqueCount = Object.keys(stringDistribution).length;
+        result.stringStats = {
+            count: strings.length,
+            uniqueCount: stringUniqueCount,
+            lengthStats: {
+                min: Math.min(...lengths),
+                max: Math.max(...lengths),
+                avg: Math.round(lengths.reduce((a, b) => a + b, 0) / lengths.length * 100) / 100,
+                median: sortedLengths[Math.floor(sortedLengths.length / 2)],
+            },
+        };
+        // Include distribution if reasonable number of unique values
+        if (stringUniqueCount <= 30) {
+            const sortedDistribution = {};
+            Object.entries(stringDistribution)
+                .sort(([, a], [, b]) => b - a)
+                .slice(0, 15)
+                .forEach(([k, v]) => { sortedDistribution[k] = v; });
+            result.stringStats.distribution = sortedDistribution;
+        }
+    }
+    // Compute number stats if there are numbers
+    const numbers = value.filter((v) => typeof v === "number" && !isNaN(v));
+    if (numbers.length > 0) {
+        const sorted = [...numbers].sort((a, b) => a - b);
+        const sum = numbers.reduce((a, b) => a + b, 0);
+        const avg = sum / numbers.length;
+        const squaredDiffs = numbers.map((n) => Math.pow(n - avg, 2));
+        const avgSquaredDiff = squaredDiffs.reduce((a, b) => a + b, 0) / numbers.length;
+        const stdDev = Math.sqrt(avgSquaredDiff);
+        const percentile = (p) => {
+            const index = (p / 100) * (sorted.length - 1);
+            const lower = Math.floor(index);
+            const upper = Math.ceil(index);
+            if (lower === upper)
+                return sorted[lower];
+            return sorted[lower] + (index - lower) * (sorted[upper] - sorted[lower]);
+        };
+        result.numericStats = {
+            count: numbers.length,
+            min: sorted[0],
+            max: sorted[sorted.length - 1],
+            avg: Math.round(avg * 1000) / 1000,
+            median: percentile(50),
+            stdDev: Math.round(stdDev * 1000) / 1000,
+            percentiles: {
+                p25: Math.round(percentile(25) * 1000) / 1000,
+                p50: Math.round(percentile(50) * 1000) / 1000,
+                p75: Math.round(percentile(75) * 1000) / 1000,
+                p90: Math.round(percentile(90) * 1000) / 1000,
+                p99: Math.round(percentile(99) * 1000) / 1000,
+            },
+        };
+    }
+    return result;
+}

package/dist/tools/structure.d.ts

@@ -28,6 +28,13 @@ export interface ValidateResult {
     valid: boolean;
     errors: ValidationError[];
     errorCount: number;
+    truncatedErrorCount?: number;
+    resolvedRefs?: string[];
 }
-export declare function jsonValidate(filePath: string, schema: object | string, path?: string): Promise<ValidateResult>;
+export interface ValidateOptions {
+    errorLimit?: number;
+    resolveLocalRefs?: boolean;
+    resolveNetworkRefs?: boolean;
+}
+export declare function jsonValidate(filePath: string, schema: object | string, path?: string, options?: ValidateOptions | number): Promise<ValidateResult>;
 export {};

package/dist/tools/structure.js

@@ -1,5 +1,6 @@
 import { loadJson, getFileInfo, formatBytes, getValueType } from "../utils/json-parser.js";
 import { getDepthPreview, getValueAtPath } from "../utils/path-helpers.js";
+import { dirname, resolve, isAbsolute } from "path";
 // Dynamic import for ajv (ESM/CJS compat)
 async function getAjv() {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -115,7 +116,130 @@ export async function jsonSchema(filePath, path) {
         schema: inferSchema(targetData),
     };
 }
-export async function jsonValidate(filePath, schema, path) {
+// Find all $ref values in a schema object
+function findRefs(obj, refs = new Set()) {
+    if (obj === null || typeof obj !== "object") {
+        return refs;
+    }
+    if (Array.isArray(obj)) {
+        for (const item of obj) {
+            findRefs(item, refs);
+        }
+    }
+    else {
+        const record = obj;
+        if (typeof record.$ref === "string") {
+            refs.add(record.$ref);
+        }
+        for (const value of Object.values(record)) {
+            findRefs(value, refs);
+        }
+    }
+    return refs;
+}
+// Check if a ref is a local file path (not a URL or JSON pointer)
+function isLocalFileRef(ref) {
+    // Skip JSON pointers (start with #)
+    if (ref.startsWith("#"))
+        return false;
+    // Skip URLs
+    if (ref.startsWith("http://") || ref.startsWith("https://"))
+        return false;
+    // It's a local file ref
+    return true;
+}
+// Check if a ref is an HTTP URL
+function isNetworkRef(ref) {
+    return ref.startsWith("http://") || ref.startsWith("https://");
+}
+// Resolve a local file ref relative to the schema's directory
+function resolveLocalRef(ref, schemaDir) {
+    // Remove any JSON pointer fragment
+    const [filePath] = ref.split("#");
+    if (!filePath)
+        return ref;
+    if (isAbsolute(filePath)) {
+        return filePath;
+    }
+    return resolve(schemaDir, filePath);
+}
+// Recursively load all local schema refs
+async function loadLocalRefs(schemaObj, schemaDir, loaded = new Map()) {
+    const refs = findRefs(schemaObj);
+    for (const ref of refs) {
+        if (!isLocalFileRef(ref))
+            continue;
+        const filePath = resolveLocalRef(ref, schemaDir);
+        if (loaded.has(filePath))
+            continue;
+        try {
+            const refSchema = await loadJson(filePath);
+            // Validate that it's actually a JSON Schema
+            if (!isValidJsonSchema(refSchema)) {
+                throw new Error(`File ${filePath} is not a valid JSON Schema`);
+            }
+            loaded.set(filePath, refSchema);
+            // Recursively load refs from this schema
+            const refDir = dirname(filePath);
+            await loadLocalRefs(refSchema, refDir, loaded);
+        }
+        catch (err) {
+            // Re-throw validation errors, skip other errors (file not found, etc.)
+            if (err instanceof Error && err.message.includes("not a valid JSON Schema")) {
+                throw err;
+            }
+            // Skip refs we can't load - ajv will report the error
+        }
+    }
+    return loaded;
+}
+// Validate that an object looks like a JSON Schema
+function isValidJsonSchema(obj) {
+    if (obj === null || typeof obj !== "object" || Array.isArray(obj)) {
+        return false;
+    }
+    const schema = obj;
+    // A valid JSON Schema should be an object with schema-like properties
+    // Check for common JSON Schema keywords
+    const schemaKeywords = [
+        "type", "properties", "items", "required", "enum", "const",
+        "allOf", "anyOf", "oneOf", "not", "$ref", "$id", "$schema",
+        "definitions", "$defs", "additionalProperties", "patternProperties",
+        "minimum", "maximum", "minLength", "maxLength", "pattern", "format"
+    ];
+    // Must have at least one schema keyword, OR be a boolean schema (but we already checked it's an object)
+    // Empty objects {} are valid schemas (match anything), so we allow those too
+    const hasSchemaKeyword = schemaKeywords.some(keyword => keyword in schema);
+    const isEmpty = Object.keys(schema).length === 0;
+    return hasSchemaKeyword || isEmpty;
+}
+// Fetch a schema from a URL
+async function fetchNetworkSchema(url) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch schema from ${url}: ${response.status} ${response.statusText}`);
+    }
+    let data;
+    try {
+        data = await response.json();
+    }
+    catch {
+        throw new Error(`Invalid JSON received from ${url}`);
+    }
+    if (!isValidJsonSchema(data)) {
+        throw new Error(`URL ${url} did not return a valid JSON Schema`);
+    }
+    return data;
+}
+export async function jsonValidate(filePath, schema, path, options = {}) {
+    // Handle legacy signature where 4th param was errorLimit number
+    const opts = typeof options === "number"
+        ? { errorLimit: options }
+        : options;
+    // Environment variable can completely disable network refs for security
+    const networkRefsDisabled = process.env.JSON_EXPLORER_NO_NETWORK === "1";
+    const { errorLimit = 10, resolveLocalRefs = true, resolveNetworkRefs = false, } = opts;
+    const effectiveResolveNetworkRefs = resolveNetworkRefs && !networkRefsDisabled;
     const data = await loadJson(filePath);
     const targetData = path ? getValueAtPath(data, path) : data;
     if (targetData === undefined) {
@@ -123,26 +247,85 @@ export async function jsonValidate(filePath, schema, path) {
     }
     // Load schema from file if it's a string path
     let schemaObj;
+    let schemaDir;
     if (typeof schema === "string") {
         schemaObj = (await loadJson(schema));
+        schemaDir = dirname(resolve(schema));
     }
     else {
         schemaObj = schema;
+        // For inline schemas, use current working directory
+        schemaDir = process.cwd();
     }
     const { Ajv, addFormats } = await getAjv();
-    const ajv = new Ajv({ allErrors: true });
+    // Configure ajv options
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const ajvOptions = { allErrors: true };
+    // Set up network schema loading if enabled
+    if (effectiveResolveNetworkRefs) {
+        ajvOptions.loadSchema = async (uri) => {
+            if (isNetworkRef(uri)) {
+                return fetchNetworkSchema(uri);
+            }
+            throw new Error(`Cannot load non-network ref: ${uri}`);
+        };
+    }
+    const ajv = new Ajv(ajvOptions);
     addFormats(ajv);
-    const validate = ajv.compile(schemaObj);
+    // Pre-load local refs if enabled
+    const resolvedRefs = [];
+    if (resolveLocalRefs) {
+        const localRefs = await loadLocalRefs(schemaObj, schemaDir);
+        for (const [refPath, refSchema] of localRefs) {
+            // If schema has $id, ajv will use that for resolution
+            // Otherwise we add it by its relative filename
+            const refRecord = refSchema;
+            if (refRecord.$id) {
+                // Schema has its own $id - ajv will register it by that
+                ajv.addSchema(refSchema);
+            }
+            else {
+                // No $id - register by filename (last component of path)
+                const filename = refPath.split("/").pop() || refPath;
+                ajv.addSchema(refSchema, filename);
+            }
+            resolvedRefs.push(refPath);
+        }
+    }
+    // Compile and validate
+    let validate;
+    try {
+        if (effectiveResolveNetworkRefs) {
+            // Use compileAsync for network refs
+            validate = await ajv.compileAsync(schemaObj);
+        }
+        else {
+            validate = ajv.compile(schemaObj);
+        }
+    }
+    catch (err) {
+        throw new Error(`Schema compilation failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
     const valid = validate(targetData);
-    const errors = (validate.errors || []).map((err) => ({
+    const allErrors = (validate.errors || []).map((err) => ({
         path: err.instancePath || "$",
         message: err.message || "Unknown error",
         keyword: err.keyword,
         params: err.params,
     }));
-    return {
+    const totalErrorCount = allErrors.length;
+    const truncated = totalErrorCount > errorLimit;
+    const errors = truncated ? allErrors.slice(0, errorLimit) : allErrors;
+    const result = {
         valid: valid === true,
         errors,
-        errorCount: errors.length,
+        errorCount: totalErrorCount,
     };
+    if (truncated) {
+        result.truncatedErrorCount = totalErrorCount - errorLimit;
+    }
+    if (resolvedRefs.length > 0) {
+        result.resolvedRefs = resolvedRefs;
+    }
+    return result;
 }

package/dist/utils/json-parser.js

@@ -27,7 +27,14 @@ export async function loadJson(filePath) {
     }
     // Read and parse file
     const content = await readFile(filePath, "utf-8");
-    const data = JSON.parse(content);
+    let data;
+    try {
+        data = JSON.parse(content);
+    }
+    catch (err) {
+        const message = err instanceof SyntaxError ? err.message : "Unknown parse error";
+        throw new Error(`Invalid JSON in ${filePath}: ${message}`);
+    }
     // Update cache (with size management)
     if (info.size < MAX_CACHE_SIZE / 2) {
         // Only cache files smaller than half the max cache size

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-explorer-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "MCP server for efficiently exploring large JSON files",
   "type": "module",
   "main": "dist/index.js",