json_transform
Modify JSON data by applying sequential operations such as mapping, grouping, sorting, flattening, and field selection. Requires specified file path, operations, and size limit for secure processing.
Instructions
Transform JSON data using a sequence of operations. Supports operations like mapping array elements, grouping by fields, sorting, flattening nested arrays, and picking/omitting fields. Requires maxBytes parameter (default 10KB). Operations are applied in sequence to transform the data structure. The path must be within allowed directories.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| maxBytes | Yes | Maximum bytes to read from the file. Must be a positive integer. Handler default: 10KB. | |
| operations | Yes | Array of transformation operations to apply in sequence | |
| path | Yes | Path to the JSON file to transform |
Implementation Reference
- src/handlers/json-handlers.ts:279-371 (handler)The core handler function for the 'json_transform' tool. It validates input arguments, reads and parses a JSON file, applies a sequence of transformation operations (map, groupBy, sort, flatten, pick, omit) based on the provided operations array, and returns the transformed JSON as a formatted string.export async function handleJsonTransform( args: unknown, allowedDirectories: string[], symlinksMap: Map<string, string>, noFollowSymlinks: boolean ) { const parsed = parseArgs(JsonTransformArgsSchema, args, 'json_transform'); const validPath = await validatePath(parsed.path, allowedDirectories, symlinksMap, noFollowSymlinks); let jsonData = await readJsonFile(validPath, parsed.maxBytes); try { // Apply operations in sequence for (const op of parsed.operations) { switch (op.type) { case 'map': if (!Array.isArray(jsonData)) { throw new Error('Data must be an array for map operation'); } if (!op.field) { throw new Error('Field is required for map operation'); } jsonData = jsonData.map(item => getProp(item, op.field!)); break; case 'groupBy': if (!Array.isArray(jsonData)) { throw new Error('Data must be an array for groupBy operation'); } if (!op.field) { throw new Error('Field is required for groupBy operation'); } jsonData = groupBy(jsonData, op.field); break; case 'sort': if (!Array.isArray(jsonData)) { throw new Error('Data must be an array for sort operation'); } if (!op.field) { throw new Error('Field is required for sort operation'); } jsonData = orderBy( jsonData, op.field, [op.order || 'asc'] ); break; case 'flatten': if (!Array.isArray(jsonData)) { throw new Error('Data must be an array for flatten operation'); } jsonData = flattenDeep(jsonData); break; case 'pick': if (!op.fields || !op.fields.length) { throw new Error('Fields array is required for pick operation'); } if (Array.isArray(jsonData)) { jsonData = jsonData.map(item => pick(item, op.fields!)); } else { jsonData = pick(jsonData, op.fields); } break; case 'omit': if (!op.fields || !op.fields.length) { throw new Error('Fields array is required for omit operation'); } if (Array.isArray(jsonData)) { jsonData = jsonData.map(item => omit(item, op.fields!)); } else { jsonData = omit(jsonData, op.fields); } break; } } return { content: [{ type: "text", text: JSON.stringify(jsonData, null, 2) }], }; } catch (error) { if (error instanceof Error) { throw new Error(`JSON transformation failed: ${error.message}`); } throw error; } }
- src/schemas/json-operations.ts:62-85 (schema)TypeBox schema definition for JsonTransformArgs, including path to JSON file, array of operations (map, groupBy, sort, flatten, pick, omit), and maxBytes limit. Defines the input validation for the tool.export const JsonTransformArgsSchema = Type.Object({ path: Type.String({ description: 'Path to the JSON file to transform' }), operations: Type.Array( Type.Object({ type: Type.Union([ Type.Literal('map'), Type.Literal('groupBy'), Type.Literal('sort'), Type.Literal('flatten'), Type.Literal('pick'), Type.Literal('omit') ], { description: 'Type of transformation operation' }), field: Type.Optional(Type.String({ description: 'Field to operate on (if applicable)' })), order: Type.Optional(Type.Union([Type.Literal('asc'), Type.Literal('desc')], { description: 'Sort order (if applicable)' })), fields: Type.Optional(Type.Array(Type.String(), { description: 'Fields to pick/omit (if applicable)' })) }), { minItems: 1, description: 'Array of transformation operations to apply in sequence' } ), maxBytes: Type.Integer({ minimum: 1, description: 'Maximum bytes to read from the file. Must be a positive integer. Handler default: 10KB.' }) }); export type JsonTransformArgs = Static<typeof JsonTransformArgsSchema>;
- index.ts:287-288 (registration)Registers the handler function for 'json_transform' in the toolHandlers object, wrapping it with context (allowedDirectories, symlinksMap, noFollowSymlinks). This is used in the server.addTool loop.json_transform: (a: unknown) => handleJsonTransform(a, allowedDirectories, symlinksMap, noFollowSymlinks),
- index.ts:330-330 (registration)Includes 'json_transform' in the allTools array with its name and description, which determines if it's enabled based on permissions and passed to server.addTool.{ name: "json_transform", description: "Transform JSON" },
- src/schemas/index.ts:95-95 (schema)Maps the 'json_transform' tool name to its JsonTransformArgsSchema in the central toolSchemas export, used by index.ts for parameter schema in tool registration.json_transform: JsonTransformArgsSchema,