# 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)