asterpay-mcp-server

Instructions

Implementation Reference

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

  The async handler function for ai_translate tool that calls the API endpoint with text, targetLanguage, and sourceLanguage parameters

  async ({ text, targetLanguage, sourceLanguage }) =>
    formatResponse(await callApi("POST", "/v1/ai/translate", { text, targetLanguage, sourceLanguage }))

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

  The callApi helper function that executes the actual HTTP POST request to the /v1/ai/translate endpoint

  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:208-212 (schema)

  Zod schema definition for ai_translate tool inputs: text (required string), targetLanguage (required string), and sourceLanguage (optional string)

  {
    text: z.string().describe("The text to translate"),
    targetLanguage: z.string().describe("Target language, e.g. 'Finnish', 'Spanish', 'Japanese'"),
    sourceLanguage: z.string().optional().describe("Source language (auto-detected if not specified)"),
  },

• mcp-server/src/index.ts:205-215 (registration)

  MCP server tool registration for 'ai_translate' with description, schema, and handler

  server.tool(
    "ai_translate",
    "Translate text to any language using AI. Supports all major languages. Cost: $0.02 USDC via x402.",
    {
      text: z.string().describe("The text to translate"),
      targetLanguage: z.string().describe("Target language, e.g. 'Finnish', 'Spanish', 'Japanese'"),
      sourceLanguage: z.string().optional().describe("Source language (auto-detected if not specified)"),
    },
    async ({ text, targetLanguage, sourceLanguage }) =>
      formatResponse(await callApi("POST", "/v1/ai/translate", { text, targetLanguage, sourceLanguage }))
  );

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

  formatResponse helper function that formats API responses for MCP tool output, including payment handling 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),
        },
      ],
    };
  }