json_sample
Extract JSON data samples from specified arrays within files. Define path, array location, sample count, and method (first or random) to retrieve precise data segments efficiently.
Instructions
Sample JSON data from a JSON file. Requires maxBytes parameter (default 10KB). Returns a random sample of data from the JSON file. The path must be within allowed directories.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| arrayPath | Yes | JSONPath expression to locate the target array (e.g., "$.items" or "$.data.records") | |
| count | Yes | Number of elements to sample | |
| maxBytes | Yes | Maximum bytes to read from the file. Must be a positive integer. Handler default: 10KB. | |
| method | No | Sampling method - "first" for first N elements, "random" for random sampling | first |
| path | Yes | Path to the JSON file containing the array |
Implementation Reference
- src/handlers/json-handlers.ts:473-524 (handler)Core handler function for json_sample tool. Parses arguments, reads and validates JSON file path, extracts target array using JSONPath, samples specified number of elements (first N or random), and returns formatted JSON response.
export async function handleJsonSample( args: unknown, allowedDirectories: string[], symlinksMap: Map<string, string>, noFollowSymlinks: boolean ) { const parsed = parseArgs(JsonSampleArgsSchema, args, 'json_sample'); const validPath = await validatePath(parsed.path, allowedDirectories, symlinksMap, noFollowSymlinks); const jsonData = await readJsonFile(validPath, parsed.maxBytes); try { // Use JSONPath to locate the target array const targetArray = JSONPath({ path: parsed.arrayPath, json: jsonData, wrap: false }); if (!Array.isArray(targetArray)) { throw new Error(`Path "${parsed.arrayPath}" did not resolve to an array`); } if (targetArray.length === 0) { return { content: [{ type: "text", text: JSON.stringify([], null, 2) }], }; } let sampledData: any[]; if (parsed.method === 'random') { sampledData = sampleSize(targetArray, Math.min(parsed.count, targetArray.length)); } else { sampledData = take(targetArray, parsed.count); } return { content: [{ type: "text", text: JSON.stringify(sampledData, null, 2) }], }; } catch (error) { if (error instanceof Error) { throw new Error(`JSON sampling failed: ${error.message}`); } throw error; } } - TypeBox schema definition for json_sample input arguments: requires path to JSON file, JSONPath to array, count of samples; optional sampling method (first/random) and maxBytes limit.
export const JsonSampleArgsSchema = Type.Object({ path: Type.String({ description: 'Path to the JSON file containing the array' }), arrayPath: Type.String({ description: 'JSONPath expression to locate the target array (e.g., "$.items" or "$.data.records")' }), count: Type.Integer({ minimum: 1, description: 'Number of elements to sample' }), method: Type.Optional( Type.Union([Type.Literal('first'), Type.Literal('random')], { default: 'first', description: 'Sampling method - "first" for first N elements, "random" for random sampling' }) ), maxBytes: Type.Integer({ minimum: 1, description: 'Maximum bytes to read from the file. Must be a positive integer. Handler default: 10KB.' }) }); export type JsonSampleArgs = Static<typeof JsonSampleArgsSchema>; - index.ts:289-290 (registration)Registers the json_sample tool handler in the central toolHandlers object, passing server context (allowedDirectories, symlinksMap, noFollowSymlinks).
json_sample: (a: unknown) => handleJsonSample(a, allowedDirectories, symlinksMap, noFollowSymlinks), - index.ts:331-331 (registration)Declares json_sample in the allTools array with name and description, used for permission filtering and tool listing.
{ name: "json_sample", description: "Sample JSON data" }, - src/schemas/index.ts:96-96 (schema)Re-exports JsonSampleArgsSchema as toolSchemas.json_sample for use in main index.ts registration loop.
json_sample: JsonSampleArgsSchema,