siliconflow-image-mcp 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 SiliconFlow Image MCP Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,306 @@
1
+ # SiliconFlow Image MCP
2
+
3
+ A Model Context Protocol (MCP) server for image generation and editing using **SiliconFlow** - optimized for China users with fast, reliable access.
4
+
5
+ ## โœจ Features
6
+
7
+ - ๐Ÿ‡จ๐Ÿ‡ณ **China Optimized** - Fast, reliable access from mainland China without VPN
8
+ - ๐Ÿ–ผ๏ธ **Image Generation** - Generate stunning images from text prompts
9
+ - โœ๏ธ **Image Editing** - Edit existing images with AI-powered modifications
10
+ - ๐Ÿ” **Model Discovery** - Browse available image generation models
11
+ - ๐Ÿ“Š **Multiple Formats** - Support for various aspect ratios and resolutions
12
+ - ๐Ÿš€ **Easy Integration** - Simple setup with Claude Desktop and other MCP clients
13
+ - โšก **Advanced Options** - Negative prompts, seeds, CFG values
14
+ - ๐Ÿ–ฅ๏ธ **Cross-Platform** - Native support for Linux, macOS, and Windows
15
+ - ๐Ÿ“ **Custom Storage** - Configure where images are saved via environment variable
16
+ - ๐Ÿงช **Mock Mode** - Test without making real API calls
17
+
18
+ ## ๐Ÿ“ฆ Installation
19
+
20
+ ### Using NPX (Recommended)
21
+ ```bash
22
+ # No installation needed - use directly via npx
23
+ npx siliconflow-image-mcp
24
+ ```
25
+
26
+ ### Global Install
27
+ ```bash
28
+ npm install -g siliconflow-image-mcp
29
+ siliconflow-image-mcp
30
+ ```
31
+
32
+ ## โš™๏ธ Setup
33
+
34
+ ### 1. Get SiliconFlow API Key
35
+ - Visit [SiliconFlow Console](https://siliconflow.cn)
36
+ - Create an account and get your API key
37
+ - The service is optimized for China network conditions
38
+
39
+ ### 2. Configure Environment
40
+ ```bash
41
+ export SILICONFLOW_API_KEY="your-siliconflow-api-key"
42
+
43
+ # Optional: Custom directory for saved images (default: system temp dir)
44
+ export SILICONFLOW_IMAGE_DIR="/path/to/your/images"
45
+
46
+ # Optional: Mock mode for testing (no real API calls)
47
+ export SILICONFLOW_MOCK="true"
48
+ ```
49
+
50
+ ### 3. Claude Desktop Configuration
51
+
52
+ Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
53
+
54
+ ```json
55
+ {
56
+ "mcpServers": {
57
+ "siliconflow-image-mcp": {
58
+ "command": "npx",
59
+ "args": ["-y", "siliconflow-image-mcp"],
60
+ "env": {
61
+ "SILICONFLOW_API_KEY": "your-siliconflow-key",
62
+ "SILICONFLOW_IMAGE_DIR": "/path/to/save/images"
63
+ }
64
+ }
65
+ }
66
+ }
67
+ ```
68
+
69
+ **Restart Claude Desktop** after adding the configuration.
70
+
71
+ ## ๐Ÿ› ๏ธ Available Tools
72
+
73
+ ### 1. `generate_image`
74
+ Generate images from text descriptions.
75
+
76
+ **Parameters:**
77
+ - `prompt` (required): Detailed description of the image to generate
78
+ - `model` (optional): Model ID (default: `black-forest-labs/FLUX.1-dev`)
79
+ - `aspectRatio` (optional): Aspect ratio - `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`
80
+ - `imageSize` (optional): Image size - `1K`, `2K`, `4K`
81
+ - `count` (optional): Number of images (1-4, default: 1)
82
+ - `negativePrompt` (optional): What to avoid in the image
83
+ - `seed` (optional): Seed for reproducible results
84
+
85
+ **Example:**
86
+ ```
87
+ Generate a beautiful sunset over mountains with a lake in the foreground,
88
+ in 16:9 aspect ratio, 4K resolution
89
+ ```
90
+
91
+ ### 2. `edit_image`
92
+ Edit existing images with AI instructions.
93
+
94
+ **Parameters:**
95
+ - `image` (required): Base64 encoded image data or image URL
96
+ - `prompt` (required): Instructions for editing
97
+ - `model` (optional): Model ID (default: `Qwen/Qwen-Image-Edit-2509`)
98
+
99
+ **Example:**
100
+ ```
101
+ Edit this image to make it brighter and increase the saturation
102
+ ```
103
+
104
+ ### 3. `list_image_models`
105
+ List all available image generation models.
106
+
107
+ **Parameters:** None
108
+
109
+ **Example:**
110
+ ```
111
+ Show me available image generation models
112
+ ```
113
+
114
+ ## ๐Ÿ’ก Usage Examples
115
+
116
+ ### Basic Image Generation
117
+ ```
118
+ Generate an image of a futuristic cityscape at night with neon lights
119
+ ```
120
+
121
+ ### Multiple Images
122
+ ```
123
+ Generate 3 different variations of a cute cat wearing a hat
124
+ ```
125
+
126
+ ### Specific Aspect Ratio
127
+ ```
128
+ Create a portrait of a wizard in 9:16 aspect ratio for mobile wallpaper
129
+ ```
130
+
131
+ ### High Resolution
132
+ ```
133
+ Generate a detailed landscape in 4K resolution with 16:9 aspect ratio
134
+ ```
135
+
136
+ ### Image Editing
137
+ ```
138
+ Edit this image to make it look like a vintage photograph from the 1950s
139
+ ```
140
+
141
+ ### Advanced Options
142
+ ```
143
+ Generate a photorealistic portrait using black-forest-labs/FLUX.1-dev
144
+ with negative prompt "blurry, low quality" and seed 12345
145
+ ```
146
+
147
+ ## ๐Ÿ”ง Model Recommendations
148
+
149
+ ### SiliconFlow Models
150
+ - `black-forest-labs/FLUX.1-dev` - High quality general purpose (default)
151
+ - `Qwen/Qwen-Image-Edit-2509` - Excellent for image editing (default)
152
+ - `Kwai-Kolors/Kolors` - Good for artistic styles
153
+ - `stabilityai/stable-diffusion-xl-base-1.0` - Classic stable diffusion
154
+
155
+ ## ๐ŸŒ China-Specific Benefits
156
+
157
+ ### SiliconFlow Advantages:
158
+ - โœ… **Fast access** from mainland China
159
+ - โœ… **Stable connection** without VPN
160
+ - โœ… **Chinese language support**
161
+ - โœ… **Local payment methods**
162
+ - โœ… **Optimized infrastructure**
163
+
164
+ ### Network Performance:
165
+ - Average response time: < 2 seconds from China
166
+ - 99.9% uptime from Chinese networks
167
+ - No Great Firewall interference
168
+
169
+ ## ๐Ÿ”ง Environment Variables
170
+
171
+ | Variable | Required | Default | Description |
172
+ |----------|----------|---------|-------------|
173
+ | `SILICONFLOW_API_KEY` | **Yes** | - | Your SiliconFlow API key from [siliconflow.cn](https://siliconflow.cn) |
174
+ | `SILICONFLOW_IMAGE_DIR` | No | System temp dir | Custom directory to save generated/edited images |
175
+ | `SILICONFLOW_MOCK` | No | `false` | Enable mock mode for testing (no real API calls) |
176
+
177
+ ### Examples
178
+
179
+ **Linux/macOS:**
180
+ ```bash
181
+ export SILICONFLOW_API_KEY="sk-xxxxx"
182
+ export SILICONFLOW_IMAGE_DIR="/home/user/siliconflow-images"
183
+ ```
184
+
185
+ **Windows CMD:**
186
+ ```cmd
187
+ set SILICONFLOW_API_KEY=sk-xxxxx
188
+ set SILICONFLOW_IMAGE_DIR=C:\Users\MyUser\Images
189
+ ```
190
+
191
+ **Windows PowerShell:**
192
+ ```powershell
193
+ $env:SILICONFLOW_API_KEY="sk-xxxxx"
194
+ $env:SILICONFLOW_IMAGE_DIR="C:\Users\MyUser\Images"
195
+ ```
196
+
197
+ ## ๐Ÿ”’ Security
198
+
199
+ - **API Key**: Your API keys are stored securely in environment variables
200
+ - **Input Validation**: All inputs are validated using Zod schemas
201
+ - **Rate Limiting**: Respect service provider limits
202
+ - **Content Filtering**: Consider implementing content policies for your use case
203
+ - **File Storage**: Images are saved to your specified directory or system temp
204
+
205
+ ## ๐Ÿ› Troubleshooting
206
+
207
+ ### "No API key provided"
208
+ Make sure you've set the environment variable:
209
+ ```bash
210
+ export SILICONFLOW_API_KEY="your-key"
211
+ ```
212
+
213
+ ### "Failed to connect to SiliconFlow"
214
+ - Check your API key is valid
215
+ - Verify network connectivity to `api.siliconflow.cn`
216
+ - Check SiliconFlow service status
217
+
218
+ ### "No images were generated"
219
+ - Try a more descriptive prompt
220
+ - Check if the model supports image generation
221
+ - Verify your API key has access to the model
222
+
223
+ ### Images not appearing in Claude
224
+ - Restart Claude Desktop after configuration changes
225
+ - Check the MCP server logs for errors
226
+ - Verify the server is running with `npm start`
227
+
228
+ ### Images saved to wrong location
229
+ - Set `SILICONFLOW_IMAGE_DIR` to your desired path
230
+ - Ensure the directory exists and is writable
231
+ - Default location: system temp directory (`/tmp/siliconflow-images/` on Linux/macOS)
232
+
233
+ ### Running on Windows
234
+ - Use the `.cmd` wrapper automatically provided by npm
235
+ - Or use Git Bash/WSL for Unix-style commands
236
+ - For native CMD/PowerShell, the `.cmd` file handles execution
237
+
238
+ ## ๐Ÿ’ฐ Pricing
239
+
240
+ ### SiliconFlow:
241
+ - **FLUX.1-dev**: ~ยฅ0.02-0.05 per image
242
+ - **Qwen-Image**: ~ยฅ0.01-0.03 per image
243
+ - **Kolors**: ~ยฅ0.01-0.02 per image
244
+ - **Free tier**: Available for new users
245
+
246
+ *Check [SiliconFlow pricing](https://siliconflow.cn/pricing) for current rates.*
247
+
248
+ ## ๐Ÿš€ Development
249
+
250
+ ### Local Development
251
+ ```bash
252
+ # Clone the repository
253
+ git clone https://github.com/martianzhang/siliconflow-image-mcp.git
254
+ cd siliconflow-image-mcp
255
+
256
+ # Install dependencies
257
+ npm install
258
+
259
+ # Build the project
260
+ npm run build
261
+
262
+ # Run tests
263
+ npm test
264
+
265
+ # Start the server
266
+ npm start
267
+ ```
268
+
269
+ ### Project Structure
270
+ ```
271
+ src/
272
+ โ”œโ”€โ”€ index.ts # Main server entry
273
+ โ”œโ”€โ”€ tools/
274
+ โ”‚ โ”œโ”€โ”€ generate.ts # Image generation tool
275
+ โ”‚ โ”œโ”€โ”€ edit.ts # Image editing tool
276
+ โ”‚ โ””โ”€โ”€ list-models.ts # Model discovery tool
277
+ โ”œโ”€โ”€ services/
278
+ โ”‚ โ””โ”€โ”€ siliconflow.ts # SiliconFlow service wrapper
279
+ โ””โ”€โ”€ types/
280
+ โ””โ”€โ”€ index.ts # Type definitions
281
+ ```
282
+
283
+ ## ๐Ÿค Contributing
284
+
285
+ Contributions are welcome! Please feel free to submit a Pull Request.
286
+
287
+ 1. Fork the repository
288
+ 2. Create a feature branch
289
+ 3. Make your changes
290
+ 4. Add tests for new functionality
291
+ 5. Submit a pull request
292
+
293
+ ## ๐Ÿ“„ License
294
+
295
+ MIT License - see [LICENSE](LICENSE) for details.
296
+
297
+ ## ๐Ÿ”— Links
298
+
299
+ - [SiliconFlow Documentation](https://docs.siliconflow.cn)
300
+ - [SiliconFlow API Reference](https://docs.siliconflow.cn/cn/api-reference/images/images-generations)
301
+ - [MCP Specification](https://modelcontextprotocol.io)
302
+ - [Report Issues](https://github.com/martianzhang/siliconflow-image-mcp/issues)
303
+
304
+ ---
305
+
306
+ **Made with โค๏ธ for the AI community - With special support for China users**
@@ -0,0 +1,24 @@
1
+ #!/usr/bin/env sh
2
+ # SiliconFlow Image MCP - Unix/Linux/macOS wrapper script
3
+ # Handles both local development and global installation
4
+ # For Windows, use the siliconflow-image-mcp.cmd wrapper
5
+
6
+ # Get the real directory of this script (resolves symlinks)
7
+ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
8
+ # If we're in a symlinked location, follow it to find the real package location
9
+ if [ -L "$0" ]; then
10
+ SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "$0")")" && pwd)"
11
+ fi
12
+
13
+ # Check if we're in a development environment (source files exist)
14
+ if [ -f "$SCRIPT_DIR/../src/index.ts" ]; then
15
+ # Development mode - run TypeScript source directly
16
+ exec tsx "$SCRIPT_DIR/../src/index.ts"
17
+ elif [ -f "$SCRIPT_DIR/../dist/index.js" ]; then
18
+ # Production mode - run compiled JavaScript
19
+ exec node "$SCRIPT_DIR/../dist/index.js"
20
+ else
21
+ echo "โŒ Error: Could not find siliconflow-image-mcp source files"
22
+ echo "Searched in: $SCRIPT_DIR/../src/index.ts and $SCRIPT_DIR/../dist/index.js"
23
+ exit 1
24
+ fi
@@ -0,0 +1,21 @@
1
+ @echo off
2
+ REM SiliconFlow Image MCP - Windows wrapper script
3
+ REM Handles both local development and global installation on Windows
4
+
5
+ setlocal
6
+
7
+ REM Get the directory where this script is located
8
+ set "SCRIPT_DIR=%~dp0"
9
+
10
+ REM Check if we're in a development environment (source files exist)
11
+ if exist "%SCRIPT_DIR%..\src\index.ts" (
12
+ REM Development mode - run TypeScript source directly
13
+ npx tsx "%SCRIPT_DIR%..\src\index.ts" %*
14
+ ) else if exist "%SCRIPT_DIR%..\dist\index.js" (
15
+ REM Production mode - run compiled JavaScript
16
+ node "%SCRIPT_DIR%..\dist\index.js" %*
17
+ ) else (
18
+ echo โŒ Error: Could not find siliconflow-image-mcp source files
19
+ echo Searched in: %SCRIPT_DIR%..\src\index.ts and %SCRIPT_DIR%..\dist\index.js
20
+ exit /b 1
21
+ )
package/dist/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 SiliconFlow Image MCP Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/dist/README.md ADDED
@@ -0,0 +1,306 @@
1
+ # SiliconFlow Image MCP
2
+
3
+ A Model Context Protocol (MCP) server for image generation and editing using **SiliconFlow** - optimized for China users with fast, reliable access.
4
+
5
+ ## โœจ Features
6
+
7
+ - ๐Ÿ‡จ๐Ÿ‡ณ **China Optimized** - Fast, reliable access from mainland China without VPN
8
+ - ๐Ÿ–ผ๏ธ **Image Generation** - Generate stunning images from text prompts
9
+ - โœ๏ธ **Image Editing** - Edit existing images with AI-powered modifications
10
+ - ๐Ÿ” **Model Discovery** - Browse available image generation models
11
+ - ๐Ÿ“Š **Multiple Formats** - Support for various aspect ratios and resolutions
12
+ - ๐Ÿš€ **Easy Integration** - Simple setup with Claude Desktop and other MCP clients
13
+ - โšก **Advanced Options** - Negative prompts, seeds, CFG values
14
+ - ๐Ÿ–ฅ๏ธ **Cross-Platform** - Native support for Linux, macOS, and Windows
15
+ - ๐Ÿ“ **Custom Storage** - Configure where images are saved via environment variable
16
+ - ๐Ÿงช **Mock Mode** - Test without making real API calls
17
+
18
+ ## ๐Ÿ“ฆ Installation
19
+
20
+ ### Using NPX (Recommended)
21
+ ```bash
22
+ # No installation needed - use directly via npx
23
+ npx siliconflow-image-mcp
24
+ ```
25
+
26
+ ### Global Install
27
+ ```bash
28
+ npm install -g siliconflow-image-mcp
29
+ siliconflow-image-mcp
30
+ ```
31
+
32
+ ## โš™๏ธ Setup
33
+
34
+ ### 1. Get SiliconFlow API Key
35
+ - Visit [SiliconFlow Console](https://siliconflow.cn)
36
+ - Create an account and get your API key
37
+ - The service is optimized for China network conditions
38
+
39
+ ### 2. Configure Environment
40
+ ```bash
41
+ export SILICONFLOW_API_KEY="your-siliconflow-api-key"
42
+
43
+ # Optional: Custom directory for saved images (default: system temp dir)
44
+ export SILICONFLOW_IMAGE_DIR="/path/to/your/images"
45
+
46
+ # Optional: Mock mode for testing (no real API calls)
47
+ export SILICONFLOW_MOCK="true"
48
+ ```
49
+
50
+ ### 3. Claude Desktop Configuration
51
+
52
+ Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
53
+
54
+ ```json
55
+ {
56
+ "mcpServers": {
57
+ "siliconflow-image-mcp": {
58
+ "command": "npx",
59
+ "args": ["-y", "siliconflow-image-mcp"],
60
+ "env": {
61
+ "SILICONFLOW_API_KEY": "your-siliconflow-key",
62
+ "SILICONFLOW_IMAGE_DIR": "/path/to/save/images"
63
+ }
64
+ }
65
+ }
66
+ }
67
+ ```
68
+
69
+ **Restart Claude Desktop** after adding the configuration.
70
+
71
+ ## ๐Ÿ› ๏ธ Available Tools
72
+
73
+ ### 1. `generate_image`
74
+ Generate images from text descriptions.
75
+
76
+ **Parameters:**
77
+ - `prompt` (required): Detailed description of the image to generate
78
+ - `model` (optional): Model ID (default: `black-forest-labs/FLUX.1-dev`)
79
+ - `aspectRatio` (optional): Aspect ratio - `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`
80
+ - `imageSize` (optional): Image size - `1K`, `2K`, `4K`
81
+ - `count` (optional): Number of images (1-4, default: 1)
82
+ - `negativePrompt` (optional): What to avoid in the image
83
+ - `seed` (optional): Seed for reproducible results
84
+
85
+ **Example:**
86
+ ```
87
+ Generate a beautiful sunset over mountains with a lake in the foreground,
88
+ in 16:9 aspect ratio, 4K resolution
89
+ ```
90
+
91
+ ### 2. `edit_image`
92
+ Edit existing images with AI instructions.
93
+
94
+ **Parameters:**
95
+ - `image` (required): Base64 encoded image data or image URL
96
+ - `prompt` (required): Instructions for editing
97
+ - `model` (optional): Model ID (default: `Qwen/Qwen-Image-Edit-2509`)
98
+
99
+ **Example:**
100
+ ```
101
+ Edit this image to make it brighter and increase the saturation
102
+ ```
103
+
104
+ ### 3. `list_image_models`
105
+ List all available image generation models.
106
+
107
+ **Parameters:** None
108
+
109
+ **Example:**
110
+ ```
111
+ Show me available image generation models
112
+ ```
113
+
114
+ ## ๐Ÿ’ก Usage Examples
115
+
116
+ ### Basic Image Generation
117
+ ```
118
+ Generate an image of a futuristic cityscape at night with neon lights
119
+ ```
120
+
121
+ ### Multiple Images
122
+ ```
123
+ Generate 3 different variations of a cute cat wearing a hat
124
+ ```
125
+
126
+ ### Specific Aspect Ratio
127
+ ```
128
+ Create a portrait of a wizard in 9:16 aspect ratio for mobile wallpaper
129
+ ```
130
+
131
+ ### High Resolution
132
+ ```
133
+ Generate a detailed landscape in 4K resolution with 16:9 aspect ratio
134
+ ```
135
+
136
+ ### Image Editing
137
+ ```
138
+ Edit this image to make it look like a vintage photograph from the 1950s
139
+ ```
140
+
141
+ ### Advanced Options
142
+ ```
143
+ Generate a photorealistic portrait using black-forest-labs/FLUX.1-dev
144
+ with negative prompt "blurry, low quality" and seed 12345
145
+ ```
146
+
147
+ ## ๐Ÿ”ง Model Recommendations
148
+
149
+ ### SiliconFlow Models
150
+ - `black-forest-labs/FLUX.1-dev` - High quality general purpose (default)
151
+ - `Qwen/Qwen-Image-Edit-2509` - Excellent for image editing (default)
152
+ - `Kwai-Kolors/Kolors` - Good for artistic styles
153
+ - `stabilityai/stable-diffusion-xl-base-1.0` - Classic stable diffusion
154
+
155
+ ## ๐ŸŒ China-Specific Benefits
156
+
157
+ ### SiliconFlow Advantages:
158
+ - โœ… **Fast access** from mainland China
159
+ - โœ… **Stable connection** without VPN
160
+ - โœ… **Chinese language support**
161
+ - โœ… **Local payment methods**
162
+ - โœ… **Optimized infrastructure**
163
+
164
+ ### Network Performance:
165
+ - Average response time: < 2 seconds from China
166
+ - 99.9% uptime from Chinese networks
167
+ - No Great Firewall interference
168
+
169
+ ## ๐Ÿ”ง Environment Variables
170
+
171
+ | Variable | Required | Default | Description |
172
+ |----------|----------|---------|-------------|
173
+ | `SILICONFLOW_API_KEY` | **Yes** | - | Your SiliconFlow API key from [siliconflow.cn](https://siliconflow.cn) |
174
+ | `SILICONFLOW_IMAGE_DIR` | No | System temp dir | Custom directory to save generated/edited images |
175
+ | `SILICONFLOW_MOCK` | No | `false` | Enable mock mode for testing (no real API calls) |
176
+
177
+ ### Examples
178
+
179
+ **Linux/macOS:**
180
+ ```bash
181
+ export SILICONFLOW_API_KEY="sk-xxxxx"
182
+ export SILICONFLOW_IMAGE_DIR="/home/user/siliconflow-images"
183
+ ```
184
+
185
+ **Windows CMD:**
186
+ ```cmd
187
+ set SILICONFLOW_API_KEY=sk-xxxxx
188
+ set SILICONFLOW_IMAGE_DIR=C:\Users\MyUser\Images
189
+ ```
190
+
191
+ **Windows PowerShell:**
192
+ ```powershell
193
+ $env:SILICONFLOW_API_KEY="sk-xxxxx"
194
+ $env:SILICONFLOW_IMAGE_DIR="C:\Users\MyUser\Images"
195
+ ```
196
+
197
+ ## ๐Ÿ”’ Security
198
+
199
+ - **API Key**: Your API keys are stored securely in environment variables
200
+ - **Input Validation**: All inputs are validated using Zod schemas
201
+ - **Rate Limiting**: Respect service provider limits
202
+ - **Content Filtering**: Consider implementing content policies for your use case
203
+ - **File Storage**: Images are saved to your specified directory or system temp
204
+
205
+ ## ๐Ÿ› Troubleshooting
206
+
207
+ ### "No API key provided"
208
+ Make sure you've set the environment variable:
209
+ ```bash
210
+ export SILICONFLOW_API_KEY="your-key"
211
+ ```
212
+
213
+ ### "Failed to connect to SiliconFlow"
214
+ - Check your API key is valid
215
+ - Verify network connectivity to `api.siliconflow.cn`
216
+ - Check SiliconFlow service status
217
+
218
+ ### "No images were generated"
219
+ - Try a more descriptive prompt
220
+ - Check if the model supports image generation
221
+ - Verify your API key has access to the model
222
+
223
+ ### Images not appearing in Claude
224
+ - Restart Claude Desktop after configuration changes
225
+ - Check the MCP server logs for errors
226
+ - Verify the server is running with `npm start`
227
+
228
+ ### Images saved to wrong location
229
+ - Set `SILICONFLOW_IMAGE_DIR` to your desired path
230
+ - Ensure the directory exists and is writable
231
+ - Default location: system temp directory (`/tmp/siliconflow-images/` on Linux/macOS)
232
+
233
+ ### Running on Windows
234
+ - Use the `.cmd` wrapper automatically provided by npm
235
+ - Or use Git Bash/WSL for Unix-style commands
236
+ - For native CMD/PowerShell, the `.cmd` file handles execution
237
+
238
+ ## ๐Ÿ’ฐ Pricing
239
+
240
+ ### SiliconFlow:
241
+ - **FLUX.1-dev**: ~ยฅ0.02-0.05 per image
242
+ - **Qwen-Image**: ~ยฅ0.01-0.03 per image
243
+ - **Kolors**: ~ยฅ0.01-0.02 per image
244
+ - **Free tier**: Available for new users
245
+
246
+ *Check [SiliconFlow pricing](https://siliconflow.cn/pricing) for current rates.*
247
+
248
+ ## ๐Ÿš€ Development
249
+
250
+ ### Local Development
251
+ ```bash
252
+ # Clone the repository
253
+ git clone https://github.com/martianzhang/siliconflow-image-mcp.git
254
+ cd siliconflow-image-mcp
255
+
256
+ # Install dependencies
257
+ npm install
258
+
259
+ # Build the project
260
+ npm run build
261
+
262
+ # Run tests
263
+ npm test
264
+
265
+ # Start the server
266
+ npm start
267
+ ```
268
+
269
+ ### Project Structure
270
+ ```
271
+ src/
272
+ โ”œโ”€โ”€ index.ts # Main server entry
273
+ โ”œโ”€โ”€ tools/
274
+ โ”‚ โ”œโ”€โ”€ generate.ts # Image generation tool
275
+ โ”‚ โ”œโ”€โ”€ edit.ts # Image editing tool
276
+ โ”‚ โ””โ”€โ”€ list-models.ts # Model discovery tool
277
+ โ”œโ”€โ”€ services/
278
+ โ”‚ โ””โ”€โ”€ siliconflow.ts # SiliconFlow service wrapper
279
+ โ””โ”€โ”€ types/
280
+ โ””โ”€โ”€ index.ts # Type definitions
281
+ ```
282
+
283
+ ## ๐Ÿค Contributing
284
+
285
+ Contributions are welcome! Please feel free to submit a Pull Request.
286
+
287
+ 1. Fork the repository
288
+ 2. Create a feature branch
289
+ 3. Make your changes
290
+ 4. Add tests for new functionality
291
+ 5. Submit a pull request
292
+
293
+ ## ๐Ÿ“„ License
294
+
295
+ MIT License - see [LICENSE](LICENSE) for details.
296
+
297
+ ## ๐Ÿ”— Links
298
+
299
+ - [SiliconFlow Documentation](https://docs.siliconflow.cn)
300
+ - [SiliconFlow API Reference](https://docs.siliconflow.cn/cn/api-reference/images/images-generations)
301
+ - [MCP Specification](https://modelcontextprotocol.io)
302
+ - [Report Issues](https://github.com/martianzhang/siliconflow-image-mcp/issues)
303
+
304
+ ---
305
+
306
+ **Made with โค๏ธ for the AI community - With special support for China users**