copyseeker-mcp-server 1.0.4 → 2.0.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 CopySeeker
+Copyright (c) 2025 Copyseeker
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,159 +1,131 @@
 # Copyseeker MCP Server
 
-A Model Context Protocol (MCP) server that integrates Copyseeker's powerful reverse image search API with Claude and other MCP-compatible AI assistants.
+Give Claude, Cursor, VS Code Copilot, Windsurf, OpenAI Codex, Gemini CLI and any other [MCP](https://modelcontextprotocol.io) client three image tools from [Copyseeker](https://copyseeker.net):
 
-## Features
+| Tool | What it does | Cost |
+|---|---|---|
+| `reverse_image_search` | Finds the web pages that show an image, ranked by prominence, with the copies each page uses | 1 search |
+| `detect_ai_image` | Tells whether an image is AI-generated, with a confidence score | 0.01 searches |
+| `detect_nsfw` | Tells whether an image contains nudity or sexual content, with a confidence score | 0.01 searches |
 
-- 🔍 **Reverse Image Search**: Find similar images and their sources across the web
-- 🖼️ **Multiple Input Methods**: Search by URL or upload images directly
-- 📊 **Detailed Results**: Get comprehensive metadata about found images
-- ⚡ **Fast & Reliable**: Powered by Copyseeker's robust API infrastructure
-- 🔒 **Secure**: Your API key stays local, never shared
+Each tool takes a direct image URL or the path to a local image file (up to 20 MB). Calls draw from the same search balance as the website, Monitor and the [Copyseeker API](https://copyseeker.net/apis).
 
-## Quick Start
+## Requirements
 
-### 1. Install the MCP Server
+- Node.js 20 or newer
+- A paid Copyseeker plan and an API key: create one under **Account → Developers** at [copyseeker.net/account](https://copyseeker.net/account#api)
 
-```bash
-npm install -g copyseeker-mcp-server
-```
-
-### 2. Get Your API Key
+## Setup
 
-1. Visit [RapidAPI Copyseeker](https://rapidapi.com/copyseeker1-copyseeker-default/api/reverse-image-search-by-copyseeker/)
-2. Subscribe to a plan (free tier available)
-3. Copy your RapidAPI key
+### Claude Code
 
-### 3. Configure Claude Desktop
+```bash
+claude mcp add copyseeker -e COPYSEEKER_API_KEY=your_api_key -- npx -y copyseeker-mcp-server
+```
 
-Add this to your Claude Desktop configuration file:
+### Claude Desktop
 
-**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
+Add this to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`), then restart Claude Desktop:
 
 ```json
 {
   "mcpServers": {
     "copyseeker": {
-      "command": "copyseeker-mcp",
+      "command": "npx",
+      "args": ["-y", "copyseeker-mcp-server"],
       "env": {
-        "COPYSEEKER_RAPIDAPI_KEY": "your_rapidapi_key_here"
+        "COPYSEEKER_API_KEY": "your_api_key"
       }
     }
   }
 }
 ```
 
-### 4. Restart Claude Desktop
+### Cursor
 
-The Copyseeker tools will now be available in Claude!
+Add the same `mcpServers` entry as for Claude Desktop to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project).
 
-## Usage Examples
+### VS Code (GitHub Copilot)
 
-### Complete Reverse Image Search
-```
-Can you do a complete reverse search on: https://copyseeker.net/assets/img/pc.png
-```
+Add this to `.vscode/mcp.json` in your project. VS Code asks for the key on first use and stores it securely:
 
-### Copyright & Source Verification
-```
-I need to check if I can legally use this image. Please analyze: [image URL]
-```
-
-### Find Exact Matches
-```
-Where exactly does this image appear online? [image URL]
-```
-
-### Find Design Inspiration
-```
-Show me images that look similar to this design for inspiration: [image URL]
-```
-
-### Page Authority Assessment
-```
-Which website is the most credible source for this image? [image URL]
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "copyseeker-api-key",
+      "description": "Copyseeker API key",
+      "password": true
+    }
+  ],
+  "servers": {
+    "copyseeker": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "copyseeker-mcp-server"],
+      "env": {
+        "COPYSEEKER_API_KEY": "${input:copyseeker-api-key}"
+      }
+    }
+  }
+}
 ```
 
-## Available Tools
+Then use the tools from Copilot Chat in agent mode.
 
-### `reverse_image_search`
-Complete reverse image search with all results formatted clearly.
+### Windsurf
 
-**Parameters:**
-- `image_url` (required): Direct URL to the image
+Add the same `mcpServers` entry as for Claude Desktop to `~/.codeium/windsurf/mcp_config.json`.
 
-**Returns:**
-- AI analysis of what the image represents
-- Exact matches (websites containing the same image)
-- Visually similar images (different images that look alike)
-- Page authority scores for credibility assessment
-- AI-detected categories with confidence scores
+### OpenAI Codex CLI
 
-### `analyze_image_copyright`
-Specialized copyright and usage rights analysis.
+Add this to `~/.codex/config.toml`:
 
-**Parameters:**
-- `image_url` (required): URL of the image to analyze
+```toml
+[mcp_servers.copyseeker]
+command = "npx"
+args = ["-y", "copyseeker-mcp-server"]
+env = { COPYSEEKER_API_KEY = "your_api_key" }
+```
 
-**Returns:**
-- Copyright risk assessment based on where image appears
-- Source credibility ranking by page authority
-- Usage recommendations and next steps
-- Likely original source identification
+### Gemini CLI
 
-### `find_exact_matches`
-Find websites containing the exact same image.
+Add the same `mcpServers` entry as for Claude Desktop to `~/.gemini/settings.json`.
 
-**Parameters:**
-- `image_url` (required): URL of the image to find matches for
+### Other clients
 
-**Returns:**
-- List of websites with the exact same image
-- Page authority scores (higher = more credible source)
-- Direct URLs to image files on each site
-- Summary of distribution patterns
+Any MCP client that can launch a local (stdio) server works. Configure it to run `npx -y copyseeker-mcp-server` with the `COPYSEEKER_API_KEY` environment variable set.
 
-### `find_similar_images`
-Discover visually similar images for inspiration and alternatives.
+ChatGPT connectors only accept remote MCP servers reached over HTTPS, so this local server does not work there.
 
-**Parameters:**
-- `image_url` (required): URL of the image to find similarities for
+## Examples
 
-**Returns:**
-- URLs to different images that look visually similar
-- Common visual elements and themes
-- Use cases for similar images
-- Style and category analysis
+- "Where else on the web does https://example.com/photo.jpg appear? Who published it first?"
+- "Is ~/Downloads/portrait.png AI-generated?"
+- "Check these five product images for NSFW content before I upload them."
 
-## Pricing
+## Errors
 
-[View all pricing plans →](https://rapidapi.com/copyseeker1-copyseeker-default/api/reverse-image-search-by-copyseeker/pricing)
+Failures come back to the assistant as plain explanations it can act on: an invalid key, a missing plan, an empty balance (with the top-up link), the rate limit of 60 calls per minute (with how long to wait), or a URL that points to a web page instead of an image. A search that fails on Copyseeker's side is refunded.
 
-## Troubleshooting
+## Upgrading from 1.x
 
-### "API key required" error
-Make sure you've set the `COPYSEEKER_RAPIDAPI_KEY` environment variable in your Claude configuration.
+Version 2 calls the Copyseeker API directly instead of RapidAPI:
 
-### "Rate limit exceeded"
-Check your usage on the [RapidAPI dashboard](https://rapidapi.com/developer/dashboard) and consider upgrading your plan.
+- Replace `COPYSEEKER_RAPIDAPI_KEY` with `COPYSEEKER_API_KEY`, a key from your Copyseeker account.
+- The tools are now `reverse_image_search`, `detect_ai_image` and `detect_nsfw`. `analyze_image_copyright`, `find_exact_matches` and `find_similar_images` are gone: `reverse_image_search` covers them.
+- Node.js 20 or newer is required.
 
-### "Image not found" error
-Ensure the image URL is directly accessible and points to a valid image file (not a webpage containing an image).
+## Development
 
-## Support
+```bash
+npm install
+npm test        # builds, then runs the server against a fake Copyseeker API
+```
 
-- 🌐 Website: [copyseeker.net](https://copyseeker.net)
-- 📚 API Documentation: [RapidAPI Docs](https://rapidapi.com/copyseeker1-copyseeker-default/api/reverse-image-search-by-copyseeker/)
+`COPYSEEKER_API_URL` points the server at another API base URL (default `https://api.copyseeker.net`).
 
 ## License
 
-MIT License - see LICENSE file for details.
-
-## Contributing
-
-We welcome contributions! Please see our contributing guidelines and submit pull requests to our GitHub repository.
-
----
-
-**Made with ❤️ by the Copyseeker team**
+MIT

package/build/client.js

@@ -0,0 +1,121 @@
+import { readFile, stat } from "node:fs/promises";
+import { basename, extname } from "node:path";
+import { fileURLToPath } from "node:url";
+export const DEFAULT_API_URL = "https://api.copyseeker.net";
+export const MAX_FILE_BYTES = 20 * 1024 * 1024;
+// Reverse image search can take tens of seconds on images found on many pages.
+const REQUEST_TIMEOUT_MS = 120_000;
+const MIME_TYPES = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+    ".tif": "image/tiff",
+    ".tiff": "image/tiff",
+    ".heic": "image/heic",
+    ".heif": "image/heif",
+    ".avif": "image/avif",
+};
+// A failure the assistant can explain to the user and often fix (new key, top-up, other image).
+export class CopyseekerError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "CopyseekerError";
+    }
+}
+export class CopyseekerClient {
+    apiKey;
+    apiUrl;
+    fetchImpl;
+    constructor(apiKey, apiUrl = DEFAULT_API_URL, fetchImpl = fetch) {
+        this.apiKey = apiKey;
+        this.apiUrl = apiUrl;
+        this.fetchImpl = fetchImpl;
+    }
+    async call(endpoint, image) {
+        const source = image.trim();
+        const headers = { "X-API-Key": this.apiKey, Accept: "application/json" };
+        let response;
+        try {
+            if (isHttpUrl(source)) {
+                const url = `${this.apiUrl}/${endpoint}?imageUrl=${encodeURIComponent(source)}`;
+                response = await this.fetchImpl(url, { headers, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+            }
+            else {
+                const body = new FormData();
+                const file = await readImageFile(source);
+                body.append("file", new Blob([file.bytes], { type: file.mimeType }), file.name);
+                response = await this.fetchImpl(`${this.apiUrl}/${endpoint}`, { method: "POST", headers, body, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+            }
+        }
+        catch (error) {
+            if (error instanceof CopyseekerError) {
+                throw error;
+            }
+            if (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError")) {
+                throw new CopyseekerError(`Copyseeker did not answer within ${REQUEST_TIMEOUT_MS / 1000} seconds. Try again in a moment.`, "TIMEOUT");
+            }
+            throw new CopyseekerError(`Could not reach Copyseeker (${error instanceof Error ? error.message : String(error)}). Check the internet connection.`, "NETWORK_ERROR");
+        }
+        if (response.ok) {
+            return (await response.json());
+        }
+        throw await toError(response);
+    }
+}
+export function isHttpUrl(value) {
+    return /^https?:\/\//i.test(value);
+}
+async function readImageFile(source) {
+    const path = source.toLowerCase().startsWith("file://") ? fileURLToPath(source) : source;
+    let size;
+    try {
+        const info = await stat(path);
+        if (!info.isFile()) {
+            throw new CopyseekerError(`"${source}" is not a file. Pass a direct image URL (http/https) or the path to a local image file.`, "INVALID_IMAGE");
+        }
+        size = info.size;
+    }
+    catch (error) {
+        if (error instanceof CopyseekerError) {
+            throw error;
+        }
+        throw new CopyseekerError(`"${source}" is neither an http(s) image URL nor a readable local file.`, "INVALID_IMAGE");
+    }
+    if (size === 0 || size > MAX_FILE_BYTES) {
+        throw new CopyseekerError(`"${source}" is ${size === 0 ? "empty" : "larger than 20 MB"}. Copyseeker accepts images up to 20 MB.`, "INVALID_IMAGE");
+    }
+    const name = basename(path);
+    return { bytes: new Uint8Array(await readFile(path)), name, mimeType: MIME_TYPES[extname(name).toLowerCase()] ?? "application/octet-stream" };
+}
+async function toError(response) {
+    let code = "";
+    try {
+        code = (await response.json())?.error ?? "";
+    }
+    catch {
+        // Not JSON (a gateway error page); the status code still tells what happened.
+    }
+    switch (code) {
+        case "INVALID_API_KEY":
+            return new CopyseekerError("The Copyseeker API key is missing or invalid. Create one at https://copyseeker.net/account#api and set it as COPYSEEKER_API_KEY in the MCP server config.", code);
+        case "PLAN_REQUIRED":
+            return new CopyseekerError("API access needs a paid Copyseeker plan. See https://copyseeker.net/pricing.", code);
+        case "QUOTA_EXHAUSTED":
+            return new CopyseekerError("The Copyseeker account has no searches left for this call. Top up at https://copyseeker.net/account#searches or wait for the monthly reset.", code);
+        case "RATE_LIMITED": {
+            const retryAfter = response.headers.get("Retry-After");
+            return new CopyseekerError(`Copyseeker's rate limit (60 calls per minute) was hit. Retry after ${retryAfter ?? "a few"} seconds.`, code);
+        }
+        case "INVALID_IMAGE":
+            return new CopyseekerError("Copyseeker could not read an image there. Use a direct link to the image file itself (not a web page that shows it), or a local file path. Nothing was charged.", code);
+        case "SEARCH_FAILED":
+            return new CopyseekerError("The search failed on Copyseeker's side and its searches were refunded. Try again.", code);
+        default:
+            return new CopyseekerError(`Copyseeker answered HTTP ${response.status}${code ? ` (${code})` : ""}.`, code || `HTTP_${response.status}`);
+    }
+}

package/build/index.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { CopyseekerClient, DEFAULT_API_URL } from "./client.js";
+import { createServer } from "./server.js";
+const apiKey = process.env.COPYSEEKER_API_KEY?.trim();
+if (!apiKey) {
+    // stdout carries the protocol, so everything for people goes to stderr.
+    console.error("COPYSEEKER_API_KEY is not set. Create an API key at https://copyseeker.net/account#api and add it to this server's env in your MCP client config.");
+    process.exit(1);
+}
+const client = new CopyseekerClient(apiKey, process.env.COPYSEEKER_API_URL?.trim() || DEFAULT_API_URL);
+// One factory serves both clients that open with the 2025 initialize handshake and stateless 2026-07-28 clients.
+serveStdio(() => createServer(client), {
+    onerror: (error) => {
+        console.error(`[copyseeker-mcp] ${error.message}`);
+    },
+});

package/build/server.js

@@ -0,0 +1,84 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { CopyseekerError, } from "./client.js";
+export const SERVER_NAME = "copyseeker";
+export const SERVER_VERSION = "2.0.1";
+const DEFAULT_MAX_RESULTS = 25;
+const INSTRUCTIONS = `Copyseeker tools work on one image each, given as a direct image URL (http/https) or the path to a local image file.
+Each call is charged to the user's Copyseeker searches: reverse_image_search 1, detect_ai_image 0.01, detect_nsfw 0.01.
+Call a tool once per image and question; do not repeat a call that already succeeded.`;
+const imageInput = z
+    .string()
+    .min(1)
+    .describe("Direct URL of the image file (http or https, not the web page showing it), or the absolute path to a local image file up to 20 MB.");
+const SEARCH_ANNOTATIONS = { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true };
+export function createServer(client) {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, { instructions: INSTRUCTIONS });
+    server.registerTool("reverse_image_search", {
+        title: "Reverse image search",
+        description: "Find the web pages that show this image, with the copies of it each page uses, ranked by how prominent the page is. " +
+            "Use it to find where an image came from, who published it first, or where it is reused without permission. Costs 1 search.",
+        inputSchema: z.object({
+            image: imageInput,
+            max_results: z.number().int().min(1).max(100).default(DEFAULT_MAX_RESULTS).describe("Most pages to return, best ranked first."),
+        }),
+        outputSchema: z.object({
+            totalPages: z.number().int().describe("Pages Copyseeker found, before max_results."),
+            pages: z.array(z.object({
+                url: z.string(),
+                title: z.string().nullable(),
+                rank: z.number().describe("Page prominence; lower is more prominent."),
+                matchingImages: z.array(z.string()).describe("URLs of the copies of the image on this page."),
+            })),
+        }),
+        annotations: { ...SEARCH_ANNOTATIONS, title: "Reverse image search" },
+    }, async ({ image, max_results }) => {
+        return run(async () => {
+            const result = await client.call("reverse-image-search", image);
+            const pages = result.pages ?? [];
+            return { totalPages: pages.length, pages: pages.slice(0, max_results) };
+        });
+    });
+    server.registerTool("detect_ai_image", {
+        title: "Detect AI-generated image",
+        description: "Tell whether an image was generated by AI (Midjourney, DALL-E, Stable Diffusion, Flux and similar) or is a real photo or artwork. Costs 0.01 searches.",
+        inputSchema: z.object({ image: imageInput }),
+        outputSchema: z.object({
+            isAiGenerated: z.boolean(),
+            confidence: z.number().min(0).max(1).describe("How sure the verdict is, from 0 to 1."),
+        }),
+        annotations: { ...SEARCH_ANNOTATIONS, title: "Detect AI-generated image" },
+    }, async ({ image }) => {
+        return run(async () => {
+            const result = await client.call("ai-detection", image);
+            return { isAiGenerated: result.isAiGenerated, confidence: result.confidence };
+        });
+    });
+    server.registerTool("detect_nsfw", {
+        title: "Detect NSFW image",
+        description: "Tell whether an image contains nudity or sexual content that is not safe for work. Costs 0.01 searches.",
+        inputSchema: z.object({ image: imageInput }),
+        outputSchema: z.object({
+            isNsfw: z.boolean(),
+            confidence: z.number().min(0).max(1).describe("How sure the verdict is, from 0 to 1."),
+        }),
+        annotations: { ...SEARCH_ANNOTATIONS, title: "Detect NSFW image" },
+    }, async ({ image }) => {
+        return run(async () => {
+            const result = await client.call("nsfw-detection", image);
+            return { isNsfw: result.isNsfw, confidence: result.confidence };
+        });
+    });
+    return server;
+}
+// Copyseeker failures go back to the model as tool errors it can read and act on, not as protocol errors.
+async function run(call) {
+    try {
+        const output = await call();
+        return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }], structuredContent: output };
+    }
+    catch (error) {
+        const message = error instanceof CopyseekerError ? error.message : `Unexpected error: ${error instanceof Error ? error.message : String(error)}`;
+        return { content: [{ type: "text", text: message }], isError: true };
+    }
+}

package/package.json

@@ -1,55 +1,57 @@
 {
-    "name": "copyseeker-mcp-server",
-    "version": "1.0.4",
-    "description": "MCP server for CopySeeker reverse image search API - find similar images and sources",
-    "main": "build/index.js",
-    "bin": {
-        "copyseeker-mcp": "build/index.js"
-    },
-    "type": "module",
-    "scripts": {
-        "build": "tsc",
-        "start": "node build/index.js",
-        "dev": "tsx src/index.ts",
-        "prepublishOnly": "npm run build"
-    },
-    "dependencies": {
-        "@modelcontextprotocol/sdk": "^0.4.0",
-        "axios": "^1.6.0"
-    },
-    "devDependencies": {
-        "@types/node": "^20.0.0",
-        "typescript": "^5.0.0",
-        "tsx": "^4.0.0"
-    },
-    "keywords": [
-        "mcp",
-        "model-context-protocol",
-        "reverse-image-search",
-        "copyseeker",
-        "claude",
-        "image-search",
-        "similar-images",
-        "reverse-search",
-        "copyright-check",
-        "image-analysis"
-    ],
-    "author": "CopySeeker <support@copyseeker.net>",
-    "license": "MIT",
-    "homepage": "https://copyseeker.net",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/copyseeker/copyseeker-mcp-server.git"
-    },
-    "bugs": {
-        "url": "https://github.com/copyseeker/copyseeker-mcp-server/issues"
-    },
-    "engines": {
-        "node": ">=18.0.0"
-    },
-    "files": [
-        "build/**/*",
-        "README.md",
-        "LICENSE"
-    ]
+  "name": "copyseeker-mcp-server",
+  "version": "2.0.1",
+  "description": "MCP server for Copyseeker: reverse image search, AI image detection and NSFW detection for Claude, Cursor, VS Code Copilot, Codex, Gemini CLI and other AI assistants",
+  "type": "module",
+  "bin": {
+    "copyseeker-mcp": "build/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test --import tsx \"test/**/*.test.ts\"",
+    "start": "node build/index.js",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.4.0",
+    "zod": "^4.2.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "^2.4.0",
+    "@types/node": "^20.19.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "copyseeker",
+    "reverse-image-search",
+    "ai-image-detection",
+    "nsfw-detection",
+    "image-search",
+    "copyright",
+    "mcp-server",
+    "claude",
+    "cursor",
+    "vscode",
+    "copilot",
+    "codex",
+    "gemini",
+    "ai-detection",
+    "deepfake-detection"
+  ],
+  "author": "Copyseeker <support@copyseeker.net>",
+  "license": "MIT",
+  "homepage": "https://copyseeker.net/apis",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "build/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "mcpName": "net.copyseeker/mcp"
 }