Uranium MCP Server

Instructions

Implementation Reference

• src/tools/list-assets.ts:59-141 (handler)

  Main handler function that fetches, processes, and returns a paginated list of assets with status formatting and helper functions.

  export async function listAssets(params: z.infer<typeof listAssetsInputSchema>): Promise<AssetListResult> {
    try {
      const response = await api.assets.list({
        contractId: params.contractId,
        page: params.page,
        pageSize: params.pageSize,
        sortBy: params.sortBy ?? "createdAt",
        order: params.order ?? "asc",
        quickFilter: params.quickFilter,
      });
  
      if (response.status !== "ok" || !response.ok) {
        return {
          success: false,
          error: response.errorCode || "Failed to load assets",
        };
      }
  
      const assetsData = response.ok.data || [];
      const meta = response.ok.meta;
  
      const assets = assetsData.map((asset) => ({
        id: asset.id,
        title: asset.title,
        description: asset.description || undefined,
        collectionName: asset.collectionName,
        contractId: asset.contractId,
        status: asset.status.toString(),
        statusText: getAssetStatusText(asset.status),
        isMinted: isAssetMinted(asset.status),
        mediaType: asset.mediaType,
        ercContractType: asset.ercContractType,
        currentEditions: asset.currentEditions,
        totalEditions: asset.editions,
        thumbnailUrl: asset.thumbnailUrl || undefined,
        sourceUrl: asset.sourceUrl,
        contractAddress: asset.contractAddress || undefined,
        tokenId: asset.tokenId || undefined,
        openSeaUrl: asset.openSeaUrl || undefined,
        creatorName: asset.creatorName,
        creatorAddress: formatAddress(asset.creatorAddress),
        currentOwnerName: asset.currentOwnerName || undefined,
        currentOwnerAddress: formatAddress(asset.currentOwnerAddress),
        location: asset.location || undefined,
        isEncrypted: asset.isEncrypted,
        isListed: asset.isListed,
        inTransfer: asset.inTransfer,
        createdAt: asset.createdAt ? formatDate(asset.createdAt) : undefined,
        mintedAt: asset.mintedAt ? formatDate(asset.mintedAt) : undefined,
      }));
  
      const pagination = meta
        ? {
            page: meta.page,
            pageSize: meta.pageSize,
            total: meta.total,
            totalPages: meta.countPages,
            hasNextPage: meta.page < meta.countPages,
            hasPreviousPage: meta.page > 1,
          }
        : {
            page: params.page,
            pageSize: params.pageSize,
            total: assets.length,
            totalPages: 1,
            hasNextPage: false,
            hasPreviousPage: false,
          };
  
      return {
        success: true,
        data: {
          assets,
          pagination,
        },
      };
    } catch (error) {
      return {
        success: false,
        error: error instanceof Error ? error.message : "Unknown error occurred",
      };
    }
  }

• src/tools/list-assets.ts:6-13 (schema)

  Zod input schema defining parameters for filtering, pagination, and sorting assets.

  export const listAssetsInputSchema = z.object({
    contractId: z.string().optional().describe("Filter assets by collection ID"),
    page: z.number().min(1).default(1).describe("Page number (default: 1)"),
    pageSize: z.number().min(1).max(100).default(20).describe("Number of assets per page (default: 20, max: 100)"),
    sortBy: z.string().default("createdAt").describe("Sort field (default: createdAt)"),
    order: z.enum(["asc", "desc"]).default("asc").describe("Sort order (default: asc)"),
    quickFilter: z.string().optional().describe("Search text to filter assets by title"),
  });

• src/server.ts:49-61 (registration)

  Registration of the list_assets tool in the MCP server request handler, including input validation and execution.

  case "list_assets": {
    // Validate and parse arguments
    const validatedArgs = listAssetsInputSchema.parse(args || {});
    const result = await listAssets(validatedArgs);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }