Filesystem MCP Server

Instructions

Implementation Reference

• src/handlers/xml-handlers.ts:40-77 (handler)

  Main handler function for the 'xml_query' tool. Validates input args using schema, checks path permissions, reads XML file, processes it with XPath query or structure analysis, handles response size limits, and returns formatted results.

  export async function handleXmlQuery(
    args: unknown,
    allowedDirectories: string[],
    symlinksMap: Map<string, string>,
    noFollowSymlinks: boolean
  ): Promise<{ content: Array<{ type: string; text: string }> }> {
    const parsed = parseArgs(XmlQueryArgsSchema, args, 'xml_query');
  
    const validPath = await validatePath(
      parsed.path,
      allowedDirectories,
      symlinksMap,
      noFollowSymlinks
    );
  
    try {
      const xmlContent = await fs.readFile(validPath, 'utf8');
  
      try {
        const responseLimit =
          (parsed as any).maxResponseBytes ?? parsed.maxBytes ?? 200 * 1024; // 200KB default
        const result = processXmlContent(
          xmlContent,
          parsed.query,
          parsed.structureOnly,
          parsed.includeAttributes,
          responseLimit
        );
        return result;
      } catch (err) {
        const errorMessage = err instanceof Error ? err.message : String(err);
        throw new Error(`Failed to process XML: ${errorMessage}`);
      }
    } catch (err) {
      const errorMessage = err instanceof Error ? err.message : String(err);
      throw new Error(`Failed to query XML file: ${errorMessage}`);
    }
  }

• src/schemas/utility-operations.ts:81-95 (schema)

  TypeBox schema definition for 'xml_query' tool input parameters, including path to XML, optional XPath query, structure-only flag, response size limits, and attribute inclusion.

  export const XmlQueryArgsSchema = Type.Object({
    path: Type.String({ description: 'Path to the XML file to query' }),
    query: Type.Optional(Type.String({ description: 'XPath query to execute against the XML file' })),
    structureOnly: Type.Optional(Type.Boolean({ default: false, description: 'If true, returns only tag names and structure instead of executing query' })),
    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.'
    })),
    includeAttributes: Type.Optional(Type.Boolean({ default: true, description: 'Whether to include attribute information in the results' }))
  });
  export type XmlQueryArgs = Static<typeof XmlQueryArgsSchema>;

• index.ts:257-258 (registration)

  Maps the 'xml_query' tool name to the handleXmlQuery execution function in the central toolHandlers object, passing server context like allowed directories.

  xml_query: (a: unknown) =>
    handleXmlQuery(a, allowedDirectories, symlinksMap, noFollowSymlinks),

• index.ts:321-321 (registration)

  Includes 'xml_query' in the allTools array with its name and description, used to conditionally register tools based on permissions before adding to the MCP server.

  { name: "xml_query", description: "Query XML" },

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

  Re-exports and maps the XmlQueryArgsSchema to 'xml_query' key in the central toolSchemas object, imported and used in index.ts for tool parameter schemas.

  xml_query: XmlQueryArgsSchema,