# Undoom Sketch MCP

[![PyPI version](https://badge.fury.io/py/undoom-sketch-mcp.svg)](https://badge.fury.io/py/undoom-sketch-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

一个基于 MCP (Model Context Protocol) 的图片素描化服务器，可以将普通图片转换为多种风格的素描效果。支持单张图片转换、批量处理，以及多种自定义参数调节。

## 🌟 在线体验

项目已发布到 PyPI，可以直接使用：
- **PyPI**: [undoom-sketch-mcp](https://pypi.org/project/undoom-sketch-mcp/)
- **GitHub**: [undoom-sketch-mcp](https://github.com/kk520879/undoom-sketch-mcp)

## 功能特性

- 🎨 **多种素描风格**：支持经典、详细、柔和三种不同的素描风格
- 📁 **批量处理**：支持批量转换文件夹中的所有图片
- 🖼️ **多格式支持**：支持 JPG、PNG、BMP、GIF、TIFF、WEBP 等常见图片格式
- 🌏 **中文路径支持**：完美支持中文文件名和路径
- ⚙️ **参数可调**：可自定义模糊程度和对比度参数
- 📊 **图片信息查看**：提供图片基本信息和推荐参数

## 安装要求

- Python >= 3.13
- 依赖包：
  - mcp[cli] >= 1.12.3
  - opencv-python >= 4.8.0
  - numpy >= 1.24.0

## 🚀 快速开始

### 方法一：直接使用 uvx（推荐）

```bash
# 使用国内镜像源（推荐）
uvx --index-url https://pypi.tuna.tsinghua.edu.cn/simple undoom-sketch-mcp

# 或使用默认源
uvx undoom-sketch-mcp
```

### 方法二：通过 PyPI 安装

```bash
# 安装包
pip install undoom-sketch-mcp

# 运行服务器
python -m undoom_sketch_mcp
```

### 方法三：从源码安装

```bash
# 克隆项目
git clone https://github.com/kk520879/undoom-sketch-mcp.git
cd undoom-sketch-mcp

# 使用 uv 安装（推荐）
uv sync

# 或使用 pip
pip install -e .
```

## 📖 使用方法

### 作为 MCP 服务器使用

#### 1. 配置 MCP 客户端

创建 `mcp_config.json` 配置文件：

```json
{
  "mcpServers": {
    "undoom-sketch-mcp": {
      "command": "uvx",
      "args": [
        "--index-url",
        "https://pypi.tuna.tsinghua.edu.cn/simple",
        "undoom-sketch-mcp"
      ]
    }
  }
}
```

#### 2. 直接运行服务器

```bash
# 启动 MCP 服务器
python -m undoom_sketch_mcp

# 或使用 uvx
uvx undoom-sketch-mcp
```

### 🛠️ 可用工具

#### 1. convert_image_to_sketch - 单张图片转换

**MCP 调用示例：**
```json
{
  "tool": "convert_image_to_sketch",
  "arguments": {
    "image_path": "D:\\photos\\portrait.jpg",
    "style": "classic",
    "blur_size": 21,
    "contrast": 256.0
  }
}
```

**Python 直接调用：**
```python
from undoom_sketch_mcp.server import convert_image_to_sketch

result = convert_image_to_sketch(
    image_path="D:/photos/portrait.jpg",
    style="classic",
    blur_size=21,
    contrast=256.0
)
print(result)
```

#### 2. batch_convert_images - 批量图片转换

```python
from undoom_sketch_mcp.server import batch_convert_images

result = batch_convert_images(
    folder_path="D:/photos/",
    style="detailed",
    blur_size=21,
    contrast=256.0
)
print(result)
```

#### 3. get_image_info - 获取图片信息

```python
from undoom_sketch_mcp.server import get_image_info

info = get_image_info("D:/photos/image.jpg")
print(info)
```

### 素描风格说明

- **classic**：经典素描风格，平衡的线条和对比度
- **detailed**：详细素描风格，更清晰的线条和细节
- **soft**：柔和素描风格，更柔和的效果，适合风景图

### 参数说明

- `image_path`：图片文件的完整路径（必需）
- `blur_size`：高斯模糊核大小（3-101，必须为奇数，默认21）
- `contrast`：对比度参数（50-500，默认256.0）
- `style`：素描风格（classic/detailed/soft，默认classic）

### 参数建议

- **大图片**（>200万像素）：blur_size=31-51，contrast=200-300
- **中等图片**（50万-200万像素）：blur_size=21-31，contrast=256
- **小图片**（<50万像素）：blur_size=11-21，contrast=300-400

## 输出文件

转换后的素描图片会保存在原图片相同目录下，文件名格式为：
```
Sketch_{style}_{原文件名}.jpg
```

例如：`Sketch_classic_photo.jpg`

## 支持的图片格式

- JPG / JPEG
- PNG
- BMP
- GIF
- TIFF
- WEBP

## 技术实现

本项目使用以下技术：

- **OpenCV**：图像处理和计算机视觉
- **NumPy**：数值计算
- **MCP (Model Context Protocol)**：与AI模型的通信协议
- **FastMCP**：快速MCP服务器实现

## 核心算法

素描效果通过以下步骤实现：
1. 将彩色图片转换为灰度图
2. 创建反转的灰度图
3. 对反转图像应用高斯模糊
4. 使用颜色减淡混合模式生成素描效果
5. 根据风格进行后处理优化

## 注意事项

- 确保图片文件存在且可读
- 处理大图片时可能需要较长时间
- 建议在处理前备份原图片
- 支持中文路径和文件名

## 许可证

本项目采用开源许可证，具体请查看 LICENSE 文件。

## 📁 项目结构

```
undoom-sketch-mcp/
├── undoom_sketch_mcp/          # 主要源码目录
│   ├── __init__.py            # 包初始化文件
│   ├── __main__.py            # 命令行入口
│   └── server.py              # MCP 服务器实现
├── pyproject.toml             # 项目配置文件
├── README.md                  # 项目说明文档
├── LICENSE                    # MIT 许可证
├── MCP使用说明.txt            # 中文详细使用说明
├── mcp_config.json            # MCP 配置示例
└── simple_sketch_example.py   # 简单使用示例
```

## 🎯 实际应用示例

### 处理单张图片

```python
# 经典风格素描
result = convert_image_to_sketch(
    "D:/photos/portrait.jpg",
    style="classic"
)

# 细节风格，适合风景照
result = convert_image_to_sketch(
    "D:/photos/landscape.jpg",
    style="detailed",
    blur_size=15,
    contrast=300.0
)

# 柔和风格，适合人像
result = convert_image_to_sketch(
    "D:/photos/selfie.jpg",
    style="soft",
    blur_size=25,
    contrast=200.0
)
```

### 批量处理文件夹

```python
# 批量转换所有图片为经典风格
batch_convert_images(
    "D:/vacation_photos/",
    style="classic"
)

# 批量转换为细节风格，自定义参数
batch_convert_images(
    "D:/artwork/",
    style="detailed",
    blur_size=31,
    contrast=280.0
)
```

## 🔧 故障排除

### 常见问题

**Q: 安装时提示找不到包？**
A: 使用国内镜像源：
```bash
uvx --index-url https://pypi.tuna.tsinghua.edu.cn/simple undoom-sketch-mcp
```

**Q: 图片处理失败？**
A: 检查以下几点：
- 图片路径是否正确
- 图片格式是否支持
- 文件是否有读取权限
- 输出目录是否有写入权限

**Q: 处理大图片很慢？**
A: 建议：
- 增大 blur_size 参数（如 31-51）
- 降低图片分辨率
- 使用 "soft" 风格处理更快

**Q: MCP 连接失败？**
A: 确认：
- 配置文件格式正确
- 服务器正常启动
- 网络连接正常

## 📊 性能参考

| 图片尺寸 | 处理时间 | 推荐参数 |
|---------|---------|----------|
| < 1MP | 1-3秒 | blur_size=11-21 |
| 1-5MP | 3-10秒 | blur_size=21-31 |
| 5-10MP | 10-30秒 | blur_size=31-41 |
| > 10MP | 30秒+ | blur_size=41-51 |

## 🤝 贡献指南

我们欢迎各种形式的贡献！

### 如何贡献

1. Fork 这个仓库
2. 创建你的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交你的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开一个 Pull Request

### 报告问题

如果你发现了 bug 或有功能建议，请在 [GitHub Issues](https://github.com/kk520879/undoom-sketch-mcp/issues) 中提交。

### 开发环境设置

```bash
# 克隆仓库
git clone https://github.com/kk520879/undoom-sketch-mcp.git
cd undoom-sketch-mcp

# 安装开发依赖
uv sync --dev

# 运行测试
python -m pytest
```

## 📄 许可证

本项目采用 [MIT 许可证](LICENSE)。

## 🙏 致谢

- [OpenCV](https://opencv.org/) - 强大的计算机视觉库
- [MCP](https://modelcontextprotocol.io/) - 模型上下文协议
- [FastMCP](https://github.com/jlowin/fastmcp) - 快速 MCP 实现

---

**如果这个项目对你有帮助，请给它一个 ⭐ Star！**