json-explorer-mcp 1.0.0

package/README.md

@@ -0,0 +1,206 @@
+# JSON Explorer MCP Server
+
+An MCP (Model Context Protocol) server for efficiently exploring large JSON files without loading entire contents into context. Designed to help AI assistants navigate complex JSON data structures while minimizing token usage.
+
+## Features
+
+- **Lazy exploration** - Only loads and returns what you need
+- **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
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Usage
+
+### With Claude Desktop
+
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "json-explorer": {
+      "command": "node",
+      "args": ["/path/to/json-explorer-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+### With Claude Code
+
+Add to `.mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "json-explorer": {
+      "command": "node",
+      "args": ["dist/index.js"]
+    }
+  }
+}
+```
+
+## Tools
+
+### json_inspect
+
+Get an overview of a JSON file including size, structure type, and a depth-limited preview.
+
+```
+json_inspect(file: "/path/to/data.json")
+```
+
+Returns:
+```json
+{
+  "file": "/path/to/data.json",
+  "size": "13.1 MB",
+  "type": "object",
+  "preview": {
+    "users": "[... 1000 items]",
+    "config": "{... 5 keys}"
+  },
+  "topLevelInfo": "Object with 2 keys: users, config"
+}
+```
+
+### json_keys
+
+List all keys (for objects) or indices (for arrays) at a given path with type info and previews.
+
+```
+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]" }
+  ],
+  "totalCount": 1000
+}
+```
+
+### json_get
+
+Retrieve the value at a specific path. Large values are automatically truncated.
+
+```
+json_get(file: "/path/to/data.json", path: "$.users[0]")
+```
+
+### json_schema
+
+Infer the JSON schema/structure at a path. For arrays, samples items to determine the item schema.
+
+```
+json_schema(file: "/path/to/data.json", path: "$.users")
+```
+
+Returns:
+```json
+{
+  "path": "$.users",
+  "schema": {
+    "type": "array",
+    "items": {
+      "type": "object",
+      "properties": {
+        "id": { "type": "number" },
+        "name": { "type": "string" },
+        "email": { "type": "string" }
+      }
+    }
+  }
+}
+```
+
+### json_search
+
+Search for keys or values matching a pattern (regex supported).
+
+```
+json_search(file: "/path/to/data.json", query: "email", searchType: "key")
+json_search(file: "/path/to/data.json", query: "@example.com", searchType: "value")
+```
+
+### json_sample
+
+Get sample items from an array. Supports first, last, random, or range-based sampling.
+
+```
+json_sample(file: "/path/to/data.json", path: "$.users", count: 5, mode: "random")
+```
+
+### json_stats
+
+Get aggregate statistics for array fields. If no path provided, discovers and analyzes all arrays of objects in the file.
+
+```
+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",
+      "arrayLength": 1000,
+      "fields": [
+        { "field": "id", "type": "number", "count": 1000, "nullCount": 0, "min": 1, "max": 1000, "avg": 500.5 },
+        { "field": "status", "type": "string", "count": 1000, "nullCount": 0, "uniqueCount": 3, "distribution": { "active": 800, "inactive": 150, "pending": 50 } }
+      ]
+    }
+  ]
+}
+```
+
+With a specific path:
+```
+json_stats(file: "/path/to/data.json", path: "$.users", fields: ["status", "created_at"])
+```
+
+## JSONPath Syntax
+
+All path parameters support JSONPath syntax:
+
+- `$` - Root object
+- `$.foo` - Property access
+- `$.foo.bar` - Nested property
+- `$.users[0]` - Array index
+- `$.users[*]` - All array items (in search results)
+- `$["special-key"]` - Bracket notation for special characters
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run in development mode
+npm run dev
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+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 { jsonSearch, jsonSample, jsonStats } from "./tools/query.js";
+const server = new McpServer({
+    name: "json-explorer",
+    version: "1.0.0",
+});
+// 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.", {
+    file: z.string().describe("Absolute path to the JSON file"),
+}, { readOnlyHint: true }, async ({ file }) => {
+    try {
+        const result = await jsonInspect(file);
+        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_keys - List keys at a path
+server.tool("json_keys", "List all keys (for objects) or indices (for arrays) at a given path. Returns type and preview for each key.", {
+    file: z.string().describe("Absolute path to the JSON file"),
+    path: z.string().optional().describe("JSONPath to the target location (e.g., '$.users', 'data.items'). Defaults to root."),
+    limit: z.number().optional().describe("Maximum number of keys to return. Defaults to 50."),
+}, { readOnlyHint: true }, async ({ file, path, limit }) => {
+    try {
+        const result = await jsonKeys(file, path, limit);
+        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_get - Get value at a path
+server.tool("json_get", "Retrieve the value at a specific path. Large values are automatically truncated with size info.", {
+    file: z.string().describe("Absolute path to the JSON file"),
+    path: z.string().describe("JSONPath to the value (e.g., '$.users[0]', 'data.config.settings')"),
+    maxSize: z.number().optional().describe("Maximum response size in characters before truncation. Defaults to 5000."),
+}, { readOnlyHint: true }, async ({ file, path, maxSize }) => {
+    try {
+        const result = await jsonGet(file, path, maxSize);
+        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"),
+    path: z.string().optional().describe("JSONPath to analyze. Defaults to root."),
+}, { readOnlyHint: true }, async ({ file, path }) => {
+    try {
+        const result = await jsonSchema(file, path);
+        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_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.", {
+    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 }) => {
+    try {
+        const result = await jsonValidate(file, schema, path);
+        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_search - Search for keys or values
+server.tool("json_search", "Search for keys or values matching a pattern (regex). Returns matching paths with previews.", {
+    file: z.string().describe("Absolute path to the JSON file"),
+    query: z.string().describe("Search pattern (regex supported)"),
+    searchType: z.enum(["key", "value"]).optional().describe("Search in keys or values. Defaults to 'key'."),
+    maxResults: z.number().optional().describe("Maximum results to return. Defaults to 50."),
+}, { readOnlyHint: true }, async ({ file, query, searchType, maxResults }) => {
+    try {
+        const result = await jsonSearch(file, query, searchType, maxResults);
+        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_sample - Sample array items
+server.tool("json_sample", "Get sample items from an array. Supports first, last, random, or range-based sampling.", {
+    file: z.string().describe("Absolute path to the JSON file"),
+    path: z.string().describe("JSONPath to the array"),
+    count: z.number().optional().describe("Number of items to sample. Defaults to 5."),
+    mode: z.enum(["first", "last", "random", "range"]).optional().describe("Sampling mode. Defaults to 'first'."),
+    rangeStart: z.number().optional().describe("Starting index for 'range' mode."),
+}, { readOnlyHint: true }, async ({ file, path, count, mode, rangeStart }) => {
+    try {
+        const result = await jsonSample(file, path, count, mode, rangeStart);
+        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_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.", {
+    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."),
+}, { readOnlyHint: true }, async ({ file, path, fields }) => {
+    try {
+        const result = await jsonStats(file, path, fields);
+        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,
+        };
+    }
+});
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});

package/dist/tools/navigation.d.ts

@@ -0,0 +1,21 @@
+export interface KeyInfo {
+    key: string;
+    type: string;
+    preview: string;
+    path: string;
+}
+export interface KeysResult {
+    path: string;
+    type: string;
+    keys: KeyInfo[];
+    totalCount: number;
+}
+export declare function jsonKeys(filePath: string, path?: string, limit?: number): Promise<KeysResult>;
+export interface GetResult {
+    path: string;
+    type: string;
+    value: unknown;
+    truncated: boolean;
+    originalSize?: number;
+}
+export declare function jsonGet(filePath: string, path: string, maxSize?: number): Promise<GetResult>;

package/dist/tools/navigation.js

@@ -0,0 +1,97 @@
+import { loadJson, getValueType, truncateValue, getValuePreview } from "../utils/json-parser.js";
+import { getValueAtPath, getKeysAtPath, buildPathTo } from "../utils/path-helpers.js";
+export async function jsonKeys(filePath, path, limit = 50) {
+    const data = await loadJson(filePath);
+    const targetPath = path || "$";
+    const value = getValueAtPath(data, targetPath);
+    if (value === undefined) {
+        throw new Error(`Path not found: ${targetPath}`);
+    }
+    const type = getValueType(value);
+    if (type !== "object" && type !== "array") {
+        throw new Error(`Cannot list keys of ${type}. Path "${targetPath}" is not an object or array.`);
+    }
+    const allKeys = getKeysAtPath(data, targetPath);
+    const limitedKeys = allKeys.slice(0, limit);
+    const keys = limitedKeys.map((key) => {
+        const childPath = buildPathTo(targetPath, key);
+        const childValue = getValueAtPath(data, childPath);
+        return {
+            key,
+            type: getValueType(childValue),
+            preview: getValuePreview(childValue, 2),
+            path: childPath,
+        };
+    });
+    return {
+        path: targetPath,
+        type,
+        keys,
+        totalCount: allKeys.length,
+    };
+}
+export async function jsonGet(filePath, path, maxSize = 5000) {
+    const data = await loadJson(filePath);
+    const value = getValueAtPath(data, path);
+    if (value === undefined) {
+        throw new Error(`Path not found: ${path}`);
+    }
+    const type = getValueType(value);
+    const stringified = JSON.stringify(value);
+    const originalSize = stringified.length;
+    let resultValue;
+    let truncated = false;
+    if (originalSize > maxSize) {
+        truncated = true;
+        // For objects/arrays, show structure with truncated content
+        if (Array.isArray(value)) {
+            const itemsToShow = Math.min(10, value.length);
+            resultValue = {
+                _truncated: true,
+                _totalItems: value.length,
+                _showing: itemsToShow,
+                items: value.slice(0, itemsToShow).map((item) => {
+                    const itemStr = JSON.stringify(item);
+                    if (itemStr.length > 500) {
+                        return JSON.parse(truncateValue(item, 500).replace(/\.\.\. \(\d+ chars total\)$/, ""));
+                    }
+                    return item;
+                }),
+            };
+        }
+        else if (type === "object" && value !== null) {
+            const keys = Object.keys(value);
+            const keysToShow = keys.slice(0, 20);
+            const truncatedObj = {
+                _truncated: true,
+                _totalKeys: keys.length,
+                _showing: keysToShow.length,
+            };
+            for (const key of keysToShow) {
+                const val = value[key];
+                const valStr = JSON.stringify(val);
+                if (valStr.length > 200) {
+                    truncatedObj[key] = getValuePreview(val, 2);
+                }
+                else {
+                    truncatedObj[key] = val;
+                }
+            }
+            resultValue = truncatedObj;
+        }
+        else {
+            // Large string or other primitive
+            resultValue = truncateValue(value, maxSize);
+        }
+    }
+    else {
+        resultValue = value;
+    }
+    return {
+        path,
+        type,
+        value: resultValue,
+        truncated,
+        ...(truncated && { originalSize }),
+    };
+}

package/dist/tools/query.d.ts

@@ -0,0 +1,54 @@
+export interface SearchMatch {
+    path: string;
+    key?: string;
+    value?: unknown;
+    preview: string;
+}
+export interface SearchResult {
+    query: string;
+    searchType: "key" | "value";
+    matches: SearchMatch[];
+    totalMatches: number;
+    truncated: boolean;
+}
+export declare function jsonSearch(filePath: string, query: string, searchType?: "key" | "value", maxResults?: number): Promise<SearchResult>;
+export interface SampleResult {
+    path: string;
+    arrayLength: number;
+    sampleType: "first" | "last" | "random" | "range";
+    items: Array<{
+        index: number;
+        value: unknown;
+        type: string;
+    }>;
+    hasMore: boolean;
+}
+export declare function jsonSample(filePath: string, path: string, count?: number, mode?: "first" | "last" | "random" | "range", rangeStart?: number): Promise<SampleResult>;
+export interface FieldStats {
+    field: string;
+    type: string;
+    count: number;
+    nullCount: number;
+    uniqueValues?: unknown[];
+    uniqueCount?: number;
+    min?: number;
+    max?: number;
+    avg?: number;
+    distribution?: Record<string, number>;
+}
+export interface ArrayInfo {
+    path: string;
+    length: number;
+    itemType: string;
+    fields?: string[];
+    fieldCount?: number;
+}
+export interface StatsResult {
+    path: string;
+    arrayLength: number;
+    fields: FieldStats[];
+}
+export interface MultiStatsResult {
+    stats: StatsResult[];
+}
+export declare function jsonStats(filePath: string, path?: string, fields?: string[]): Promise<StatsResult | MultiStatsResult>;

package/dist/tools/query.js

@@ -0,0 +1,249 @@
+import { loadJson, getValuePreview, getValueType } from "../utils/json-parser.js";
+import { findPaths, getValueAtPath } from "../utils/path-helpers.js";
+export async function jsonSearch(filePath, query, searchType = "key", maxResults = 50) {
+    const data = await loadJson(filePath);
+    const regex = new RegExp(query, "i");
+    let matchingPaths;
+    if (searchType === "key") {
+        // Search for keys matching the pattern
+        matchingPaths = findPaths(data, (_, path) => {
+            // Extract the last key from the path
+            const lastDot = path.lastIndexOf(".");
+            const lastBracket = path.lastIndexOf("[");
+            const lastSep = Math.max(lastDot, lastBracket);
+            if (lastSep === -1)
+                return false;
+            let key;
+            if (lastBracket > lastDot) {
+                // It's an array index or bracket notation
+                const match = path.slice(lastBracket).match(/\["?([^\]"]+)"?\]/);
+                key = match ? match[1] : "";
+            }
+            else {
+                key = path.slice(lastDot + 1);
+            }
+            return regex.test(key);
+        }, "$", maxResults + 1);
+    }
+    else {
+        // Search for values matching the pattern
+        matchingPaths = findPaths(data, (value) => {
+            if (typeof value === "string") {
+                return regex.test(value);
+            }
+            if (typeof value === "number" || typeof value === "boolean") {
+                return regex.test(String(value));
+            }
+            return false;
+        }, "$", maxResults + 1);
+    }
+    const truncated = matchingPaths.length > maxResults;
+    const limitedPaths = matchingPaths.slice(0, maxResults);
+    const matches = limitedPaths.map((path) => {
+        const value = getValueAtPath(data, path);
+        const lastDot = path.lastIndexOf(".");
+        const lastBracket = path.lastIndexOf("[");
+        const lastSep = Math.max(lastDot, lastBracket);
+        let key;
+        if (lastSep !== -1) {
+            if (lastBracket > lastDot) {
+                const match = path.slice(lastBracket).match(/\["?([^\]"]+)"?\]/);
+                key = match ? match[1] : undefined;
+            }
+            else {
+                key = path.slice(lastDot + 1);
+            }
+        }
+        return {
+            path,
+            key,
+            value: searchType === "value" ? value : undefined,
+            preview: getValuePreview(value, 2),
+        };
+    });
+    return {
+        query,
+        searchType,
+        matches,
+        totalMatches: matchingPaths.length,
+        truncated,
+    };
+}
+export async function jsonSample(filePath, path, count = 5, mode = "first", rangeStart) {
+    const data = await loadJson(filePath);
+    const value = getValueAtPath(data, path);
+    if (!Array.isArray(value)) {
+        throw new Error(`Path "${path}" is not an array. Got: ${getValueType(value)}`);
+    }
+    const arrayLength = value.length;
+    let indices;
+    switch (mode) {
+        case "first":
+            indices = Array.from({ length: Math.min(count, arrayLength) }, (_, i) => i);
+            break;
+        case "last":
+            const start = Math.max(0, arrayLength - count);
+            indices = Array.from({ length: Math.min(count, arrayLength) }, (_, i) => start + i);
+            break;
+        case "random":
+            const available = Array.from({ length: arrayLength }, (_, i) => i);
+            indices = [];
+            for (let i = 0; i < Math.min(count, arrayLength); i++) {
+                const randomIndex = Math.floor(Math.random() * available.length);
+                indices.push(available.splice(randomIndex, 1)[0]);
+            }
+            indices.sort((a, b) => a - b);
+            break;
+        case "range":
+            const rangeStartIdx = rangeStart ?? 0;
+            indices = Array.from({ length: Math.min(count, arrayLength - rangeStartIdx) }, (_, i) => rangeStartIdx + i);
+            break;
+    }
+    const items = indices.map((index) => {
+        const itemValue = value[index];
+        const itemStr = JSON.stringify(itemValue);
+        const isTruncated = itemStr.length > 1000;
+        return {
+            index,
+            value: isTruncated ? getValuePreview(itemValue, 3) : itemValue,
+            type: getValueType(itemValue),
+            ...(isTruncated && { truncated: true, originalSize: itemStr.length }),
+        };
+    });
+    return {
+        path,
+        arrayLength,
+        sampleType: mode,
+        items,
+        hasMore: arrayLength > count,
+    };
+}
+function findArraysOfObjects(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)
+        if (typeof firstItem === "object" && firstItem !== null && !Array.isArray(firstItem)) {
+            const fields = Object.keys(firstItem);
+            results.push({
+                path: currentPath,
+                length: data.length,
+                itemType: "object",
+                fields: fields.slice(0, 10),
+                fieldCount: fields.length,
+            });
+            // Check for nested arrays within the object items
+            for (const key of fields) {
+                const childValue = firstItem[key];
+                if (Array.isArray(childValue) && childValue.length > 0) {
+                    const nestedFirst = childValue[0];
+                    if (typeof nestedFirst === "object" && nestedFirst !== null && !Array.isArray(nestedFirst)) {
+                        const nestedFields = Object.keys(nestedFirst);
+                        results.push({
+                            path: `${currentPath}[*].${key}`,
+                            length: childValue.length,
+                            itemType: "object",
+                            fields: nestedFields.slice(0, 10),
+                            fieldCount: nestedFields.length,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    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));
+        }
+    }
+    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 (!path) {
+        const arrays = findArraysOfObjects(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);
+                }
+            }
+            catch {
+                // Skip arrays we can't access (e.g., wildcard paths)
+            }
+        }
+        return { stats: allStats };
+    }
+    const value = getValueAtPath(data, path);
+    if (!Array.isArray(value)) {
+        throw new Error(`Path "${path}" is not an array. Got: ${getValueType(value)}`);
+    }
+    return computeArrayStats(value, path, fields);
+}
+function computeArrayStats(value, path, fields) {
+    if (value.length === 0) {
+        return { path, arrayLength: 0, fields: [] };
+    }
+    // Determine fields to analyze
+    const firstItem = value[0];
+    const fieldsToAnalyze = fields ?? (typeof firstItem === "object" && firstItem !== null
+        ? Object.keys(firstItem)
+        : []);
+    const fieldStats = fieldsToAnalyze.map((field) => {
+        const values = value.map((item) => {
+            if (typeof item === "object" && item !== null) {
+                return item[field];
+            }
+            return undefined;
+        });
+        const nonNullValues = values.filter((v) => v !== null && v !== undefined);
+        const nullCount = values.length - nonNullValues.length;
+        // Determine predominant type
+        const types = new Set(nonNullValues.map((v) => getValueType(v)));
+        const type = types.size === 1 ? [...types][0] : [...types].join(" | ");
+        const stats = {
+            field,
+            type,
+            count: nonNullValues.length,
+            nullCount,
+        };
+        // Numeric stats
+        const numericValues = nonNullValues.filter((v) => typeof v === "number");
+        if (numericValues.length > 0) {
+            stats.min = Math.min(...numericValues);
+            stats.max = Math.max(...numericValues);
+            stats.avg = numericValues.reduce((a, b) => a + b, 0) / numericValues.length;
+        }
+        // String/categorical stats
+        const stringValues = nonNullValues.filter((v) => typeof v === "string" || typeof v === "boolean");
+        if (stringValues.length > 0) {
+            const distribution = {};
+            for (const v of stringValues) {
+                const key = String(v);
+                distribution[key] = (distribution[key] || 0) + 1;
+            }
+            const uniqueKeys = Object.keys(distribution);
+            stats.uniqueCount = uniqueKeys.length;
+            // Only show distribution if there are <= 20 unique values
+            if (uniqueKeys.length <= 20) {
+                stats.distribution = distribution;
+                stats.uniqueValues = uniqueKeys;
+            }
+        }
+        return stats;
+    });
+    return {
+        path,
+        arrayLength: value.length,
+        fields: fieldStats,
+    };
+}

package/dist/tools/structure.d.ts

@@ -0,0 +1,33 @@
+export interface InspectResult {
+    file: string;
+    size: string;
+    type: string;
+    preview: unknown;
+    topLevelInfo: string;
+}
+export declare function jsonInspect(filePath: string): Promise<InspectResult>;
+interface SchemaNode {
+    type: string;
+    properties?: Record<string, SchemaNode>;
+    items?: SchemaNode;
+    nullable?: boolean;
+    enum?: unknown[];
+}
+export interface SchemaResult {
+    path: string;
+    schema: SchemaNode;
+}
+export declare function jsonSchema(filePath: string, path?: string): Promise<SchemaResult>;
+export interface ValidationError {
+    path: string;
+    message: string;
+    keyword: string;
+    params: Record<string, unknown>;
+}
+export interface ValidateResult {
+    valid: boolean;
+    errors: ValidationError[];
+    errorCount: number;
+}
+export declare function jsonValidate(filePath: string, schema: object | string, path?: string): Promise<ValidateResult>;
+export {};

package/dist/tools/structure.js

@@ -0,0 +1,148 @@
+import { loadJson, getFileInfo, formatBytes, getValueType } from "../utils/json-parser.js";
+import { getDepthPreview, getValueAtPath } from "../utils/path-helpers.js";
+// 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 };
+}
+export async function jsonInspect(filePath) {
+    const info = await getFileInfo(filePath);
+    if (!info.exists) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    const data = await loadJson(filePath);
+    const type = getValueType(data);
+    let topLevelInfo;
+    if (Array.isArray(data)) {
+        topLevelInfo = `Array with ${data.length} items`;
+    }
+    else if (type === "object" && data !== null) {
+        const keys = Object.keys(data);
+        topLevelInfo = `Object with ${keys.length} keys: ${keys.slice(0, 10).join(", ")}${keys.length > 10 ? ` ... +${keys.length - 10} more` : ""}`;
+    }
+    else {
+        topLevelInfo = `Primitive value: ${type}`;
+    }
+    return {
+        file: filePath,
+        size: formatBytes(info.size),
+        type,
+        preview: getDepthPreview(data, 2),
+        topLevelInfo,
+    };
+}
+function inferSchema(value, sampleSize = 5) {
+    if (value === null) {
+        return { type: "null" };
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            return { type: "array", items: { type: "unknown" } };
+        }
+        // Sample items to infer item schema
+        const sampled = value.slice(0, sampleSize);
+        const itemSchemas = sampled.map((item) => inferSchema(item, sampleSize));
+        // Merge item schemas
+        const mergedItemSchema = mergeSchemas(itemSchemas);
+        return { type: "array", items: mergedItemSchema };
+    }
+    if (typeof value === "object") {
+        const properties = {};
+        for (const [key, val] of Object.entries(value)) {
+            properties[key] = inferSchema(val, sampleSize);
+        }
+        return { type: "object", properties };
+    }
+    return { type: typeof value };
+}
+function mergeSchemas(schemas) {
+    if (schemas.length === 0) {
+        return { type: "unknown" };
+    }
+    if (schemas.length === 1) {
+        return schemas[0];
+    }
+    // Check if all schemas are the same type
+    const types = new Set(schemas.map((s) => s.type));
+    if (types.size === 1) {
+        const type = schemas[0].type;
+        if (type === "object") {
+            // Merge object properties
+            const allKeys = new Set();
+            for (const schema of schemas) {
+                if (schema.properties) {
+                    for (const key of Object.keys(schema.properties)) {
+                        allKeys.add(key);
+                    }
+                }
+            }
+            const properties = {};
+            for (const key of allKeys) {
+                const keySchemas = schemas
+                    .filter((s) => s.properties && s.properties[key])
+                    .map((s) => s.properties[key]);
+                properties[key] = keySchemas.length > 0 ? mergeSchemas(keySchemas) : { type: "unknown" };
+            }
+            return { type: "object", properties };
+        }
+        if (type === "array") {
+            const itemSchemas = schemas
+                .filter((s) => s.items)
+                .map((s) => s.items);
+            return {
+                type: "array",
+                items: itemSchemas.length > 0 ? mergeSchemas(itemSchemas) : { type: "unknown" },
+            };
+        }
+        return schemas[0];
+    }
+    // Mixed types - return union description
+    return { type: Array.from(types).join(" | ") };
+}
+export async function jsonSchema(filePath, path) {
+    const data = await loadJson(filePath);
+    const targetData = path ? getValueAtPath(data, path) : data;
+    if (targetData === undefined) {
+        throw new Error(`Path not found: ${path}`);
+    }
+    return {
+        path: path || "$",
+        schema: inferSchema(targetData),
+    };
+}
+export async function jsonValidate(filePath, schema, path) {
+    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
+    let schemaObj;
+    if (typeof schema === "string") {
+        schemaObj = (await loadJson(schema));
+    }
+    else {
+        schemaObj = schema;
+    }
+    const { Ajv, addFormats } = await getAjv();
+    const ajv = new Ajv({ allErrors: true });
+    addFormats(ajv);
+    const validate = ajv.compile(schemaObj);
+    const valid = validate(targetData);
+    const errors = (validate.errors || []).map((err) => ({
+        path: err.instancePath || "$",
+        message: err.message || "Unknown error",
+        keyword: err.keyword,
+        params: err.params,
+    }));
+    return {
+        valid: valid === true,
+        errors,
+        errorCount: errors.length,
+    };
+}

package/dist/utils/json-parser.d.ts

@@ -0,0 +1,10 @@
+export declare function getFileInfo(filePath: string): Promise<{
+    size: number;
+    mtime: number;
+    exists: boolean;
+}>;
+export declare function loadJson(filePath: string): Promise<unknown>;
+export declare function getValueType(value: unknown): string;
+export declare function truncateValue(value: unknown, maxLength?: number): string;
+export declare function getValuePreview(value: unknown, maxItems?: number): string;
+export declare function formatBytes(bytes: number): string;

package/dist/utils/json-parser.js

@@ -0,0 +1,86 @@
+import { readFile, stat } from "fs/promises";
+const cache = new Map();
+const MAX_CACHE_SIZE = 100 * 1024 * 1024; // 100MB total cache limit
+let currentCacheSize = 0;
+export async function getFileInfo(filePath) {
+    try {
+        const stats = await stat(filePath);
+        return {
+            size: stats.size,
+            mtime: stats.mtimeMs,
+            exists: true,
+        };
+    }
+    catch {
+        return { size: 0, mtime: 0, exists: false };
+    }
+}
+export async function loadJson(filePath) {
+    const info = await getFileInfo(filePath);
+    if (!info.exists) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    // Check cache
+    const cached = cache.get(filePath);
+    if (cached && cached.mtime === info.mtime) {
+        return cached.data;
+    }
+    // Read and parse file
+    const content = await readFile(filePath, "utf-8");
+    const data = JSON.parse(content);
+    // Update cache (with size management)
+    if (info.size < MAX_CACHE_SIZE / 2) {
+        // Only cache files smaller than half the max cache size
+        while (currentCacheSize + info.size > MAX_CACHE_SIZE && cache.size > 0) {
+            // Evict oldest entry
+            const firstKey = cache.keys().next().value;
+            if (firstKey) {
+                const entry = cache.get(firstKey);
+                if (entry) {
+                    currentCacheSize -= entry.size;
+                }
+                cache.delete(firstKey);
+            }
+        }
+        cache.set(filePath, { data, mtime: info.mtime, size: info.size });
+        currentCacheSize += info.size;
+    }
+    return data;
+}
+export function getValueType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+export function truncateValue(value, maxLength = 500) {
+    const str = JSON.stringify(value);
+    if (str.length <= maxLength)
+        return str;
+    return str.slice(0, maxLength) + `... (${str.length} chars total)`;
+}
+export function getValuePreview(value, maxItems = 3) {
+    if (value === null)
+        return "null";
+    if (typeof value !== "object")
+        return truncateValue(value, 100);
+    if (Array.isArray(value)) {
+        const preview = value.slice(0, maxItems).map((v) => truncateValue(v, 50));
+        const more = value.length > maxItems ? `, ... +${value.length - maxItems} more` : "";
+        return `[${preview.join(", ")}${more}]`;
+    }
+    const keys = Object.keys(value);
+    const preview = keys.slice(0, maxItems).map((k) => `"${k}": ${truncateValue(value[k], 30)}`);
+    const more = keys.length > maxItems ? `, ... +${keys.length - maxItems} more` : "";
+    return `{${preview.join(", ")}${more}}`;
+}
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}

package/dist/utils/path-helpers.d.ts

@@ -0,0 +1,6 @@
+export declare function getValueAtPath(data: unknown, path: string): unknown;
+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[];
+export declare function getDepthPreview(data: unknown, maxDepth?: number, currentDepth?: number): unknown;

package/dist/utils/path-helpers.js

@@ -0,0 +1,98 @@
+import { JSONPath } from "jsonpath-plus";
+export function getValueAtPath(data, path) {
+    if (!path || path === "$" || path === ".") {
+        return data;
+    }
+    // Normalize path to JSONPath format
+    const normalizedPath = normalizeToJsonPath(path);
+    const results = JSONPath({ path: normalizedPath, json: data, wrap: false });
+    return results;
+}
+export function normalizeToJsonPath(path) {
+    // Already a JSONPath expression
+    if (path.startsWith("$")) {
+        return path;
+    }
+    // Dot notation like "foo.bar.baz" or "foo[0].bar"
+    if (path.startsWith(".")) {
+        return "$" + path;
+    }
+    // Simple path without leading $ or .
+    return "$." + path;
+}
+export function getKeysAtPath(data, path) {
+    const value = getValueAtPath(data, path);
+    if (value === null || typeof value !== "object") {
+        return [];
+    }
+    if (Array.isArray(value)) {
+        return value.map((_, i) => `[${i}]`);
+    }
+    return Object.keys(value);
+}
+export function buildPathTo(basePath, key) {
+    const normalizedBase = basePath === "$" || basePath === "." || !basePath ? "$" : normalizeToJsonPath(basePath);
+    if (key.startsWith("[")) {
+        return normalizedBase + key;
+    }
+    // Handle keys that need bracket notation (spaces, dots, special chars)
+    if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(key)) {
+        return normalizedBase + "." + key;
+    }
+    return normalizedBase + `["${key}"]`;
+}
+export function findPaths(data, predicate, currentPath = "$", maxResults = 100) {
+    const results = [];
+    function traverse(value, path) {
+        if (results.length >= maxResults)
+            return;
+        if (predicate(value, path)) {
+            results.push(path);
+        }
+        if (value !== null && typeof value === "object") {
+            if (Array.isArray(value)) {
+                for (let i = 0; i < value.length && results.length < maxResults; i++) {
+                    traverse(value[i], `${path}[${i}]`);
+                }
+            }
+            else {
+                for (const key of Object.keys(value)) {
+                    if (results.length >= maxResults)
+                        break;
+                    const childPath = /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(key)
+                        ? `${path}.${key}`
+                        : `${path}["${key}"]`;
+                    traverse(value[key], childPath);
+                }
+            }
+        }
+    }
+    traverse(data, currentPath);
+    return results;
+}
+export function getDepthPreview(data, maxDepth = 2, currentDepth = 0) {
+    if (currentDepth >= maxDepth) {
+        if (data === null)
+            return null;
+        if (typeof data !== "object")
+            return data;
+        if (Array.isArray(data))
+            return `[... ${data.length} items]`;
+        return `{... ${Object.keys(data).length} keys}`;
+    }
+    if (data === null || typeof data !== "object") {
+        return data;
+    }
+    if (Array.isArray(data)) {
+        return data.slice(0, 5).map((item) => getDepthPreview(item, maxDepth, currentDepth + 1));
+    }
+    const result = {};
+    const keys = Object.keys(data);
+    for (const key of keys.slice(0, 10)) {
+        result[key] = getDepthPreview(data[key], maxDepth, currentDepth + 1);
+    }
+    if (keys.length > 10) {
+        result["..."] = `+${keys.length - 10} more keys`;
+    }
+    return result;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "json-explorer-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for efficiently exploring large JSON files",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "json-explorer-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "mcp",
+    "json",
+    "explorer",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "jsonpath-plus": "^10.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.17"
+  }
+}