@translateimage/mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,23 @@
+Proprietary Software License
+
+Copyright (c) 2025 TranslateImage
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are the 
+proprietary property of TranslateImage and are protected by copyright law.
+
+You may not use, copy, modify, merge, publish, distribute, sublicense, or 
+sell copies of the Software without explicit written permission from 
+TranslateImage.
+
+The above copyright notice and this permission notice shall be included in 
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,533 @@
+# @translateimage/mcp-server
+
+MCP (Model Context Protocol) server for TranslateImage - AI-powered image translation.
+
+## Overview
+
+This package provides a Model Context Protocol server that exposes TranslateImage translation capabilities to Claude and other MCP-compatible clients. It enables AI assistants to:
+
+- Translate text in images while preserving layout
+- Extract text from images using OCR
+- Remove text from images using inpainting
+- Translate Shopify product images at scale
+
+## Installation
+
+### From npm
+
+```bash
+npm install @translateimage/mcp-server
+# or
+pnpm add @translateimage/mcp-server
+```
+
+### From source
+
+```bash
+git clone https://github.com/translateimage/mcp-server
+cd mcp-server
+pnpm install
+pnpm build
+```
+
+## Quick Start
+
+### Get Your API Key
+
+1. Go to [TranslateImage Dashboard](https://translateimage.io/dashboard)
+2. Navigate to **Settings** → **API Keys**
+3. Create a new API key for MCP integration
+
+### AI Agent Integration
+
+Add to your AI Agent configuration (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "translateimage": {
+      "command": "npx",
+      "args": ["@translateimage/mcp-server"],
+      "env": {
+        "TRANSLATEIMAGE_API_KEY": "your-translateimage-api-key"
+      }
+    }
+  }
+}
+```
+
+**Config file locations:**
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+### HTTP Server
+
+For remote access or web integrations:
+
+```bash
+# Set environment variables
+export TRANSLATEIMAGE_API_KEY=your-translateimage-api-key
+export PORT=3001
+export ALLOWED_ORIGINS=http://localhost:3000
+
+# Start HTTP server
+npx @translateimage/mcp-server --http
+```
+
+Or run directly:
+
+```bash
+node dist/bin/http.js
+```
+
+The HTTP server exposes a single endpoint:
+
+- `POST /mcp` - JSON-RPC endpoint for MCP requests
+- `GET /mcp` - Returns 405 (SSE not supported in stateless mode)
+
+## Environment Variables
+
+| Variable                 | Required | Description                                                                                                          |
+| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
+| `TRANSLATEIMAGE_API_KEY` | Yes      | Your TranslateImage API key from the dashboard. Required for all tools.                                              |
+| `ALLOWED_ORIGINS`        | No       | Comma-separated list of allowed CORS origins for HTTP server. Default: `http://localhost:3000,http://localhost:3001` |
+| `PORT`                   | No       | HTTP server port. Default: `3001`                                                                                    |
+
+## Tools Reference
+
+### Core Tools
+
+#### `translate_image`
+
+Translate text in images while preserving the original layout. Detects text, translates it to the target language, and renders the translation back onto the image.
+
+**Input:**
+
+| Parameter     | Type   | Required | Description                                                                                                                                                                                           |
+| ------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `image`       | object | Yes      | Image input (see [Image Input](#image-input))                                                                                                                                                         |
+| `target_lang` | string | Yes      | Target language code (e.g., `"en"`, `"ja"`, `"zh"`, `"es"`)                                                                                                                                           |
+| `translator`  | string | Yes      | Translator model: `"gemini-2.5-flash"`, `"deepseek"`, `"grok-4-fast"`, `"kimi-k2"`, `"gemini-3-flash"`, `"gpt-5.1"`                                                                                   |
+| `font`        | string | No       | Font for rendered text: `"NotoSans"` (default), `"WildWords"`, `"BadComic"`, `"MaShanZheng"`, `"KomikaJam"`, `"Bangers"`, `"Edo"`, `"RIDIBatang"`, `"Bushidoo"`, `"Hayah"`, `"Itim"`, `"Mogul Irina"` |
+
+**Output:**
+
+| Field             | Type   | Description                                                |
+| ----------------- | ------ | ---------------------------------------------------------- |
+| `translatedImage` | string | Base64-encoded translated image (PNG)                      |
+| `inpaintedImage`  | string | Base64-encoded image with text removed                     |
+| `textRegions`     | array  | Array of detected/translated text regions with positioning |
+
+**Example:**
+
+```json
+{
+  "image": { "url": "https://example.com/manga-page.jpg" },
+  "target_lang": "en",
+  "translator": "gemini-2.5-flash",
+  "font": "WildWords"
+}
+```
+
+---
+
+#### `extract_text`
+
+Extract text from images using OCR (Optical Character Recognition). Returns detected paragraphs with bounding boxes and detected language information.
+
+**Input:**
+
+| Parameter | Type   | Required | Description                                   |
+| --------- | ------ | -------- | --------------------------------------------- |
+| `image`   | object | Yes      | Image input (see [Image Input](#image-input)) |
+
+**Output:**
+
+| Field        | Type   | Description                                                               |
+| ------------ | ------ | ------------------------------------------------------------------------- |
+| `paragraphs` | array  | Array of detected paragraphs with text, bounding boxes, and language info |
+| `width`      | number | Image width in pixels                                                     |
+| `height`     | number | Image height in pixels                                                    |
+| `angle`      | number | Detected text angle/rotation in degrees                                   |
+
+**Paragraph structure:**
+
+```typescript
+{
+  boundingBox: [x1, y1, x2, y2],  // Bounding box coordinates
+  text: string,                   // Paragraph text
+  lines: [{                       // Array of lines
+    boundingBox: [x1, y1, x2, y2],
+    text: string,
+    words: [{
+      boundingBox: [x1, y1, x2, y2],
+      text: string,
+      confidence: number  // 0-1
+    }]
+  }],
+  detectedLanguage: {
+    language: string,    // Language name
+    code: string,        // Language code
+    confidence: number   // 0-1
+  }
+}
+```
+
+**Example:**
+
+```json
+{
+  "image": { "base64": "iVBORw0KGgo...", "mimeType": "image/png" }
+}
+```
+
+---
+
+#### `remove_text`
+
+Remove text from images using inpainting. Detects text regions and fills them with appropriate background content.
+
+**Input:**
+
+| Parameter | Type   | Required | Description                                   |
+| --------- | ------ | -------- | --------------------------------------------- |
+| `image`   | object | Yes      | Image input (see [Image Input](#image-input)) |
+
+**Output:**
+
+| Field          | Type   | Description                                            |
+| -------------- | ------ | ------------------------------------------------------ |
+| `cleanedImage` | string | Base64-encoded image with text removed/inpainted (PNG) |
+
+**Example:**
+
+```json
+{
+  "image": { "url": "https://example.com/image-with-text.png" }
+}
+```
+
+---
+
+#### `image_to_text`
+
+Extract text from images using AI and optionally translate to specified languages. Provides high-quality OCR with language detection and translation capabilities.
+
+**Input:**
+
+| Parameter         | Type     | Required | Description                                   |
+| ----------------- | -------- | -------- | --------------------------------------------- |
+| `image`           | object   | Yes      | Image input (see [Image Input](#image-input)) |
+| `targetLanguages` | string[] | No       | Target language codes for translation         |
+
+**Output:**
+
+| Field              | Type   | Description                                                         |
+| ------------------ | ------ | ------------------------------------------------------------------- |
+| `extractedText`    | string | Text extracted from the image                                       |
+| `detectedLanguage` | string | Detected language of the extracted text                             |
+| `translations`     | object | Translations keyed by language code (if `targetLanguages` provided) |
+
+**Example:**
+
+```json
+{
+  "image": { "url": "https://example.com/document.jpg" },
+  "targetLanguages": ["en", "es", "fr"]
+}
+```
+
+---
+
+### Shopify Tools
+
+#### `shopify_translate_product`
+
+Translate product images for a Shopify store. Fetches product media from Shopify and translates text in images to the target language.
+
+**Input:**
+
+| Parameter                        | Type   | Required | Description                                  |
+| -------------------------------- | ------ | -------- | -------------------------------------------- |
+| `shopifyCredentials`             | object | Yes      | Shopify credentials                          |
+| `shopifyCredentials.shopDomain`  | string | Yes      | Shop domain (e.g., `"myshop.myshopify.com"`) |
+| `shopifyCredentials.accessToken` | string | Yes      | Shopify API access token                     |
+| `productId`                      | string | Yes      | Shopify product ID                           |
+| `targetLanguage`                 | string | Yes      | Target language code                         |
+| `translator`                     | string | Yes      | Translator model                             |
+
+**Output:**
+
+| Field              | Type   | Description                 |
+| ------------------ | ------ | --------------------------- |
+| `productId`        | string | Shopify product ID          |
+| `productTitle`     | string | Product title               |
+| `status`           | string | Translation status          |
+| `imagesTranslated` | number | Number of images translated |
+
+**Example:**
+
+```json
+{
+  "shopifyCredentials": {
+    "shopDomain": "myshop.myshopify.com",
+    "accessToken": "shpat_xxxxx"
+  },
+  "productId": "gid://shopify/Product/123456789",
+  "targetLanguage": "ja",
+  "translator": "gemini-2.5-flash"
+}
+```
+
+---
+
+#### `shopify_batch_translate`
+
+Batch translate product images for multiple Shopify products.
+
+**Input:**
+
+| Parameter            | Type     | Required | Description                  |
+| -------------------- | -------- | -------- | ---------------------------- |
+| `shopifyCredentials` | object   | Yes      | Shopify credentials          |
+| `productIds`         | string[] | Yes      | Array of Shopify product IDs |
+| `targetLanguage`     | string   | Yes      | Target language code         |
+| `translator`         | string   | Yes      | Translator model             |
+
+**Output:**
+
+| Field            | Type   | Description                |
+| ---------------- | ------ | -------------------------- |
+| `totalProducts`  | number | Total products processed   |
+| `successCount`   | number | Successful translations    |
+| `failureCount`   | number | Failed translations        |
+| `targetLanguage` | string | Target language used       |
+| `results`        | array  | Individual product results |
+
+**Example:**
+
+```json
+{
+  "shopifyCredentials": {
+    "shopDomain": "myshop.myshopify.com",
+    "accessToken": "shpat_xxxxx"
+  },
+  "productIds": ["gid://shopify/Product/123", "gid://shopify/Product/456"],
+  "targetLanguage": "en",
+  "translator": "deepseek"
+}
+```
+
+---
+
+#### `shopify_shop_stats`
+
+Get statistics about a Shopify shop including total products, products with images, and total image count.
+
+**Input:**
+
+| Parameter            | Type   | Required | Description         |
+| -------------------- | ------ | -------- | ------------------- |
+| `shopifyCredentials` | object | Yes      | Shopify credentials |
+
+**Output:**
+
+| Field                | Type    | Description                           |
+| -------------------- | ------- | ------------------------------------- |
+| `shopName`           | string  | Shop name                             |
+| `totalProducts`      | number  | Total products in shop                |
+| `productsWithImages` | number  | Products with at least one image      |
+| `totalImages`        | number  | Total image count                     |
+| `isPartial`          | boolean | Whether scan was partial (large shop) |
+
+**Example:**
+
+```json
+{
+  "shopifyCredentials": {
+    "shopDomain": "myshop.myshopify.com",
+    "accessToken": "shpat_xxxxx"
+  }
+}
+```
+
+---
+
+#### `shopify_scan_products`
+
+Scan Shopify product images for text detection. Identifies which images contain translatable text.
+
+**Input:**
+
+| Parameter            | Type   | Required | Description                                 |
+| -------------------- | ------ | -------- | ------------------------------------------- |
+| `shopifyCredentials` | object | Yes      | Shopify credentials                         |
+| `productId`          | string | No       | Specific product ID to scan                 |
+| `maxProducts`        | number | No       | Max products to scan (default: 10, max: 50) |
+
+**Output:**
+
+| Field             | Type    | Description               |
+| ----------------- | ------- | ------------------------- |
+| `productsScanned` | number  | Products scanned          |
+| `imagesScanned`   | number  | Images scanned            |
+| `imagesWithText`  | number  | Images with detected text |
+| `isPartial`       | boolean | Whether scan was partial  |
+| `stoppedReason`   | string  | Reason if stopped early   |
+| `results`         | array   | Detailed scan results     |
+
+**Example:**
+
+```json
+{
+  "shopifyCredentials": {
+    "shopDomain": "myshop.myshopify.com",
+    "accessToken": "shpat_xxxxx"
+  },
+  "productId": "gid://shopify/Product/123456789"
+}
+```
+
+---
+
+## Image Input
+
+All tools that accept images support three input methods:
+
+### URL
+
+```json
+{
+  "image": {
+    "url": "https://example.com/image.jpg"
+  }
+}
+```
+
+### Base64 with MIME type
+
+```json
+{
+  "image": {
+    "base64": "iVBORw0KGgo...",
+    "mimeType": "image/png"
+  }
+}
+```
+
+### Data URL
+
+```json
+{
+  "image": {
+    "base64": "data:image/png;base64,iVBORw0KGgo..."
+  }
+}
+```
+
+**Supported MIME types:** `image/jpeg`, `image/png`, `image/webp`, `image/gif`
+
+**Size limit:** 10MB
+
+## Programmatic Usage
+
+```typescript
+import { createMcpServer, McpServerConfig } from "@translateimage/mcp-server";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+const config: McpServerConfig = {
+  // Server-side configuration (loaded from environment)
+};
+
+const server = createMcpServer(config);
+const transport = new StdioServerTransport();
+
+await server.connect(transport);
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Type check
+pnpm typecheck
+
+# Build
+pnpm build
+
+# Run tests
+pnpm test
+
+# Run tests with coverage
+pnpm test --coverage
+```
+
+## Architecture
+
+```
+packages/mcp-server/
+├── src/
+│   ├── index.ts          # Package exports
+│   ├── server.ts         # createMcpServer factory
+│   ├── schemas/          # Zod schemas for all tools
+│   ├── utils/            # Image handling, errors, config
+│   └── tools/            # Tool implementations
+│       ├── index.ts      # Tool registration
+│       ├── translate.ts  # translate_image
+│       ├── ocr.ts        # extract_text
+│       ├── text-removal.ts # remove_text
+│       ├── image-to-text.ts # image_to_text
+│       └── shopify/      # Shopify integration tools
+├── bin/
+│   ├── stdio.ts          # CLI entry point
+│   └── http.ts           # HTTP server entry point
+└── __tests__/            # Test files
+```
+
+## Troubleshooting
+
+### "API key missing" error
+
+Ensure you've set your TranslateImage API key:
+
+```bash
+export TRANSLATEIMAGE_API_KEY=your-api-key
+```
+
+Or in AI Agent config, add it to the `env` section.
+
+### "Origin not allowed" error (HTTP server)
+
+Add your origin to `ALLOWED_ORIGINS`:
+
+```bash
+export ALLOWED_ORIGINS=http://localhost:3000,http://yourdomain.com
+```
+
+### Image size exceeds limit
+
+Images must be under 10MB. Compress or resize large images before sending.
+
+### AI Agent not detecting server
+
+1. Ensure the config file path is correct for your OS
+2. Restart AI Agent after config changes
+3. Check that `npx @translateimage/mcp-server` runs without errors
+
+### HTTP server returns 405
+
+The HTTP server runs in stateless mode and doesn't support SSE. Use POST requests to `/mcp` only.
+
+## API Key & Billing
+
+- Get your API key from the [TranslateImage Dashboard](https://translateimage.io/dashboard)
+- Usage is billed based on your subscription plan
+- Monitor usage in the dashboard under **Settings** → **Usage**
+
+## License
+
+Proprietary - All rights reserved

package/dist/bin/http.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=http.d.ts.map

package/dist/bin/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../bin/http.ts"],"names":[],"mappings":""}

package/dist/bin/http.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import express from "express";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createMcpServer } from "../src/server.js";
+import { loadConfigFromEnv } from "../src/utils/config.js";
+const app = express();
+const config = loadConfigFromEnv();
+app.use(express.json());
+const allowedOrigins = (process.env.ALLOWED_ORIGINS || "http://localhost:3000,http://localhost:3001")
+    .split(",")
+    .map((origin) => origin.trim());
+app.use((req, res, next) => {
+    const origin = req.headers.origin;
+    if (origin && !allowedOrigins.includes(origin)) {
+        return res.status(403).json({
+            jsonrpc: "2.0",
+            error: { code: -32603, message: "Origin not allowed" },
+            id: null,
+        });
+    }
+    next();
+});
+app.post("/mcp", async (req, res) => {
+    try {
+        const server = createMcpServer(config);
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        res.status(500).json({
+            jsonrpc: "2.0",
+            error: { code: -32603, message: errorMessage },
+            id: null,
+        });
+    }
+});
+app.get("/mcp", (req, res) => {
+    res.status(405).json({
+        jsonrpc: "2.0",
+        error: { code: -32603, message: "SSE not supported in stateless mode" },
+        id: null,
+    });
+});
+const port = parseInt(process.env.PORT || "3001", 10);
+app.listen(port, () => {
+    console.log(`MCP HTTP server listening on port ${port}`);
+});

package/dist/bin/stdio.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=stdio.d.ts.map

package/dist/bin/stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../../bin/stdio.ts"],"names":[],"mappings":""}

package/dist/bin/stdio.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createMcpServer } from "../src/server.js";
+import { loadConfigFromEnv } from "../src/utils/config.js";
+async function main() {
+    const config = loadConfigFromEnv();
+    const server = createMcpServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Failed to start MCP server:", error);
+    process.exit(1);
+});

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export { createMcpServer } from "./server.js";
+export type { McpServerConfig } from "./utils/config.js";
+export { loadConfigFromEnv } from "./utils/config.js";
+export * from "./schemas/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,cAAc,oBAAoB,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,3 @@
+export { createMcpServer } from "./server.js";
+export { loadConfigFromEnv } from "./utils/config.js";
+export * from "./schemas/index.js";

package/dist/src/schemas/common.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+export declare const LanguageCodeSchema: z.ZodString;
+/**
+ * Image input schema - handles URL, base64, or data URLs
+ * Refinements:
+ * - Requires either url OR base64 (at least one)
+ * - If base64 is raw (not starting with "data:"), mimeType is required
+ * - If base64 starts with "data:", mimeType is extracted automatically
+ */
+export declare const ImageInputSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
+    url: z.ZodOptional<z.ZodString>;
+    base64: z.ZodOptional<z.ZodString>;
+    mimeType: z.ZodOptional<z.ZodEnum<["image/jpeg", "image/png", "image/webp", "image/gif"]>>;
+}, "strip", z.ZodTypeAny, {
+    url?: string | undefined;
+    base64?: string | undefined;
+    mimeType?: "image/jpeg" | "image/png" | "image/webp" | "image/gif" | undefined;
+}, {
+    url?: string | undefined;
+    base64?: string | undefined;
+    mimeType?: "image/jpeg" | "image/png" | "image/webp" | "image/gif" | undefined;
+}>, {
+    url?: string | undefined;
+    base64?: string | undefined;
+    mimeType?: "image/jpeg" | "image/png" | "image/webp" | "image/gif" | undefined;
+}, {
+    url?: string | undefined;
+    base64?: string | undefined;
+    mimeType?: "image/jpeg" | "image/png" | "image/webp" | "image/gif" | undefined;
+}>, {
+    url?: string | undefined;
+    base64?: string | undefined;
+    mimeType?: "image/jpeg" | "image/png" | "image/webp" | "image/gif" | undefined;
+}, {
+    url?: string | undefined;
+    base64?: string | undefined;
+    mimeType?: "image/jpeg" | "image/png" | "image/webp" | "image/gif" | undefined;
+}>;
+export type ImageInput = z.infer<typeof ImageInputSchema>;
+//# sourceMappingURL=common.d.ts.map