cryptopunks-mcp-server

Instructions

Implementation Reference

• src/handlers.ts:172-207 (handler)

  The handler for the 'get_punk' tool. It fetches basic data from the API and enriches it with metadata to ensure accurate type classification for non-human punks.

  case "get_punk": {
    const raw = await api.getPunk(args.punk_index);
    // Bug 2 fix: the basic /punks/{index} endpoint returns incorrect type
    // for non-human punks (e.g. Alien #7804 reports as MALE). Enrich with
    // metadata which has the correct type classification.
    try {
      const metadata = await api.getPunkMetadata(args.punk_index);
      const metaWrapper = metadata as { data?: Record<string, unknown> };
      const metaData = metaWrapper.data ?? metadata as Record<string, unknown>;
      const rawWrapper = raw as { success?: boolean; data?: Record<string, unknown> };
      const rawData = rawWrapper.data ?? raw as Record<string, unknown>;
      return ok({
        success: true,
        data: {
          ...(rawData as Record<string, unknown>),
          type: (metaData as Record<string, unknown>).type ?? (rawData as Record<string, unknown>).type,
          typeName: (metaData as Record<string, unknown>).typeName ?? (rawData as Record<string, unknown>).typeName,
          isHuman: (metaData as Record<string, unknown>).isHuman ?? (rawData as Record<string, unknown>).isHuman,
          _typeSource: "metadata (corrected)",
        },
      });
    } catch {
      // If metadata fails, return raw with a warning
      const rawWrapper = raw as { success?: boolean; data?: Record<string, unknown> };
      if (rawWrapper.data) {
        return ok({
          success: true,
          data: {
            ...rawWrapper.data,
            _typeWarning: "Type may be inaccurate for non-human punks. Use get_punk_metadata for reliable type data.",
          },
        });
      }
      return ok(raw);
    }
  }

• src/tools.ts:27-31 (registration)

  The registration and schema definition for the 'get_punk' tool.

  get_punk: {
    description:
      "Get basic information about a specific CryptoPunk: owner address, type, attributes, current asking price, current bid, and whether it is for sale. NOTE: the type field from this endpoint may be unreliable for non-human punks (Aliens, Apes, Zombies). Use get_punk_metadata or get_punk_traits for accurate type data.",
    inputSchema: z.object({ punk_index: punkIndex }),
  },