detect_fingerprint

Check media for prior registration using fingerprint matching against your indexed library at varying detection depths to identify copyright infringement.

Instructions

Detect whether media has been previously registered or seen, using fingerprint matching. Compares against your indexed library at varying depth. Tiers: exact (hash match), quick (perceptual hash), perceptual (visual similarity), compositional (scene structure), full (all tiers). Returns results immediately.

Input Schema

TableJSON Schema

Name	Required	Description
`media_url`	No	Public URL of the media to check
`media`	No	Base64-encoded media content to check
`tags`	No	Tags to scope the detection to
`tier`	No	Detection depth — controls thoroughness vs speed. Default: quick

Implementation Reference

src/tools/detect-fingerprint.ts:31-56 (handler)

The main handler function that executes the detect_fingerprint tool. It accepts media_url, media (base64), tags, and tier parameters, constructs a request body, calls the API via api.post('/api/v1/detect', body), and returns the JSON response with error handling.

async (params) => {
  try {
    const body: Record<string, unknown> = {};
    if (params.media_url) body.media_url = params.media_url;
    if (params.media) body.media = params.media;
    if (params.tags) body.tags = params.tags;
    if (params.tier) body.tier = params.tier;

    const result = await api.post("/api/v1/detect", body);
    return {
      content: [
        { type: "text" as const, text: JSON.stringify(result, null, 2) },
      ],
    };
  } catch (err) {
    return {
      content: [
        {
          type: "text" as const,
          text: `Error: ${err instanceof Error ? err.message : String(err)}`,
        },
      ],
      isError: true as const,
    };
  }
},

src/tools/detect-fingerprint.ts:13-30 (schema)

Input schema definition for the detect_fingerprint tool using Zod validation. Defines optional parameters: media_url (URL string), media (base64 string), tags (string array), and tier (enum with values: exact, quick, perceptual, compositional, full).

  media_url: z
    .string()
    .url()
    .optional()
    .describe("Public URL of the media to check"),
  media: z
    .string()
    .optional()
    .describe("Base64-encoded media content to check"),
  tags: z
    .array(z.string())
    .optional()
    .describe("Tags to scope the detection to"),
  tier: z
    .enum(["exact", "quick", "perceptual", "compositional", "full"])
    .optional()
    .describe("Detection depth — controls thoroughness vs speed. Default: quick"),
},

src/tools/detect-fingerprint.ts:5-58 (registration)

Complete registration function that registers the detect_fingerprint tool with the MCP server. Includes the tool name, description, schema, and handler function.

export function register(server: McpServer, api: ApiClient): void {
  server.tool(
    "detect_fingerprint",
    "Detect whether media has been previously registered or seen, using fingerprint matching. " +
      "Compares against your indexed library at varying depth. " +
      "Tiers: exact (hash match), quick (perceptual hash), perceptual (visual similarity), " +
      "compositional (scene structure), full (all tiers). Returns results immediately.",
    {
      media_url: z
        .string()
        .url()
        .optional()
        .describe("Public URL of the media to check"),
      media: z
        .string()
        .optional()
        .describe("Base64-encoded media content to check"),
      tags: z
        .array(z.string())
        .optional()
        .describe("Tags to scope the detection to"),
      tier: z
        .enum(["exact", "quick", "perceptual", "compositional", "full"])
        .optional()
        .describe("Detection depth — controls thoroughness vs speed. Default: quick"),
    },
    async (params) => {
      try {
        const body: Record<string, unknown> = {};
        if (params.media_url) body.media_url = params.media_url;
        if (params.media) body.media = params.media;
        if (params.tags) body.tags = params.tags;
        if (params.tier) body.tier = params.tier;

        const result = await api.post("/api/v1/detect", body);
        return {
          content: [
            { type: "text" as const, text: JSON.stringify(result, null, 2) },
          ],
        };
      } catch (err) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error: ${err instanceof Error ? err.message : String(err)}`,
            },
          ],
          isError: true as const,
        };
      }
    },
  );
}

src/index.ts:13-13 (registration)
Import statement for the detect_fingerprint tool's register function from the tools module.
```
import { register as detectFingerprint } from "./tools/detect-fingerprint.js";
```
src/index.ts:55-55 (registration)
Registration call that invokes detectFingerprint(server, api) to register the tool with the MCP server instance.
```
detectFingerprint(server, api);
```

Sidearm MCP Server