Metadata-Version: 2.4
Name: mcp-image-reader
Version: 0.1.0
Summary: MCP server for reading and analyzing images with OCR and AI vision capabilities
Author-email: MCP Image Reader Contributors <mcp-image-reader@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/thanhma/mcp-image-reader
Project-URL: Repository, https://github.com/thanhma/mcp-image-reader.git
Project-URL: Issues, https://github.com/thanhma/mcp-image-reader/issues
Project-URL: Documentation, https://github.com/thanhma/mcp-image-reader#readme
Keywords: mcp,ocr,image,vision,ai,tesseract,server
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: pytesseract>=0.3.10
Requires-Dist: opencv-python>=4.8.0
Requires-Dist: numpy<3.0.0,>=1.24.0
Requires-Dist: pandas>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# MCP Image Reader Server

[![PyPI version](https://badge.fury.io/py/mcp-image-reader.svg)](https://badge.fury.io/py/mcp-image-reader)
[![Python Support](https://img.shields.io/pypi/pyversions/mcp-image-reader.svg)](https://pypi.org/project/mcp-image-reader/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub](https://img.shields.io/github/stars/thanhma/mcp-image-reader?style=social)](https://github.com/thanhma/mcp-image-reader)

MCP server cung cấp các công cụ để đọc và phân tích nội dung từ ảnh sử dụng OCR và AI vision.

## 🚀 Cài đặt nhanh với uvx

```bash
# Cài đặt và chạy trực tiếp
uvx mcp-image-reader

# Hoặc cài đặt global
pip install mcp-image-reader
```

## ✨ Tính năng

- **🔤 Đọc text từ ảnh**: Sử dụng Tesseract OCR để trích xuất text từ các định dạng ảnh phổ biến
- **📊 Phân tích bảng**: Phát hiện và trích xuất dữ liệu từ bảng trong ảnh
- **🖼️ Mô tả ảnh**: Phân tích và mô tả nội dung tổng quát của ảnh
- **🎯 Phát hiện đối tượng**: Nhận diện các đối tượng và thành phần trong ảnh
- **⚡ Xử lý ảnh**: Cải thiện chất lượng ảnh trước khi phân tích
- **🌍 Đa ngôn ngữ**: Hỗ trợ tiếng Việt, tiếng Anh và nhiều ngôn ngữ khác

## 📋 Yêu cầu hệ thống

### Tesseract OCR

**macOS:**
```bash
brew install tesseract tesseract-lang
```

**Ubuntu/Debian:**
```bash
sudo apt-get install tesseract-ocr tesseract-ocr-vie
```

**Windows:**
Tải từ: https://github.com/UB-Mannheim/tesseract/wiki

## 🔧 Cấu hình MCP Client

### Claude Desktop

Thêm vào `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "image-reader": {
      "command": "uvx",
      "args": ["mcp-image-reader"]
    }
  }
}
```

### Cline (VS Code)

```json
{
  "cline.mcpServers": {
    "image-reader": {
      "command": "uvx", 
      "args": ["mcp-image-reader"]
    }
  }
}
```

## 🛠️ Các công cụ có sẵn

| Tool | Mô tả | Input | Output |
|------|-------|-------|--------|
| `read_image_text` | Đọc text từ ảnh | image_path, language, preprocess | Text + confidence scores |
| `analyze_image_table` | Phân tích bảng | image_path, output_format | Structured table data |
| `describe_image` | Mô tả nội dung ảnh | image_path, include_text, include_tables | Comprehensive description |
| `detect_objects` | Phát hiện đối tượng | image_path, min_area | Object list with properties |
| `preprocess_image` | Xử lý ảnh | image_path, output_path, options | Processed image |
| `get_image_info` | Thông tin ảnh | image_path | File info + dimensions |

## 💡 Ví dụ sử dụng

### Đọc text từ ảnh
```
Hãy đọc text từ ảnh này: /path/to/document.jpg
```

### Phân tích bảng
```
Trích xuất dữ liệu từ bảng trong ảnh: /path/to/table.png
```

### Mô tả ảnh
```
Mô tả nội dung của ảnh này: /path/to/image.jpg
```

## 🎨 Định dạng ảnh được hỗ trợ

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

## 🌍 Ngôn ngữ OCR được hỗ trợ

- `eng` - Tiếng Anh
- `vie` - Tiếng Việt
- `vie+eng` - Kết hợp (khuyến nghị cho văn bản hỗn hợp)
- Các ngôn ngữ khác được Tesseract hỗ trợ

## 🔍 Use Cases

- **📄 Xử lý tài liệu**: Scan tài liệu giấy thành text, trích xuất thông tin từ hóa đơn
- **📊 Phân tích dữ liệu**: Đọc bảng từ screenshot, trích xuất dữ liệu từ biểu đồ  
- **🎓 Hỗ trợ giáo dục**: Đọc bài tập từ ảnh, phân tích sơ đồ
- **♿ Accessibility**: Mô tả ảnh cho người khiếm thị, chuyển đổi nội dung visual

## 🚀 Development

### Cài đặt từ source

```bash
git clone https://github.com/thanhma/mcp-image-reader.git
cd mcp-image-reader
pip install -e ".[dev]"
```

### Chạy tests

```bash
python test_server.py
python demo.py
```

## 📚 Tài liệu

- [📖 Quick Start Guide](QUICKSTART.md)
- [🔧 Installation Guide](INSTALLATION.md) 
- [💡 Examples](examples.md)
- [📋 Technical Summary](SUMMARY.md)

## 🤝 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/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📄 License

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

## 🙏 Acknowledgments

- [Tesseract OCR](https://github.com/tesseract-ocr/tesseract) for OCR capabilities
- [OpenCV](https://opencv.org/) for image processing
- [MCP](https://modelcontextprotocol.io/) for the protocol specification

## 📞 Support

- 🐛 [Report Issues](https://github.com/thanhma/mcp-image-reader/issues)
- 💬 [Discussions](https://github.com/thanhma/mcp-image-reader/discussions)
- 📧 [Email Support](mailto:thanhma@example.com)
