aimetadatacleaner-mcp 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# AI Metadata Cleaner MCP server
+
+Remove hidden metadata from your files by asking your AI assistant:
+
+> "Remove the location and camera details from the videos in ~/Downloads/trip"
+
+It removes GPS locations and tracks, phone and camera models, serial numbers, dates, author and
+software names, and AI-generation labels from:
+
+- **Video:** MP4, MOV, M4V, 3GP, MKV, WebM (video and sound are not re-encoded)
+- **PDF**
+- **Camera RAW:** CR2, CR3, NEF, ARW, RAF, RW2, DNG
+- **Photos:** JPEG, PNG, WebP
+
+Each file is sent to the [AI Metadata Cleaner](https://aimetadatacleaner.com) server, cleaned,
+checked, and saved next to the original as `name-clean.ext`. Your originals are never changed.
+Files are deleted from the server right after cleaning, and the clean copy right after it is
+downloaded.
+
+## You need
+
+- Node.js 18.17 or newer
+- An API key. Keys come with the Business plan: <https://aimetadatacleaner.com/api-keys>
+
+## Set up
+
+**Claude Desktop** — Settings → Developer → Edit Config, then add:
+
+```json
+{
+  "mcpServers": {
+    "aimetadatacleaner": {
+      "command": "npx",
+      "args": ["-y", "aimetadatacleaner-mcp"],
+      "env": { "AMC_API_KEY": "amc_live_..." }
+    }
+  }
+}
+```
+
+**Claude Code**
+
+```sh
+claude mcp add aimetadatacleaner -e AMC_API_KEY=amc_live_... -- npx -y aimetadatacleaner-mcp
+```
+
+**Cursor** — add the same block as Claude Desktop to `~/.cursor/mcp.json`.
+
+Full guide for every app: <https://aimetadatacleaner.com/mcp>
+
+## Tools
+
+- `clean_files` — clean files or folders (a folder means the supported files directly inside it).
+  Options: `output_dir`, `image_mode` (`reencode` or `strip`), `keep_pdf_signature`.
+- `check_usage` — jobs and data used this month.
+
+Each file is one job from your monthly allowance.

package/index.js

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+/**
+ * AI Metadata Cleaner — MCP server for AI assistants (Claude Desktop, Claude Code, Cursor, ...).
+ *
+ * A thin client: it reads the user's files from disk, sends each one to the AI Metadata Cleaner
+ * API, and saves the clean copy next to the original. All cleaning and all counting happen on
+ * the server, so this package holds no cleaning logic and nothing here can skip the plan limits.
+ *
+ * Needs AMC_API_KEY (a Business key from https://aimetadatacleaner.com/api-keys).
+ */
+import { createReadStream, createWriteStream } from 'node:fs';
+import { stat, readdir, rename, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const VERSION = '0.1.0';
+const API = (process.env.AMC_API_URL || 'https://api.aimetadatacleaner.com').replace(/\/+$/, '');
+const KEY = (process.env.AMC_API_KEY || '').trim();
+const KEYS_URL = 'https://aimetadatacleaner.com/api-keys';
+const MAX_FILES = 50;
+
+// What the server cleans. HEIC is cleaned in the browser on the website, not by the API.
+const SUPPORTED = new Set([
+  '.mp4', '.mov', '.m4v', '.3gp', '.mkv', '.webm',
+  '.pdf',
+  '.cr2', '.cr3', '.nef', '.arw', '.raf', '.rw2', '.dng',
+  '.jpg', '.jpeg', '.png', '.webp'
+]);
+
+const LABELS = {
+  clean: 'Clean',
+  unverified: 'Cleaned, but not everything could be confirmed removed',
+  failed: 'Not cleaned',
+  not_sent: 'Not sent'
+};
+
+class ApiError extends Error {
+  constructor(status, code, message, retryAfter) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.retryAfter = retryAfter;
+  }
+}
+
+function expandHome(p) {
+  return p === '~' || p.startsWith('~/') ? path.join(homedir(), p.slice(1)) : p;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function apiError(res) {
+  let code = `http_${res.status}`;
+  let message = `The server answered ${res.status}.`;
+  try {
+    const body = await res.json();
+    if (body?.error) ({ code, message } = body.error);
+  } catch {}
+  return new ApiError(res.status, code, message, Number(res.headers.get('retry-after')) || 0);
+}
+
+function authHeaders() {
+  return { Authorization: `Bearer ${KEY}`, 'User-Agent': `aimetadatacleaner-mcp/${VERSION}` };
+}
+
+/** Busy (503) and rate-limited (429) are worth one wait-and-retry; everything else is final. */
+async function withRetry(fn) {
+  try {
+    return await fn();
+  } catch (e) {
+    if (e instanceof ApiError && (e.status === 429 || e.status === 503)) {
+      await sleep(Math.min(Math.max(e.retryAfter, 5), 60) * 1000);
+      return fn();
+    }
+    throw e;
+  }
+}
+
+async function uploadAndClean(file, size, options) {
+  const query = new URLSearchParams();
+  if (options.mode) query.set('mode', options.mode);
+  if (options.keep_pdf_signature) query.set('keep_signature', 'true');
+  const qs = query.toString();
+  const res = await fetch(`${API}/v1/clean${qs ? `?${qs}` : ''}`, {
+    method: 'POST',
+    headers: {
+      ...authHeaders(),
+      'Content-Type': 'application/octet-stream',
+      'Content-Length': String(size),
+      // Only the extension matters to the server (some formats are detected by it). Header
+      // values must be plain ASCII, and the saved name is chosen here from the real one anyway.
+      'X-Filename': `upload${path.extname(file).toLowerCase().replace(/[^.a-z0-9]/g, '')}`
+    },
+    body: Readable.toWeb(createReadStream(file)),
+    duplex: 'half'
+  });
+  if (!res.ok) throw await apiError(res);
+  return res.json();
+}
+
+/** A name next to the original that doesn't exist yet: photo-clean.jpg, photo-clean (2).jpg ... */
+async function freeName(dir, stem, ext) {
+  for (let n = 1; ; n++) {
+    const candidate = path.join(dir, `${stem}-clean${n > 1 ? ` (${n})` : ''}${ext}`);
+    try {
+      await stat(candidate);
+    } catch {
+      return candidate;
+    }
+  }
+}
+
+function extFromDisposition(header) {
+  const m = /filename\*?=(?:UTF-8'')?"?([^";]+)"?/i.exec(header || '');
+  return m ? path.extname(decodeURIComponent(m[1])).toLowerCase() : '';
+}
+
+async function download(url, file, outputDir) {
+  const res = await fetch(url, { headers: { 'User-Agent': `aimetadatacleaner-mcp/${VERSION}` } });
+  if (!res.ok || !res.body) throw await apiError(res);
+  // The server may change the extension (e.g. a converted image), so take it from the reply.
+  const ext = extFromDisposition(res.headers.get('content-disposition')) || path.extname(file);
+  const dest = await freeName(outputDir || path.dirname(file), path.basename(file, path.extname(file)), ext);
+  const partial = `${dest}.part`;
+  try {
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(partial, { flags: 'wx' }));
+    await rename(partial, dest);
+  } catch (e) {
+    await unlink(partial).catch(() => {});
+    throw e;
+  }
+  return dest;
+}
+
+/** Files named directly, plus the supported files directly inside any folder named. */
+async function collect(paths) {
+  const files = [];
+  const skipped = [];
+  for (const raw of paths) {
+    const p = path.resolve(expandHome(raw));
+    let s;
+    try {
+      s = await stat(p);
+    } catch {
+      skipped.push({ path: p, reason: 'not found' });
+      continue;
+    }
+    if (s.isDirectory()) {
+      for (const entry of (await readdir(p, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isFile() || entry.name.startsWith('.')) continue;
+        const ext = path.extname(entry.name).toLowerCase();
+        // Earlier clean copies sit in the same folder; cleaning them again would just use up jobs.
+        if (!SUPPORTED.has(ext) || /-clean( \(\d+\))?$/.test(path.basename(entry.name, ext))) continue;
+        files.push(path.join(p, entry.name));
+      }
+    } else if (s.isFile()) {
+      files.push(p);
+    } else {
+      skipped.push({ path: p, reason: 'not a file' });
+    }
+  }
+  return { files: [...new Set(files)], skipped };
+}
+
+function describe(r) {
+  const lines = [`${path.basename(r.source)}: ${LABELS[r.status] || r.status}`];
+  if (r.saved_to) lines.push(`  saved to: ${r.saved_to}`);
+  if (r.removed?.length) lines.push(`  removed: ${r.removed.join(', ')}`);
+  if (r.kept?.length) lines.push(`  kept on purpose: ${r.kept.join(', ')}`);
+  if (r.left && Object.keys(r.left).length) lines.push(`  still present: ${Object.keys(r.left).join(', ')}`);
+  for (const n of r.notes || []) lines.push(`  note: ${n}`);
+  for (const p of r.problems || []) lines.push(`  problem: ${p}`);
+  if (r.error) lines.push(`  ${r.error}`);
+  return lines.join('\n');
+}
+
+function noKey() {
+  return {
+    isError: true,
+    content: [{
+      type: 'text',
+      text: `No API key is set. Add AMC_API_KEY to this MCP server's settings. Keys come with the Business plan: ${KEYS_URL}`
+    }]
+  };
+}
+
+const server = new McpServer({ name: 'aimetadatacleaner', version: VERSION });
+
+server.registerTool(
+  'clean_files',
+  {
+    title: 'Remove metadata from files',
+    description:
+      'Removes hidden metadata (GPS location, camera or phone model, serial numbers, dates, author, ' +
+      'software, AI-generation labels and credentials) from videos (MP4, MOV, M4V, 3GP, MKV, WebM), ' +
+      'PDFs, camera RAW files (CR2, CR3, NEF, ARW, RAF, RW2, DNG) and photos (JPEG, PNG, WebP). ' +
+      'Each file is sent to the AI Metadata Cleaner server, cleaned, and a clean copy is saved next ' +
+      'to the original as "<name>-clean.<ext>". Originals are never changed. Video and audio are not ' +
+      're-encoded. Pass files or folders (a folder means the supported files directly inside it). ' +
+      `Each file uses one job from the monthly allowance. At most ${MAX_FILES} files per call.`,
+    inputSchema: {
+      paths: z.array(z.string()).min(1).describe('Absolute paths to files or folders. ~ is allowed.'),
+      output_dir: z.string().optional().describe('Folder to save clean copies in. Default: next to each original.'),
+      image_mode: z.enum(['reencode', 'strip']).optional()
+        .describe('Photos only. "reencode" (default) rebuilds the image, the most thorough. "strip" removes metadata without touching the pixels.'),
+      keep_pdf_signature: z.boolean().optional()
+        .describe('PDFs only. Keep a digital signature (it carries the signer and signing date). Default false: signatures are removed.')
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+  },
+  async ({ paths, output_dir, image_mode, keep_pdf_signature }, extra) => {
+    if (!KEY) return noKey();
+
+    let outputDir;
+    if (output_dir) {
+      outputDir = path.resolve(expandHome(output_dir));
+      const s = await stat(outputDir).catch(() => null);
+      if (!s?.isDirectory()) {
+        return { isError: true, content: [{ type: 'text', text: `Output folder not found: ${outputDir}` }] };
+      }
+    }
+
+    const { files, skipped } = await collect(paths);
+    if (!files.length) {
+      const why = skipped.map((s) => `${s.path}: ${s.reason}`).join('\n');
+      return { isError: true, content: [{ type: 'text', text: `No files to clean.${why ? `\n${why}` : ''}` }] };
+    }
+    if (files.length > MAX_FILES) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: `That is ${files.length} files. Send at most ${MAX_FILES} per call.` }]
+      };
+    }
+
+    const progressToken = extra?._meta?.progressToken;
+    const results = [];
+    let stop = null;
+    for (const [i, file] of files.entries()) {
+      if (progressToken !== undefined) {
+        await extra.sendNotification({
+          method: 'notifications/progress',
+          params: { progressToken, progress: i, total: files.length, message: `Cleaning ${path.basename(file)}` }
+        }).catch(() => {});
+      }
+      if (stop) {
+        results.push({ source: file, status: 'not_sent', error: 'Not sent: stopped after the error above.' });
+        continue;
+      }
+      try {
+        const { size } = await stat(file);
+        const report = await withRetry(() =>
+          uploadAndClean(file, size, { mode: image_mode, keep_pdf_signature })
+        );
+        const saved = await download(report.download_url, file, outputDir);
+        results.push({
+          source: file,
+          saved_to: saved,
+          status: report.status,
+          file_type: report.file_type,
+          removed: report.removed,
+          kept: report.kept,
+          left: report.left,
+          notes: report.notes,
+          problems: report.problems,
+          usage: report.usage
+        });
+      } catch (e) {
+        const message = e instanceof ApiError ? e.message : `Could not reach the server: ${e.message}`;
+        results.push({ source: file, status: 'failed', error: message });
+        // Out of allowance, bad key or no API on this plan: every remaining file would fail the same way.
+        if (e instanceof ApiError && (e.status === 401 || e.status === 402 || e.status === 403)) stop = e;
+      }
+    }
+
+    const cleaned = results.filter((r) => r.saved_to).length;
+    const last = [...results].reverse().find((r) => r.usage)?.usage;
+    const summary = [
+      `Cleaned ${cleaned} of ${files.length} file${files.length === 1 ? '' : 's'}.`,
+      ...(last ? [`Jobs used this month: ${last.jobs_used.toLocaleString('en-US')} of ${last.job_limit.toLocaleString('en-US')}.`] : []),
+      '',
+      ...results.map(describe),
+      ...skipped.map((s) => `${s.path}: skipped (${s.reason})`)
+    ].join('\n');
+
+    return {
+      isError: cleaned === 0,
+      content: [{ type: 'text', text: summary }],
+      structuredContent: { cleaned, total: files.length, results, skipped }
+    };
+  }
+);
+
+server.registerTool(
+  'check_usage',
+  {
+    title: 'Check monthly allowance',
+    description: 'Shows how many cleaning jobs and how much data this month\'s plan has used and allows.',
+    inputSchema: {},
+    annotations: { readOnlyHint: true, openWorldHint: true }
+  },
+  async () => {
+    if (!KEY) return noKey();
+    try {
+      const res = await fetch(`${API}/v1/usage`, { headers: authHeaders() });
+      if (!res.ok) throw await apiError(res);
+      const u = await res.json();
+      const gb = (b) => `${(b / 1024 ** 3).toFixed(1)}GB`;
+      const text = [
+        `Plan: ${u.plan}`,
+        `Jobs: ${u.jobs_used.toLocaleString('en-US')} of ${u.job_limit.toLocaleString('en-US')} this month`,
+        `Data: ${gb(u.bytes_used)} of ${gb(u.byte_limit)} this month`,
+        `Largest file: ${gb(u.max_file_bytes)}`,
+        'Allowances reset on the 1st of each month (UTC).'
+      ].join('\n');
+      return { content: [{ type: 'text', text }], structuredContent: u };
+    } catch (e) {
+      const message = e instanceof ApiError ? e.message : `Could not reach the server: ${e.message}`;
+      return { isError: true, content: [{ type: 'text', text: message }] };
+    }
+  }
+);
+
+await server.connect(new StdioServerTransport());

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "aimetadatacleaner-mcp",
+  "version": "0.1.0",
+  "description": "Remove metadata (GPS, device, dates, AI labels) from video, PDF, RAW and photos from Claude, Cursor and other AI assistants. Uses the AI Metadata Cleaner API.",
+  "type": "module",
+  "bin": {
+    "aimetadatacleaner-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "keywords": [
+    "mcp",
+    "metadata",
+    "exif",
+    "gps",
+    "privacy",
+    "video",
+    "pdf",
+    "raw"
+  ],
+  "homepage": "https://aimetadatacleaner.com/mcp",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "zod": "^4.6.5"
+  }
+}