Proofly MCP Integration

Instructions

Implementation Reference

• server.js:500-559 (handler)

  The handler function that executes the logic for the 'get-face-details' tool. It fetches the full analysis result for the given session UUID, validates the face index, extracts the specific face data, and formats the output as JSON or human-readable text.

  async handleGetFaceDetails(params) {
    logInfo("Handling get-face-details with params:", params);
    const { sessionUuid, faceIndex, format = 'text' } = params;
  
    if (!sessionUuid || typeof faceIndex !== 'number' || faceIndex < 0) {
      throw new McpError(ErrorCode.InvalidParams, "Missing or invalid sessionUuid or faceIndex parameter");
    }
  
    try {
      logInfo(`Fetching full analysis data for UUID ${sessionUuid} to get face details`);
      const resultResp = await axios.get(`${PROOFLY_CONFIG.baseUrl}/api/${sessionUuid}`);
      const analysisResult = resultResp.data;
      logInfo(`Full analysis data for ${sessionUuid}:`, analysisResult);
  
      if (!analysisResult.faces || faceIndex >= analysisResult.faces.length) {
        throw new McpError(ErrorCode.NotFound, `Face with index ${faceIndex} not found in session ${sessionUuid}. Total faces: ${analysisResult.faces ? analysisResult.faces.length : 0}.`);
      }
  
      const specificFace = analysisResult.faces[faceIndex];
  
      if (format === 'json') {
        return { content: [{ type: "text", text: JSON.stringify(specificFace, null, 2) }] }; 
      } else {
        // Format only a single face
        let output = `**Details for Face ${faceIndex + 1} (Session: ${sessionUuid}):**\n`;
        const faceVerdict = getVerdict(specificFace.ansamble);
        output += `* Verdict: **${faceVerdict}**\n`;
        if (typeof specificFace.ansamble !== 'undefined' && specificFace.ansamble !== null) {
         output += `* Probability "real": ${(specificFace.ansamble * 100).toFixed(2)}%, "fake": ${(100 - specificFace.ansamble * 100).toFixed(2)}%\n`;
        }
        if (specificFace.is_real_model_1 !== undefined) {
          output += `* Individual model results:\n`;
          for (let i = 1; i <= 10; i++) {
            if (specificFace[`is_real_model_${i}`] !== undefined) {
              output += `  - Model ${i}: ${(specificFace[`is_real_model_${i}`] * 100).toFixed(2)}%\n`;
            }
          }
        }
        if (specificFace.face_path) {
          let faceImageUrl = `${PROOFLY_CONFIG.baseUrl}${specificFace.face_path}`;
          if (faceImageUrl.includes('ai./')) {
            faceImageUrl = faceImageUrl.replace('ai./', 'ai/');
          }
          output += `* Face image URL: ${faceImageUrl}\n`;
        }
        return { content: [{ type: "text", text: output }] };
      }
  
    } catch (error) {
      logError("Error in handleGetFaceDetails:", error.message);
      if (error.response) {
        logError("Error response data:", error.response.data);
        logError("Error response status:", error.response.status);
      }
      if (error.response && error.response.status === 404) {
        throw new McpError(ErrorCode.NotFound, `Session with UUID ${sessionUuid} not found when fetching face details.`);
      }
      throw new McpError(ErrorCode.ServerError, `Failed to get face details: ${error.message}`);
    }
  }

• server.js:224-232 (schema)

  Input schema defining the parameters for the 'get-face-details' tool: sessionUuid (string, required), faceIndex (number, required), and optional format.

  inputSchema: {
    type: "object",
    properties: {
      sessionUuid: { type: "string", description: "Session UUID from the analyze-image result." },
      faceIndex: { type: "number", description: "Index of the face to get details for (starting from 0)." },
      format: { type: "string", enum: ["json", "text"], default: "text", description: "Output format." },
    },
    required: ["sessionUuid", "faceIndex"],
  },

• server.js:221-233 (registration)

  Registration of the 'get-face-details' tool in the tools array provided to ListToolsRequest handler.

  {
    name: "get-face-details",
    description: "Get detailed information about a specific face detected in an image.",
    inputSchema: {
      type: "object",
      properties: {
        sessionUuid: { type: "string", description: "Session UUID from the analyze-image result." },
        faceIndex: { type: "number", description: "Index of the face to get details for (starting from 0)." },
        format: { type: "string", enum: ["json", "text"], default: "text", description: "Output format." },
      },
      required: ["sessionUuid", "faceIndex"],
    },
  },

• server.js:249-250 (registration)

  Registration of the tool handler dispatch in the switch statement for CallToolRequest.

  case "get-face-details":
    return await this.handleGetFaceDetails(args);

• server.js:61-69 (helper)

  Helper function used by the get-face-details handler to convert probability to a human-readable verdict.

  function getVerdict(probability) {
    if (probability === null || typeof probability === 'undefined') return "Uncertain (no score)";
    if (probability > 0.8) {
      return "Likely Real";
    } else if (probability < 0.2) {
      return "Likely Fake";
    } else {
      return "Uncertain";
    }