Magic Hour MCP Server

Instructions

Implementation Reference

• src/index.ts:215-263 (registration)

  Complete registration of the 'detect_faces' tool using server.tool(), including name, description, input schema, and handler function

  server.tool(
    "detect_faces",
    "Detect faces in an image or video. Returns face IDs that can be used for individual face swapping.",
    {
      file_url: z
        .string()
        .describe("URL or local path to the image or video to scan for faces"),
      confidence_score: z
        .number()
        .min(0.3)
        .max(0.9)
        .optional()
        .describe(
          "Confidence threshold (0.3-0.9). Higher = stricter detection. Default varies."
        ),
    },
    async ({ file_url, confidence_score }) => {
      try {
        const result = await client.v1.faceDetection.create({
          assets: { targetFilePath: file_url },
          confidenceScore: confidence_score,
        });
  
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify(
                {
                  id: result.id,
                  message:
                    "Face detection job submitted. Use get_face_detection_result to get the detected faces.",
                },
                null,
                2
              ),
            },
          ],
        };
      } catch (error: any) {
        return {
          content: [
            { type: "text" as const, text: `Error: ${error.message}` },
          ],
          isError: true,
        };
      }
    }
  );

• src/index.ts:218-230 (schema)

  Input validation schema using Zod for 'detect_faces' parameters: file_url (required string) and confidence_score (optional number with min 0.3 and max 0.9)

  {
    file_url: z
      .string()
      .describe("URL or local path to the image or video to scan for faces"),
    confidence_score: z
      .number()
      .min(0.3)
      .max(0.9)
      .optional()
      .describe(
        "Confidence threshold (0.3-0.9). Higher = stricter detection. Default varies."
      ),
  },

• src/index.ts:231-262 (handler)

  Handler function that executes the face detection logic: calls client.v1.faceDetection.create() with file_url and confidence_score, returns job ID, and includes error handling

  async ({ file_url, confidence_score }) => {
    try {
      const result = await client.v1.faceDetection.create({
        assets: { targetFilePath: file_url },
        confidenceScore: confidence_score,
      });
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(
              {
                id: result.id,
                message:
                  "Face detection job submitted. Use get_face_detection_result to get the detected faces.",
              },
              null,
              2
            ),
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [
          { type: "text" as const, text: `Error: ${error.message}` },
        ],
        isError: true,
      };
    }
  }