query_commitment

Instructions

Implementation Reference

• src/mcp/server.ts:42-131 (handler)

  The 'query_commitment' tool handler function. It normalizes the domain, fetches commitment data from the backend API, computes repeat visit rate and average time, formats a summary string, and returns it both as text and as raw JSON.

  server.tool(
    "query_commitment",
    "Query verified behavioral commitment data for a domain. Returns aggregated signals: unique verified visitors, repeat visit rate, and average time spent. These prove real human engagement — harder to fake than reviews or content.",
    {
      domain: z
        .string()
        .describe(
          "The domain to query (e.g. 'example.com'). Will be normalized to lowercase without protocol or path."
        ),
    },
    async ({ domain }) => {
      const normalized = domain
        .trim()
        .toLowerCase()
        .replace(/^https?:\/\//, "")
        .split("/")[0]!;
  
      try {
        const res = await fetch(
          `${BACKEND_URL}/api/domain/${encodeURIComponent(normalized)}`
        );
  
        if (!res.ok) {
          return {
            content: [
              {
                type: "text" as const,
                text: `Backend error: ${res.status} ${res.statusText}`,
              },
            ],
            isError: true,
          };
        }
  
        const data = (await res.json()) as any;
  
        const repeatRate =
          data.uniqueCommitments > 0 && data.totalVisits > 0
            ? Math.round(
                ((data.totalVisits - data.uniqueCommitments) /
                  data.totalVisits) *
                  100
              )
            : 0;
  
        const avgMinutes =
          data.avgSeconds > 0 ? Math.round(data.avgSeconds / 60) : 0;
  
        const summary =
          data.uniqueCommitments === 0
            ? `No verified commitment data for ${normalized}.`
            : [
                `Domain: ${normalized}`,
                `Verified unique visitors: ${data.uniqueCommitments}`,
                `Total visits: ${data.totalVisits}`,
                `Repeat visit rate: ${repeatRate}%`,
                `Average time per visitor: ${avgMinutes} minutes (${Math.round(data.avgSeconds)}s)`,
                `Total time invested: ${Math.round(data.totalSeconds / 3600)} hours`,
                data.lastUpdated ? `Last updated: ${data.lastUpdated}` : null,
              ]
                .filter(Boolean)
                .join("\n");
  
        return {
          content: [
            { type: "text" as const, text: summary },
            {
              type: "text" as const,
              text: JSON.stringify(
                { ...data, repeatRate, avgMinutes },
                null,
                2
              ),
            },
          ],
        };
      } catch (err) {
        const message = err instanceof Error ? err.message : "Unknown error";
        return {
          content: [
            {
              type: "text" as const,
              text: `Failed to reach backend at ${BACKEND_URL}: ${message}`,
            },
          ],
          isError: true,
        };
      }
    }
  );

• src/mcp/server.ts:42-51 (registration)

  Registration of the 'query_commitment' tool via server.tool(), including its description and Zod schema for the 'domain' input parameter.

  server.tool(
    "query_commitment",
    "Query verified behavioral commitment data for a domain. Returns aggregated signals: unique verified visitors, repeat visit rate, and average time spent. These prove real human engagement — harder to fake than reviews or content.",
    {
      domain: z
        .string()
        .describe(
          "The domain to query (e.g. 'example.com'). Will be normalized to lowercase without protocol or path."
        ),
    },

• src/mcp/server.ts:45-51 (schema)

  Zod schema defining the 'domain' input parameter for query_commitment — a string that gets normalized to lowercase without protocol/path.

  {
    domain: z
      .string()
      .describe(
        "The domain to query (e.g. 'example.com'). Will be normalized to lowercase without protocol or path."
      ),
  },