mcp-xpath

Instructions

Implementation Reference

• index.ts:132-167 (handler)

  Handler logic for the 'xpath' tool: validates arguments with Zod schema, parses XML content, checks for parsing errors, executes XPath query using xpath.select, handles empty results and errors, and returns formatted text content.

  if (name === "xpath") {
      const { xml, query, mimeType } = XPathArgumentsSchema.parse(args);
  
      try {
          // Parse XML
          const firstOpeningTag = xml.indexOf("<");
          const lastClosingTag = xml.lastIndexOf(">");
          const sanitizedXml = xml.substring(firstOpeningTag, lastClosingTag + 1);
          const parsedXml = parser.parseFromString(sanitizedXml, mimeType);
          
          // Check for parsing errors
          const errors = xpath.select('//parsererror', parsedXml);
          if (Array.isArray(errors) && errors.length > 0) {
              return {
                  content: [{ type: "text", text: "XML parsing error: " + resultToString(errors[0]) }]
              };
          }
          
          const result = xpath.select(query, parsedXml);
          
          // If result is an empty array, provide more information
          if (Array.isArray(result) && result.length === 0) {
              return {
                  content: [{ type: "text", text: "No nodes matched the query." }]
              };
          }
          
          return {
              content: [{ type: "text", text: resultToString(result) }]
          };
      } catch (error: unknown) {
          const errorMessage = error instanceof Error ? error.message : String(error);
          return {
              content: [{ type: "text", text: `Error processing XPath query: ${errorMessage}` }]
          };
      }

• index.ts:78-99 (registration)

  Registration of the 'xpath' tool in the listTools response, including name, description, and JSON input schema.

      name: "xpath",
      description: "Select query XML content using XPath",
      inputSchema: {
          type: "object",
          properties: {
              xml: {
                  type: "string",
                  description: "The XML content to query",
              },
              query: {
                  type: "string",
                  description: "The XPath query to execute",
              },
              mimeType: {
                  type: "string",
                  description: "The MIME type (e.g. text/xml, application/xml, text/html, application/xhtml+xml)",
                  default: "text/html"
              }
          },
          required: ["xml", "query"],
      },
  },

• index.ts:16-22 (schema)

  Zod schema used for runtime validation of 'xpath' tool arguments in the handler.

  const XPathArgumentsSchema = z.object({
      xml: z.string().describe("The XML content to query"),
      query: z.string().describe("The XPath query to execute"),
      mimeType: z.string()
      .describe("The MIME type (e.g. text/xml, application/xml, text/html, application/xhtml+xml)")
      .default("text/html")
  });

• index.ts:46-72 (helper)

  Helper function to convert XPath selection results (nodes, arrays, primitives) to a string representation for the tool output.

  function resultToString(result: string | number | boolean | Node | Node[] | null): string {
      if (result === null) {
          return "null";
      } else if (Array.isArray(result)) {
          return result.map(resultToString).join("\n");
      } else if (typeof result === 'object' && result.nodeType !== undefined) {
          // Handle DOM nodes
          if (result.nodeType === 1) { // Element node
              const serializer = new XMLSerializer();
              return serializer.serializeToString(result);
          } else if (result.nodeType === 2) { // Attribute node
              return `${result.nodeName}="${result.nodeValue}"`;
          } else if (result.nodeType === 3) { // Text node
              return result.nodeValue || "";
          } else {
              // Default fallback for other node types
              try {
                  const serializer = new XMLSerializer();
                  return serializer.serializeToString(result);
              } catch (e) {
                  return String(result);
              }
          }
      } else {
          return String(result);
      }
  }