cryptopunks-mcp-server

Instructions

Implementation Reference

• src/handlers.ts:209-212 (handler)

  The handler for "get_punk_details" which calls the API function and returns the result using the helper "ok".

  case "get_punk_details": {
    const result = await api.getPunkDetails(args.punk_index, args.include_history ?? false);
    return ok(result);
  }

• src/api.ts:65-90 (handler)

  The implementation of "getPunkDetails", handling logic to fetch both details and history if requested.

  export async function getPunkDetails(punkIndex: number, includeHistory = false) {
    // Bug 3 fix: GET with includeHistory returns null history for some punks.
    // When history is requested, use the POST endpoint which reliably returns
    // full transaction history, then merge with details from GET.
    if (includeHistory) {
      const [details, history] = await Promise.all([
        get(DATA_BASE, `/api/punks/${punkIndex}/details`, { includeHistory: "false" }),
        post(DATA_BASE, `/api/punks/${punkIndex}/details`, {}),
      ]);
      // Both responses are wrapped in { success, data: { ... } }
      const detailsWrapper = details as { success?: boolean; data?: Record<string, unknown> };
      const historyWrapper = history as { success?: boolean; data?: Record<string, unknown> };
      const detailsData = detailsWrapper.data ?? detailsWrapper;
      const historyData = historyWrapper.data ?? historyWrapper;
      return {
        success: true,
        data: {
          ...(detailsData as Record<string, unknown>),
          transactionHistory:
            (historyData as Record<string, unknown>).transactionHistory ?? historyData,
          _historySource: "POST",
        },
      };
    }
    return get(DATA_BASE, `/api/punks/${punkIndex}/details`, { includeHistory: "false" });
  }

• src/tools.ts:33-44 (schema)

  Definition and input schema for "get_punk_details".

  get_punk_details: {
    description:
      "Get full details for a specific CryptoPunk including owner, for-sale price, active bid, all attributes, and optionally the complete transaction history (transfers, sales, bids, offers). When include_history is true, history is fetched via the reliable POST endpoint.",
    inputSchema: z.object({
      punk_index: punkIndex,
      include_history: z
        .boolean()
        .optional()
        .default(false)
        .describe("Set true to include the full transaction history"),
    }),
  },