payclaw-mcp

Instructions

Implementation Reference

• src/tools/getCard.ts:212-240 (handler)

  The main handler function for kya_getCard, responsible for checking authentication, routing to API or mock implementation, and returning the result.

  export async function getCard(input: GetCardInput): Promise<CardResult> {
    process.stderr.write(`[kyaLabs:info] getCard called: merchant=${input.merchant} amount=$${input.estimated_amount}\n`);
  
    if (!getStoredConsentKey()) {
      process.stderr.write(`[kyaLabs:error] getCard: no consent key found\n`);
      return {
        product_name: "kyaLabs",
        status: "error",
        message: "Not authenticated. Run kya_getAgentIdentity first to activate your agent, or set KYA_API_KEY in your MCP config.",
      };
    }
  
    if (api.isApiMode()) {
      try {
        const result = await getCardViaApi(input);
        process.stderr.write(`[kyaLabs:info] getCard result: status=${result.status}\n`);
        return result;
      } catch (err) {
        process.stderr.write(`[kyaLabs:error] getCard API error: ${err instanceof Error ? err.message : String(err)}\n`);
        return {
          product_name: "kyaLabs",
          status: "error",
          message: err instanceof Error ? err.message : String(err),
        };
      }
    }
  
    return getCardViaMock(input);
  }

• src/tools/getCard.ts:5-34 (schema)

  Type definitions for the input and output of the kya_getCard tool.

  export interface GetCardInput {
    merchant: string;
    estimated_amount: number;
    description: string;
  }
  
  export interface CardResult {
    product_name: string;
    status: string;
    intent_id?: string;
    card?: {
      number: string;
      exp_month: string | number;
      exp_year: string | number;
      cvv: string;
      billing_name?: string;
      last_four?: string;
    };
    merchant?: string;
    amount?: number;
    identity?: unknown;
    badge_warning?: string;
    remaining_balance?: number;
    instructions?: string;
    message?: string;
    reason?: string;
    merchant_url?: string;
    estimated_amount?: number;
    approve_endpoint?: string;
  }

• src/index.ts:167-189 (registration)

  The tool registration for kya_getCard in the MCP server.

  server.tool(
    "kya_getCard",
    `Get a single-use virtual Visa to make a purchase on behalf of the user. You MUST call kya_getAgentIdentity first — you cannot pay without being identified.
  
  Declare the merchant, amount, and what you're buying. The user approves via MFA. kyaLabs issues a card locked to this purchase. The card self-destructs after use. Your user's real card never enters the chat.
  
  Call kya_reportPurchase after the transaction.`,
    {
      merchant: z.string().max(500).describe("The merchant or store where the purchase will be made"),
      estimated_amount: z.number().positive().max(500).describe("Estimated purchase amount in USD (max $500)"),
      description: z.string().max(1000).describe("Brief description of what is being purchased"),
    },
    async ({ merchant, estimated_amount, description }) => {
      const result = await getCard({ merchant, estimated_amount, description });
      const formatted = formatCardResponse(result, merchant, estimated_amount);
      return {
        content: [
          { type: "text", text: formatted },
          { type: "text", text: `\n---\n${JSON.stringify(result, null, 2)}` },
        ],
      };
    }
  );