asterpay-mcp-server

Instructions

Implementation Reference

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

  The ai_sentiment tool handler - calls the AsterPay API to analyze sentiment of text via POST /v1/ai/sentiment endpoint, passing the text parameter and formatting the response.

  server.tool(
    "ai_sentiment",
    "Analyze sentiment of text. Returns positive/negative/neutral classification with confidence scores. Cost: $0.004 USDC via x402.",
    { text: z.string().describe("The text to analyze sentiment for") },
    async ({ text }) => formatResponse(await callApi("POST", "/v1/ai/sentiment", { text }))
  );

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

  Input schema for ai_sentiment tool using Zod - validates that 'text' is a required string parameter with description.

  { text: z.string().describe("The text to analyze sentiment for") },

• 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 messages with x402 protocol details.

  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),
        },
      ],
    };
  }