Uranium MCP Server

Instructions

Implementation Reference

• src/tools/create-collection.ts:27-122 (handler)

  The exported async createCollection function that implements the core tool logic: input validation, user account and limit checks, listing existing collections, API call to create new collection, result formatting, and comprehensive error handling.

  export async function createCollection(
    params: z.infer<typeof createCollectionInputSchema>,
  ): Promise<CreateCollectionResult> {
    try {
      // First validate input using our schema
      const validatedParams = createCollectionInputSchema.parse(params);
  
      // Get user info to check limits
      const accountResponse = await api.account.getMe({
        deviceId: MCP_CONFIG.DEVICE_ID,
      });
  
      if (accountResponse.status !== "ok" || !accountResponse.ok) {
        return {
          success: false,
          error: "Failed to get user account information",
        };
      }
  
      const user = accountResponse.ok;
      const isAdmin = user.role === "ADMIN";
      const userId = user.userId;
      const smartContractsLimit = isAdmin ? SMART_CONTRACTS_ADMIN_LIMIT : SMART_CONTRACTS_USER_LIMIT;
  
      // Get existing contracts to check limits
      const contractsResponse = await api.contracts.list(null);
  
      if (contractsResponse.status !== "ok") {
        return {
          success: false,
          error: "Failed to check existing collections",
        };
      }
  
      const contracts = contractsResponse.data || [];
      const personalContracts = contracts.filter(
        (contract) => contract.type !== "EXTERNAL" && userId === contract.userId,
      );
  
      // Check if user can create more contracts
      if (personalContracts.length >= smartContractsLimit) {
        return {
          success: false,
          error: `You have reached the limit of ${smartContractsLimit} collections`,
        };
      }
  
      // Create the contract
      const createResponse = await api.contracts.create({
        name: validatedParams.name,
        symbol: validatedParams.symbol,
        type: validatedParams.type,
      });
  
      if (createResponse.status !== "ok" || !createResponse.data) {
        return {
          success: false,
          error: createResponse.errorCode || "Failed to create collection",
        };
      }
  
      const createdContract = createResponse.data;
  
      return {
        success: true,
        data: {
          collection: {
            id: createdContract.id,
            name: createdContract.name,
            symbol: createdContract.symbol,
            type: createdContract.type,
            status: createdContract.status,
            ercType: createdContract.ercType,
            address: createdContract.address || undefined,
            createdAt: createdContract.createdAt
              ? new Date(createdContract.createdAt.seconds * 1000).toISOString()
              : undefined,
          },
          message: `Collection "${createdContract.name}" created successfully!`,
        },
      };
    } catch (error) {
      if (error instanceof z.ZodError) {
        const errorMessages = error.issues.map((err) => err.message).join(", ");
        return {
          success: false,
          error: `Validation error: ${errorMessages}`,
        };
      }
  
      return {
        success: false,
        error: error instanceof Error ? error.message : "Unknown error occurred",
      };
    }
  }

• src/utils/schemas.ts:4-18 (schema)

  Zod input schema for creating smart contracts/collections, defining validated fields: name (regex), symbol (regex), type (ERC721|ERC1155). Reused as createCollectionInputSchema.

  export const createSmartContractSchema = z.object({
    name: z
      .string()
      .regex(
        smartContractNameRegex,
        "Name must be between 3 and 30 characters long and can contain only letters, numbers and [_.-] symbols",
      ),
    symbol: z
      .string()
      .regex(
        smartContractSymbolRegex,
        "Identifier must be between 3 and 30 characters long and can contain only letters, numbers and underscores",
      ),
    type: z.enum(["ERC721", "ERC1155"]),
  });

• src/server.ts:63-75 (registration)

  Switch case in the MCP CallToolRequest handler that registers 'create_collection': parses args with input schema, calls createCollection handler, returns result as JSON text content.

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

• src/tools/create-collection.ts:9-25 (schema)

  TypeScript interface for the tool's output: CreateCollectionResult with success flag, data (collection details), optional error.

  export interface CreateCollectionResult {
    success: boolean;
    data?: {
      collection: {
        id: string;
        name: string;
        symbol: string;
        type: string;
        status: string;
        ercType: string;
        address?: string;
        createdAt?: string;
      };
      message: string;
    };
    error?: string;
  }

• src/tools/create-collection.ts:7-7 (schema)

  Exports the input schema for the tool by aliasing createSmartContractSchema.

  export const createCollectionInputSchema = createSmartContractSchema;