Filesystem MCP Server

Instructions

Implementation Reference

• src/handlers/xml-handlers.ts:82-145 (handler)

  Main handler function for the 'xml_structure' tool. Validates arguments, reads and parses the XML file, extracts structure using extractXmlStructure, handles response size limits, and returns the structure as JSON.

  export async function handleXmlStructure(
    args: unknown,
    allowedDirectories: string[],
    symlinksMap: Map<string, string>,
    noFollowSymlinks: boolean
  ): Promise<{ content: Array<{ type: string; text: string }> }> {
    const parsed = parseArgs(XmlStructureArgsSchema, args, 'xml_structure');
  
    const validPath = await validatePath(
      parsed.path,
      allowedDirectories,
      symlinksMap,
      noFollowSymlinks
    );
  
    try {
      const xmlContent = await fs.readFile(validPath, 'utf8');
  
      try {
        const parser = new XmldomDOMParser();
        const doc: any = parser.parseFromString(xmlContent, 'text/xml');
        const structure = extractXmlStructure(
          doc,
          parsed.maxDepth,
          parsed.includeAttributes
        );
  
        const responseLimit = (parsed as any).maxResponseBytes ?? parsed.maxBytes ?? 200 * 1024; // 200KB default
        let json = JSON.stringify(structure, null, 2);
  
        if (typeof responseLimit === 'number' && responseLimit > 0) {
          const size = Buffer.byteLength(json, 'utf8');
          if (size > responseLimit) {
            // Fallback to a summarized structure to respect response limit
            const summary = {
              rootElement: structure.rootElement,
              namespaces: structure.namespaces,
              elementTypeCount: Object.keys(structure.elements).length,
              attributeKeyCount: structure.attributes ? Object.keys(structure.attributes).length : 0,
              hierarchy: structure.hierarchy ? { name: structure.hierarchy.name, hasChildren: structure.hierarchy.hasChildren, childrenCount: structure.hierarchy.children?.length ?? 0 } : undefined,
              _meta: {
                truncated: true,
                note: `Full structure omitted to fit response limit of ${responseLimit} bytes`
              }
            };
            json = JSON.stringify(summary, null, 2);
          }
        }
  
        return {
          content: [{
            type: 'text',
            text: json
          }]
        };
      } catch (err) {
        const errorMessage = err instanceof Error ? err.message : String(err);
        throw new Error(`Failed to extract XML structure: ${errorMessage}`);
      }
    } catch (err) {
      const errorMessage = err instanceof Error ? err.message : String(err);
      throw new Error(`Failed to analyze XML structure: ${errorMessage}`);
    }
  }

• src/handlers/xml-handlers.ts:313-347 (helper)

  Core helper function that extracts detailed XML structure: root element, element counts, attribute counts, namespaces, and hierarchy up to maxDepth.

  function extractXmlStructure(doc: any, maxDepth = 2, includeAttributes = true): XmlStructureInfo {
    const structure: XmlStructureInfo = {
      rootElement: doc.documentElement?.nodeName,
      elements: {},
      attributes: includeAttributes ? {} : undefined,
      namespaces: extractNamespaces(doc),
    };
  
    // Get all element names and counts
    const elementQuery = "//*";
    const elements = xpath.select(elementQuery, doc) as any[];
  
    elements.forEach((element) => {
      const el = element as any;
      const name = el.nodeName;
      structure.elements[name] = (structure.elements[name] || 0) + 1;
  
      if (includeAttributes && el.attributes && el.attributes.length > 0) {
        for (let i = 0; i < el.attributes.length; i++) {
          const attr = el.attributes[i];
          const attrKey = `${name}@${attr.nodeName}`;
          if (structure.attributes) {
            structure.attributes[attrKey] = (structure.attributes[attrKey] || 0) + 1;
          }
        }
      }
    });
  
    // Get child relationship structure up to maxDepth
    if (maxDepth > 0 && doc.documentElement) {
      structure.hierarchy = buildHierarchy(doc.documentElement, maxDepth);
    }
  
    return structure;
  }

• src/schemas/utility-operations.ts:97-113 (schema)

  TypeBox schema defining input parameters for the xml_structure tool: path, maxDepth, includeAttributes, size limits.

  export const XmlStructureArgsSchema = Type.Object({
    path: Type.String({ description: 'Path to the XML file to analyze' }),
    maxDepth: Type.Integer({
      minimum: 1,
      description: 'How deep to analyze the hierarchy. Must be a positive integer. Handler default: 2.'
    }),
    includeAttributes: Type.Optional(Type.Boolean({ default: true, description: 'Whether to include attribute information' })),
    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 content. Parsing reads full file; response may be truncated to respect this limit.'
    }))
  });
  export type XmlStructureArgs = Static<typeof XmlStructureArgsSchema>;

• index.ts:259-260 (registration)

  Registers the handleXmlStructure function as the executor for the 'xml_structure' tool in the toolHandlers object, which is used in server.addTool.

  xml_structure: (a: unknown) =>
    handleXmlStructure(a, allowedDirectories, symlinksMap, noFollowSymlinks),

• index.ts:322-322 (registration)

  Includes 'xml_structure' in the allTools list with description, used to conditionally add the tool via server.addTool.

  { name: "xml_structure", description: "Analyze XML structure" },