trace.moe-mcp 1.0.0 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
 # 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)
+[![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)

package/dist/index.js

@@ -0,0 +1,316 @@
+#!/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.js";
+import { formatAnilistSearchResultsMarkdown, formatSearchResultsMarkdown, formatUserQuotaMarkdown, } from "./src/format.js";
+import { processImageToVector } from "./src/image-processor.js";
+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/dist/src/api.js

@@ -0,0 +1,109 @@
+export class TraceMoeClient {
+    baseUrl;
+    apiKey;
+    constructor(options) {
+        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 || "";
+    }
+    getHeaders() {
+        const headers = {
+            "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, options) {
+        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;
+        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());
+    }
+    /**
+     * Search anime by title/synonym using /anilist?q=...
+     */
+    async searchAnilist(query) {
+        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());
+    }
+    /**
+     * Get user quota, priority, concurrency, and usage info from /me
+     */
+    async getMe() {
+        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());
+    }
+}
+export const defaultClient = new TraceMoeClient();

package/dist/src/format.js

@@ -0,0 +1,155 @@
+import {} from "./api.js";
+/**
+ * Formats seconds into MM:SS or HH:MM:SS format.
+ */
+export function formatTime(seconds) {
+    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) {
+    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) {
+    if (typeof anilist === "number") {
+        return { primary: `Anilist ID ${anilist}`, titles: [`Anilist ID ${anilist}`], id: anilist };
+    }
+    const { chinese, english, native, romaji } = anilist.title || {};
+    const titles = [];
+    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) {
+    let epText = 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) {
+    if (!response.result || response.result.length === 0) {
+        return "No matching anime scene found on trace.moe.";
+    }
+    const lines = [];
+    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}?size=l`);
+        lines.push(`- **Preview Video**: ${item.video}?size=l`);
+        lines.push("");
+    });
+    return lines.join("\n");
+}
+/**
+ * Formats anime name search results into markdown.
+ */
+export function formatAnilistSearchResultsMarkdown(results, query) {
+    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) {
+    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}
+`;
+}