dropbg-mcp 0.0.0-stage → 1.0.1

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/README.md CHANGED
@@ -1,3 +1,56 @@
1
- # Temporary Holding Version
1
+ # dropbg-mcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Zero-dependency Model Context Protocol (MCP) `stdio` server for [DropBG](https://dropbg.io). Works with **Claude, DeepSeek, Qwen, Kimi, and GLM** across **Claude Desktop, Cursor, Claude Code, Trae, Cherry Studio, Windsurf, Cline, Roo Code, and Ollama** clients — removing backgrounds from local images or URLs and saving cutouts directly to disk without bloating context windows with base64 strings.
4
+
5
+ ## Quick Setup (Zero API Key Required)
6
+
7
+ ### Cursor, Claude Desktop, Trae, Cherry Studio, Windsurf, Cline & Roo Code
8
+
9
+ ```json
10
+ {
11
+ "mcpServers": {
12
+ "dropbg": {
13
+ "command": "npx",
14
+ "args": ["-y", "dropbg-mcp"]
15
+ }
16
+ }
17
+ }
18
+ ```
19
+
20
+ ### Claude Code CLI
21
+
22
+ ```bash
23
+ claude mcp add dropbg -- npx -y dropbg-mcp
24
+ ```
25
+
26
+ ## Available Tools
27
+
28
+ ### 1. `remove_background_file`
29
+ Removes the background from a local image file and writes the result to disk.
30
+
31
+ - `input_path` (`string`, required): Local path to PNG, JPG, JPEG, or WEBP image.
32
+ - `output_path` (`string`, optional): Output file path (defaults to `<name>_cutout.png` or `.jpg` when using solid `bg_color`).
33
+ - `bg_color` (`string`, optional): 6-digit hex color (e.g. `#FFFFFF` for Amazon/passport photos). Omit for transparent PNG.
34
+ - `format` (`"auto" | "png" | "jpg" | "jpeg"`, optional, default `"auto"`).
35
+ - `size` (`"auto" | "preview" | "full" | "regular" | "medium" | "hd" | "4k"`, optional, default `"auto"`).
36
+ - `defringe` (`boolean`, optional, default `true`): Color decontamination along fine hair/fur edges.
37
+
38
+ ### 2. `remove_background_url`
39
+ Removes the background from a public `http://` or `https://` image URL and saves it to a local path.
40
+
41
+ - `image_url` (`string`, required): Public image URL.
42
+ - `output_path` (`string`, required): Destination file path.
43
+ - `bg_color`, `format`, `size`, `defringe`: Same as above.
44
+
45
+ ### 3. `remove_background_batch`
46
+ Sequentially removes backgrounds from up to 10 local image files and saves cutouts to disk or a target `output_dir`.
47
+
48
+ - `input_paths` (`string[]`, required): Local image paths (max 10).
49
+ - `output_dir` (`string`, optional): Destination directory.
50
+ - `bg_color`, `format`, `defringe`: Same as above.
51
+
52
+ ## Testing
53
+
54
+ ```bash
55
+ npm test --prefix apps/mcp
56
+ ```
@@ -0,0 +1,411 @@
1
+ #!/usr/bin/env node
2
+
3
+ import fs from 'node:fs/promises';
4
+ import path from 'node:path';
5
+ import readline from 'node:readline';
6
+
7
+ const API_URL = process.env.DROPBG_API_URL || 'https://api.dropbg.io/v1.0/removebg';
8
+ const PROTOCOL_VERSION = '2024-11-05';
9
+ const MAX_BATCH_FILES = 10;
10
+
11
+ const SERVER_INFO = {
12
+ name: 'dropbg-mcp',
13
+ version: '1.0.1',
14
+ };
15
+
16
+ const TOOLS = [
17
+ {
18
+ name: 'remove_background_file',
19
+ description:
20
+ 'Remove the background from a local image file (PNG, JPG, JPEG, WEBP) using DropBG and save the transparent PNG or solid-color cutout to disk.',
21
+ inputSchema: {
22
+ type: 'object',
23
+ properties: {
24
+ input_path: {
25
+ type: 'string',
26
+ description: 'Path to the local source image file.',
27
+ },
28
+ output_path: {
29
+ type: 'string',
30
+ description:
31
+ 'Path to save the processed image. Defaults to <dir>/<name>_cutout.png (or .jpg when format is jpg/jpeg or bg_color is set with format "auto").',
32
+ },
33
+ bg_color: {
34
+ type: 'string',
35
+ description:
36
+ 'Optional 6-digit hex color (e.g. #FFFFFF for Amazon/passport white backgrounds). Omit for transparent cutout.',
37
+ },
38
+ format: {
39
+ type: 'string',
40
+ enum: ['auto', 'png', 'jpg', 'jpeg'],
41
+ default: 'auto',
42
+ description: 'Output image format.',
43
+ },
44
+ size: {
45
+ type: 'string',
46
+ enum: ['auto', 'preview', 'full', 'regular', 'medium', 'hd', '4k'],
47
+ default: 'auto',
48
+ description: 'Output resolution preset.',
49
+ },
50
+ defringe: {
51
+ type: 'boolean',
52
+ default: true,
53
+ description: 'Apply color decontamination on hair/fur edges.',
54
+ },
55
+ },
56
+ required: ['input_path'],
57
+ },
58
+ },
59
+ {
60
+ name: 'remove_background_url',
61
+ description:
62
+ 'Remove the background from a public HTTP/HTTPS image URL using DropBG and save the result to a local file path.',
63
+ inputSchema: {
64
+ type: 'object',
65
+ properties: {
66
+ image_url: {
67
+ type: 'string',
68
+ description: 'Public http:// or https:// URL of the source image.',
69
+ },
70
+ output_path: {
71
+ type: 'string',
72
+ description: 'Local destination path to save the processed cutout image.',
73
+ },
74
+ bg_color: {
75
+ type: 'string',
76
+ description: 'Optional 6-digit hex background color (e.g. #FFFFFF).',
77
+ },
78
+ format: {
79
+ type: 'string',
80
+ enum: ['auto', 'png', 'jpg', 'jpeg'],
81
+ default: 'auto',
82
+ description: 'Output image format.',
83
+ },
84
+ size: {
85
+ type: 'string',
86
+ enum: ['auto', 'preview', 'full', 'regular', 'medium', 'hd', '4k'],
87
+ default: 'auto',
88
+ description: 'Output resolution preset.',
89
+ },
90
+ defringe: {
91
+ type: 'boolean',
92
+ default: true,
93
+ description: 'Apply color decontamination on hair/fur edges.',
94
+ },
95
+ },
96
+ required: ['image_url', 'output_path'],
97
+ },
98
+ },
99
+ {
100
+ name: 'remove_background_batch',
101
+ description:
102
+ 'Remove backgrounds from multiple local image files sequentially (up to 10 files per batch) and save the cutouts to disk.',
103
+ inputSchema: {
104
+ type: 'object',
105
+ properties: {
106
+ input_paths: {
107
+ type: 'array',
108
+ items: { type: 'string' },
109
+ description: 'List of local image file paths (max 10).',
110
+ },
111
+ output_dir: {
112
+ type: 'string',
113
+ description: "Optional directory to write all processed cutouts into. Defaults to each input file's directory.",
114
+ },
115
+ bg_color: {
116
+ type: 'string',
117
+ description: 'Optional 6-digit hex background color (e.g. #FFFFFF).',
118
+ },
119
+ format: {
120
+ type: 'string',
121
+ enum: ['auto', 'png', 'jpg', 'jpeg'],
122
+ default: 'auto',
123
+ description: 'Output image format.',
124
+ },
125
+ defringe: {
126
+ type: 'boolean',
127
+ default: true,
128
+ description: 'Apply color decontamination on hair/fur edges.',
129
+ },
130
+ },
131
+ required: ['input_paths'],
132
+ },
133
+ },
134
+ ];
135
+
136
+ function inferMimeType(filePath) {
137
+ const ext = path.extname(filePath).toLowerCase();
138
+ if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg';
139
+ if (ext === '.webp') return 'image/webp';
140
+ return 'image/png';
141
+ }
142
+
143
+ function resolveDefaultOutputExt({ format = 'auto', bg_color }) {
144
+ const normalizedFormat = String(format).toLowerCase();
145
+ if (normalizedFormat === 'jpg' || normalizedFormat === 'jpeg') return 'jpg';
146
+ if (normalizedFormat === 'auto' && bg_color) return 'jpg';
147
+ return 'png';
148
+ }
149
+
150
+ function resolveOutputPath(inputPath, outputPath, options) {
151
+ if (outputPath) {
152
+ return path.resolve(outputPath);
153
+ }
154
+ const parsed = path.parse(path.resolve(inputPath));
155
+ const ext = resolveDefaultOutputExt(options);
156
+ return path.join(parsed.dir, `${parsed.name}_cutout.${ext}`);
157
+ }
158
+
159
+ function appendCommonFormFields(formData, { size = 'auto', format = 'auto', bg_color, defringe = true }) {
160
+ formData.append('size', String(size));
161
+ formData.append('format', String(format));
162
+ formData.append('defringe', String(defringe));
163
+ if (bg_color) {
164
+ formData.append('bg_color', String(bg_color));
165
+ }
166
+ }
167
+
168
+ function parseIntHeader(headers, name) {
169
+ const raw = headers.get(name);
170
+ if (!raw) return null;
171
+ const parsed = Number.parseInt(raw, 10);
172
+ return Number.isFinite(parsed) ? parsed : null;
173
+ }
174
+
175
+ async function parseErrorResponse(response) {
176
+ const text = await response.text();
177
+ try {
178
+ const parsed = JSON.parse(text);
179
+ if (Array.isArray(parsed?.errors) && parsed.errors[0]?.detail) {
180
+ return `HTTP ${response.status}: ${parsed.errors[0].detail}`;
181
+ }
182
+ if (parsed?.detail) {
183
+ return `HTTP ${response.status}: ${parsed.detail}`;
184
+ }
185
+ } catch {
186
+ // Non-JSON response body
187
+ }
188
+ return `HTTP ${response.status}: ${text || response.statusText}`;
189
+ }
190
+
191
+ async function callRemoveBgApi(formData, destinationPath) {
192
+ const response = await fetch(API_URL, {
193
+ method: 'POST',
194
+ body: formData,
195
+ });
196
+
197
+ if (!response.ok) {
198
+ throw new Error(await parseErrorResponse(response));
199
+ }
200
+
201
+ const resolvedOutput = path.resolve(destinationPath);
202
+ const arrayBuffer = await response.arrayBuffer();
203
+ await fs.mkdir(path.dirname(resolvedOutput), { recursive: true });
204
+ await fs.writeFile(resolvedOutput, Buffer.from(arrayBuffer));
205
+
206
+ return {
207
+ output_path: resolvedOutput,
208
+ content_type: response.headers.get('content-type') || 'image/png',
209
+ bytes: arrayBuffer.byteLength,
210
+ width: parseIntHeader(response.headers, 'x-width'),
211
+ height: parseIntHeader(response.headers, 'x-height'),
212
+ processing_time_ms: parseIntHeader(response.headers, 'x-processing-time-ms'),
213
+ quota_remaining: parseIntHeader(response.headers, 'x-ratelimit-remaining'),
214
+ quota_reset_seconds: parseIntHeader(response.headers, 'x-ratelimit-reset'),
215
+ };
216
+ }
217
+
218
+ async function handleRemoveBackgroundFile(args) {
219
+ if (!args || typeof args.input_path !== 'string' || !args.input_path.trim()) {
220
+ throw new Error("Missing required parameter 'input_path'.");
221
+ }
222
+
223
+ const resolvedInput = path.resolve(args.input_path);
224
+ const fileBuffer = await fs.readFile(resolvedInput);
225
+ const mimeType = inferMimeType(resolvedInput);
226
+ const blob = new Blob([fileBuffer], { type: mimeType });
227
+
228
+ const formData = new FormData();
229
+ formData.append('image_file', blob, path.basename(resolvedInput));
230
+ appendCommonFormFields(formData, args);
231
+
232
+ const destinationPath = resolveOutputPath(resolvedInput, args.output_path, args);
233
+ return callRemoveBgApi(formData, destinationPath);
234
+ }
235
+
236
+ async function handleRemoveBackgroundUrl(args) {
237
+ if (!args || typeof args.image_url !== 'string' || !args.image_url.trim()) {
238
+ throw new Error("Missing required parameter 'image_url'.");
239
+ }
240
+ if (typeof args.output_path !== 'string' || !args.output_path.trim()) {
241
+ throw new Error("Missing required parameter 'output_path'.");
242
+ }
243
+
244
+ const url = new URL(args.image_url);
245
+ if (url.protocol !== 'http:' && url.protocol !== 'https:') {
246
+ throw new Error("'image_url' must use http:// or https://.");
247
+ }
248
+
249
+ const formData = new FormData();
250
+ formData.append('image_url', url.toString());
251
+ appendCommonFormFields(formData, args);
252
+
253
+ return callRemoveBgApi(formData, args.output_path);
254
+ }
255
+
256
+ async function handleRemoveBackgroundBatch(args) {
257
+ if (!args || !Array.isArray(args.input_paths) || args.input_paths.length === 0) {
258
+ throw new Error("Missing required non-empty array parameter 'input_paths'.");
259
+ }
260
+ if (args.input_paths.length > MAX_BATCH_FILES) {
261
+ throw new Error(`Batch size exceeds maximum of ${MAX_BATCH_FILES} files.`);
262
+ }
263
+
264
+ const results = [];
265
+ const ext = resolveDefaultOutputExt(args);
266
+ const resolvedOutDir = args.output_dir ? path.resolve(args.output_dir) : null;
267
+
268
+ for (const inputPath of args.input_paths) {
269
+ if (typeof inputPath !== 'string' || !inputPath.trim()) {
270
+ results.push({ input_path: inputPath, ok: false, error: 'Invalid input path entry.' });
271
+ continue;
272
+ }
273
+ const parsed = path.parse(path.resolve(inputPath));
274
+ const targetDir = resolvedOutDir || parsed.dir;
275
+ const outputPath = path.join(targetDir, `${parsed.name}_cutout.${ext}`);
276
+ try {
277
+ const processed = await handleRemoveBackgroundFile({
278
+ ...args,
279
+ input_path: inputPath,
280
+ output_path: outputPath,
281
+ });
282
+ results.push({ input_path: path.resolve(inputPath), ok: true, ...processed });
283
+ } catch (error) {
284
+ results.push({
285
+ input_path: path.resolve(inputPath),
286
+ ok: false,
287
+ error: error instanceof Error ? error.message : String(error),
288
+ });
289
+ }
290
+ }
291
+
292
+ return {
293
+ total: results.length,
294
+ succeeded: results.filter((r) => r.ok).length,
295
+ failed: results.filter((r) => !r.ok).length,
296
+ results,
297
+ };
298
+ }
299
+
300
+ async function dispatchToolCall(name, args) {
301
+ switch (name) {
302
+ case 'remove_background_file':
303
+ return handleRemoveBackgroundFile(args);
304
+ case 'remove_background_url':
305
+ return handleRemoveBackgroundUrl(args);
306
+ case 'remove_background_batch':
307
+ return handleRemoveBackgroundBatch(args);
308
+ default:
309
+ throw new Error(`Unknown tool: ${name}`);
310
+ }
311
+ }
312
+
313
+ function writeResponse(message) {
314
+ process.stdout.write(`${JSON.stringify(message)}\n`);
315
+ }
316
+
317
+ function writeResult(id, result) {
318
+ writeResponse({ jsonrpc: '2.0', id, result });
319
+ }
320
+
321
+ function writeError(id, code, message) {
322
+ writeResponse({ jsonrpc: '2.0', id, error: { code, message } });
323
+ }
324
+
325
+ async function handleMessage(msg) {
326
+ const hasId = msg && msg.id !== undefined && msg.id !== null;
327
+ if (!msg || typeof msg.method !== 'string') {
328
+ if (hasId) {
329
+ writeError(msg.id, -32600, 'Invalid Request');
330
+ }
331
+ return;
332
+ }
333
+
334
+ const { id, method, params } = msg;
335
+
336
+ switch (method) {
337
+ case 'initialize': {
338
+ const clientVersion = params?.protocolVersion;
339
+ if (hasId) {
340
+ writeResult(id, {
341
+ protocolVersion: typeof clientVersion === 'string' && clientVersion ? clientVersion : PROTOCOL_VERSION,
342
+ capabilities: { tools: {} },
343
+ serverInfo: SERVER_INFO,
344
+ });
345
+ }
346
+ return;
347
+ }
348
+
349
+ case 'notifications/initialized':
350
+ return;
351
+
352
+ case 'ping':
353
+ if (hasId) writeResult(id, {});
354
+ return;
355
+
356
+ case 'tools/list':
357
+ if (hasId) writeResult(id, { tools: TOOLS });
358
+ return;
359
+
360
+ case 'tools/call': {
361
+ const toolName = params?.name;
362
+ const toolArgs = params?.arguments ?? {};
363
+ try {
364
+ const result = await dispatchToolCall(toolName, toolArgs);
365
+ if (hasId) {
366
+ writeResult(id, {
367
+ content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
368
+ });
369
+ }
370
+ } catch (error) {
371
+ const errorMessage = error instanceof Error ? error.message : String(error);
372
+ if (hasId) {
373
+ writeResult(id, {
374
+ isError: true,
375
+ content: [{ type: 'text', text: errorMessage }],
376
+ });
377
+ }
378
+ }
379
+ return;
380
+ }
381
+
382
+ default:
383
+ if (hasId) {
384
+ writeError(id, -32601, `Method not found: ${method}`);
385
+ }
386
+ }
387
+ }
388
+
389
+ const rl = readline.createInterface({
390
+ input: process.stdin,
391
+ crlfDelay: Number.POSITIVE_INFINITY,
392
+ });
393
+
394
+ // Serialize message handling so writes never interleave and shutdown waits for in-flight tool calls
395
+ let queue = Promise.resolve();
396
+ rl.on('line', (line) => {
397
+ const trimmed = line.trim();
398
+ if (!trimmed) return;
399
+ queue = queue.then(async () => {
400
+ try {
401
+ const parsed = JSON.parse(trimmed);
402
+ await handleMessage(parsed);
403
+ } catch {
404
+ writeError(null, -32700, 'Parse error');
405
+ }
406
+ });
407
+ });
408
+
409
+ rl.on('close', () => {
410
+ queue.finally(() => process.exit(0));
411
+ });
package/package.json CHANGED
@@ -1,6 +1,44 @@
1
1
  {
2
2
  "name": "dropbg-mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "mcpName": "io.dropbg/dropbg-mcp",
4
+ "version": "1.0.1",
5
+ "description": "Model Context Protocol (MCP) server for DropBG (dropbg.io) AI background removal — works with Claude, Cursor, DeepSeek, Qwen, Kimi, GLM, Trae, Cherry Studio, Windsurf, Cline, and Roo Code",
6
+ "license": "MIT",
7
+ "type": "module",
8
+ "bin": {
9
+ "dropbg-mcp": "./bin/dropbg-mcp.mjs"
10
+ },
11
+ "main": "./bin/dropbg-mcp.mjs",
12
+ "files": [
13
+ "bin/",
14
+ "README.md",
15
+ "server.json"
16
+ ],
17
+ "scripts": {
18
+ "start": "node ./bin/dropbg-mcp.mjs",
19
+ "test": "node --test ./test/mcp.test.mjs"
20
+ },
21
+ "keywords": [
22
+ "mcp",
23
+ "model-context-protocol",
24
+ "dropbg",
25
+ "remove-bg",
26
+ "background-removal",
27
+ "ai",
28
+ "image-processing",
29
+ "claude",
30
+ "cursor",
31
+ "deepseek",
32
+ "qwen",
33
+ "kimi",
34
+ "glm",
35
+ "trae",
36
+ "cherry-studio",
37
+ "cline",
38
+ "roo-code",
39
+ "ollama"
40
+ ],
41
+ "engines": {
42
+ "node": ">=18.0.0"
43
+ }
44
+ }
package/server.json ADDED
@@ -0,0 +1,22 @@
1
+ {
2
+ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
3
+ "name": "io.dropbg/dropbg-mcp",
4
+ "description": "Free AI background removal MCP server for local image files and public URLs via dropbg.io.",
5
+ "status": "active",
6
+ "repository": {
7
+ "url": "https://dropbg.io",
8
+ "source": "github"
9
+ },
10
+ "version": "1.0.1",
11
+ "packages": [
12
+ {
13
+ "registryType": "npm",
14
+ "registryBaseUrl": "https://registry.npmjs.org",
15
+ "identifier": "dropbg-mcp",
16
+ "version": "1.0.1",
17
+ "transport": {
18
+ "type": "stdio"
19
+ }
20
+ }
21
+ ]
22
+ }