Sidearm MCP Server

Instructions

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);