run402

Instructions

Implementation Reference

• src/tools/request-faucet.ts:16-82 (handler)

  The handleRequestFaucet function implements the tool logic: reads wallet address from args or local file, calls /v1/faucet API endpoint, updates wallet file with funded status, and returns formatted markdown response with transaction details.

  export async function handleRequestFaucet(args: {
    address?: string;
  }): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
    let address = args.address;
    const walletPath = getWalletPath();
  
    if (!address) {
      try {
        const wallet = JSON.parse(readFileSync(walletPath, "utf-8"));
        address = wallet.address;
      } catch {
        return {
          content: [
            {
              type: "text",
              text: "Error: No wallet address provided and no local wallet found. " +
                "Use `wallet_create` to create a wallet first, or pass an `address` parameter.",
            },
          ],
          isError: true,
        };
      }
    }
  
    const res = await apiRequest("/v1/faucet", {
      method: "POST",
      body: { address },
    });
  
    if (!res.ok) return formatApiError(res, "requesting faucet funds");
  
    const body = res.body as {
      transactionHash: string;
      amount: string;
      token: string;
      network: string;
    };
  
    // Update wallet file with funded status
    if (existsSync(walletPath)) {
      try {
        const wallet = JSON.parse(readFileSync(walletPath, "utf-8"));
        wallet.funded = true;
        wallet.lastFaucet = new Date().toISOString();
        writeFileSync(walletPath, JSON.stringify(wallet, null, 2), {
          mode: 0o600,
        });
      } catch {
        // non-fatal — wallet update is best-effort
      }
    }
  
    const lines = [
      `## Faucet Funded`,
      ``,
      `| Field | Value |`,
      `|-------|-------|`,
      `| address | \`${address}\` |`,
      `| amount | ${body.amount} ${body.token} |`,
      `| network | ${body.network} |`,
      `| tx | \`${body.transactionHash}\` |`,
      ``,
      `Wallet funded with testnet USDC. You can now provision databases and deploy sites.`,
    ];
  
    return { content: [{ type: "text", text: lines.join("\n") }] };
  }

• src/tools/request-faucet.ts:7-14 (schema)

  The requestFaucetSchema defines the input validation schema with an optional 'address' parameter (wallet address to fund, defaults to local wallet if omitted).

  export const requestFaucetSchema = {
    address: z
      .string()
      .optional()
      .describe(
        "Wallet address (0x...) to fund. If omitted, reads from local wallet file.",
      ),
  };

• src/index.ts:326-331 (registration)

  Registers the 'request_faucet' tool with the MCP server, providing the tool name, description, schema, and async handler wrapper.

  server.tool(
    "request_faucet",
    "Request free testnet USDC from the Run402 faucet (Base Sepolia). Rate limit: 1 per IP per 24h. Returns 0.25 USDC — enough for 2 prototype databases.",
    requestFaucetSchema,
    async (args) => handleRequestFaucet(args),
  );

• src/index.ts:55-55 (helper)

  Import statement that brings in requestFaucetSchema and handleRequestFaucet from the request-faucet module.

  import { requestFaucetSchema, handleRequestFaucet } from "./tools/request-faucet.js";