64 lines
3.2 KiB
Markdown
64 lines
3.2 KiB
Markdown
# MattCP Image Server
|
|
|
|
A Model Context Protocol (MCP) server designed to provide LLMs with efficient, token-optimized visual access to image directories. Instead of dumping full-resolution images (which waste tokens and cause context overflow), MattCP provides a hierarchical workflow: **List $\rightarrow$ Scan $\rightarrow$ Preview $\rightarrow$ Inspect**.
|
|
|
|
## ⚠️ AI SLOP DISCLAIMER
|
|
This server is designed to facilitate the interaction between AI models and image datasets. While it provides tools for "previewing" and "inspecting" images, remember that AI models can still hallucinate visual details, especially when working with low-resolution previews. **Always verify critical visual information with the `read_image` tool (full resolution) before drawing final conclusions.**
|
|
|
|
## Tools Overview
|
|
|
|
### 📁 `list_directory`
|
|
Provides a simplified file-browser view of a directory.
|
|
* **Best for**: Getting a sense of the files present and their basic metadata (size, date).
|
|
* **Features**: Pagination and sorting by name, size, or modification date.
|
|
|
|
### 🖼️ `contact_sheet`
|
|
Generates a high-density grid of thumbnails.
|
|
* **Best for**: Quickly scanning hundreds of images to find a specific one or get a general "vibe" of a folder.
|
|
* **Note**: This tool is paginated. You must iterate through pages to see all images in a folder.
|
|
* **Workflow**: Use the indices shown on the contact sheet to call `preview_image`.
|
|
|
|
### 🔍 `preview_image`
|
|
Provides medium-detail previews optimized for the model's token budget.
|
|
* **Best for**: Comparing a few candidates, inspecting specific details, or selecting a "favorite" image.
|
|
* **Efficiency**: Automatically calculates dimensions to fit the model's patch size (e.g., 48px patches for Gemma 4), ensuring maximum detail without wasting tokens on padding.
|
|
* **Workflow**: Pass indices from the `contact_sheet` or a direct file path.
|
|
|
|
### 📖 `read_png_metadata`
|
|
Extracts AI generation parameters from PNG files.
|
|
* **Best for**: Retrieving prompts, seeds, and model hashes from AI-generated images.
|
|
|
|
### 📸 `read_image`
|
|
Returns the full-resolution image.
|
|
* **Best for**: Final confirmation or deep visual analysis where every pixel counts.
|
|
|
|
---
|
|
|
|
## Installation & Requirements
|
|
|
|
### Dependencies
|
|
This server requires Python 3.10+ and the following packages:
|
|
* `uvicorn`: ASGI server for the SSE transport.
|
|
* `starlette`: Lightweight ASGI framework.
|
|
* `Pillow`: Image processing and thumbnail generation.
|
|
|
|
```bash
|
|
pip install uvicorn starlette Pillow
|
|
```
|
|
|
|
### Setup
|
|
1. Clone this repository to your server.
|
|
2. (Optional) Edit `config.py` to adjust the server port, log level, or token budgets if you are using a model other than Gemma 4.
|
|
3. Run the server:
|
|
```bash
|
|
python main.py
|
|
```
|
|
|
|
## Configuration (`config.py`)
|
|
|
|
You can tune the server's behavior in `config.py`:
|
|
- **`PATCH_SIZE`**: Set this to `(clip.vision.patch_size * n_merge)` for your specific model to ensure token-perfect resizing.
|
|
- **`PREVIEW_TOKEN_BUDGET`**: Controls how many tokens the `preview_image` tool aims for (default: 70).
|
|
- **`CONTACT_SHEET_COLS/ROWS`**: Adjust the grid size to fit within your model's maximum context window.
|
|
- **`IMAGE_QUALITY`**: Adjust JPEG compression (1-100).
|