asterpay-mcp-server

Instructions

Implementation Reference

• mcp-server/src/index.ts:188-196 (registration)

  Registration of the 'ai_summarize' tool with server.tool(), including name, description, input schema (text and maxLength), and handler function

  server.tool(
    "ai_summarize",
    "Summarize any text using AI. Returns a concise summary of the input. Cost: $0.004 USDC via x402.",
    {
      text: z.string().describe("The text to summarize"),
      maxLength: z.number().optional().describe("Maximum summary length in words"),
    },
    async ({ text, maxLength }) => formatResponse(await callApi("POST", "/v1/ai/summarize", { text, maxLength }))
  );

• mcp-server/src/index.ts:195-195 (handler)

  Handler function for ai_summarize tool - async arrow function that calls the AsterPay API POST /v1/ai/summarize endpoint with text and maxLength parameters

  async ({ text, maxLength }) => formatResponse(await callApi("POST", "/v1/ai/summarize", { text, maxLength }))

• mcp-server/src/index.ts:191-194 (schema)

  Zod schema definition for ai_summarize tool inputs: 'text' (required string to summarize) and 'maxLength' (optional number for max summary length in words)

  {
    text: z.string().describe("The text to summarize"),
    maxLength: z.number().optional().describe("Maximum summary length in words"),
  },

• mcp-server/src/index.ts:25-50 (helper)

  callApi helper function that makes HTTP requests to the AsterPay API, handles 402 payment-required responses, and returns status/data

  async function callApi(
    method: "GET" | "POST",
    path: string,
    body?: Record<string, unknown>
  ): Promise<{ status: number; data: unknown; paymentRequired?: unknown }> {
    const url = `${API_BASE}${path}`;
    const headers: Record<string, string> = { "Content-Type": "application/json" };
  
    const res = await fetch(url, {
      method,
      headers,
      ...(body ? { body: JSON.stringify(body) } : {}),
    });
  
    const data = await res.json();
  
    if (res.status === 402) {
      return {
        status: 402,
        data: null,
        paymentRequired: data,
      };
    }
  
    return { status: res.status, data };
  }

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

  formatResponse helper function that formats API responses for MCP tool output, including payment-required instructions for 402 responses

  function formatResponse(result: { status: number; data: unknown; paymentRequired?: unknown }): {
    content: Array<{ type: "text"; text: string }>;
  } {
    if (result.status === 402) {
      const pr = result.paymentRequired as Record<string, unknown>;
      const accepts = (pr?.accepts as Array<Record<string, unknown>>)?.[0];
      const amount = accepts?.amount
        ? `${(parseInt(accepts.amount as string) / 1e6).toFixed(6)} USDC`
        : "unknown";
      const network = (accepts?.network as string) || "unknown";
  
      return {
        content: [
          {
            type: "text",
            text: [
              "Payment required to access this endpoint.",
              "",
              `Amount: ${amount}`,
              `Network: ${network}`,
              `Asset: USDC`,
              `Pay to: ${(accepts?.payTo as string) || "unknown"}`,
              "",
              "To use this endpoint, send an x402 payment via @x402/fetch or the AsterPay SDK.",
              "Install: npm install @x402/fetch",
              "",
              "Example:",
              "```",
              'import { wrapFetch } from "@x402/fetch";',
              'const fetchWithPay = wrapFetch(fetch, wallet);',
              `const res = await fetchWithPay("${API_BASE}${(pr?.resource as Record<string, unknown>)?.url || ""}");`,
              "```",
              "",
              "Docs: https://x402-api-production-ba87.up.railway.app/docs",
              "Discovery: https://x402-api-production-ba87.up.railway.app/discovery/resources",
            ].join("\n"),
          },
        ],
      };
    }
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result.data, null, 2),
        },
      ],
    };
  }