Filesystem MCP Server

Instructions

Implementation Reference

• src/handlers/utility-handlers.ts:183-235 (handler)

  The core handler function implementing the xml_to_json_string tool: validates input, reads XML file, parses it to JSON object using fast-xml-parser, stringifies with formatting, applies optional size truncation for large outputs, and returns as text content.

  export async function handleXmlToJsonString(
    args: unknown,
    allowedDirectories: string[],
    symlinksMap: Map<string, string>,
    noFollowSymlinks: boolean
  ) {
    const parsed = parseArgs(XmlToJsonStringArgsSchema, args, 'xml_to_json_string');
  
    const { xmlPath, maxBytes, options } = parsed;
    const validXmlPath = await validatePath(xmlPath, allowedDirectories, symlinksMap, noFollowSymlinks);
    
    try {
      // Read the XML file (no input size gating; limit only output)
      const xmlContent = await fs.readFile(validXmlPath, "utf-8");
      
      // Parse XML to JSON
      const parserOptions = {
        ignoreAttributes: options?.ignoreAttributes ?? false,
        preserveOrder: options?.preserveOrder ?? true,
        // Add other options as needed
      };
      
      const parser = new XMLParser(parserOptions);
      const jsonObj = parser.parse(xmlContent);
      
      // Return the JSON as a string
      let jsonContent = JSON.stringify(jsonObj, null, 2);
  
      // Apply response-size cap
      const responseLimit = (parsed as any).maxResponseBytes ?? maxBytes ?? 200 * 1024; // default 200KB
      if (typeof responseLimit === 'number' && responseLimit > 0) {
        const size = Buffer.byteLength(jsonContent, 'utf8');
        if (size > responseLimit) {
          const summary = {
            _meta: {
              truncated: true,
              originalSize: size,
              note: `JSON too large; summarizing to fit ${responseLimit} bytes.`
            },
            sample: Array.isArray(jsonObj) ? jsonObj.slice(0, 5) : (typeof jsonObj === 'object' ? Object.fromEntries(Object.entries(jsonObj).slice(0, 100)) : jsonObj)
          };
          jsonContent = JSON.stringify(summary, null, 2);
        }
      }
      
      return {
        content: [{ type: "text", text: jsonContent }],
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      throw new Error(`Failed to convert XML to JSON: ${errorMessage}`);
    }
  }

• src/schemas/utility-operations.ts:62-79 (schema)

  TypeBox schema defining the input parameters for the tool: xmlPath (required), maxBytes/maxResponseBytes (optional limits), options for parser behavior.

  export const XmlToJsonStringArgsSchema = Type.Object({
    xmlPath: Type.String({ description: 'Path to the XML file to convert' }),
    maxBytes: Type.Optional(Type.Integer({
      minimum: 1,
      description: '[Deprecated semantics] Previously limited file bytes read; now treated as a response size cap in bytes.'
    })),
    maxResponseBytes: Type.Optional(Type.Integer({
      minimum: 1,
      description: 'Maximum size, in bytes, of the returned JSON string. Parsing reads full file; response may be truncated to respect this limit.'
    })),
    options: Type.Optional(
      Type.Object({
        ignoreAttributes: Type.Boolean({ default: false, description: 'Whether to ignore attributes in XML' }),
        preserveOrder: Type.Boolean({ default: true, description: 'Whether to preserve the order of properties' })
      }, { default: {} })
    )
  });
  export type XmlToJsonStringArgs = Static<typeof XmlToJsonStringArgsSchema>;

• index.ts:269-270 (registration)

  Maps the tool name 'xml_to_json_string' to its handler function in the toolHandlers object, which is used during server tool registration.

  xml_to_json_string: (a: unknown) =>
    handleXmlToJsonString(a, allowedDirectories, symlinksMap, noFollowSymlinks),

• index.ts:324-324 (registration)

  Declares the tool metadata (name and description) in the allTools array, which determines available tools based on permissions.

  { name: "xml_to_json_string", description: "XML to JSON string" },

• src/schemas/index.ts:90-90 (schema)

  Re-exports and maps the schema to the tool name in the central toolSchemas object used by the server.

  xml_to_json_string: XmlToJsonStringArgsSchema,