xml_query
Extract specific data from large XML files using XPath 1.0 queries, efficiently searching elements, attributes, and text content without loading the entire file into memory.
Instructions
Query XML file using XPath expressions. Provides powerful search capabilities without reading the entire file into memory. Supports standard XPath 1.0 query syntax for finding elements, attributes, and text content. Requires maxBytes parameter (default 10KB). Can be used to extract specific data from large XML files with precise queries. The path must be within allowed directories.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| includeAttributes | No | Whether to include attribute information in the results | |
| maxBytes | Yes | Maximum bytes to read from the file. Must be a positive integer. Handler default: 10KB. | |
| path | Yes | Path to the XML file to query | |
| query | No | XPath query to execute against the XML file | |
| structureOnly | No | If true, returns only tag names and structure instead of executing query |
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}`); } }
- 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,