mcp-xml

# MCP-XML Server A powerful Model Context Protocol (MCP) server for comprehensive XML file operations. This server provides tools to read, analyze, search, find, relate, and write XML files within your project directories. ## Features - **Find XML Files**: Locate XML files in directories and subdirectories - **Read XML Files**: Parse and display XML content with structured data - **Analyze XML Structure**: Get detailed analysis of XML structure, elements, attributes, and depth - **Search XML Content**: Search for specific content within XML files or specific elements - **Write XML Files**: Create new XML files from JavaScript objects - **Transform XML**: Perform various transformations on XML files (filter, rename, add/remove attributes) - **Relate XML Files**: Find relationships between XML files based on structure or content - **Validate XML**: Check XML files for well-formedness and basic validation ## Installation ```bash npm install npm run build ``` ## Usage This is an MCP server that can be integrated with MCP-compatible clients like Claude Desktop or other AI assistants. ### Configuration Add this server to your MCP client configuration: ```json { "servers": { "mcp-xml": { "command": "node", "args": ["/path/to/mcp-xml/dist/index.js"] } } } ``` ### Available Tools #### 1. `find_xml_files` Find XML files in the current directory and subdirectories. **Parameters:** - `directory` (optional): Directory to search (defaults to current directory) - `pattern` (optional): Glob pattern for XML files (defaults to `**/*.xml`) **Example usage:** ``` Find all XML files in the current project Find XML files in the 'config' directory Find XML files matching pattern '**/test*.xml' ``` #### 2. `read_xml_file` Read and parse an XML file, showing both raw content and parsed structure. **Parameters:** - `filePath` (required): Path to the XML file to read **Example usage:** ``` Read the config.xml file Read ./data/sample.xml ``` #### 3. `analyze_xml_file` Analyze XML file structure including element count, attributes, depth, and namespaces. **Parameters:** - `filePath` (required): Path to the XML file to analyze **Example usage:** ``` Analyze the structure of config.xml Get analysis of ./schemas/sample.xml ``` #### 4. `search_xml_content` Search for specific content within XML files. **Parameters:** - `searchTerm` (required): Term to search for in XML content - `directory` (optional): Directory to search (defaults to current directory) - `elementName` (optional): Specific XML element name to search within **Example usage:** ``` Search for "configuration" in all XML files Search for "localhost" in the "server" element across XML files Search for "error" in XML files in the logs directory ``` #### 5. `write_xml_file` Write data to an XML file from a JavaScript object. **Parameters:** - `filePath` (required): Path where to write the XML file - `data` (required): JavaScript object to convert to XML - `xmlDeclaration` (optional): Include XML declaration (defaults to true) **Example usage:** ``` Create a new config.xml file with the provided data structure Write user data to users.xml ``` #### 6. `transform_xml` Transform XML content using various operations. **Parameters:** - `filePath` (required): Path to the XML file to transform - `outputPath` (required): Path where to save the transformed XML - `operation` (required): Type of transformation (`filter_elements`, `rename_elements`, `add_attributes`, `remove_attributes`) - `parameters` (optional): Parameters for the transformation operation **Operations:** - `filter_elements`: Keep only specified elements - `rename_elements`: Rename elements based on mapping - `add_attributes`: Add attributes to specified elements - `remove_attributes`: Remove attributes from specified elements **Example usage:** ``` Filter config.xml to keep only 'server' and 'database' elements Rename all 'config' elements to 'configuration' in settings.xml Add version="1.0" attribute to all 'module' elements Remove deprecated attributes from legacy.xml ``` #### 7. `relate_xml_files` Find relationships between XML files based on content or structure. **Parameters:** - `directory` (optional): Directory to analyze (defaults to current directory) - `relationType` (required): Type of relationship (`common_elements`, `shared_attributes`, `similar_structure`, `reference_links`) **Relationship Types:** - `common_elements`: Files that share the same XML elements - `shared_attributes`: Files that use the same attributes - `similar_structure`: Files with similar XML structure (>70% similarity) - `reference_links`: Files that reference each other's content **Example usage:** ``` Find XML files with common elements Identify files sharing similar structure Find cross-references between XML files ``` #### 8. `validate_xml` Validate XML file structure and check for well-formedness. **Parameters:** - `filePath` (required): Path to the XML file to validate **Example usage:** ``` Validate the config.xml file Check if data.xml is well-formed ``` ## XML Processing Features The server uses the [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser) library, which provides: - **Namespace Support**: Full XML namespace handling - **Attribute Preservation**: Maintains all XML attributes during parsing - **Format Preservation**: Maintains XML formatting when writing files - **Error Handling**: Graceful error handling for malformed XML ## Technical Details ### Dependencies - `@modelcontextprotocol/sdk`: MCP TypeScript SDK for server implementation - `fast-xml-parser`: High-performance XML parser and builder - `glob`: File pattern matching for finding XML files - `fs-extra`: Enhanced filesystem operations ### Architecture The server is built as a single class `XMLMCPServer` that: 1. Initializes the MCP server with tool definitions 2. Sets up XML parser and builder with appropriate configurations 3. Implements each tool as a private method 4. Handles errors gracefully and provides meaningful feedback 5. Uses the current working directory as the base for operations ### Security Considerations - File operations are restricted to the current working directory and subdirectories - Common directories like `node_modules`, `dist`, and `.git` are excluded from searches - File paths are resolved using Node.js path utilities to prevent directory traversal ## Examples ### Example XML Analysis Output ``` XML Analysis for config.xml: Element Count: 15 Attribute Count: 8 Max Depth: 4 Has Namespaces: true Elements Found: config, server, database, logging, security Attributes Found: version, type, enabled, port, host, name Namespaces: cfg, db ``` ### Example Relationship Analysis ``` XML File Relationships (common_elements): config.xml ↔ settings.xml Common elements: server, database, logging schema.xml ↔ validation.xml Common elements: rules, validation, constraints ``` ## Development ### Building ```bash npm run build ``` ### Development Mode ```bash npm run dev ``` ### Project Structure ``` mcp-xml/ ├── src/ │ └── index.ts # Main server implementation ├── dist/ # Compiled JavaScript output ├── package.json # Package configuration ├── tsconfig.json # TypeScript configuration └── README.md # This file ``` ## Contributing This MCP server is designed to be comprehensive and extensible. Contributions are welcome for: - Additional XML transformation operations - Enhanced relationship analysis algorithms - Performance optimizations - Additional validation rules - Support for XML Schema validation ## License MIT License - see the package.json file for details. ## Related Resources - [Model Context Protocol Documentation](https://github.com/modelcontextprotocol/) - [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - [fast-xml-parser Documentation](https://github.com/NaturalIntelligence/fast-xml-parser) - [Working with XML in Node.js](https://johnnyreilly.com/xml-read-and-write-with-node-js)