Filesystem MCP Server

Instructions

Implementation Reference

• src/handlers/json-handlers.ts:376-468 (handler)

  Main handler function that reads a JSON file, analyzes its structure recursively up to maxDepth, determines types including array element types, and returns a structured representation of the JSON schema-like structure.

  export async function handleJsonStructure(
    args: unknown,
    allowedDirectories: string[],
    symlinksMap: Map<string, string>,
    noFollowSymlinks: boolean
  ) {
    const parsed = parseArgs(JsonStructureArgsSchema, args, 'json_structure');
  
    const validPath = await validatePath(parsed.path, allowedDirectories, symlinksMap, noFollowSymlinks);
    const jsonData = await readJsonFile(validPath, parsed.maxBytes);
    const { maxDepth, detailedArrayTypes = false } = parsed;
    const effectiveMaxDepth = maxDepth ?? 2; // Default depth 2
  
    try {
      // Define a type that includes our custom type strings
      type ValueType = 'string' | 'number' | 'boolean' | 'object' | 'array' | `array<${string}>` | 'null' | 'undefined';
      
      /**
       * Analyze the type of a value, including detailed array analysis if requested
       */
      function analyzeType(value: any, currentDepth: number = 0): { type: ValueType; structure?: Record<string, any> } {
        // Handle null and undefined
        if (value === null) return { type: 'null' };
        if (value === undefined) return { type: 'undefined' };
  
        // Handle arrays
        if (Array.isArray(value)) {
          if (value.length === 0) return { type: 'array<empty>' as ValueType };
          
          if (detailedArrayTypes) {
            // Analyze all elements for mixed types
            const elementTypes = new Set<string>();
            value.forEach(item => {
              const itemType = analyzeType(item, currentDepth + 1);
              elementTypes.add(itemType.type);
            });
            
            const typeString = Array.from(elementTypes).join('|');
            return { type: `array<${typeString}>` as ValueType };
          } else {
            // Just analyze first element
            const firstType = analyzeType(value[0], currentDepth + 1);
            return { type: `array<${firstType.type}>` as ValueType };
          }
        }
  
        // Handle objects
        if (isPlainObject(value)) {
          const type = 'object' as ValueType;
          // If we haven't reached depth limit and object isn't empty, analyze structure
          if (currentDepth < effectiveMaxDepth && !isEmpty(value)) { // Use effectiveMaxDepth
            const structure: Record<string, any> = {};
            for (const [key, val] of Object.entries(value)) {
              structure[key] = analyzeType(val, currentDepth + 1);
            }
            return { type, structure };
          }
          return { type };
        }
  
        // Handle primitives
        if (typeof value === 'string') return { type: 'string' };
        if (typeof value === 'number') return { type: 'number' };
        if (typeof value === 'boolean') return { type: 'boolean' };
  
        // Fallback
        return { type: typeof value as ValueType };
      }
  
      // Analyze the root structure
      const structure = Array.isArray(jsonData)
        ? { type: 'array', elements: analyzeType(jsonData, 0) }
        : transform(
            jsonData,
            (result: Record<string, any>, value: unknown, key: string) => {
              result[key] = analyzeType(value, 0);
            },
            {} as Record<string, any>
          );
  
      return {
        content: [{ 
          type: "text", 
          text: JSON.stringify(structure, null, 2)
        }],
      };
    } catch (error) {
      if (error instanceof Error) {
        throw new Error(`JSON structure analysis failed: ${error.message}`);
      }
      throw error;
    }
  }

• src/schemas/json-operations.ts:88-103 (schema)

  TypeBox schema defining input arguments for the json_structure tool: path to JSON file, maxBytes limit, maxDepth for analysis, and optional detailedArrayTypes flag.

  export const JsonStructureArgsSchema = Type.Object({
    path: Type.String({ description: 'Path to the JSON file to analyze' }),
    maxBytes: Type.Integer({
      minimum: 1,
      description: 'Maximum bytes to read from the file. Must be a positive integer. Handler default: 10KB.'
    }),
    maxDepth: Type.Integer({
      minimum: 1,
      description: 'How deep to analyze the structure. Must be a positive integer. Handler default: 2.'
    }),
    detailedArrayTypes: Type.Optional(Type.Boolean({
      default: false,
      description: 'Whether to analyze all array elements for mixed types (default: false)'
    }))
  });
  export type JsonStructureArgs = Static<typeof JsonStructureArgsSchema>;

• index.ts:281-282 (registration)

  Registration of the json_structure tool handler in the central toolHandlers object, binding it to handleJsonStructure with server context (allowedDirectories, symlinksMap, noFollowSymlinks).

  json_structure: (a: unknown) =>
    handleJsonStructure(a, allowedDirectories, symlinksMap, noFollowSymlinks),

• index.ts:327-327 (registration)

  Declaration of the json_structure tool in the allTools array, including its name and description.

  { name: "json_structure", description: "JSON structure" },

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

  Mapping of the json_structure tool name to its JsonStructureArgsSchema in the central toolSchemas export.

  json_structure: JsonStructureArgsSchema,