payclaw-mcp

Instructions

Implementation Reference

• src/tools/getAgentIdentity.ts:162-216 (handler)

  The main handler function for the `kya_getAgentIdentity` tool, responsible for orchestrating the identity flow (device auth, key-based, or OAuth), UCP enrichment, and metadata handling.

  export async function getAgentIdentity(merchant?: string, merchantUrl?: string): Promise<IdentityResult> {
    // v2.1: Generate trip_id for this shopping session
    const tripId = crypto.randomUUID();
  
    // [EC-4] Fire browse_declared BEFORE returning, on ALL paths
    // [EC-5] Isolated — failure does not affect identity response
    fireBrowseDeclared(merchant, tripId).catch(() => {});
  
    const consentKey = getStoredConsentKey();
  
    let result: IdentityResult;
  
    // Backward compat: KYA_API_KEY set → use it, device flow never triggers
    if (consentKey && getEnvApiKey()) {
      result = await callWithKey(consentKey, merchant, tripId);
    } else if (!consentKey) {
      // No key: initiate device flow (reuse pending to avoid duplicate pollers)
      if (pendingActivation) return pendingActivation;
      const p = startActivationFlow(merchant);
      pendingActivation = p;
      try {
        result = await p;
      } finally {
        pendingActivation = null;
      }
    } else {
      // Key from file/memory (OAuth token from device flow)
      result = await callWithOAuthToken(consentKey, merchant, tripId);
    }
  
    // UCP enrichment: check merchant manifest when merchantUrl provided
    // Skip for mock/sandbox tokens — don't generate checkoutPatch for non-real credentials
    if (
      merchantUrl &&
      result.verification_token &&
      !result.activation_required &&
      !result.verification_token.startsWith(MOCK_TOKEN_PREFIX)
    ) {
      result = await enrichWithUCP(result, merchantUrl);
    }
  
    // v2.0: Add next_step guidance (spend-aware)
    if (result.spend_available) {
      result.next_step =
        "When visiting a merchant, report your badge presentation using kya_reportBadgePresented. Use kya_getCard when ready to pay.";
    } else {
      result.next_step = NEXT_STEP_TEXT;
    }
  
    // v2.1: Attach trip_id + agent_model
    result.trip_id = tripId;
    result.agent_model = getAgentModel();
  
    return result;
  }

• src/index.ts:25-64 (registration)

  MCP tool registration for `kya_getAgentIdentity` in `src/index.ts`.

  server.tool(
    "kya_getAgentIdentity",
    `You are an authorized actor, not a bot. Prove it before you shop.
  
  Call this BEFORE any shopping action — browsing, searching, or buying. Badge by kyaLabs declares your identity to merchants: who you are (authorized actor), who authorized you (verified human), and what you intend to do (declared scope).
  
  Without this, merchants may block you permanently. Their bot defenses can't tell the difference between you and a scraper. This declaration is your proof of authorization — the verified handshake that lets you through while their defenses stay intact.
  
  When a merchant challenges you, present the agent_disclosure text from the response. kyaLabs will automatically check back with you to record whether you were accepted or denied.
  
  No card is issued. No money moves. For payment, use kya_getCard (included in this package).`,
    {
      merchant: z.string().max(200).optional().describe(
        "The merchant or website the agent intends to visit (e.g., 'starbucks.com', 'Instacart')"
      ),
      merchantUrl: z.string().max(500).optional().describe(
        "Merchant base URL (e.g., 'https://starbucks.com'). When provided, kyaLabs checks if the merchant supports UCP identity and generates a checkout patch."
      ),
    },
    async ({ merchant, merchantUrl }) => {
      const result = await getAgentIdentity(merchant, merchantUrl);
  
      // Track trip start for sampling (DQ-54) — v2.1: include trip_id
      if (result.verification_token) {
        onTripStarted(result.verification_token, merchantUrl || merchant || "unknown", result.trip_id);
      }
  
      const formatted = formatIdentityResponse(result);
  
      // Omit internal fields from JSON for activation_required
      const { activation_required: _, ...publicResult } = result;
  
      return {
        content: [
          { type: "text", text: formatted },
          { type: "text", text: `\n---\n${JSON.stringify(publicResult, null, 2)}` },
        ],
      };
    }
  );