Filesystem MCP Server

Instructions

Implementation Reference

• src/handlers/json-handlers.ts:529-593 (handler)

  Main handler function for the json_validate tool. Parses arguments, reads JSON data and schema files, validates using Ajv JSON Schema validator, returns validation status and detailed errors.

  export async function handleJsonValidate(
    args: unknown,
    allowedDirectories: string[],
    symlinksMap: Map<string, string>,
    noFollowSymlinks: boolean
  ) {
    const parsed = parseArgs(JsonValidateArgsSchema, args, 'json_validate');
  
    const validPath = await validatePath(parsed.path, allowedDirectories, symlinksMap, noFollowSymlinks);
    const validSchemaPath = await validatePath(parsed.schemaPath, allowedDirectories, symlinksMap, noFollowSymlinks);
  
    try {
      // Read both the data and schema files
      const [jsonData, schemaData] = await Promise.all([
        readJsonFile(validPath, parsed.maxBytes),
        readJsonFile(validSchemaPath)
      ]);
  
      // Configure Ajv instance
      const ajv = new Ajv({
        allErrors: parsed.allErrors,
        strict: parsed.strict,
        validateSchema: true, // Validate the schema itself
        verbose: true // Include more detailed error information
      });
  
      try {
        // Compile and validate the schema itself first
        const validateSchema = ajv.compile(schemaData);
        
        // Validate the data
        const isValid = validateSchema(jsonData);
  
        // Prepare the validation result
        const result = {
          isValid,
          errors: isValid ? null : (validateSchema.errors as ErrorObject[])?.map(error => ({
            path: error.instancePath,
            keyword: error.keyword,
            message: error.message,
            params: error.params,
            schemaPath: error.schemaPath
          }))
        };
  
        return {
          content: [{
            type: "text",
            text: JSON.stringify(result, null, 2)
          }],
        };
      } catch (validationError) {
        // Handle schema compilation errors
        if (validationError instanceof Error) {
          throw new Error(`Schema validation failed: ${validationError.message}`);
        }
        throw validationError;
      }
    } catch (error) {
      if (error instanceof Error) {
        throw new Error(`JSON validation failed: ${error.message}`);
      }
      throw error;
    }
  }

• src/schemas/json-operations.ts:124-140 (schema)

  TypeBox schema defining input parameters for json_validate: paths to data and schema files, maxBytes limit, strict mode, and allErrors option.

  export const JsonValidateArgsSchema = Type.Object({
    path: Type.String({ description: 'Path to the JSON file to validate' }),
    schemaPath: Type.String({ description: 'Path to the JSON Schema file' }),
    maxBytes: Type.Integer({
      minimum: 1,
      description: 'Maximum bytes to read from the file. Must be a positive integer. Handler default: 10KB.'
    }),
    strict: Type.Optional(Type.Boolean({
      default: false,
      description: 'Whether to enable strict mode validation (additionalProperties: false)'
    })),
    allErrors: Type.Optional(Type.Boolean({
      default: true,
      description: 'Whether to collect all validation errors or stop at first error'
    }))
  });
  export type JsonValidateArgs = Static<typeof JsonValidateArgsSchema>;

• index.ts:291-292 (registration)

  Registers the json_validate handler function in the toolHandlers object, which is used to add the tool to the FastMCP server.

  json_validate: (a: unknown) =>
    handleJsonValidate(a, allowedDirectories, symlinksMap, noFollowSymlinks),

• src/schemas/index.ts:97-97 (registration)

  Maps the JsonValidateArgsSchema to the 'json_validate' tool name in the central toolSchemas export.

  json_validate: JsonValidateArgsSchema,

• index.ts:332-332 (registration)

  Declares the json_validate tool metadata (name and description) in the allTools array used for server registration.

  { name: "json_validate", description: "Validate JSON" },