Content
# Image Server MCP
MCP (Model Context Protocol) service, used to connect external AI clients with image generation backend services.
## Features
- **Text-to-Image**: Generate images using Burgeon and Agnes API
- **Image-to-Image**: Support uploading images for style transfer, image editing, and image fusion
## Configuration Instructions
### 1. Get the Project Code
Download the project from the Git repository:
```bash
git clone https://github.com/xiaomile/topboth-gen.git
```
### 2. Check the Environment
Ensure that the uv package manager is installed on the server:
```bash
uv --version
```
If not installed, please contact the administrator or run the following command to install:
```bash
irm https://astral.sh/uv/install.ps1 | iex
```
### 3. Install Dependencies
Run the following commands in the mcp_server directory:
```bash
cd topboth-gen
uv init
uv add mcp httpx python-dotenv cryptography
```
### 4. Get MCP API Key
**Please contact the administrator or obtain the MCP_API_KEY from the system**, which is uniformly generated and managed by the server.
## Trae Configuration
Configure the MCP server in Trae:
```json
{
"mcpServers": {
"topboth-gen": {
"command": "uv",
"args": [
"run",
"mcp_server.py"
],
"cwd": "your topboth-gen directory",
"env": {
"IMAGE_SERVER_URL": "http://aiphoto.topboth.com",
"MCP_API_KEY": "your_mcp_api_key"
}
}
}
}
```
## Qoder Configuration
Due to a bug in qoder, the `cwd` parameter will be ignored during rewriting, so it is necessary to explicitly specify the work directory.
Configure the MCP server in Qoder:
```json
{
"mcpServers": {
"topboth-gen": {
"command": "uv",
"args": [
"run",
"--directory",
"your topboth-gen directory",
"mcp_server.py"
],
"env": {
"IMAGE_SERVER_URL": "http://aiphoto.topboth.com",
"MCP_API_KEY": "your_mcp_api_key"
}
}
}
}
```
### Parameter Description
| Parameter | Description |
|------|------|
| `command` | Command, usually `uv` |
| `args` | Argument array, specifying the running method and script path |
| `IMAGE_SERVER_URL` | Image generation backend server address (provided by the administrator or obtained from the system) |
| `MCP_API_KEY` | Encrypted API Key (provided by the administrator or obtained from the system) |
## Usage
### Text-to-Image
Enter in the AI dialog box:
```
Please generate a landscape oil painting
```
Or specify parameters explicitly:
```
Call burgeon_generate_image tool, parameters:
- Prompt: Generate a cyberpunk-style city night scene
- Aspect ratio: 16:9
- Size: 1K
```
### Image-to-Image
1. Upload an image in the dialog box (drag or paste)
2. Enter the image-to-image instruction:
```
Please convert this image (https://example.com/image.png) to watercolor style
```
Or:
```
Call agnes_generate_image tool for image-to-image:
- Prompt: Convert the image to Van Gogh-style oil painting
- Mode: image-to-image
- Image: ['file:///path/to/image.png']
```
## Supported Image Formats
The MCP server supports the following image input formats:
1. **File path**: `file:///path/to/image.jpg` or `/path/to/image.png`
2. **URL**: Image URL, e.g., `https://example.com/image.png`
## Project Structure
```
topboth-gen/
├── mcp_server.py # MCP server main program
├── pyproject.toml # Project dependency configuration
├── README.md # Project documentation
└── uv.lock # Dependency lock file
```
## Frequently Asked Questions
### Q: Unable to read uploaded images
Check the following points:
1. Is the image path correct?
2. Does the MCP server have permission to read the image file?
3. Is the image format supported (PNG, JPEG, WebP)?
### Q: MCP server startup failure
Check:
1. Is uv installed?
2. Are dependencies installed (run `uv sync`)?
3. Are `IMAGE_SERVER_URL` and `MCP_API_KEY` configured correctly?
### Q: Generated images cannot be saved
Ensure:
1. `IMAGE_SERVER_URL` is configured correctly
2. The backend server is running
3. `MCP_API_KEY` is valid
## Precautions
1. MCP_API_KEY contains user information, please do not leak
2. It is recommended to regularly contact the administrator to replace MCP_API_KEY
4. For large images, it is recommended to use smaller sizes to improve generation speed
## License
MIT License
