json-explorer-mcp 1.0.1 → 1.0.3

package/README.md

@@ -8,8 +8,8 @@ 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
-- **Schema validation** - Validate data against JSON Schema
-- **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
 
@@ -110,6 +110,80 @@ Retrieve the value at a specific path. Large values are automatically truncated.
 json_get(file: "/path/to/data.json", path: "$.users[0]")
 ```
 
+### json_set
+
+Set a value at a specific JSONPath with optional schema validation.
+
+```typescript
+json_set(
+  file: "/path/to/data.json",
+  path: "$.users[0].name",
+  value: "New Name"
+)
+```
+
+With schema validation (validates before writing):
+
+```typescript
+json_set(
+  file: "/path/to/data.json",
+  path: "$.users[0]",
+  value: { id: 1, name: "Alice", email: "alice@example.com" },
+  schema: "/path/to/user-schema.json"
+)
+```
+
+With inferred schema (infers type from existing value):
+
+```typescript
+json_set(
+  file: "/path/to/data.json",
+  path: "$.config.maxRetries",
+  value: 5,
+  inferSchema: true  // Will reject if new value type doesn't match existing
+)
+```
+
+With dry run (validates without writing):
+
+```typescript
+json_set(
+  file: "/path/to/data.json",
+  path: "$.config.enabled",
+  value: true,
+  dryRun: true,      // Returns result without modifying file
+  outputFile: "/path/to/output.json"  // Or write to different file
+)
+```
+
+Returns:
+
+```json
+{
+  "success": true,
+  "path": "$.config.enabled",
+  "previousValue": false,
+  "newValue": true,
+  "dryRun": false,
+  "outputFile": "/path/to/data.json"
+}
+```
+
+On validation failure:
+
+```json
+{
+  "success": false,
+  "path": "$.config.maxRetries",
+  "previousValue": 3,
+  "newValue": "not a number",
+  "validationErrors": [
+    { "path": "$", "message": "must be integer" }
+  ],
+  "dryRun": true
+}
+```
+
 ### json_schema
 
 Infer the JSON schema/structure at a path. For arrays, samples items to determine the item schema.
@@ -141,6 +215,13 @@ Returns:
 
 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)
+- Schema registry for pre-registering schemas by URI (map remote refs to local files)
+- 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",
@@ -149,7 +230,7 @@ json_validate(
 )
 ```
 
-Or with a schema file:
+Or with a schema file (local `$ref`s are automatically resolved):
 
 ```typescript
 json_validate(
@@ -158,16 +239,58 @@ json_validate(
 )
 ```
 
+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)
+)
+```
+
+With pre-registered schemas (for complex `$ref` scenarios):
+
+```typescript
+json_validate(
+  file: "/path/to/data.json",
+  schema: "/path/to/schema.json",
+  schemas: {
+    // Map URIs to local files or inline schemas
+    "https://example.com/schemas/user.json": "/local/path/to/user-schema.json",
+    "https://example.com/schemas/address.json": { type: "object", properties: { ... } }
+  }
+)
+```
+
+With schema directory (loads all schemas by their `$id`):
+
+```typescript
+json_validate(
+  file: "/path/to/data.json",
+  schema: {},  // Not needed when using schemaDir+schemaId
+  schemaDir: "/path/to/schemas/",   // Directory with .json schema files
+  schemaId: "main-schema"           // $id of the entrypoint schema
+)
+```
+
+This is useful when you have a directory of interconnected schemas that reference each other by `$id`. All `.json` files in the directory are loaded and registered by their `$id` (or filename if no `$id` is present).
+
 Returns:
 
 ```json
 {
   "valid": false,
-  "errorCount": 2,
+  "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"]
 }
 ```
 
@@ -230,6 +353,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

package/dist/index.js

@@ -3,11 +3,11 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { jsonInspect, jsonSchema, jsonValidate } from "./tools/structure.js";
-import { jsonKeys, jsonGet } from "./tools/navigation.js";
+import { jsonKeys, jsonGet, jsonSet } from "./tools/navigation.js";
 import { jsonSearch, jsonSample, jsonStats } from "./tools/query.js";
 const server = new McpServer({
     name: "json-explorer",
-    version: "1.0.0",
+    version: "1.0.3",
 });
 // Tool: json_inspect - Get file overview
 server.tool("json_inspect", "Get an overview of a JSON file including size, structure type, and a depth-limited preview. Use this first to understand what you're working with.", {
@@ -94,6 +94,44 @@ server.tool("json_get", "Retrieve the value at a specific path. Large values are
         };
     }
 });
+// Tool: json_set - Set value at path with optional schema validation
+server.tool("json_set", "Set a value at a specific JSONPath. Supports schema validation (inline, file, or inferred from existing data) and dry-run mode. Can write to the source file or a different output file.", {
+    file: z.string().describe("Absolute path to the JSON file to modify"),
+    path: z.string().describe("JSONPath where to set the value (e.g., '$.users[0].name', 'config.enabled')"),
+    value: z.unknown().describe("The value to set at the path"),
+    schema: z.union([z.string(), z.object({}).passthrough()]).optional().describe("JSON Schema to validate value against (inline object or path to schema file)"),
+    inferSchema: z.boolean().optional().describe("If true, infers schema from existing value at path and validates against it. Defaults to false."),
+    dryRun: z.boolean().optional().describe("If true, validates and returns result without writing to file. Defaults to false."),
+    outputFile: z.string().optional().describe("Output file path. If not provided, writes to the source file."),
+}, { readOnlyHint: false }, async ({ file, path, value, schema, inferSchema, dryRun, outputFile }) => {
+    try {
+        const result = await jsonSet(file, path, value, {
+            schema,
+            inferSchema,
+            dryRun,
+            outputFile,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
 // Tool: json_schema - Infer structure
 server.tool("json_schema", "Infer the JSON schema/structure at a path. For arrays, samples items to determine the item schema.", {
     file: z.string().describe("Absolute path to the JSON file"),
@@ -123,13 +161,26 @@ 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, as a file path, or loaded from a directory by $id. Automatically resolves local file $refs. Use schemas to pre-register schemas by URI, or schemaDir+schemaId to load all schemas from a directory.", {
     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"),
+    schema: z.union([z.string(), z.object({}).passthrough()]).optional().describe("JSON Schema object or path to schema file. Optional if using schemaDir+schemaId."),
     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."),
+    schemas: z.record(z.union([z.string(), z.object({}).passthrough()])).optional().describe("Pre-register schemas by URI. Map of URI to schema file path or inline schema object."),
+    schemaDir: z.string().optional().describe("Directory containing schema files. All .json files will be loaded and registered by their $id."),
+    schemaId: z.string().optional().describe("When using schemaDir, the $id of the schema to use as entrypoint."),
+}, { readOnlyHint: true }, async ({ file, schema, path, errorLimit, resolveLocalRefs, resolveNetworkRefs, schemas, schemaDir, schemaId }) => {
     try {
-        const result = await jsonValidate(file, schema, path);
+        const result = await jsonValidate(file, schema ?? {}, path, {
+            errorLimit,
+            resolveLocalRefs,
+            resolveNetworkRefs,
+            schemas,
+            schemaDir,
+            schemaId,
+        });
         return {
             content: [
                 {
@@ -213,7 +264,7 @@ server.tool("json_sample", "Get sample items from an array. Supports first, last
     }
 });
 // Tool: json_stats - Aggregate statistics for arrays
-server.tool("json_stats", "Get aggregate statistics for array fields. If no path provided, discovers all arrays in the file. With a path, returns counts, min/max/avg for numbers, value distributions for strings.", {
+server.tool("json_stats", "Get aggregate statistics for arrays. Supports arrays of objects (field-level stats), strings (length distribution), numbers (min/max/avg/median/stdDev/percentiles), and mixed types. If no path provided, discovers and analyzes all arrays in the file.", {
     file: z.string().describe("Absolute path to the JSON file"),
     path: z.string().optional().describe("JSONPath to the array. If omitted, discovers and lists all arrays in the file."),
     fields: z.array(z.string()).optional().describe("Specific fields to analyze. If not provided, analyzes all top-level fields."),

package/dist/tools/navigation.d.ts

@@ -19,3 +19,26 @@ export interface GetResult {
     originalSize?: number;
 }
 export declare function jsonGet(filePath: string, path: string, maxSize?: number): Promise<GetResult>;
+export interface SetOptions {
+    /** JSON Schema to validate against (inline object or file path) */
+    schema?: object | string;
+    /** Infer schema from existing value at path. Defaults to false. */
+    inferSchema?: boolean;
+    /** If true, only validate without writing. Returns the modified JSON. */
+    dryRun?: boolean;
+    /** Output file path. If not provided, writes to the source file. */
+    outputFile?: string;
+}
+export interface SetResult {
+    success: boolean;
+    path: string;
+    previousValue?: unknown;
+    newValue: unknown;
+    validationErrors?: Array<{
+        path: string;
+        message: string;
+    }>;
+    outputFile?: string;
+    dryRun: boolean;
+}
+export declare function jsonSet(filePath: string, path: string, value: unknown, options?: SetOptions): Promise<SetResult>;

package/dist/tools/navigation.js

@@ -1,5 +1,6 @@
 import { loadJson, getValueType, truncateValue, getValuePreview } from "../utils/json-parser.js";
-import { getValueAtPath, getKeysAtPath, buildPathTo } from "../utils/path-helpers.js";
+import { getValueAtPath, getKeysAtPath, buildPathTo, setValueAtPath } from "../utils/path-helpers.js";
+import { writeFile } from "fs/promises";
 export async function jsonKeys(filePath, path, limit = 50) {
     const data = await loadJson(filePath);
     const targetPath = path || "$";
@@ -95,3 +96,107 @@ export async function jsonGet(filePath, path, maxSize = 5000) {
         ...(truncated && { originalSize }),
     };
 }
+// Dynamic import for ajv (ESM/CJS compat)
+async function getAjv() {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const ajvModule = await import("ajv");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const formatsModule = await import("ajv-formats");
+    const Ajv = ajvModule.default || ajvModule;
+    const addFormats = formatsModule.default || formatsModule;
+    return { Ajv, addFormats };
+}
+// Infer a simple JSON Schema from a value
+function inferSimpleSchema(value) {
+    if (value === null) {
+        return { type: "null" };
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            return { type: "array" };
+        }
+        // Sample first item for items schema
+        return { type: "array", items: inferSimpleSchema(value[0]) };
+    }
+    if (typeof value === "object") {
+        const properties = {};
+        for (const [key, val] of Object.entries(value)) {
+            properties[key] = inferSimpleSchema(val);
+        }
+        return { type: "object", properties };
+    }
+    if (typeof value === "number") {
+        return Number.isInteger(value) ? { type: "integer" } : { type: "number" };
+    }
+    return { type: typeof value };
+}
+export async function jsonSet(filePath, path, value, options = {}) {
+    const { schema, inferSchema: shouldInferSchema = false, dryRun = false, outputFile, } = options;
+    // Load the JSON file
+    const data = await loadJson(filePath);
+    // Deep clone to avoid mutating cached data
+    const clonedData = JSON.parse(JSON.stringify(data));
+    // Get previous value at path (may be undefined if path doesn't exist yet)
+    const previousValue = getValueAtPath(clonedData, path);
+    // Determine schema for validation
+    let schemaToValidate;
+    if (schema) {
+        if (typeof schema === "string") {
+            // Load schema from file
+            schemaToValidate = (await loadJson(schema));
+        }
+        else {
+            schemaToValidate = schema;
+        }
+    }
+    else if (shouldInferSchema && previousValue !== undefined) {
+        // Infer schema from existing value
+        schemaToValidate = inferSimpleSchema(previousValue);
+    }
+    // Validate the new value against schema
+    if (schemaToValidate) {
+        const { Ajv, addFormats } = await getAjv();
+        const ajv = new Ajv({ allErrors: true });
+        addFormats(ajv);
+        const validate = ajv.compile(schemaToValidate);
+        const valid = validate(value);
+        if (!valid) {
+            const errors = (validate.errors || []).map((err) => ({
+                path: err.instancePath || "$",
+                message: err.message || "Unknown error",
+            }));
+            return {
+                success: false,
+                path,
+                previousValue,
+                newValue: value,
+                validationErrors: errors,
+                dryRun: true, // Force dryRun on validation failure
+            };
+        }
+    }
+    // Set the value at path
+    const modifiedData = setValueAtPath(clonedData, path, value);
+    // If dry run, return the modified data without writing
+    if (dryRun) {
+        return {
+            success: true,
+            path,
+            previousValue,
+            newValue: value,
+            dryRun: true,
+        };
+    }
+    // Write to file
+    const targetFile = outputFile || filePath;
+    const jsonOutput = JSON.stringify(modifiedData, null, 2);
+    await writeFile(targetFile, jsonOutput, "utf-8");
+    return {
+        success: true,
+        path,
+        previousValue,
+        newValue: value,
+        outputFile: targetFile,
+        dryRun: false,
+    };
+}

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,19 @@ 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;
+    /** Pre-register schemas by URI. Value can be inline schema object or path to schema file. */
+    schemas?: Record<string, object | string>;
+    /** Directory containing schema files. All .json files will be loaded and registered by their $id. */
+    schemaDir?: string;
+    /** When using schemaDir, specify the $id of the schema to use as entrypoint (instead of schema param). */
+    schemaId?: string;
+}
+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,7 @@
 import { loadJson, getFileInfo, formatBytes, getValueType } from "../utils/json-parser.js";
 import { getDepthPreview, getValueAtPath } from "../utils/path-helpers.js";
+import { dirname, resolve, isAbsolute, join } from "path";
+import { readdir } from "fs/promises";
 // Dynamic import for ajv (ESM/CJS compat)
 async function getAjv() {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -115,34 +117,287 @@ 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;
+}
+// Load all JSON schema files from a directory, returning map of $id -> schema
+async function loadSchemasFromDir(dir) {
+    const schemas = new Map();
+    const files = await readdir(dir);
+    const jsonFiles = files.filter(f => f.endsWith(".json"));
+    for (const file of jsonFiles) {
+        const filePath = join(dir, file);
+        try {
+            const schema = await loadJson(filePath);
+            if (!isValidJsonSchema(schema)) {
+                continue; // Skip non-schema JSON files
+            }
+            const schemaRecord = schema;
+            const id = schemaRecord.$id;
+            if (id) {
+                schemas.set(id, { schema, file: filePath });
+            }
+            else {
+                // Use filename as fallback id
+                schemas.set(file, { schema, file: filePath });
+            }
+        }
+        catch {
+            // Skip files that can't be loaded
+        }
+    }
+    return schemas;
+}
+// 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, schemas = {}, schemaDir, schemaId, } = opts;
+    const effectiveResolveNetworkRefs = resolveNetworkRefs && !networkRefsDisabled;
     const data = await loadJson(filePath);
     const targetData = path ? getValueAtPath(data, path) : data;
     if (targetData === undefined) {
         throw new Error(`Path not found: ${path}`);
     }
-    // Load schema from file if it's a string path
+    // Load schema - from schemaDir+schemaId, file path, or inline
     let schemaObj;
-    if (typeof schema === "string") {
+    let schemaBaseDir;
+    let dirSchemas;
+    if (schemaDir && schemaId) {
+        // Load all schemas from directory and use schemaId as entrypoint
+        dirSchemas = await loadSchemasFromDir(schemaDir);
+        const entry = dirSchemas.get(schemaId);
+        if (!entry) {
+            const availableIds = Array.from(dirSchemas.keys()).join(", ");
+            throw new Error(`Schema with $id "${schemaId}" not found in ${schemaDir}. Available: ${availableIds}`);
+        }
+        schemaObj = entry.schema;
+        schemaBaseDir = schemaDir;
+    }
+    else if (typeof schema === "string") {
         schemaObj = (await loadJson(schema));
+        schemaBaseDir = dirname(resolve(schema));
     }
     else {
         schemaObj = schema;
+        // For inline schemas, use current working directory
+        schemaBaseDir = 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-register user-provided schemas
+    const resolvedRefs = [];
+    for (const [uri, schemaValue] of Object.entries(schemas)) {
+        let schemaToAdd;
+        if (typeof schemaValue === "string") {
+            // Load from file
+            const loaded = await loadJson(schemaValue);
+            if (!isValidJsonSchema(loaded)) {
+                throw new Error(`Schema file ${schemaValue} is not a valid JSON Schema`);
+            }
+            schemaToAdd = loaded;
+            resolvedRefs.push(schemaValue);
+        }
+        else {
+            // Inline schema object
+            if (!isValidJsonSchema(schemaValue)) {
+                throw new Error(`Inline schema for "${uri}" is not a valid JSON Schema`);
+            }
+            schemaToAdd = schemaValue;
+        }
+        ajv.addSchema(schemaToAdd, uri);
+    }
+    // Register all schemas from schemaDir (if provided)
+    if (dirSchemas) {
+        for (const [id, { schema: dirSchema, file }] of dirSchemas) {
+            // Don't re-register the entrypoint schema
+            if (id !== schemaId) {
+                ajv.addSchema(dirSchema, id);
+                resolvedRefs.push(file);
+            }
+        }
+    }
+    // Pre-load local refs if enabled (skip if using schemaDir since all schemas are already loaded)
+    if (resolveLocalRefs && !dirSchemas) {
+        const localRefs = await loadLocalRefs(schemaObj, schemaBaseDir);
+        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/dist/utils/path-helpers.d.ts

@@ -3,4 +3,10 @@ export declare function normalizeToJsonPath(path: string): string;
 export declare function getKeysAtPath(data: unknown, path: string): string[];
 export declare function buildPathTo(basePath: string, key: string): string;
 export declare function findPaths(data: unknown, predicate: (value: unknown, path: string) => boolean, currentPath?: string, maxResults?: number): string[];
+/**
+ * Set a value at a specific JSONPath in the data.
+ * Mutates the data in place and returns the modified data.
+ * Throws if the path doesn't exist (parent must exist).
+ */
+export declare function setValueAtPath(data: unknown, path: string, value: unknown): unknown;
 export declare function getDepthPreview(data: unknown, maxDepth?: number, currentDepth?: number): unknown;

package/dist/utils/path-helpers.js

@@ -70,6 +70,94 @@ export function findPaths(data, predicate, currentPath = "$", maxResults = 100)
     traverse(data, currentPath);
     return results;
 }
+/**
+ * Parse a JSONPath into segments for traversal.
+ * Returns array of keys/indices to traverse.
+ */
+function parsePathSegments(path) {
+    const normalized = normalizeToJsonPath(path);
+    if (normalized === "$")
+        return [];
+    const segments = [];
+    // Remove leading $
+    const pathWithoutRoot = normalized.slice(1);
+    // Match either .key, [index], or ["key"]
+    const regex = /\.([a-zA-Z_][a-zA-Z0-9_]*)|\.?(\[(\d+)\])|\.?\["([^"]+)"\]|\.?\['([^']+)'\]/g;
+    let match;
+    while ((match = regex.exec(pathWithoutRoot)) !== null) {
+        if (match[1] !== undefined) {
+            // .key format
+            segments.push(match[1]);
+        }
+        else if (match[3] !== undefined) {
+            // [index] format
+            segments.push(parseInt(match[3], 10));
+        }
+        else if (match[4] !== undefined) {
+            // ["key"] format
+            segments.push(match[4]);
+        }
+        else if (match[5] !== undefined) {
+            // ['key'] format
+            segments.push(match[5]);
+        }
+    }
+    return segments;
+}
+/**
+ * Set a value at a specific JSONPath in the data.
+ * Mutates the data in place and returns the modified data.
+ * Throws if the path doesn't exist (parent must exist).
+ */
+export function setValueAtPath(data, path, value) {
+    const segments = parsePathSegments(path);
+    if (segments.length === 0) {
+        // Setting root - just return the new value
+        return value;
+    }
+    // Traverse to parent
+    let current = data;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const segment = segments[i];
+        if (current === null || typeof current !== "object") {
+            throw new Error(`Cannot traverse path: parent at segment "${segment}" is not an object or array`);
+        }
+        if (Array.isArray(current)) {
+            if (typeof segment !== "number") {
+                throw new Error(`Cannot use string key "${segment}" on array`);
+            }
+            if (segment < 0 || segment >= current.length) {
+                throw new Error(`Array index ${segment} out of bounds (length: ${current.length})`);
+            }
+            current = current[segment];
+        }
+        else {
+            const key = String(segment);
+            if (!(key in current)) {
+                throw new Error(`Key "${key}" not found in object`);
+            }
+            current = current[key];
+        }
+    }
+    // Set the value at the final segment
+    const finalSegment = segments[segments.length - 1];
+    if (current === null || typeof current !== "object") {
+        throw new Error(`Cannot set value: parent is not an object or array`);
+    }
+    if (Array.isArray(current)) {
+        if (typeof finalSegment !== "number") {
+            throw new Error(`Cannot use string key "${finalSegment}" on array`);
+        }
+        if (finalSegment < 0 || finalSegment >= current.length) {
+            throw new Error(`Array index ${finalSegment} out of bounds (length: ${current.length})`);
+        }
+        current[finalSegment] = value;
+    }
+    else {
+        current[String(finalSegment)] = value;
+    }
+    return data;
+}
 export function getDepthPreview(data, maxDepth = 2, currentDepth = 0) {
     if (currentDepth >= maxDepth) {
         if (data === null)

package/package.json

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