JSON MCP Boilerplate

Instructions

Implementation Reference

• src/index.ts:195-294 (handler)

  The handler function for the 'json_read' tool. It reads the JSON file, navigates to a specific path if provided, applies analysis options like structure preview or sampling, includes optional stats and types, truncates large outputs, and returns formatted markdown content.
  async ({ file_path, path, max_depth, max_keys, sample_arrays, keys_only, include_types, include_stats, }) => { try { const data = readJSONFile(file_path); const target = path ? getValueByPath(data, path) : data; let result: any; if (keys_only) { result = analyzeJSONStructure(target, max_depth || 3, 0, max_keys); } else if (sample_arrays !== undefined) { result = JSON.parse( JSON.stringify(target, (key, value) => { if (Array.isArray(value) && sample_arrays) { return value.slice(0, sample_arrays); } return value; }) ); } else { result = target; } // Build stats markdown section if requested let statsMarkdown = ""; if (include_stats) { const fileContent = readFileSync(resolve(file_path), "utf8"); const fileSize = (fileContent.length / 1024).toFixed(2); const nodeCount = JSON.stringify(data).length; statsMarkdown = "## File Statistics\n\n"; statsMarkdown += `- **File Size**: ${fileSize} KB\n`; statsMarkdown += `- **Total Nodes**: ${nodeCount.toLocaleString()}\n`; statsMarkdown += `- **Root Type**: ${ Array.isArray(data) ? "array" : typeof data }\n`; if (Array.isArray(target)) { statsMarkdown += `- **Array Length**: ${target.length}\n`; const elementTypes = [...new Set(target.map((item) => typeof item))]; statsMarkdown += `- **Element Types**: ${elementTypes.join(", ")}\n`; } else if (typeof target === "object" && target !== null) { const keys = Object.keys(target); statsMarkdown += `- **Key Count**: ${keys.length}\n`; if (keys.length > 0) { const topKeys = keys.slice(0, 10); statsMarkdown += `- **Top Keys**: ${topKeys.join(", ")}`; if (keys.length > 10) { statsMarkdown += ` (and ${keys.length - 10} more)`; } statsMarkdown += "\n"; } } statsMarkdown += "\n## Data\n\n"; } // Build type info markdown if requested let typeInfo = ""; if (include_types && !include_stats) { typeInfo = `**Type**: ${typeof target}`; if (Array.isArray(target)) { typeInfo = `**Type**: array (length: ${target.length})`; } typeInfo += "\n\n"; } const truncatedOutput = truncateForOutput(result); let outputText = JSON.stringify(truncatedOutput, null, 2); // Replace quoted truncation messages with unquoted text for markdown-like output outputText = outputText.replace( /"\.\.\.(\d+) more items"/g, "...$1 more items" ); outputText = outputText.replace( /"\.\.\.(\d+) more properties": "\.\.\.?"/g, "...$1 more properties" ); return { content: [ { type: "text", text: statsMarkdown + typeInfo + outputText }, ], }; } catch (error: any) { return { content: [{ type: "text", text: `Error: ${error.message}` }], }; } }
• src/index.ts:175-194 (schema)

  The input schema definition for the 'json_read' tool using Zod, defining parameters like file_path, path, max_depth, etc., with descriptions.
  file_path: z.string().describe("Path to the JSON file"), path: z.string().optional().describe("Dot notation to specific location"), max_depth: z.number().optional().describe("Limit traversal depth"), max_keys: z .number() .optional() .describe( "Maximum number of keys to show per object (default: show all keys)" ), sample_arrays: z .number() .optional() .describe("Show only first N array items"), keys_only: z.boolean().optional().describe("Return only the key structure"), include_types: z.boolean().optional().describe("Add type information"), include_stats: z .boolean() .optional() .describe("Add file size and structure statistics"), },
• src/index.ts:171-295 (registration)

  The registration of the 'json_read' tool using server.tool(), including name, description, schema, and handler.
  server.tool( "json_read", "Read and analyze JSON. Always use this tool to explore JSON structure, understand data schema, or get high-level overviews of large JSON. Use this for initial data exploration or when you need to understand the shape and types of data before extracting specific values.", { file_path: z.string().describe("Path to the JSON file"), path: z.string().optional().describe("Dot notation to specific location"), max_depth: z.number().optional().describe("Limit traversal depth"), max_keys: z .number() .optional() .describe( "Maximum number of keys to show per object (default: show all keys)" ), sample_arrays: z .number() .optional() .describe("Show only first N array items"), keys_only: z.boolean().optional().describe("Return only the key structure"), include_types: z.boolean().optional().describe("Add type information"), include_stats: z .boolean() .optional() .describe("Add file size and structure statistics"), }, async ({ file_path, path, max_depth, max_keys, sample_arrays, keys_only, include_types, include_stats, }) => { try { const data = readJSONFile(file_path); const target = path ? getValueByPath(data, path) : data; let result: any; if (keys_only) { result = analyzeJSONStructure(target, max_depth || 3, 0, max_keys); } else if (sample_arrays !== undefined) { result = JSON.parse( JSON.stringify(target, (key, value) => { if (Array.isArray(value) && sample_arrays) { return value.slice(0, sample_arrays); } return value; }) ); } else { result = target; } // Build stats markdown section if requested let statsMarkdown = ""; if (include_stats) { const fileContent = readFileSync(resolve(file_path), "utf8"); const fileSize = (fileContent.length / 1024).toFixed(2); const nodeCount = JSON.stringify(data).length; statsMarkdown = "## File Statistics\n\n"; statsMarkdown += `- **File Size**: ${fileSize} KB\n`; statsMarkdown += `- **Total Nodes**: ${nodeCount.toLocaleString()}\n`; statsMarkdown += `- **Root Type**: ${ Array.isArray(data) ? "array" : typeof data }\n`; if (Array.isArray(target)) { statsMarkdown += `- **Array Length**: ${target.length}\n`; const elementTypes = [...new Set(target.map((item) => typeof item))]; statsMarkdown += `- **Element Types**: ${elementTypes.join(", ")}\n`; } else if (typeof target === "object" && target !== null) { const keys = Object.keys(target); statsMarkdown += `- **Key Count**: ${keys.length}\n`; if (keys.length > 0) { const topKeys = keys.slice(0, 10); statsMarkdown += `- **Top Keys**: ${topKeys.join(", ")}`; if (keys.length > 10) { statsMarkdown += ` (and ${keys.length - 10} more)`; } statsMarkdown += "\n"; } } statsMarkdown += "\n## Data\n\n"; } // Build type info markdown if requested let typeInfo = ""; if (include_types && !include_stats) { typeInfo = `**Type**: ${typeof target}`; if (Array.isArray(target)) { typeInfo = `**Type**: array (length: ${target.length})`; } typeInfo += "\n\n"; } const truncatedOutput = truncateForOutput(result); let outputText = JSON.stringify(truncatedOutput, null, 2); // Replace quoted truncation messages with unquoted text for markdown-like output outputText = outputText.replace( /"\.\.\.(\d+) more items"/g, "...$1 more items" ); outputText = outputText.replace( /"\.\.\.(\d+) more properties": "\.\.\.?"/g, "...$1 more properties" ); return { content: [ { type: "text", text: statsMarkdown + typeInfo + outputText }, ], }; } catch (error: any) { return { content: [{ type: "text", text: `Error: ${error.message}` }], }; } } );
• src/index.ts:24-32 (helper)

  Core helper function to read and parse a JSON file safely, used by the json_read handler.
  function readJSONFile(filePath: string): any { const absolutePath = resolve(filePath); if (!existsSync(absolutePath)) { throw new Error(`File not found: ${absolutePath}`); } const content = readFileSync(absolutePath, "utf8"); return safeParseJSON(content, absolutePath); }
• src/index.ts:44-86 (helper)

  Helper function to analyze and preview JSON structure up to max depth and keys, used when keys_only is true.
  function analyzeJSONStructure( obj: any, maxDepth: number = 3, currentDepth: number = 0, maxKeys?: number ): any { if (currentDepth > maxDepth) return "[...depth limit reached...]"; if (obj === null) return null; if (typeof obj !== "object") return typeof obj; if (Array.isArray(obj)) { if (obj.length === 0) return []; const sample = obj .slice(0, 3) .map((item) => analyzeJSONStructure(item, maxDepth, currentDepth + 1, maxKeys) ); return obj.length > 3 ? [...sample, `[...${obj.length - 3} more items]`] : sample; } const result: any = {}; const keys = Object.keys(obj); const keyLimit = maxKeys ?? keys.length; // Show all keys by default const sampleKeys = keys.slice(0, keyLimit); for (const key of sampleKeys) { result[key] = analyzeJSONStructure( obj[key], maxDepth, currentDepth + 1, maxKeys ); } if (keys.length > keyLimit) { result[`[...${keys.length - keyLimit} more keys]`] = "..."; } return result; }