# Directory Structure
```
├── .github
│ └── workflows
│ └── release.yml
├── .gitignore
├── Cargo.lock
├── Cargo.toml
├── docs
│ ├── config.png
│ ├── Snipaste_2025-04-26_15-18-02.png
│ └── Snipaste_2025-04-26_15-18-15.png
├── README.md
└── src
└── main.rs
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | /target
2 |
```
--------------------------------------------------------------------------------
/Cargo.toml:
--------------------------------------------------------------------------------
```toml
1 | [package]
2 | name = "imagen3-mcp"
3 | version = "0.1.0"
4 | edition = "2024"
5 |
6 | [dependencies]
7 | rmcp = { version = "0.1", features = ["server", "transport-io"] }
8 | tokio = { version = "1.44.2", features = ["macros", "rt-multi-thread", "fs", "io-util"] }
9 | tokio-util = "0.7.15"
10 | serde = { version = "1.0", features = ["derive"] }
11 | serde_json = "1.0"
12 | warp = "0.3"
13 | image = "0.24.8"
14 | directories = "5.0.1"
15 | reqwest = { version = "0.11", features = ["json"] }
16 | base64 = "0.21"
17 | chrono = "0.4"
18 | nanoid = "0.4.0"
19 | tracing = "0.1"
20 | tracing-subscriber = { version = "0.3", features = ["env-filter", "fmt"] }
21 | tracing-appender = "0.2"
22 |
```
--------------------------------------------------------------------------------
/.github/workflows/release.yml:
--------------------------------------------------------------------------------
```yaml
1 | name: Release
2 |
3 | on:
4 | push:
5 | tags:
6 | - 'v*'
7 |
8 | env:
9 | CARGO_TERM_COLOR: always
10 |
11 | jobs:
12 | build-and-release:
13 | strategy:
14 | fail-fast: false
15 | matrix:
16 | include:
17 | - platform: 'macos-latest'
18 | target: 'aarch64-apple-darwin'
19 | artifact_name: 'imagen3-mcp-aarch64-apple-darwin'
20 | - platform: 'macos-latest'
21 | target: 'x86_64-apple-darwin'
22 | artifact_name: 'imagen3-mcp-x86_64-apple-darwin'
23 | - platform: 'ubuntu-22.04'
24 | target: 'x86_64-unknown-linux-gnu'
25 | artifact_name: 'imagen3-mcp-x86_64-linux'
26 | - platform: 'windows-latest'
27 | target: 'x86_64-pc-windows-msvc'
28 | artifact_name: 'imagen3-mcp-x86_64-windows'
29 |
30 | runs-on: ${{ matrix.platform }}
31 |
32 | steps:
33 | - uses: actions/checkout@v4
34 |
35 | - name: Install Rust
36 | uses: actions-rs/toolchain@v1
37 | with:
38 | toolchain: stable
39 | profile: minimal
40 | override: true
41 | target: ${{ matrix.target }}
42 |
43 | - name: Build
44 | run: cargo build --release --target ${{ matrix.target || 'x86_64-unknown-linux-gnu' }} --verbose
45 |
46 | - name: Create artifact directory
47 | run: mkdir -p artifacts
48 |
49 | - name: Package (Unix)
50 | if: runner.os != 'Windows'
51 | run: |
52 | cp target/${{ matrix.target || 'x86_64-unknown-linux-gnu' }}/release/imagen3-mcp artifacts/${{ matrix.artifact_name }}
53 | chmod +x artifacts/${{ matrix.artifact_name }}
54 |
55 | - name: Package (Windows)
56 | if: runner.os == 'Windows'
57 | run: copy target\${{ matrix.target || 'x86_64-pc-windows-msvc' }}\release\imagen3-mcp.exe artifacts\${{ matrix.artifact_name }}.exe
58 |
59 | - name: Upload artifacts
60 | uses: actions/upload-artifact@v4
61 | with:
62 | name: ${{ matrix.artifact_name }}
63 | path: artifacts/${{ matrix.artifact_name }}${{ runner.os == 'Windows' && '.exe' || '' }}
64 | if-no-files-found: error
65 |
66 | create-release:
67 | needs: build-and-release
68 | runs-on: ubuntu-latest
69 | steps:
70 | - name: Download all artifacts
71 | uses: actions/download-artifact@v4
72 | with:
73 | path: artifacts
74 |
75 | - name: Create Release
76 | id: create_release
77 | uses: actions/create-release@v1
78 | env:
79 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
80 | with:
81 | tag_name: ${{ github.ref_name }}
82 | release_name: Release ${{ github.ref_name }}
83 | draft: true
84 | prerelease: false
85 |
86 | - name: Upload Release Assets (macOS ARM)
87 | uses: actions/upload-release-asset@v1
88 | env:
89 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
90 | with:
91 | upload_url: ${{ steps.create_release.outputs.upload_url }}
92 | asset_path: artifacts/imagen3-mcp-aarch64-apple-darwin/imagen3-mcp-aarch64-apple-darwin
93 | asset_name: imagen3-mcp-aarch64-apple-darwin
94 | asset_content_type: application/octet-stream
95 |
96 | - name: Upload Release Assets (macOS Intel)
97 | uses: actions/upload-release-asset@v1
98 | env:
99 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
100 | with:
101 | upload_url: ${{ steps.create_release.outputs.upload_url }}
102 | asset_path: artifacts/imagen3-mcp-x86_64-apple-darwin/imagen3-mcp-x86_64-apple-darwin
103 | asset_name: imagen3-mcp-x86_64-apple-darwin
104 | asset_content_type: application/octet-stream
105 |
106 | - name: Upload Release Assets (Linux)
107 | uses: actions/upload-release-asset@v1
108 | env:
109 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
110 | with:
111 | upload_url: ${{ steps.create_release.outputs.upload_url }}
112 | asset_path: artifacts/imagen3-mcp-x86_64-linux/imagen3-mcp-x86_64-linux
113 | asset_name: imagen3-mcp-x86_64-linux
114 | asset_content_type: application/octet-stream
115 |
116 | - name: Upload Release Assets (Windows)
117 | uses: actions/upload-release-asset@v1
118 | env:
119 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
120 | with:
121 | upload_url: ${{ steps.create_release.outputs.upload_url }}
122 | asset_path: artifacts/imagen3-mcp-x86_64-windows/imagen3-mcp-x86_64-windows.exe
123 | asset_name: imagen3-mcp-x86_64-windows.exe
124 | asset_content_type: application/octet-stream
125 |
126 | - name: Publish Release
127 | uses: eregon/publish-release@v1
128 | env:
129 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
130 | with:
131 | release_id: ${{ steps.create_release.outputs.id }}
132 |
```
--------------------------------------------------------------------------------
/src/main.rs:
--------------------------------------------------------------------------------
```rust
1 | use base64::{self, Engine as _};
2 | use chrono;
3 | use directories::ProjectDirs;
4 | use nanoid;
5 | use reqwest;
6 | use rmcp::{
7 | ServerHandler, ServiceExt,
8 | model::{Implementation, ServerCapabilities, ServerInfo},
9 | schemars, tool,
10 | };
11 | use serde::{Deserialize, Serialize};
12 | use std::env;
13 | use std::fs;
14 | use std::net::SocketAddr;
15 | use std::path::PathBuf;
16 | use tracing::{error, info, instrument};
17 | use tracing_subscriber::{EnvFilter, fmt, prelude::*};
18 | use warp::Filter;
19 |
20 | #[derive(Debug, Clone)]
21 | struct ImageGenerationServer {
22 | resources_path: PathBuf,
23 | image_resource_server_addr: String,
24 | server_port: u16,
25 | }
26 |
27 | #[derive(Debug, Deserialize, schemars::JsonSchema)]
28 | struct ImagePrompt {
29 | #[schemars(
30 | description = "The prompt text for image generation. The prompt MUST be in English."
31 | )]
32 | prompt: String,
33 |
34 | // Supported values are "1:1", "3:4", "4:3", "9:16", and "16:9". The default is "1:1".
35 | #[schemars(
36 | description = "The aspect ratio of the image to generate. Supported values are \"1:1\", \"3:4\", \"4:3\", \"9:16\", and \"16:9\". The default is \"1:1\"."
37 | )]
38 | aspect_ratio: Option<String>,
39 | }
40 |
41 | // Request and response structures for the Gemini API
42 | #[derive(Debug, Serialize)]
43 | struct GeminiRequest {
44 | instances: Vec<GeminiInstance>,
45 | parameters: GeminiParameters,
46 | }
47 |
48 | #[derive(Debug, Serialize)]
49 | struct GeminiInstance {
50 | prompt: String,
51 | }
52 |
53 | #[derive(Debug, Serialize)]
54 | struct GeminiParameters {
55 | #[serde(rename = "sampleCount")]
56 | sample_count: i32,
57 | #[serde(rename = "aspectRatio")]
58 | aspect_ratio: Option<String>,
59 | }
60 |
61 | #[derive(Debug, Deserialize)]
62 | struct GeminiResponse {
63 | predictions: Option<Vec<GeminiPrediction>>,
64 | }
65 |
66 | #[derive(Debug, Deserialize)]
67 | struct GeminiPrediction {
68 | #[serde(rename = "mimeType")]
69 | mime_type: String,
70 | #[serde(rename = "bytesBase64Encoded")]
71 | bytes_base64_encoded: String,
72 | }
73 |
74 | // Function to generate an image using the Gemini API
75 | #[instrument(skip(resources_path), fields(prompt_length = prompt.len()))]
76 | async fn generate_image_from_gemini(
77 | prompt: &str,
78 | aspect_ratio: Option<&str>,
79 | resources_path: &PathBuf,
80 | ) -> Result<Vec<String>, Box<dyn std::error::Error>> {
81 | info!(?prompt, ?aspect_ratio, "Generating image from Gemini");
82 |
83 | // Get the API key from environment variables
84 | let api_key =
85 | env::var("GEMINI_API_KEY").map_err(|_| "GEMINI_API_KEY environment variable not set")?;
86 |
87 | // Create the request
88 | let request = GeminiRequest {
89 | instances: vec![GeminiInstance {
90 | prompt: prompt.to_string(),
91 | }],
92 | parameters: GeminiParameters {
93 | sample_count: 1, // Just generate one image
94 | aspect_ratio: aspect_ratio.map(|s| s.to_string()),
95 | },
96 | };
97 | info!(
98 | "Sending request to Gemini: {}",
99 | serde_json::to_string(&request)?
100 | );
101 |
102 | // Create URL with API key
103 | let base_url = env::var("BASE_URL")
104 | .unwrap_or_else(|_| "https://generativelanguage.googleapis.com".to_string());
105 | let url = format!(
106 | "{}/v1beta/models/imagen-3.0-generate-002:predict?key={}",
107 | base_url, api_key
108 | );
109 |
110 | // Make the request
111 | let client = reqwest::Client::new();
112 | let response_result = client.post(&url).json(&request).send().await;
113 |
114 | let response_text = match response_result {
115 | Ok(resp) => resp.text().await?,
116 | Err(e) => {
117 | error!("Failed to send request to Gemini: {}", e);
118 | return Err(e.into());
119 | }
120 | };
121 |
122 | let response: GeminiResponse = match serde_json::from_str(&response_text) {
123 | Ok(response) => response,
124 | Err(e) => {
125 | error!(
126 | response_body = %response_text,
127 | "Failed to parse Gemini response: {}",
128 | e
129 | );
130 | return Err(format!(
131 | "Failed to parse Gemini response: {}
132 | The response was: {}",
133 | e, response_text
134 | )
135 | .into());
136 | }
137 | };
138 |
139 | let predictions = response.predictions.unwrap_or_default();
140 |
141 | // Make sure we got at least one prediction
142 | if predictions.is_empty() {
143 | error!("No images were generated by Gemini. This might be due to safety filters.");
144 | return Err("No images were generated. This might be due to the image not passing Google's safety review.".into());
145 | }
146 |
147 | let mut filenames = Vec::new();
148 |
149 | // Get the first prediction
150 | for pred in predictions {
151 | // Generate a filename based on the prompt
152 | let timestamp = chrono::Local::now().format("%Y%m%d%H%M%S").to_string();
153 | let id = nanoid::nanoid!(10);
154 | let filename = format!("{}_{}.png", id, timestamp);
155 | let path = resources_path.join("images").join(&filename);
156 |
157 | // Decode the base64 image using updated API
158 | let image_data =
159 | match base64::engine::general_purpose::STANDARD.decode(&pred.bytes_base64_encoded) {
160 | Ok(data) => data,
161 | Err(e) => {
162 | error!("Failed to decode base64 image: {}", e);
163 | return Err(e.into());
164 | }
165 | };
166 |
167 | // Write the image to disk
168 | if let Err(e) = fs::write(&path, &image_data) {
169 | error!(file_path = %path.display(), "Failed to write image to disk: {}", e);
170 | return Err(e.into());
171 | }
172 | info!(file_path = %path.display(), "Successfully saved generated image.");
173 |
174 | filenames.push(filename);
175 | }
176 |
177 | Ok(filenames)
178 | }
179 |
180 | // Define the tool and its implementation
181 | #[tool(tool_box)]
182 | impl ImageGenerationServer {
183 | #[tool(
184 | description = "Generate an image based on a prompt. Returns an image URL that can be used in markdown format like  to display the image"
185 | )]
186 | // #[instrument(skip(self))] // Removed due to macro conflict
187 | async fn generate_image(&self, #[tool(aggr)] args: ImagePrompt) -> String {
188 | info!(?args, "Received image generation request"); // Log args explicitly
189 |
190 | // Generate the image using the Gemini API
191 |
192 | const SUPPORTED_ASPECT_RATIOS: [&str; 5] = ["1:1", "3:4", "4:3", "9:16", "16:9"];
193 | if let Some(aspect_ratio) = &args.aspect_ratio {
194 | if !SUPPORTED_ASPECT_RATIOS.contains(&aspect_ratio.as_str()) {
195 | let error_msg = format!(
196 | "Invalid aspect ratio: {}, supported values are: {}",
197 | aspect_ratio,
198 | SUPPORTED_ASPECT_RATIOS.join(", ")
199 | );
200 | error!("{}", error_msg);
201 | return error_msg;
202 | }
203 | }
204 |
205 | match generate_image_from_gemini(
206 | &args.prompt,
207 | args.aspect_ratio.as_deref(),
208 | &self.resources_path,
209 | )
210 | .await
211 | {
212 | Ok(filenames) => {
213 | // Return the URL to the generated image using the configured address and port
214 | let urls = filenames
215 | .iter()
216 | .map(|filename| {
217 | format!(
218 | "http://{}:{}/images/{}",
219 | self.image_resource_server_addr,
220 | self.server_port, // Use the configured port
221 | filename
222 | )
223 | })
224 | .collect::<Vec<String>>()
225 | .join("\n");
226 | info!(num_images = filenames.len(), "Image generation successful.");
227 | urls
228 | }
229 | Err(e) => {
230 | error!("Error generating image: {}", e);
231 | format!("Error generating image: {}", e)
232 | }
233 | }
234 | }
235 | }
236 |
237 | // Implement ServerHandler trait for our image generation server
238 | #[tool(tool_box)]
239 | impl ServerHandler for ImageGenerationServer {
240 | fn get_info(&self) -> ServerInfo {
241 | ServerInfo {
242 | server_info: Implementation {
243 | name: "imagen3-mcp".into(),
244 | version: "0.1.0".into(),
245 | },
246 | instructions: Some(r#"
247 | Use the generate_image tool to create images from text descriptions. The returned URL can be used in markdown format like  to display the image.
248 |
249 | Before generating an image, please read the <Imagen_prompt_guide> section to understand how to create effective prompts.
250 |
251 | <Imagen_prompt_guide>
252 | ## Prompt writing basics
253 | Description of the image to generate. Maximum prompt length is 480 tokens. A good prompt is descriptive and clear, and makes use of meaningful keywords and modifiers. Start by thinking of your subject, context, and style.
254 | Example Prompt: A sketch (style) of a modern apartment building (subject) surrounded by skyscrapers (context and background).
255 | 1. Subject: The first thing to think about with any prompt is the subject: the object, person, animal, or scenery you want an image of.
256 | 2. Context and background: Just as important is the background or context in which the subject will be placed. Try placing your subject in a variety of backgrounds. For example, a studio with a white background, outdoors, or indoor environments.
257 | 3. Style: Finally, add the style of image you want. Styles can be general (painting, photograph, sketches) or very specific (pastel painting, charcoal drawing, isometric 3D). You can also combine styles.
258 | After you write a first version of your prompt, refine your prompt by adding more details until you get to the image that you want. Iteration is important. Start by establishing your core idea, and then refine and expand upon that core idea until the generated image is close to your vision.
259 | Imagen 3 can transform your ideas into detailed images, whether your prompts are short or long and detailed. Refine your vision through iterative prompting, adding details until you achieve the perfect result.
260 | Example Prompt: close-up photo of a woman in her 20s, street photography, movie still, muted orange warm tones
261 | Example Prompt: captivating photo of a woman in her 20s utilizing a street photography style. The image should look like a movie still with muted orange warm tones.
262 | Additional advice for Imagen prompt writing:
263 | - Use descriptive language: Employ detailed adjectives and adverbs to paint a clear picture for Imagen 3.
264 | - Provide context: If necessary, include background information to aid the AI's understanding.
265 | - Reference specific artists or styles: If you have a particular aesthetic in mind, referencing specific artists or art movements can be helpful.
266 | - Use prompt engineering tools: Consider exploring prompt engineering tools or resources to help you refine your prompts and achieve optimal results.
267 | - Enhancing the facial details in your personal and group images: Specify facial details as a focus of the photo (for example, use the word "portrait" in the prompt).
268 | ## Generate text in images
269 | Imagen can add text into images, opening up more creative image generation possibilities. Use the following guidance to get the most out of this feature:
270 | - Iterate with confidence: You might have to regenerate images until you achieve the look you want. Imagen's text integration is still evolving, and sometimes multiple attempts yield the best results.
271 | - Keep it short: Limit text to 25 characters or less for optimal generation.
272 | - Multiple phrases: Experiment with two or three distinct phrases to provide additional information. Avoid exceeding three phrases for cleaner compositions.
273 | Example Prompt: A poster with the text "Summerland" in bold font as a title, underneath this text is the slogan "Summer never felt so good"
274 | - Guide Placement: While Imagen can attempt to position text as directed, expect occasional variations. This feature is continually improving.
275 | - Inspire font style: Specify a general font style to subtly influence Imagen's choices. Don't rely on precise font replication, but expect creative interpretations.
276 | - Font size: Specify a font size or a general indication of size (for example, small, medium, large) to influence the font size generation.
277 | ## Advanced prompt writing techniques
278 | Use the following examples to create more specific prompts based on attributes like photography descriptors, shapes and materials, historical art movements, and image quality modifiers.
279 | ### Photography
280 | - Prompt includes: "A photo of..."
281 | To use this style, start with using keywords that clearly tell Imagen that you're looking for a photograph. Start your prompts with "A photo of. . .". For example:
282 | Example Prompt: A photo of coffee beans in a kitchen on a wooden surface
283 | Example Prompt: A photo of a chocolate bar on a kitchen counter
284 | Example Prompt: A photo of a modern building with water in the background
285 | #### Photography modifiers
286 | In the following examples, you can see several photography-specific modifiers and parameters. You can combine multiple modifiers for more precise control.
287 | 1. Camera Proximity - Close up, taken from far away
288 | Example Prompt: A close-up photo of coffee beans
289 | Example Prompt: A zoomed out photo of a small bag of coffee beans in a messy kitchen
290 | 2. Camera Position - aerial, from below
291 | Example Prompt: aerial photo of urban city with skyscrapers
292 | Example Prompt: A photo of a forest canopy with blue skies from below
293 | 3. Lighting - natural, dramatic, warm, cold
294 | Example Prompt: studio photo of a modern arm chair, natural lighting
295 | Example Prompt: studio photo of a modern arm chair, dramatic lighting
296 | 4. Camera Settings - motion blur, soft focus, bokeh, portrait
297 | Example Prompt: photo of a city with skyscrapers from the inside of a car with motion blur
298 | Example Prompt: soft focus photograph of a bridge in an urban city at night
299 | 5. Lens types - 35mm, 50mm, fisheye, wide angle, macro
300 | Example Prompt: photo of a leaf, macro lens
301 | Example Prompt: street photography, new york city, fisheye lens
302 | 6. Film types - black and white, polaroid
303 | Example Prompt: a polaroid portrait of a dog wearing sunglasses
304 | Example Prompt: black and white photo of a dog wearing sunglasses
305 | ### Illustration and art
306 | - Prompt includes: "A painting of...", "A sketch of..."
307 | Art styles vary from monochrome styles like pencil sketches, to hyper-realistic digital art. For example, the following images use the same prompt with different styles:
308 | "An [art style or creation technique] of an angular sporty electric sedan with skyscrapers in the background"
309 | Example Prompt: A technical pencil drawing of an angular...
310 | Example Prompt: A charcoal drawing of an angular...
311 | Example Prompt: A color pencil drawing of an angular...
312 | Example Prompt: A pastel painting of an angular...
313 | Example Prompt: A digital art of an angular...
314 | Example Prompt: An art deco (poster) of an angular...
315 | #### Shapes and materials
316 | - Prompt includes: "...made of...", "...in the shape of..."
317 | One of the strengths of this technology is that you can create imagery that is otherwise difficult or impossible. For example, you can recreate your company logo in different materials and textures.
318 | Example Prompt: a duffle bag made of cheese
319 | Example Prompt: neon tubes in the shape of a bird
320 | Example Prompt: an armchair made of paper, studio photo, origami style
321 | #### Historical art references
322 | - Prompt includes: "...in the style of..."
323 | Certain styles have become iconic over the years. The following are some ideas of historical painting or art styles that you can try.
324 | "generate an image in the style of [art period or movement] : a wind farm"
325 | Example Prompt: generate an image in the style of an impressionist painting: a wind farm
326 | Example Prompt: generate an image in the style of a renaissance painting: a wind farm
327 | Example Prompt: generate an image in the style of pop art: a wind farm
328 | ### Image quality modifiers
329 | Certain keywords can let the model know that you're looking for a high-quality asset. Examples of quality modifiers include the following:
330 | - General Modifiers - high-quality, beautiful, stylized
331 | - Photos - 4K, HDR, Studio Photo
332 | - Art, Illustration - by a professional, detailed
333 | The following are a few examples of prompts without quality modifiers and the same prompt with quality modifiers.
334 | Example Prompt: (no quality modifiers): a photo of a corn stalk
335 | Example Prompt: (with quality modifiers): 4k HDR beautiful photo of a corn stalk taken by a professional photographer
336 | ### Aspect ratios
337 | Imagen 3 image generation lets you set five distinct image aspect ratios.
338 | 1. Square (1:1, default) - A standard square photo. Common uses for this aspect ratio include social media posts.
339 | 2. Fullscreen (4:3) - This aspect ratio is commonly used in media or film. It is also the dimensions of most old (non-widescreen) TVs and medium format cameras. It captures more of the scene horizontally (compared to 1:1), making it a preferred aspect ratio for photography.
340 | Example Prompt: close up of a musician's fingers playing the piano, black and white film, vintage (4:3 aspect ratio)
341 | Example Prompt: A professional studio photo of french fries for a high end restaurant, in the style of a food magazine (4:3 aspect ratio)
342 | 3. Portrait full screen (3:4) - This is the fullscreen aspect ratio rotated 90 degrees. This lets to capture more of the scene vertically compared to the 1:1 aspect ratio.
343 | Example Prompt: a woman hiking, close of her boots reflected in a puddle, large mountains in the background, in the style of an advertisement, dramatic angles (3:4 aspect ratio)
344 | Example Prompt: aerial shot of a river flowing up a mystical valley (3:4 aspect ratio)
345 | 4. Widescreen (16:9) - This ratio has replaced 4:3 and is now the most common aspect ratio for TVs, monitors, and mobile phone screens (landscape). Use this aspect ratio when you want to capture more of the background (for example, scenic landscapes).
346 | Example Prompt: a man wearing all white clothing sitting on the beach, close up, golden hour lighting (16:9 aspect ratio)
347 | 5. Portrait (9:16) - This ratio is widescreen but rotated. This a relatively new aspect ratio that has been popularized by short form video apps (for example, YouTube shorts). Use this for tall objects with strong vertical orientations such as buildings, trees, waterfalls, or other similar objects.
348 | Example Prompt: a digital render of a massive skyscraper, modern, grand, epic with a beautiful sunset in the background (9:16 aspect ratio)
349 | ### Photorealistic images
350 | Different versions of the image generation model might offer a mix of artistic and photorealistic output. Use the following wording in prompts to generate more photorealistic output, based on the subject you want to generate.
351 | Note: Take these keywords as general guidance when you try to create photorealistic images. They aren't required to achieve your goal.
352 | | Use case | Lens type | Focal lengths | Additional details |
353 | | --- | --- | --- | --- |
354 | | People (portraits) | Prime, zoom | 24-35mm | black and white film, Film noir, Depth of field, duotone (mention two colors) |
355 | | Food, insects, plants (objects, still life) | Macro | 60-105mm | High detail, precise focusing, controlled lighting |
356 | | Sports, wildlife (motion) | Telephoto zoom | 100-400mm | Fast shutter speed, Action or movement tracking |
357 | | Astronomical, landscape (wide-angle) | Wide-angle | 10-24mm | Long exposure times, sharp focus, long exposure, smooth water or clouds |
358 | #### Portraits
359 | | Use case | Lens type | Focal lengths | Additional details |
360 | | --- | --- | --- | --- |
361 | | People (portraits) | Prime, zoom | 24-35mm | black and white film, Film noir, Depth of field, duotone (mention two colors) |
362 | Using several keywords from the table, Imagen can generate the following portraits:
363 | Example Prompt: A woman, 35mm portrait, blue and grey duotones
364 | Example Prompt: A woman, 35mm portrait, film noir
365 | #### Objects:
366 | | Use case | Lens type | Focal lengths | Additional details |
367 | | --- | --- | --- | --- |
368 | | Food, insects, plants (objects, still life) | Macro | 60-105mm | High detail, precise focusing, controlled lighting |
369 | Using several keywords from the table, Imagen can generate the following object images:
370 | Example Prompt: leaf of a prayer plant, macro lens, 60mm
371 | Example Prompt: a plate of pasta, 100mm Macro lens
372 | #### Motion
373 | | Use case | Lens type | Focal lengths | Additional details |
374 | | --- | --- | --- | --- |
375 | | Sports, wildlife (motion) | Telephoto zoom | 100-400mm | Fast shutter speed, Action or movement tracking |
376 | Using several keywords from the table, Imagen can generate the following motion images:
377 | Example Prompt: a winning touchdown, fast shutter speed, movement tracking
378 | Example Prompt: A deer running in the forest, fast shutter speed, movement tracking
379 | #### Wide-angle
380 | | Use case | Lens type | Focal lengths | Additional details |
381 | | --- | --- | --- | --- |
382 | | Astronomical, landscape (wide-angle) | Wide-angle | 10-24mm | Long exposure times, sharp focus, long exposure, smooth water or clouds |
383 | Using several keywords from the table, Imagen can generate the following wide-angle images:
384 | Example Prompt: an expansive mountain range, landscape wide angle 10mm
385 | Example Prompt: a photo of the moon, astro photography, wide angle 10mm
386 | </Imagen_prompt_guide>
387 | "#.trim().into()),
388 | capabilities: ServerCapabilities::builder()
389 | .enable_tools()
390 | .build(),
391 | ..Default::default()
392 | }
393 | }
394 | }
395 |
396 | // Create resources directory if it doesn't exist using cross-platform approach
397 | async fn ensure_resources_dir() -> std::io::Result<PathBuf> {
398 | // Get application data directory in a cross-platform way
399 | let project_dirs = ProjectDirs::from("cn", "hamflx", "imagen3-mcp").ok_or_else(|| {
400 | std::io::Error::new(
401 | std::io::ErrorKind::NotFound,
402 | "Could not determine application data directory",
403 | )
404 | })?;
405 |
406 | // Use data_local_dir for Windows (AppData\Local), data_dir for macOS/Linux
407 | let base_dir = project_dirs.data_local_dir();
408 |
409 | // Create full path to resources directory
410 | let resources_path = base_dir.join("artifacts");
411 | let images_dir = resources_path.join("images");
412 |
413 | // Create directories if they don't exist
414 | if !resources_path.exists() {
415 | tokio::fs::create_dir_all(&resources_path).await?;
416 | info!(path = %resources_path.display(), "Created resources directory.");
417 | }
418 |
419 | if !images_dir.exists() {
420 | tokio::fs::create_dir(&images_dir).await?;
421 | info!(path = %images_dir.display(), "Created images directory.");
422 | }
423 |
424 | Ok(resources_path)
425 | }
426 |
427 | // Function to ensure the log directory exists
428 | async fn ensure_log_dir() -> std::io::Result<PathBuf> {
429 | let project_dirs = ProjectDirs::from("cn", "hamflx", "imagen3-mcp").ok_or_else(|| {
430 | std::io::Error::new(
431 | std::io::ErrorKind::NotFound,
432 | "Could not determine application data directory",
433 | )
434 | })?;
435 | let base_dir = project_dirs.data_local_dir();
436 | let log_dir = base_dir.join("logs");
437 |
438 | if !log_dir.exists() {
439 | tokio::fs::create_dir_all(&log_dir).await?;
440 | // Can't log here yet as tracing isn't initialized
441 | }
442 | Ok(log_dir)
443 | }
444 |
445 | // Handler to list images in the images directory
446 | async fn list_images(resources_path: PathBuf) -> Result<Vec<String>, std::io::Error> {
447 | let images_dir = resources_path.join("images");
448 | let mut images = Vec::new();
449 |
450 | let mut entries = tokio::fs::read_dir(images_dir).await?;
451 | while let Some(entry) = entries.next_entry().await? {
452 | let path = entry.path();
453 | if path.is_file() {
454 | if let Some(filename) = path.file_name() {
455 | if let Some(filename_str) = filename.to_str() {
456 | images.push(filename_str.to_string());
457 | }
458 | }
459 | }
460 | }
461 |
462 | Ok(images)
463 | }
464 |
465 | #[tokio::main]
466 | async fn main() -> Result<(), Box<dyn std::error::Error>> {
467 | // --- Tracing Setup ---
468 | let log_dir = ensure_log_dir()
469 | .await
470 | .expect("Failed to ensure log directory exists");
471 | let log_file_prefix = "imagen3-mcp.log";
472 | let file_appender = tracing_appender::rolling::daily(log_dir.clone(), log_file_prefix);
473 | let (non_blocking_writer, _guard) = tracing_appender::non_blocking(file_appender);
474 |
475 | // Build subscriber layers
476 | let file_layer = fmt::layer()
477 | .with_writer(non_blocking_writer)
478 | .with_ansi(false); // No ANSI colors in files
479 | // Optionally add .json() for structured JSON logs in the file
480 |
481 | let console_layer = fmt::layer().with_writer(std::io::stdout); // Log to stdout
482 |
483 | // Use RUST_LOG environment variable for log level filtering (e.g., RUST_LOG=info,imagen3_mcp=debug)
484 | // Defaults to "info" if RUST_LOG is not set.
485 | let env_filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("info"));
486 |
487 | // Combine layers and set global subscriber
488 | tracing_subscriber::registry()
489 | .with(env_filter)
490 | .with(file_layer)
491 | .with(console_layer) // Add console layer
492 | .init();
493 |
494 | info!(
495 | "Tracing initialized. Logging to console and {}/{}",
496 | log_dir.display(),
497 | log_file_prefix
498 | );
499 | // --- End Tracing Setup ---
500 |
501 | // Ensure resources directories exist and get the path
502 | let resources_path = match ensure_resources_dir().await {
503 | Ok(path) => path,
504 | Err(e) => {
505 | error!("Failed to ensure resources directory: {}", e);
506 | return Err(e.into());
507 | }
508 | };
509 |
510 | // Read configuration from environment variables
511 | let image_resource_server_addr =
512 | env::var("IMAGE_RESOURCE_SERVER_ADDR").unwrap_or_else(|_| "127.0.0.1".to_string());
513 | let server_port_str = env::var("SERVER_PORT").unwrap_or_else(|_| "9981".to_string());
514 | let server_port: u16 = server_port_str
515 | .parse()
516 | .map_err(|e| format!("Invalid SERVER_PORT: {}", e))?;
517 | let listen_addr_str =
518 | env::var("SERVER_LISTEN_ADDR").unwrap_or_else(|_| "127.0.0.1".to_string());
519 |
520 | // Create service for MCP
521 | let service = ImageGenerationServer {
522 | resources_path: resources_path.clone(),
523 | image_resource_server_addr: image_resource_server_addr.clone(), // Clone for info log
524 | server_port,
525 | };
526 | info!(
527 | ?image_resource_server_addr,
528 | server_port, "Image server configured."
529 | );
530 |
531 | // Check if GEMINI_API_KEY is set
532 | if env::var("GEMINI_API_KEY").is_err() {
533 | error!("GEMINI_API_KEY environment variable is not set. Image generation will fail.");
534 | std::process::exit(1);
535 | } else {
536 | info!("GEMINI_API_KEY found.");
537 | }
538 |
539 | // Set up static file server with warp
540 | let images_path = resources_path.join("images");
541 | let resources_path_clone = resources_path.clone();
542 |
543 | // Route for serving images
544 | let images_route = warp::path("images")
545 | .and(warp::fs::dir(images_path.clone())) // Clone for info log
546 | .with(warp::cors().allow_any_origin());
547 | info!(path = %images_path.display(), "Serving images from directory");
548 |
549 | // Route for listing available images
550 | let list_images_route = warp::path("list-images").and_then(move || {
551 | let path = resources_path_clone.clone();
552 | info!("Received request to list images."); // Added info log
553 | async move {
554 | match list_images(path).await {
555 | Ok(images) => Ok(warp::reply::json(&images)),
556 | Err(e) => {
557 | error!("Failed to list images: {}", e); // Added error log
558 | Err(warp::reject::not_found())
559 | }
560 | }
561 | }
562 | });
563 |
564 | // Combine all routes
565 | let routes = images_route.or(list_images_route);
566 |
567 | // Parse server listen address
568 | let listen_addr: SocketAddr = format!("{}:{}", listen_addr_str, server_port)
569 | .parse()
570 | .map_err(|e| format!("Invalid SERVER_LISTEN_ADDR or SERVER_PORT: {}", e))?;
571 |
572 | // Start HTTP server in a separate task
573 | info!(address = %listen_addr, "Starting HTTP server for image resources.");
574 | let http_server = warp::serve(routes).run(listen_addr);
575 |
576 | let http_handle = tokio::spawn(async move {
577 | http_server.await;
578 | info!("HTTP server shut down.");
579 | });
580 |
581 | // Start MCP server in the main task
582 | info!("Starting MCP server...");
583 | let mcp_future = ServiceExt::serve(service, (tokio::io::stdin(), tokio::io::stdout()))
584 | .await?
585 | .waiting();
586 |
587 | // Run MCP server to completion
588 | mcp_future.await?;
589 | info!("MCP server shut down.");
590 |
591 | // If we get here, the MCP server has shut down, so cancel the HTTP server
592 | http_handle.abort();
593 | info!("Aborted HTTP server task.");
594 |
595 | Ok(())
596 | }
597 |
```