trace.moe-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 soruly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+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,94 @@
+# trace.moe-mcp
+
+[![License](https://img.shields.io/github/license/soruly/trace.moe-mcp.svg?style=flat-square)](https://github.com/soruly/trace.moe-mcp/blob/master/LICENSE)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/soruly/trace.moe-mcp/node.js.yml?style=flat-square)](https://github.com/soruly/trace.moe-mcp/actions)
+[![npm](https://img.shields.io/npm/v/trace.moe-mcp.svg?style=flat-square)](https://www.npmjs.com/package/trace.moe-mcp)
+[![Discord](https://img.shields.io/discord/437578425767559188.svg?style=flat-square)](https://discord.gg/K9jn6Kj)
+
+Model Context Protocol (MCP) server for [trace.moe](https://trace.moe) anime scene search API.
+
+## Features
+
+- **Local Image Pre-processing & Vector Extraction**:
+  - Automatically loads and decodes images locally (JPEG, PNG, WebP, AVIF, etc.).
+  - Detects and crops black letterbox/pillarbox borders (`cutBorders`).
+  - Computes the 33-element MPEG-7 Color Layout Descriptor vector using 8×8 2D-DCT locally.
+  - Sends **only the compact 33-number vector** (~150 bytes JSON payload) to `api.trace.moe`, minimizing bandwidth and keeping image content private.
+- **Multiple Image Sources**: Supports direct Image URLs, local file paths, base64 strings, or pre-computed vectors.
+- **Anime Title & Metadata Search**: Search anime titles, romanized names, and synonyms via `/anilist`.
+- **Account & Quota Status**: Check remaining quota, concurrency limits, and priority via `/me` resource and tool.
+- **Guided AI Prompt Template**: `identify_anime_scene` prompt template for LLMs.
+
+## Available Tools
+
+| Tool                         | Description                                                                   | Inputs                                                                                                                                                                               |
+| :--------------------------- | :---------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `search_anime_by_image_url`  | Search anime scene by image URL (preprocessed locally into 33-element vector) | `url` (string, required)<br>`cutBorders` (boolean, default true)<br>`anilistInfo` (boolean, default true)<br>`anilistID` (number, optional)                                          |
+| `search_anime_by_image_file` | Search anime scene from local file path or base64 string                      | `filePath` (string, optional)<br>`imageBase64` (string, optional)<br>`cutBorders` (boolean, default true)<br>`anilistInfo` (boolean, default true)<br>`anilistID` (number, optional) |
+| `search_anime_by_vector`     | Search anime scene directly using a 33-element color layout vector            | `vector` (array of 33 numbers, required)<br>`anilistInfo` (boolean, default true)<br>`anilistID` (number, optional)                                                                  |
+| `search_anime_by_name`       | Search anime metadata and retrieve Anilist IDs by name/title                  | `query` (string, required)                                                                                                                                                           |
+| `get_account_quota`          | Check current daily search quota, concurrency limit, and priority             | _(None)_                                                                                                                                                                             |
+
+## Available Resources
+
+- `tracemoe://me` - Current search quota, priority, concurrency, and 24h usage status in JSON format.
+
+## Available Prompts
+
+- `trace_moe` - Prompt template guiding the AI model on how to identify an anime screenshot.
+
+## Environment Variables
+
+- `TRACE_MOE_API_KEY`: Optional API key sent via `x-trace-key` for higher rate limits and daily quota.
+- `TRACE_MOE_API_HOST`: Optional custom API endpoint (defaults to `https://api.trace.moe`).
+
+## Installation & Running
+
+### Option 1: Run with `npx` (No installation required)
+
+```bash
+npx -y trace.moe-mcp
+```
+
+### Option 2: Run directly from source
+
+```bash
+git clone https://github.com/soruly/trace.moe-mcp.git
+cd trace.moe-mcp
+npm install
+node index.ts
+```
+
+### MCP Client Configuration (Claude Desktop, Cursor, Antigravity, etc.)
+
+#### Using `npx`:
+
+```json
+{
+  "mcpServers": {
+    "trace_moe": {
+      "command": "npx",
+      "args": ["-y", "trace.moe-mcp"],
+      "env": {
+        "TRACE_MOE_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Using local repository:
+
+```json
+{
+  "mcpServers": {
+    "trace_moe": {
+      "command": "node",
+      "args": ["/absolute/path/to/trace.moe-mcp/index.ts"],
+      "env": {
+        "TRACE_MOE_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```

package/index.ts

@@ -0,0 +1,370 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import { defaultClient } from "./src/api.ts";
+import {
+  formatAnilistSearchResultsMarkdown,
+  formatSearchResultsMarkdown,
+  formatUserQuotaMarkdown,
+} from "./src/format.ts";
+import { processImageToVector } from "./src/image-processor.ts";
+
+const server = new McpServer({
+  name: "trace.moe-mcp",
+  version: "1.0.0",
+});
+
+// Tool: Search Anime by Image URL (with local vector preprocessing)
+server.registerTool(
+  "search_anime_by_image_url",
+  {
+    title: "Search Anime by Image URL",
+    description:
+      "Search anime scene by image URL. Pre-processes the image locally into a 33-element Color Layout Descriptor vector and sends only the vector to api.trace.moe.",
+    inputSchema: {
+      url: z.url().describe("Direct HTTP/HTTPS URL of the anime screenshot"),
+      cutBorders: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Automatically crop black letterbox or pillarbox borders before searching"),
+      anilistInfo: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Include full anime titles and metadata"),
+      anilistID: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Optional Anilist ID to filter search results within a specific anime"),
+    },
+  },
+  async ({ url, cutBorders, anilistInfo, anilistID }) => {
+    try {
+      const vector = await processImageToVector({ url }, cutBorders);
+      const searchResult = await defaultClient.searchByVector(vector, {
+        anilistInfo,
+        anilistID,
+      });
+
+      const markdown = formatSearchResultsMarkdown(searchResult);
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: markdown,
+          },
+          {
+            type: "text",
+            text: JSON.stringify(searchResult, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `Failed to search anime by image URL: ${error instanceof Error ? error.message : String(error)}`,
+          },
+        ],
+      };
+    }
+  },
+);
+
+// Tool: Search Anime by Local File or Base64 Image
+server.registerTool(
+  "search_anime_by_image_file",
+  {
+    title: "Search Anime by Image File or Base64",
+    description:
+      "Search anime scene from a local file path or base64 encoded image. Pre-processes the image locally into a 33-element vector and sends only the vector to api.trace.moe.",
+    inputSchema: {
+      filePath: z
+        .string()
+        .optional()
+        .describe("Local absolute or relative filesystem path to the image file"),
+      imageBase64: z
+        .string()
+        .optional()
+        .describe("Base64-encoded image string (with or without data URI scheme prefix)"),
+      cutBorders: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Automatically crop black letterbox or pillarbox borders before searching"),
+      anilistInfo: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Include full anime titles and metadata"),
+      anilistID: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Optional Anilist ID to filter search results within a specific anime"),
+    },
+  },
+  async ({ filePath, imageBase64, cutBorders, anilistInfo, anilistID }) => {
+    try {
+      if (!filePath && !imageBase64) {
+        throw new Error("Must provide either 'filePath' or 'imageBase64'.");
+      }
+
+      const vector = await processImageToVector({ filePath, imageBase64 }, cutBorders);
+      const searchResult = await defaultClient.searchByVector(vector, {
+        anilistInfo,
+        anilistID,
+      });
+
+      const markdown = formatSearchResultsMarkdown(searchResult);
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: markdown,
+          },
+          {
+            type: "text",
+            text: JSON.stringify(searchResult, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `Failed to search anime by image file: ${error instanceof Error ? error.message : String(error)}`,
+          },
+        ],
+      };
+    }
+  },
+);
+
+// Tool: Search Anime by 33-element Color Layout Vector
+server.registerTool(
+  "search_anime_by_vector",
+  {
+    title: "Search Anime by Color Layout Vector",
+    description:
+      "Search anime scene directly using a 33-element MPEG-7 Color Layout Descriptor vector.",
+    inputSchema: {
+      vector: z
+        .array(z.number())
+        .length(33)
+        .describe("33-element integer vector representing MPEG-7 Color Layout Descriptor"),
+      anilistInfo: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Include full anime titles and metadata"),
+      anilistID: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Optional Anilist ID to filter search results within a specific anime"),
+    },
+  },
+  async ({ vector, anilistInfo, anilistID }) => {
+    try {
+      const searchResult = await defaultClient.searchByVector(vector, {
+        anilistInfo,
+        anilistID,
+      });
+
+      const markdown = formatSearchResultsMarkdown(searchResult);
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: markdown,
+          },
+          {
+            type: "text",
+            text: JSON.stringify(searchResult, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `Failed to search anime by vector: ${error instanceof Error ? error.message : String(error)}`,
+          },
+        ],
+      };
+    }
+  },
+);
+
+// Tool: Search Anime by Name
+server.registerTool(
+  "search_anime_by_name",
+  {
+    title: "Search Anime by Name",
+    description:
+      "Search anime titles, romanized names, and synonyms using trace.moe Anilist database to retrieve Anilist IDs and metadata.",
+    inputSchema: {
+      query: z
+        .string()
+        .min(1)
+        .describe("Anime name, Chinese name, Japanese name, or keyword to search"),
+    },
+  },
+  async ({ query }) => {
+    try {
+      const results = await defaultClient.searchAnilist(query);
+      const markdown = formatAnilistSearchResultsMarkdown(results, query);
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: markdown,
+          },
+          {
+            type: "text",
+            text: JSON.stringify(results, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `Failed to search anime by name: ${error instanceof Error ? error.message : String(error)}`,
+          },
+        ],
+      };
+    }
+  },
+);
+
+// Tool: Get Account Quota & Concurrency
+server.registerTool(
+  "get_account_quota",
+  {
+    title: "Get Account Quota & Concurrency",
+    description:
+      "Check remaining daily search quota, concurrency limit, and priority for the current IP / API key on trace.moe.",
+    inputSchema: {},
+  },
+  async () => {
+    try {
+      const user = await defaultClient.getMe();
+      const markdown = formatUserQuotaMarkdown(user);
+      return {
+        content: [
+          {
+            type: "text",
+            text: markdown,
+          },
+          {
+            type: "text",
+            text: JSON.stringify(user, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `Failed to get quota: ${error instanceof Error ? error.message : String(error)}`,
+          },
+        ],
+      };
+    }
+  },
+);
+
+// Resource: tracemoe://me
+server.registerResource(
+  "user-quota",
+  "tracemoe://me",
+  {
+    mimeType: "application/json",
+    description: "Current trace.moe search quota, limits, and usage",
+  },
+  async () => {
+    const user = await defaultClient.getMe();
+    return {
+      contents: [
+        {
+          uri: "tracemoe://me",
+          mimeType: "application/json",
+          text: JSON.stringify(user, null, 2),
+        },
+      ],
+    };
+  },
+);
+
+// Prompt: trace_moe
+server.registerPrompt(
+  "trace_moe",
+  {
+    title: "Trace Anime Scene",
+    description:
+      "Guide the model on identifying an anime screenshot scene using trace.moe and presenting accurate information.",
+    argsSchema: {
+      imageUrl: z.string().optional().describe("URL of the anime scene image to identify"),
+      filePath: z
+        .string()
+        .optional()
+        .describe("Local file path of the anime scene image to identify"),
+      notes: z.string().optional().describe("Additional clues or context"),
+    },
+  },
+  ({ imageUrl, filePath, notes }) => {
+    const promptText = `Please identify the anime scene from the provided image ${imageUrl ? `at ${imageUrl}` : ""}${filePath ? `(file: ${filePath})` : ""}.${notes ? ` Additional context: ${notes}` : ""}
+
+Steps to follow:
+1. Use the 'search_anime_by_image_url' or 'search_anime_by_image_file' tool to search trace.moe.
+2. If similarity is >= 85%, report the matched Anime Title (English, Romaji, and Native Japanese), Episode number, and exact timestamp (e.g. 00:12:34).
+3. Include the Anilist link and preview thumbnail / video clip URL for verification.
+4. If similarity is low (< 80%), warn the user that the match might be uncertain.`;
+
+    return {
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: promptText,
+          },
+        },
+      ],
+    };
+  },
+);
+
+// Start server using Stdio transport
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("Fatal error running trace.moe MCP server:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "trace.moe-mcp",
+  "version": "1.0.0",
+  "description": "Model Context Protocol (MCP) server for trace.moe anime scene search",
+  "keywords": [
+    "anime",
+    "mcp",
+    "trace.moe"
+  ],
+  "homepage": "https://github.com/soruly/trace.moe-mcp",
+  "bugs": {
+    "url": "https://github.com/soruly/trace.moe-mcp/issues"
+  },
+  "license": "MIT",
+  "author": "soruly",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/soruly/trace.moe-mcp.git"
+  },
+  "bin": {
+    "trace.moe-mcp": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src"
+  ],
+  "type": "module",
+  "main": "index.ts",
+  "scripts": {
+    "start": "node index.ts",
+    "format": "oxfmt",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "test": "oxfmt --check && oxlint && node --test test/*.test.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "sharp": "^0.35.4",
+    "trace.moe-id": "^2.0.0",
+    "zod": "^4.6.2"
+  },
+  "devDependencies": {
+    "@types/node": "^26.5.1",
+    "@types/sharp": "^0.31.1",
+    "oxfmt": "^0.67.0",
+    "oxlint": "^1.82.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/src/api.ts

@@ -0,0 +1,192 @@
+export interface AnilistTitle {
+  native?: string | null;
+  romaji?: string | null;
+  english?: string | null;
+  chinese?: string | null;
+}
+
+export interface AnilistData {
+  id: number;
+  idMal?: number | null;
+  title: AnilistTitle;
+  synonyms?: string[];
+  synonyms_chinese?: string[];
+  isAdult?: boolean;
+  episodes?: number | null;
+}
+
+export interface SearchResultItem {
+  anilist: number | AnilistData;
+  filename: string;
+  episode?: number | string | (number | string)[] | null;
+  episode_start?: number | null;
+  episode_end?: number | null;
+  from: number;
+  to: number;
+  similarity: number;
+  video: string;
+  image: string;
+}
+
+export interface SearchResponse {
+  frameCount: number;
+  error?: string;
+  result: SearchResultItem[];
+  quota?: number;
+  quotaUsed?: number;
+}
+
+export interface UserResponse {
+  id: string;
+  priority: number;
+  concurrency: number;
+  quota: number;
+  quotaUsed: number;
+}
+
+export interface AnilistSearchResultItem {
+  id: number;
+  title: string;
+  similarity: number;
+  anilist: AnilistData;
+}
+
+export class TraceMoeClient {
+  private baseUrl: string;
+  private apiKey: string;
+
+  constructor(options?: { baseUrl?: string; apiKey?: string }) {
+    this.baseUrl = (
+      options?.baseUrl ||
+      process.env.TRACE_MOE_API_HOST ||
+      "https://api.trace.moe"
+    ).replace(/\/$/, "");
+
+    this.apiKey = options?.apiKey || process.env.TRACE_MOE_API_KEY || "";
+  }
+
+  private getHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      "User-Agent": "trace.moe-mcp/1.0.0",
+    };
+    if (this.apiKey) {
+      headers["x-trace-key"] = this.apiKey;
+    }
+    return headers;
+  }
+
+  /**
+   * Search anime scene by sending a 33-element MPEG-7 Color Layout Descriptor vector.
+   */
+  async searchByVector(
+    vector: number[],
+    options?: {
+      anilistInfo?: boolean;
+      anilistID?: number;
+    },
+  ): Promise<SearchResponse> {
+    if (!Array.isArray(vector) || vector.length !== 33) {
+      throw new Error(
+        `Invalid feature vector: expected 33 numbers, got ${Array.isArray(vector) ? vector.length : typeof vector}`,
+      );
+    }
+
+    const queryParams = new URLSearchParams();
+    if (options?.anilistInfo !== false) {
+      queryParams.set("anilistInfo", "2");
+    }
+    if (options?.anilistID !== undefined) {
+      queryParams.set("anilistID", String(options.anilistID));
+    }
+
+    const qs = queryParams.toString();
+    const url = `${this.baseUrl}/search${qs ? `?${qs}` : ""}`;
+
+    const headers = {
+      ...this.getHeaders(),
+      "Content-Type": "application/json",
+    };
+
+    let response: Response | undefined;
+    let retries = 3;
+
+    while (retries > 0) {
+      response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ vector }),
+      });
+
+      if (response.status !== 503 || retries === 1) {
+        break;
+      }
+
+      retries--;
+      await new Promise((resolve) => setTimeout(resolve, 1500));
+    }
+
+    if (!response) {
+      throw new Error("No response received from trace.moe API");
+    }
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "");
+      let parsedError = errorText;
+      try {
+        const json = JSON.parse(errorText);
+        if (json.error) parsedError = json.error;
+      } catch {}
+
+      if (response.status === 402) {
+        throw new Error(`trace.moe search quota exceeded. ${parsedError}`);
+      }
+      if (response.status === 429) {
+        throw new Error(`trace.moe rate limit exceeded. Please try again later. ${parsedError}`);
+      }
+      if (response.status === 503) {
+        throw new Error(`trace.moe server is currently busy or overloaded. ${parsedError}`);
+      }
+      throw new Error(`trace.moe API error (${response.status}): ${parsedError}`);
+    }
+
+    return (await response.json()) as SearchResponse;
+  }
+
+  /**
+   * Search anime by title/synonym using /anilist?q=...
+   */
+  async searchAnilist(query: string): Promise<AnilistSearchResultItem[]> {
+    const url = `${this.baseUrl}/anilist?q=${encodeURIComponent(query)}`;
+    const response = await fetch(url, {
+      method: "GET",
+      headers: this.getHeaders(),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "");
+      throw new Error(`trace.moe anilist search failed (${response.status}): ${errorText}`);
+    }
+
+    return (await response.json()) as AnilistSearchResultItem[];
+  }
+
+  /**
+   * Get user quota, priority, concurrency, and usage info from /me
+   */
+  async getMe(): Promise<UserResponse> {
+    const url = `${this.baseUrl}/me`;
+    const response = await fetch(url, {
+      method: "GET",
+      headers: this.getHeaders(),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "");
+      throw new Error(`trace.moe /me failed (${response.status}): ${errorText}`);
+    }
+
+    return (await response.json()) as UserResponse;
+  }
+}
+
+export const defaultClient = new TraceMoeClient();

package/src/format.ts

@@ -0,0 +1,195 @@
+import {
+  type AnilistData,
+  type AnilistSearchResultItem,
+  type SearchResponse,
+  type SearchResultItem,
+  type UserResponse,
+} from "./api.ts";
+
+/**
+ * Formats seconds into MM:SS or HH:MM:SS format.
+ */
+export function formatTime(seconds: number): string {
+  if (isNaN(seconds) || seconds < 0) return "00:00";
+  const sec = Math.floor(seconds);
+  const h = Math.floor(sec / 3600);
+  const m = Math.floor((sec % 3600) / 60);
+  const s = sec % 60;
+
+  const mm = String(m).padStart(2, "0");
+  const ss = String(s).padStart(2, "0");
+
+  if (h > 0) {
+    const hh = String(h).padStart(2, "0");
+    return `${hh}:${mm}:${ss}`;
+  }
+  return `${mm}:${ss}`;
+}
+
+/**
+ * Formats a similarity float (0.0 - 1.0) into a percentage string (e.g. "98.5%").
+ */
+export function formatSimilarity(similarity: number): string {
+  return `${(similarity * 100).toFixed(1)}%`;
+}
+
+/**
+ * Extracts anime titles for all languages (native Japanese, romaji, English, Chinese).
+ * Returns primary English/Romaji title and the full list of titles across all languages.
+ */
+export function getAnimeTitles(anilist: number | AnilistData): {
+  primary: string;
+  titles: string[];
+  id: number;
+} {
+  if (typeof anilist === "number") {
+    return { primary: `Anilist ID ${anilist}`, titles: [`Anilist ID ${anilist}`], id: anilist };
+  }
+
+  const { chinese, english, native, romaji } = anilist.title || {};
+  const titles: string[] = [];
+
+  if (native && !titles.includes(native)) titles.push(native);
+  if (romaji && !titles.includes(romaji)) titles.push(romaji);
+  if (english && !titles.includes(english)) titles.push(english);
+  if (chinese && !titles.includes(chinese)) titles.push(chinese);
+
+  if (titles.length === 0) {
+    titles.push(`Anilist ID ${anilist.id}`);
+  }
+
+  const primary = english || romaji || native || chinese || `Anilist ID ${anilist.id}`;
+
+  return {
+    primary,
+    titles,
+    id: anilist.id,
+  };
+}
+
+/**
+ * Formats episode information into a readable string (e.g. "1/12", "1-2/12", "1", "1-2").
+ * Prefers episode_start and episode_end (aligned with Anilist episode count) over filename episode.
+ * Returns null if episode is unknown.
+ */
+export function formatEpisode(item: SearchResultItem): string | null {
+  let epText: string | null = null;
+
+  if (item.episode_start !== undefined && item.episode_start !== null) {
+    if (
+      item.episode_end !== undefined &&
+      item.episode_end !== null &&
+      item.episode_end !== item.episode_start
+    ) {
+      epText = `${item.episode_start}-${item.episode_end}`;
+    } else {
+      epText = String(item.episode_start);
+    }
+  } else if (item.episode !== undefined && item.episode !== null && item.episode !== "") {
+    if (Array.isArray(item.episode)) {
+      epText = item.episode.join(", ");
+    } else {
+      epText = String(item.episode);
+    }
+  }
+
+  if (!epText) {
+    return null;
+  }
+
+  // If total episode count from Anilist is available, append /total (e.g. "1/12")
+  if (typeof item.anilist === "object" && item.anilist !== null && item.anilist.episodes) {
+    epText = `${epText}/${item.anilist.episodes}`;
+  }
+
+  return epText;
+}
+
+/**
+ * Formats a list of search results into markdown.
+ */
+export function formatSearchResultsMarkdown(response: SearchResponse): string {
+  if (!response.result || response.result.length === 0) {
+    return "No matching anime scene found on trace.moe.";
+  }
+
+  const lines: string[] = [];
+  lines.push(
+    `### trace.moe Search Results (Found ${response.result.length} matches, compared ${response.frameCount.toLocaleString()} frames)`,
+  );
+  lines.push("");
+
+  response.result.slice(0, 5).forEach((item, index) => {
+    const titleInfo = getAnimeTitles(item.anilist);
+    const ep = formatEpisode(item);
+    const timeRange = `${formatTime(item.from)} - ${formatTime(item.to)}`;
+    const sim = formatSimilarity(item.similarity);
+    const warningEmoji = item.similarity < 0.8 ? " ⚠️" : "";
+
+    lines.push(`#### ${index + 1}. ${titleInfo.primary}${warningEmoji} (${sim} similarity)`);
+    for (const t of titleInfo.titles) {
+      if (t !== titleInfo.primary) {
+        lines.push(`- ${t}`);
+      }
+    }
+    if (ep) {
+      lines.push(`- **Episode**: ${ep}`);
+    }
+    lines.push(`- **Timestamp**: \`${timeRange}\``);
+    lines.push(
+      `- **Anilist**: [https://anilist.co/anime/${titleInfo.id}](https://anilist.co/anime/${titleInfo.id})`,
+    );
+    lines.push(`- **Preview Image**: ${item.image}`);
+    lines.push(`- **Preview Video**: ${item.video}`);
+    lines.push("");
+  });
+
+  return lines.join("\n");
+}
+
+/**
+ * Formats anime name search results into markdown.
+ */
+export function formatAnilistSearchResultsMarkdown(
+  results: AnilistSearchResultItem[],
+  query: string,
+): string {
+  if (!results || results.length === 0) {
+    return `No anime found matching query: "${query}"`;
+  }
+
+  const lines = [`### Anime Search Results for "${query}" (Found ${results.length} matches):`, ""];
+
+  results.slice(0, 10).forEach((item, idx) => {
+    const titleInfo = getAnimeTitles(item.anilist);
+    const sim = (item.similarity * 100).toFixed(0);
+    lines.push(
+      `#### ${idx + 1}. ${titleInfo.primary} (Match: ${sim}%, Anilist ID: \`${item.id}\`)`,
+    );
+    for (const t of titleInfo.titles) {
+      if (t !== titleInfo.primary) {
+        lines.push(`- ${t}`);
+      }
+    }
+    lines.push(
+      `- **Anilist**: [https://anilist.co/anime/${item.id}](https://anilist.co/anime/${item.id})`,
+    );
+    lines.push("");
+  });
+
+  return lines.join("\n");
+}
+
+/**
+ * Formats user quota information into markdown.
+ */
+export function formatUserQuotaMarkdown(user: UserResponse): string {
+  const remaining = Math.max(0, user.quota - user.quotaUsed);
+  return `### trace.moe Account Quota & Status
+- **ID**: \`${user.id}\`
+- **Remaining Daily Quota**: **${remaining.toLocaleString()}** / ${user.quota.toLocaleString()}
+- **Searches Used (last 24h)**: ${user.quotaUsed.toLocaleString()}
+- **Concurrency Limit**: ${user.concurrency}
+- **Search Queue Priority**: ${user.priority}
+`;
+}

package/src/image-processor.ts

@@ -0,0 +1,262 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import sharp from "sharp";
+import { ColorLayout } from "trace.moe-id";
+
+sharp.cache(false);
+sharp.concurrency(1);
+
+function getVideoFrameRect(
+  data: Buffer,
+  width: number,
+  height: number,
+  channels = 3,
+  colorTolerance = 10,
+) {
+  function isDark(x: number, y: number) {
+    const i = (y * width + x) * channels;
+    return (
+      data[i] <= colorTolerance && data[i + 1] <= colorTolerance && data[i + 2] <= colorTolerance
+    );
+  }
+
+  function isRowDark(y: number) {
+    let darkPixelCount = 0;
+    for (let x = 0; x < width; x++) {
+      if (isDark(x, y)) darkPixelCount++;
+    }
+    return darkPixelCount > width * 0.95;
+  }
+
+  function isColDark(x: number) {
+    let darkPixelCount = 0;
+    for (let y = 0; y < height; y++) {
+      if (isDark(x, y)) darkPixelCount++;
+    }
+    return darkPixelCount > height * 0.95;
+  }
+
+  let top: number, bottom: number, left: number, right: number;
+
+  const centerY = Math.floor(height / 2);
+  const centerX = Math.floor(width / 2);
+
+  if (!isDark(centerX, centerY)) {
+    top = centerY;
+    bottom = centerY;
+    left = centerX;
+    right = centerX;
+    while (top > 0 && !isRowDark(top - 1)) top--;
+    while (bottom < height - 1 && !isRowDark(bottom + 1)) bottom++;
+    while (left > 0 && !isColDark(left - 1)) left--;
+    while (right < width - 1 && !isColDark(right + 1)) right++;
+  } else {
+    top = 0;
+    bottom = height - 1;
+    left = 0;
+    right = width - 1;
+    while (top < height && isRowDark(top)) top++;
+    while (bottom > top && isRowDark(bottom)) bottom--;
+    while (left < width && isColDark(left)) left++;
+    while (right > left && isColDark(right)) right--;
+  }
+
+  return {
+    x: left,
+    y: top,
+    width: Math.max(1, right - left + 1),
+    height: Math.max(1, bottom - top + 1),
+  };
+}
+
+function getNearestAspectRatio(
+  width: number,
+  height: number,
+  targetAspectRatios: number[],
+  threshold = 0.05,
+) {
+  const aspectRatio = width / height;
+  let bestRatio = null;
+  let minDiff = Infinity;
+
+  for (const targetRatio of targetAspectRatios) {
+    const diff = Math.abs(aspectRatio - targetRatio);
+    if (diff < minDiff) {
+      minDiff = diff;
+      bestRatio = targetRatio;
+    }
+  }
+
+  if (minDiff <= threshold) {
+    return bestRatio;
+  }
+  return null;
+}
+
+function snapRectToNearestAspectRatio(
+  rect: { x: number; y: number; width: number; height: number },
+  maxW: number,
+  maxH: number,
+) {
+  const targetRatios = [4 / 3, 16 / 9, 21 / 9];
+  const currentRatio = rect.width / (rect.height || 1);
+  let R = targetRatios[0];
+  let minDiff = Math.abs(currentRatio - R);
+  for (let i = 1; i < targetRatios.length; i++) {
+    const diff = Math.abs(currentRatio - targetRatios[i]);
+    if (diff < minDiff) {
+      minDiff = diff;
+      R = targetRatios[i];
+    }
+  }
+
+  let w = rect.width;
+  let h = rect.height;
+  if (w / R > h) {
+    w = h * R;
+  } else {
+    h = w / R;
+  }
+
+  if (w < 10) w = 10;
+  if (h < 10) h = 10;
+
+  const cx = rect.x + rect.width / 2;
+  const cy = rect.y + rect.height / 2;
+  let x = cx - w / 2;
+  let y = cy - h / 2;
+
+  if (x < 0) x = 0;
+  if (y < 0) y = 0;
+  if (x + w > maxW) {
+    x = maxW - w;
+    if (x < 0) {
+      x = 0;
+      w = maxW;
+    }
+  }
+  if (y + h > maxH) {
+    y = maxH - h;
+    if (y < 0) {
+      y = 0;
+      h = maxH;
+    }
+  }
+
+  return {
+    x: Math.round(x),
+    y: Math.round(y),
+    width: Math.round(w),
+    height: Math.round(h),
+  };
+}
+
+/**
+ * Resizes and optionally crops black borders from an image buffer,
+ * returning raw RGB pixel data and dimensions.
+ */
+export async function resizeAndCropImage(
+  imageBuffer: Buffer,
+  cutBorders: boolean = true,
+): Promise<{ data: Buffer; width: number; height: number }> {
+  const resized = await sharp(imageBuffer)
+    .resize({ width: 320, height: 320, fit: "inside" })
+    .toBuffer();
+
+  let cropped = sharp(resized);
+
+  if (cutBorders) {
+    try {
+      const { data, info } = await sharp(resized)
+        .removeAlpha()
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+
+      const targetRatios = [4 / 3, 16 / 9, 21 / 9];
+      const matchedRatio = getNearestAspectRatio(info.width, info.height, targetRatios);
+      if (matchedRatio === null) {
+        const detected = getVideoFrameRect(data, info.width, info.height, 3, 10);
+        const snapped = snapRectToNearestAspectRatio(detected, info.width, info.height);
+        cropped = sharp(resized).extract({
+          left: snapped.x,
+          top: snapped.y,
+          width: snapped.width,
+          height: snapped.height,
+        });
+      }
+    } catch {
+      // If border trimming fails, fallback to uncropped resized image
+      cropped = sharp(resized);
+    }
+  }
+
+  const { data, info } = await cropped
+    .flatten({ background: "#000000" })
+    .removeAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+
+  return {
+    data,
+    width: info.width,
+    height: info.height,
+  };
+}
+
+/**
+ * Extracts the 33-element MPEG-7 Color Layout Vector from an image buffer.
+ */
+export async function extractVectorFromBuffer(
+  imageBuffer: Buffer,
+  cutBorders: boolean = true,
+): Promise<number[]> {
+  const { data, width, height } = await resizeAndCropImage(imageBuffer, cutBorders);
+  return ColorLayout.extract({ data, width, height, channels: 3 });
+}
+
+/**
+ * Resolves an image input (URL, local file path, or Base64 string) to a Buffer.
+ */
+export async function resolveImageInputToBuffer(input: {
+  url?: string;
+  filePath?: string;
+  imageBase64?: string;
+}): Promise<Buffer> {
+  if (input.imageBase64) {
+    // Strip data URL prefix if present (e.g. data:image/jpeg;base64,...)
+    const cleanBase64 = input.imageBase64.replace(/^data:image\/[a-z]+;base64,/, "");
+    return Buffer.from(cleanBase64, "base64");
+  }
+
+  if (input.filePath) {
+    const resolvedPath = path.resolve(input.filePath);
+    return await fs.readFile(resolvedPath);
+  }
+
+  if (input.url) {
+    const response = await fetch(input.url, {
+      headers: {
+        "User-Agent": "trace.moe-mcp/1.0.0",
+      },
+    });
+    if (!response.ok) {
+      throw new Error(`Failed to fetch image from URL: ${response.status} ${response.statusText}`);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+  }
+
+  throw new Error("No image source provided. Must provide url, filePath, or imageBase64.");
+}
+
+/**
+ * High-level helper to process an image input directly into a 33-element vector.
+ */
+export async function processImageToVector(
+  input: { url?: string; filePath?: string; imageBase64?: string },
+  cutBorders: boolean = true,
+): Promise<number[]> {
+  const buffer = await resolveImageInputToBuffer(input);
+  return extractVectorFromBuffer(buffer, cutBorders);
+}