Metadata-Version: 2.4
Name: mac2win-zip-mcp
Version: 1.0.0
Summary: MCP Server for creating Windows-compatible ZIP files from macOS
Project-URL: Homepage, https://github.com/Wordbe/mac2win-zip-mcp
Project-URL: Repository, https://github.com/Wordbe/mac2win-zip-mcp
Project-URL: Issues, https://github.com/Wordbe/mac2win-zip-mcp/issues
Author: mac2win-zip-mcp contributors
License: MIT License
        
        Copyright (c) 2025 mac2win-zip-mcp contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: macos,mcp,nfc,nfd,unicode,windows,zip
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Archiving :: Compression
Requires-Python: >=3.10
Requires-Dist: mac2win-zip>=1.0.1
Requires-Dist: mcp>=1.9.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# mac2win-zip MCP Server

<p align="center">
  <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python Version">
  <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License">
  <img src="https://img.shields.io/badge/platform-macOS-lightgrey.svg" alt="Platform">
  <img src="https://img.shields.io/badge/package%20manager-uv-ff69b4.svg" alt="Package Manager">
  <img src="https://img.shields.io/badge/MCP-v1.9+-purple.svg" alt="MCP Version">
</p>

<p align="center">
  <strong>Create Windows-compatible ZIP files from macOS via MCP</strong>
</p>

> **An MCP (Model Context Protocol) server for creating Windows-compatible ZIP files.**
>
> This MCP server wraps the functionality of [mac2win-zip](https://github.com/Wordbe/mac2win-zip) to create ZIP files that work perfectly on Windows from macOS.

## Why mac2win-zip MCP Server?

### The Problem

macOS uses **NFD (Normalization Form Decomposed)** for Unicode filenames, while Windows uses **NFC (Normalization Form Composed)**. When you create a ZIP file on macOS containing files with Unicode characters (like Korean, Japanese, or special characters), Windows users often see garbled filenames.

| macOS (ZIP created)   | Windows (ZIP opened) |
| --------------------- | -------------------- |
| 📄 Hello?.pdf          | ❌ (removed)          |
| 📄 안녕하세요 세상.pdf | ❌ (removed)          |

### The Solution

This MCP server automatically:
1. Normalizes all filenames from NFD to NFC
2. Removes or replaces Windows-forbidden characters
3. Excludes macOS-specific files (`.DS_Store`, etc.)
4. Preserves the folder structure

**Result:** ZIP files that work perfectly on both macOS and Windows!

| macOS (ZIP created)   | Windows (ZIP opened)  |
| --------------------- | --------------------- |
| 📄 Hello.pdf          | ✅ Hello.pdf           |
| 📄 안녕하세요 세상.pdf | ✅ 안녕하세요 세상.pdf |

## Installation

### Quick Install (Recommended)

```bash
# Install with uv (creates a global command)
uvx --from git+https://github.com/Wordbe/mac2win-zip-mcp mac2win-zip-mcp

# Or install with pipx
pipx install git+https://github.com/Wordbe/mac2win-zip-mcp
```

### Development Install

```bash
# Clone the repository
git clone https://github.com/Wordbe/mac2win-zip-mcp.git
cd mac2win-zip-mcp

# Install in development mode
uv pip install -e ".[dev]"
```

## Usage

### MCP Configuration for Claude Desktop

Add this to your Claude Desktop configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mac2win-zip": {
      "command": "mac2win-zip-mcp"
    }
  }
}
```

That's it! No path configuration needed. The command is globally available after installation.

### MCP Tools

This server provides the following tools:

#### `create_windows_compatible_zip`

Create a Windows-compatible ZIP file from files and/or folders.

**Parameters:**
- `paths` (array, required): List of file or folder paths to zip
- `output` (string, optional): Output ZIP filename (default: "archive.zip")
- `working_dir` (string, optional): Base directory for relative paths

**Example usage:**
```
Create a Windows-compatible ZIP of the current directory

Paths: ["."]
Output: "backup.zip"
```

#### `validate_zip_for_windows`

Validate if a ZIP file is Windows-compatible.

**Parameters:**
- `zip_path` (string, required): Path to the ZIP file to validate
- `working_dir` (string, optional): Base directory for relative path

**Example usage:**
```
Check if a ZIP file is Windows-compatible

ZIP Path: "archive.zip"
```

## Example Usage with AI Assistants

### Create a ZIP of a folder

```
Create a Windows-compatible ZIP of my Documents folder containing all PDF files.
```

The AI assistant will:
1. Call `create_windows_compatible_zip` with the Documents folder path
2. Return the created ZIP file path and file count

### Validate a ZIP file

```
Check if my-backup.zip is Windows-compatible.
```

The AI assistant will:
1. Call `validate_zip_for_windows` with the ZIP file path
2. Return validation results and any issues found

## Features

- **Unicode Normalization**: Converts macOS NFD filenames to Windows-compatible NFC
- **Character Sanitization**: Removes Windows-forbidden characters (`<>:"|?*\`)
- **Auto Recursive**: Automatically includes all subdirectories when zipping folders
- **Smart Naming**: Creates `folder-name.zip` by default (no -o needed for single folder)
- **Structure Preservation**: Maintains original folder hierarchy in ZIP
- **Smart Filtering**: Excludes hidden files (`.DS_Store`, etc.)
- **Korean Support**: Perfect handling of Korean and other Unicode filenames
- **MCP Protocol**: Works with any MCP-compliant AI assistant (Claude, etc.)

## Requirements

- Python 3.10 or higher
- uv (recommended) or pip
- MCP-compatible AI assistant (e.g., Claude Desktop)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Architecture

This MCP server is a thin wrapper around the [mac2win-zip](https://github.com/Wordbe/mac2win-zip) library, exposing its functionality via the Model Context Protocol. This means:

- **Single source of truth**: Core ZIP creation logic lives in `mac2win-zip`
- **Always in sync**: Updates to `mac2win-zip` automatically benefit this MCP server
- **Separation of concerns**: CLI tool and MCP server share the same battle-tested code

## Related Projects

- [mac2win-zip](https://github.com/Wordbe/mac2win-zip) - CLI tool for creating Windows-compatible ZIP files (core library)
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol powering this server

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Bug Reports

If you discover any bugs, please create an issue on GitHub with:
- Your operating system and version
- Python version
- MCP client information
- Steps to reproduce the bug
- Expected vs actual behavior

## Show Your Support

If this project helped you, please give it a star!

---

<p align="center">
  Made with ❤️ by Wordbe for seamless macOS-Windows file sharing
</p>
