json-explorer-mcp 1.0.3 → 1.0.6

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, jsonSet } from "./tools/navigation.js";
+import { jsonKeys, jsonGet, jsonSet, jsonFormat } from "./tools/navigation.js";
 import { jsonSearch, jsonSample, jsonStats } from "./tools/query.js";
 const server = new McpServer({
     name: "json-explorer",
-    version: "1.0.3",
+    version: "1.0.6",
 });
 // 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.", {
@@ -103,13 +103,49 @@ server.tool("json_set", "Set a value at a specific JSONPath. Supports schema val
     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 }) => {
+    strict: z.boolean().optional().describe("Enable AJV strict mode. Set to false for schemas with custom keywords. Defaults to true."),
+}, { readOnlyHint: false }, async ({ file, path, value, schema, inferSchema, dryRun, outputFile, strict }) => {
     try {
         const result = await jsonSet(file, path, value, {
             schema,
             inferSchema,
             dryRun,
             outputFile,
+            strict,
+        });
+        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_format - Reformat JSON file
+server.tool("json_format", "Reformat a JSON file with configurable indentation and optional key sorting. Useful for normalizing JSON formatting or preparing files for version control.", {
+    file: z.string().describe("Absolute path to the JSON file to format"),
+    indent: z.number().optional().describe("Number of spaces for indentation. Use 0 for compact single-line output. Defaults to 2."),
+    sortKeys: z.boolean().optional().describe("Sort object keys alphabetically (recursive). Defaults to false."),
+    outputFile: z.string().optional().describe("Output file path. If not provided, overwrites the source file."),
+}, { readOnlyHint: false }, async ({ file, indent, sortKeys, outputFile }) => {
+    try {
+        const result = await jsonFormat(file, {
+            indent,
+            sortKeys,
+            outputFile,
         });
         return {
             content: [
@@ -171,7 +207,8 @@ server.tool("json_validate", "Validate JSON data against a JSON Schema. Schema c
     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 }) => {
+    strict: z.boolean().optional().describe("Enable AJV strict mode. Set to false for schemas with custom keywords. Defaults to true."),
+}, { readOnlyHint: true }, async ({ file, schema, path, errorLimit, resolveLocalRefs, resolveNetworkRefs, schemas, schemaDir, schemaId, strict }) => {
     try {
         const result = await jsonValidate(file, schema ?? {}, path, {
             errorLimit,
@@ -180,6 +217,7 @@ server.tool("json_validate", "Validate JSON data against a JSON Schema. Schema c
             schemas,
             schemaDir,
             schemaId,
+            strict,
         });
         return {
             content: [

package/dist/tools/navigation.d.ts

@@ -28,6 +28,8 @@ export interface SetOptions {
     dryRun?: boolean;
     /** Output file path. If not provided, writes to the source file. */
     outputFile?: string;
+    /** Enable AJV strict mode. Set to false for schemas with custom keywords. Defaults to true. */
+    strict?: boolean;
 }
 export interface SetResult {
     success: boolean;
@@ -42,3 +44,19 @@ export interface SetResult {
     dryRun: boolean;
 }
 export declare function jsonSet(filePath: string, path: string, value: unknown, options?: SetOptions): Promise<SetResult>;
+export interface FormatOptions {
+    /** Number of spaces for indentation. Use 0 for compact output. Defaults to 2. */
+    indent?: number;
+    /** Sort object keys alphabetically. Defaults to false. */
+    sortKeys?: boolean;
+    /** Output file path. If not provided, writes to the source file. */
+    outputFile?: string;
+}
+export interface FormatResult {
+    success: boolean;
+    inputFile: string;
+    outputFile: string;
+    originalSize: number;
+    formattedSize: number;
+}
+export declare function jsonFormat(filePath: string, options?: FormatOptions): Promise<FormatResult>;

package/dist/tools/navigation.js

@@ -131,7 +131,7 @@ function inferSimpleSchema(value) {
     return { type: typeof value };
 }
 export async function jsonSet(filePath, path, value, options = {}) {
-    const { schema, inferSchema: shouldInferSchema = false, dryRun = false, outputFile, } = options;
+    const { schema, inferSchema: shouldInferSchema = false, dryRun = false, outputFile, strict = true, } = options;
     // Load the JSON file
     const data = await loadJson(filePath);
     // Deep clone to avoid mutating cached data
@@ -156,7 +156,7 @@ export async function jsonSet(filePath, path, value, options = {}) {
     // Validate the new value against schema
     if (schemaToValidate) {
         const { Ajv, addFormats } = await getAjv();
-        const ajv = new Ajv({ allErrors: true });
+        const ajv = new Ajv({ allErrors: true, strict });
         addFormats(ajv);
         const validate = ajv.compile(schemaToValidate);
         const valid = validate(value);
@@ -189,7 +189,7 @@ export async function jsonSet(filePath, path, value, options = {}) {
     }
     // Write to file
     const targetFile = outputFile || filePath;
-    const jsonOutput = JSON.stringify(modifiedData, null, 2);
+    const jsonOutput = JSON.stringify(modifiedData, null, 2) + "\n";
     await writeFile(targetFile, jsonOutput, "utf-8");
     return {
         success: true,
@@ -200,3 +200,45 @@ export async function jsonSet(filePath, path, value, options = {}) {
         dryRun: false,
     };
 }
+// Recursively sort object keys
+function sortObjectKeys(obj) {
+    if (obj === null || typeof obj !== "object") {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(sortObjectKeys);
+    }
+    const sorted = {};
+    const keys = Object.keys(obj).sort();
+    for (const key of keys) {
+        sorted[key] = sortObjectKeys(obj[key]);
+    }
+    return sorted;
+}
+export async function jsonFormat(filePath, options = {}) {
+    const { indent = 2, sortKeys = false, outputFile, } = options;
+    // Load the JSON file
+    const data = await loadJson(filePath);
+    // Get original size
+    const originalContent = JSON.stringify(data);
+    const originalSize = originalContent.length;
+    // Sort keys if requested
+    const dataToFormat = sortKeys ? sortObjectKeys(data) : data;
+    // Format the JSON
+    const formattedContent = indent === 0
+        ? JSON.stringify(dataToFormat)
+        : JSON.stringify(dataToFormat, null, indent);
+    // Add trailing newline
+    const outputContent = formattedContent + "\n";
+    const formattedSize = formattedContent.length;
+    // Write to file
+    const targetFile = outputFile || filePath;
+    await writeFile(targetFile, outputContent, "utf-8");
+    return {
+        success: true,
+        inputFile: filePath,
+        outputFile: targetFile,
+        originalSize,
+        formattedSize,
+    };
+}

package/dist/tools/structure.d.ts

@@ -41,6 +41,8 @@ export interface ValidateOptions {
     schemaDir?: string;
     /** When using schemaDir, specify the $id of the schema to use as entrypoint (instead of schema param). */
     schemaId?: string;
+    /** Disable AJV strict mode for schemas with custom keywords. Defaults to true. */
+    strict?: boolean;
 }
 export declare function jsonValidate(filePath: string, schema: object | string, path?: string, options?: ValidateOptions | number): Promise<ValidateResult>;
 export {};

package/dist/tools/structure.js

@@ -267,7 +267,7 @@ export async function jsonValidate(filePath, schema, path, 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 { errorLimit = 10, resolveLocalRefs = true, resolveNetworkRefs = false, schemas = {}, schemaDir, schemaId, strict = true, } = opts;
     const effectiveResolveNetworkRefs = resolveNetworkRefs && !networkRefsDisabled;
     const data = await loadJson(filePath);
     const targetData = path ? getValueAtPath(data, path) : data;
@@ -301,7 +301,7 @@ export async function jsonValidate(filePath, schema, path, options = {}) {
     const { Ajv, addFormats } = await getAjv();
     // Configure ajv options
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const ajvOptions = { allErrors: true };
+    const ajvOptions = { allErrors: true, strict };
     // Set up network schema loading if enabled
     if (effectiveResolveNetworkRefs) {
         ajvOptions.loadSchema = async (uri) => {

package/dist/utils/path-helpers.js

@@ -81,10 +81,20 @@ function parsePathSegments(path) {
     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;
+    // Match either .key (including $-prefixed keys like $id), [index], or ["key"]
+    // Keys can start with letter, underscore, or $ and contain alphanumeric, underscore, or $
+    const regex = /\.([a-zA-Z_$][a-zA-Z0-9_$]*)|\.?(\[(\d+)\])|\.?\["([^"]+)"\]|\.?\['([^']+)'\]/g;
     let match;
+    let lastIndex = 0;
     while ((match = regex.exec(pathWithoutRoot)) !== null) {
+        // Check for gaps in parsing (unmatched content)
+        if (match.index > lastIndex) {
+            const unmatched = pathWithoutRoot.slice(lastIndex, match.index);
+            if (unmatched && unmatched !== ".") {
+                throw new Error(`Invalid path segment: could not parse "${unmatched}" in path "${path}"`);
+            }
+        }
+        lastIndex = regex.lastIndex;
         if (match[1] !== undefined) {
             // .key format
             segments.push(match[1]);
@@ -102,6 +112,17 @@ function parsePathSegments(path) {
             segments.push(match[5]);
         }
     }
+    // Check for trailing unmatched content
+    if (lastIndex < pathWithoutRoot.length) {
+        const unmatched = pathWithoutRoot.slice(lastIndex);
+        if (unmatched && unmatched !== ".") {
+            throw new Error(`Invalid path segment: could not parse "${unmatched}" in path "${path}"`);
+        }
+    }
+    // Safety check: if path has content but no segments were parsed, something is wrong
+    if (pathWithoutRoot.length > 0 && segments.length === 0) {
+        throw new Error(`Failed to parse path "${path}": no valid segments found`);
+    }
     return segments;
 }
 /**

package/package.json

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