Content
# Tool List
> Automatically identify and mask sensitive information in images, Word documents, and PDFs: names, phone numbers, ID numbers, addresses, emails, and bank card numbers. Generate a desensitized copy, leaving the original file unchanged.
## 🚀 One-Click Installation (Single Command)
```bash
bash setup.sh
```
**This script will handle everything automatically:**
1. 🔍 Detect the operating system (macOS / Ubuntu / Debian / CentOS / Fedora / Arch / Windows)
2. 📦 Install Tesseract OCR + Chinese language pack
3. 📄 Install LibreOffice (for .doc → .docx conversion, optional)
4. 🐍 Install Python packages and all dependencies
5. ✅ Verify the installation is successful
You can start using it right away, **no manual processing required**.
> If you prefer not to use the script: `pip install file-desensitizer` (but you'll still need to manually install Tesseract for image OCR).
## 🤖 AI IDE Automatic Check
MCP Server provides two tools to help AI complete everything for you:
| MCP Tool | Function |
|----------|------|
| `check_environment` | Automatically check the environment and list missing dependencies and installation commands |
| `auto_setup` | One-click automatic installation of missing dependencies (automatically detects the system) |
In the conversation, say "check environment" or "help me install," and AI will handle it automatically.
## 📋 Environment Requirements (Reference)
| Dependency | Version Requirement | Purpose | Required |
|------|---------|------|:------:|
| Python | >= 3.10 | Runtime environment | ✅ Required |
| Tesseract OCR | Any version | Image text recognition | ⚠️ Only required for image desensitization |
| Tesseract Chinese package | chi_sim | Chinese OCR | ⚠️ Only required for Chinese image desensitization |
| LibreOffice | Any version | .doc to .docx conversion | ❌ Only required for processing old .doc files |
## 📖 Manual Installation (Reference)
> ⚠️ We recommend using the `bash setup.sh` command above. The following are manual installation commands for reference.
### System Dependencies
<details>
<summary><b>macOS</b></summary>
```bash
# Tesseract OCR + Chinese and English language packs
brew install tesseract tesseract-lang
# Optional: old .doc conversion
brew install --cask libreoffice
```
</details>
<details>
<summary><b>Ubuntu / Debian</b></summary>
```bash
# Tesseract OCR + Chinese and English language packs
sudo apt-get update
sudo apt-get install -y tesseract-ocr tesseract-ocr-chi-sim tesseract-ocr-eng
# Optional: old .doc conversion
sudo apt-get install -y libreoffice-writer
```
</details>
<details>
<summary><b>CentOS / RHEL / Fedora</b></summary>
```bash
# Tesseract OCR + Chinese and English language packs
sudo dnf install -y tesseract tesseract-langpack-chi-sim tesseract-langpack-eng
# Optional: old .doc conversion
sudo dnf install -y libreoffice-writer
```
</details>
<details>
<summary><b>Windows</b></summary>
1. Download the Tesseract installation package: https://github.com/UB-Mannheim/tesseract/wiki
2. Select the **Chinese (Simplified)** language pack during installation
3. Add the installation directory (e.g., `C:\Program Files\Tesseract-OCR`) to the system PATH
4. Verify: `tesseract --list-langs`
Optional: install LibreOffice for .doc conversion
</details>
<details>
<summary><b>Arch Linux</b></summary>
```bash
# Tesseract OCR + Chinese and English language packs
sudo pacman -S tesseract tesseract-data-chi_sim tesseract-data-eng
# Optional: old .doc conversion
sudo pacman -S libreoffice-fresh
```
</details>
**Verify Tesseract installation:**
```bash
tesseract --list-langs | grep chi_sim
# Should output: chi_sim
```
### Step 2: Install Python Packages
```bash
pip install file-desensitizer
```
This will automatically install all Python dependencies:
- `pillow>=10.0` — Image processing
- `pytesseract>=0.3.10` — OCR interface
- `PyMuPDF>=1.23.0` — PDF parsing
- `python-docx>=1.0.0` — Word document read/write
- `mcp>=1.0.0` — MCP protocol support
## 📖 Three Usage Methods
### 🎯 Method 1: AI IDE One-Click Usage (MCP)
Configure MCP in AI IDEs like Trae / Cursor / CodeBuddy, then directly say "desensitize this file" in the conversation.
**MCP configuration:**
```json
{
"mcpServers": {
"file-desensitizer": {
"command": "python",
"args": ["-m", "file_desensitizer.server"]
}
}
}
```
**MCP-provided tools:**
| Tool Name | Function | Required Parameters | Optional Parameters |
|--------|------|---------|---------|
| `desensitize_file` | Desensitize a single file | `file_path` | `output_dir`, `method`, `pdf_mode` |
| `desensitize_text` | Desensitize pure text content | `text` | — |
| `desensitize_batch` | Batch desensitize multiple files | `file_paths` | `output_dir`, `method` |
### ⌨️ Method 2: Command Line
```bash
# Single file
file-desensitizer contract.pdf
# Batch processing
file-desensitizer file1.pdf file2.jpg file3.docx
# Specify output directory
file-desensitizer document.docx --output-dir ./output
# Image masking method: black (default) / blur / pixelate
file-desensitizer photo.jpg --method blur
# PDF mode: auto (default) / text (text replacement) / image (image masking)
file-desensitizer scanned.pdf --pdf-mode image
```
### 🐍 Method 3: Python API
```python
from file_desensitizer import process_file, process_files, TextDesensitizer
# Desensitize a single file
result = process_file("contract.pdf", output_dir="./output")
print(result["output_path"]) # Desensitized file path
print(result["records"]) # Desensitization record list
# Desensitize pure text
text, records = TextDesensitizer.desensitize_text("张三 13812345678 北京市朝阳区建国路88号")
# text = "张* 138****5678 北京市朝阳区****"
# Batch desensitization
result = process_files(["a.pdf", "b.docx", "c.jpg"], output_dir="./output")
for r in result["results"]:
print(f"{r['input_path']} → {r['output_path']}")
```
## 🔒 Desensitization Rules
| Type | Rule | Example |
|------|------|------|
| 👤 Name | Keep surname, replace name with * | 张三丰 → 张** |
| 📱 Phone Number | Keep first 3 and last 4 digits | 13812345678 → 138****5678 |
| 🆔 ID Number | Keep first 6 and last 4 digits | 110101199001011234 → 110101********1234 |
| 🏠 Address | Keep province and city | 北京市朝阳区建国路88号 → 北京市朝阳区**** |
| 📧 Email | Keep first character and domain | lisi@example.com → l\*\*\*@example.com |
| 💳 Bank Card Number | Keep last 4 digits | 622202...0123 → \*\*\*\*0123 |
## 📁 Supported File Types
| Type | Extension | Processing Method |
|------|--------|---------|
| 🖼️ Image | .png .jpg .jpeg .bmp .tiff .webp | OCR recognition → Text desensitization → Black block / blur / pixelation masking |
| 📝 Word | .docx | Directly modify document text, mark desensitized content in red |
| 📄 PDF | .pdf | Text search and replacement / Render as image + OCR masking |
## 📂 Project Structure
```
file-desensitizer/
├── SKILL.md ← CodeBuddy Skill configuration
├── README.md ← This file
├── pyproject.toml ← pip package configuration
├── scripts/ ← Independent scripts (directly called by CodeBuddy Skill)
│ ├── main.py ← CLI entry
│ ├── desensitizer.py ← Core desensitization engine
│ ├── image_processor.py ← Image processor
│ ├── docx_processor.py ← Word processor
│ └── pdf_processor.py ← PDF processor
└── src/file_desensitizer/ ← pip package source code
├── __init__.py ← Package entry
├── core.py ← Core desensitization engine
├── main.py ← CLI + process_file/process_files
├── server.py ← MCP Server
├── image_processor.py
├── docx_processor.py
└── pdf_processor.py
```
## ⚠️ Precautions
1. **Original file will not be modified** — All operations are performed on a copy
2. **OCR accuracy** — Image desensitization effect depends on OCR accuracy, limited by low-resolution screenshots and handwritten Chinese characters
3. **Scanned PDF** — Recommended to use `--pdf-mode image` mode
4. **Word format** — Only supports `.docx`, old `.doc` needs to be converted using LibreOffice/WPS
5. **Desensitization is irreversible** — Desensitized file cannot be restored, please ensure the original file is properly saved
## 📄 License
MIT
