83 lines
4.1 KiB
Markdown
83 lines
4.1 KiB
Markdown
# MooseCP 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), MooseCP provides a hierarchical workflow: **List $\rightarrow$ Scan $\rightarrow$ Preview $\rightarrow$ Inspect**.
|
|
|
|
## ⚠️ AI SLOP DISCLAIMER
|
|
This entire project was vibe-coded by an AI. It is 100% slop code. Use it at your own risk.
|
|
|
|
## 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.
|
|
|
|
### 🌐 `browse_wikipedia`
|
|
Allows the model to browse Wikipedia using its API.
|
|
* **Best for**: Quickly retrieving summaries, structural maps (ToC), or specific section content from Wikipedia without dumping the entire page.
|
|
* **Workflow**: Use `mode='summary'` (default) to get an overview and a Table of Contents. Use `mode='section'` with a linear index from the ToC to dive into specific details.
|
|
* **Features**: Returns raw Wikitext to save tokens, handles redirects, and automatically falls back to a search result list if a page is not found.
|
|
|
|
---
|
|
|
|
## 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`:
|
|
|
|
### Server & Logging
|
|
- **`HOST` / `PORT`**: The network address and port the server binds to.
|
|
- **`LOG_LEVEL`**: Logging verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`).
|
|
- **`LOG_FILE`**: Path to the server log file.
|
|
- **`USER_AGENT`**: The User-Agent string used for API requests (e.g., Wikipedia). Use a browser-like string to avoid 403 Forbidden errors.
|
|
|
|
### Model & Token Tuning
|
|
- **`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.
|
|
- **`CONTACT_SHEET_THUMB_SIZE`**: The pixel size of thumbnails in the contact sheet.
|
|
|
|
### Image & Font Settings
|
|
- **`IMAGE_QUALITY`**: Adjust JPEG compression (1-100).
|
|
- **`SYSTEM_FONT_NAMES`**: A list of font names Pillow should attempt to find in the system path.
|
|
- **`FALLBACK_FONT_PATHS`**: Absolute paths to `.ttf` files used if no system fonts are found.
|