Filesystem MCP Server

Instructions

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,