@fil-b/foc-storage-mcp 0.1.0

package/dist/mcp-server.js

@@ -0,0 +1,1412 @@
+#!/usr/bin/env node
+
+// src/mcp-server.ts
+import { config as config2 } from "dotenv";
+
+// src/mastra/index.ts
+import { Mastra } from "@mastra/core/mastra";
+import { PinoLogger } from "@mastra/loggers";
+import { LibSQLStore } from "@mastra/libsql";
+import { MCPServer } from "@mastra/mcp";
+
+// src/mastra/agents/foc-storage-agent.ts
+import { Agent } from "@mastra/core/agent";
+
+// src/mastra/tools/dataset-tools.ts
+import { createTool } from "@mastra/core";
+
+// src/types/core.ts
+import {
+  TIME_CONSTANTS,
+  SIZE_CONSTANTS,
+  TOKENS
+} from "@filoz/synapse-sdk";
+
+// src/types/schemas.ts
+import { z as z2 } from "zod";
+
+// src/config/index.ts
+import { config } from "dotenv";
+import { z } from "zod";
+config();
+var EnvSchema = z.object({
+  PRIVATE_KEY: z.string().min(1, "PRIVATE_KEY is required"),
+  FILECOIN_NETWORK: z.enum(["mainnet", "calibration"]).default("calibration"),
+  TOTAL_STORAGE_NEEDED_GiB: z.coerce.number().default(1024),
+  PERSISTENCE_PERIOD_DAYS: z.coerce.number().default(365),
+  RUNOUT_NOTIFICATION_THRESHOLD_DAYS: z.coerce.number().default(10)
+});
+var env = EnvSchema.parse(process.env);
+var NETWORK_CONFIGS = {
+  mainnet: {
+    chainId: 314,
+    name: "Filecoin Mainnet",
+    rpcUrl: "https://api.node.glif.io/rpc/v1"
+  },
+  calibration: {
+    chainId: 314159,
+    name: "Filecoin Calibration",
+    rpcUrl: "https://api.calibration.node.glif.io/rpc/v1"
+  }
+};
+var MAX_UINT256 = 2n ** 256n - 1n;
+var DATA_SET_CREATION_FEE = BigInt(0.1 * 10 ** 18);
+var BYTES_PER_TIB = 1024n * 1024n * 1024n * 1024n;
+var BYTES_PER_GIB = 1024n * 1024n * 1024n;
+var DEFAULT_EXPECTED_STORAGE_BYTES = 1024 * 1024 * 1024 * 1024;
+
+// src/types/schemas.ts
+import { SIZE_CONSTANTS as SIZE_CONSTANTS2 } from "@filoz/synapse-sdk";
+var GetDatasetsSchema = z2.object({
+  includeAllDatasets: z2.boolean().optional().describe("Include all datasets. Default: false"),
+  filterByCDN: z2.boolean().optional().describe("Filter to only CDN-enabled datasets. Default: false. If includeAllDatasets is true, this will be ignored")
+});
+var GetDatasetSchema = z2.object({
+  datasetId: z2.string().describe("Dataset ID to get.")
+});
+var CreateDatasetSchema = z2.object({
+  withCDN: z2.boolean().optional().default(false).describe("Enable CDN for faster file retrieval. Default: false. Recommended for frequently accessed files"),
+  providerId: z2.string().optional().describe("Specific storage provider ID. If not specified, best provider will be auto-selected"),
+  // Metadata for the dataset - allows up to 10 string key-value pairs
+  metadata: z2.record(z2.string(), z2.string()).optional().refine((data) => !data || Object.keys(data).length <= 10, {
+    message: "Metadata can contain at most 10 key-value pairs"
+  }).describe("Metadata for the dataset. Supports up to 10 string key-value pairs where both keys and values must be strings")
+});
+var UploadFileSchema = z2.object({
+  filePath: z2.string().describe("Absolute path to file on local filesystem to upload"),
+  fileName: z2.string().optional().describe("Custom filename for storage. If not provided, uses original filename"),
+  metadata: z2.record(z2.string(), z2.string()).optional().refine((data) => !data || Object.keys(data).length <= 4, {
+    message: "Metadata can contain at most 4 key-value pairs"
+  }).describe("Metadata for the file. Supports up to 4 string key-value pairs where both keys and values must be strings"),
+  datasetId: z2.string().optional().describe("Existing dataset ID to add file to. If not provided, creates new dataset"),
+  withCDN: z2.boolean().optional().describe("Enable CDN for this file. Default: false. Use for frequently accessed files"),
+  autoPayment: z2.boolean().optional().default(true).describe("Automatically process payment if insufficient balance. Default: true")
+});
+var GetBalancesSchema = z2.object({
+  storageCapacityBytes: z2.number().optional().default(env.TOTAL_STORAGE_NEEDED_GiB * Number(SIZE_CONSTANTS2.GiB)).describe("Storage capacity in bytes. Default: 1 TB. This is used to calculate the storage needs and the deposit needed."),
+  persistencePeriodDays: z2.number().optional().default(env.PERSISTENCE_PERIOD_DAYS).describe("Persistence period in days. Default: 365. This is used to calculate the storage needs and the deposit needed."),
+  notificationThresholdDays: z2.number().optional().default(env.RUNOUT_NOTIFICATION_THRESHOLD_DAYS).describe("Notification threshold in days. Default: 10. This is used check if the user needs to top up their storage balance before the storage balance runs out.")
+});
+var ProcessPaymentSchema = z2.object({
+  depositAmount: z2.number().optional().default(0).describe("Amount to deposit in USDFC. Default: 0. If not provided, the tool will check the balance and deposit the necessary amount.")
+});
+var GetProvidersSchema = z2.object({
+  onlyApproved: z2.boolean().optional().default(true).describe("Filter to only approved providers. Default: true")
+});
+var BaseErrorResponseSchema = z2.object({
+  success: z2.literal(false),
+  error: z2.string(),
+  message: z2.string()
+});
+var UnifiedSizeInfoSchema = z2.object({
+  sizeBytes: z2.string(),
+  sizeKiB: z2.number(),
+  sizeMiB: z2.number(),
+  sizeGiB: z2.number(),
+  withCDN: z2.boolean().optional(),
+  leafCount: z2.number().optional(),
+  pieceCount: z2.number().optional(),
+  message: z2.string().optional()
+});
+var DataSetPieceSchema = z2.object({
+  pieceCid: z2.string(),
+  retrievalUrl: z2.string(),
+  sizes: UnifiedSizeInfoSchema,
+  metadata: z2.record(z2.string(), z2.string())
+});
+var DataSetSchema = z2.object({
+  datasetId: z2.number(),
+  withCDN: z2.boolean(),
+  datasetMetadata: z2.record(z2.string(), z2.string()),
+  totalDatasetSizeMessage: z2.string(),
+  dataSetPieces: z2.array(DataSetPieceSchema)
+});
+var FormattedStorageBalanceResultSchema = z2.object({
+  depositNeeded: z2.string(),
+  availableToFreeUp: z2.string(),
+  daysLeftAtMaxBurnRate: z2.number(),
+  daysLeftAtBurnRate: z2.number(),
+  isRateSufficient: z2.boolean(),
+  isLockupSufficient: z2.boolean(),
+  isSufficient: z2.boolean(),
+  availableFunds: z2.string(),
+  currentMonthlyRate: z2.string(),
+  maxMonthlyRate: z2.string()
+});
+var GetProvidersOutputSchema = z2.object({
+  success: z2.boolean(),
+  // Success fields
+  providers: z2.array(z2.any()).optional(),
+  count: z2.number().optional(),
+  // Error fields  
+  error: z2.string().optional(),
+  // Common field
+  message: z2.string()
+});
+var UploadFileOutputSchema = z2.object({
+  success: z2.boolean(),
+  // Success fields
+  taskId: z2.string().optional(),
+  pieceCid: z2.string().optional(),
+  retrievalUrl: z2.string().optional(),
+  txHash: z2.string().optional(),
+  fileName: z2.string().optional(),
+  fileSize: z2.number().optional(),
+  progressLog: z2.array(z2.string()).optional(),
+  // Error fields
+  error: z2.string().optional(),
+  // Common field
+  message: z2.string()
+});
+var ProcessPaymentOutputSchema = z2.object({
+  success: z2.boolean(),
+  message: z2.string(),
+  txHash: z2.string().nullable().optional(),
+  required: z2.object({
+    deposit: z2.number()
+  }).optional(),
+  available: z2.number().optional(),
+  // Error fields
+  error: z2.string().optional()
+});
+var GetBalancesOutputSchema = z2.object({
+  success: z2.boolean(),
+  // Success fields
+  checkStorageBalanceResultFormatted: z2.any().optional(),
+  checkStorageBalanceResult: z2.any().optional(),
+  // Error fields
+  error: z2.string().optional(),
+  message: z2.string().optional()
+});
+var GetDatasetsOutputSchema = z2.object({
+  success: z2.boolean(),
+  // Success fields
+  datasets: z2.array(DataSetSchema).optional(),
+  count: z2.number().optional(),
+  // Error fields
+  error: z2.string().optional(),
+  // Common field
+  message: z2.string()
+});
+var GetDatasetOutputSchema = z2.object({
+  success: z2.boolean(),
+  // Success fields
+  dataset: DataSetSchema,
+  // Error fields
+  error: z2.string().optional(),
+  // Common field
+  message: z2.string()
+});
+var CreateDatasetOutputSchema = z2.object({
+  success: z2.boolean(),
+  // Success fields
+  datasetId: z2.string().optional(),
+  txHash: z2.string().optional(),
+  // Error fields
+  error: z2.string().optional(),
+  // Common field
+  message: z2.string()
+});
+
+// src/lib/calculations.ts
+import Decimal from "decimal.js";
+import { SIZE_CONSTANTS as SIZE_CONSTANTS3 } from "@filoz/synapse-sdk";
+import { getSizeFromPieceCID } from "@filoz/synapse-sdk/piece";
+Decimal.set({
+  precision: 34,
+  rounding: Decimal.ROUND_HALF_UP,
+  toExpNeg: -21,
+  toExpPos: 21,
+  maxE: 9e15,
+  minE: -9e15,
+  modulo: Decimal.ROUND_DOWN
+});
+var toDecimal = (value) => value instanceof Decimal ? value : new Decimal(value.toString());
+var bytesToKiB = (bytes) => toDecimal(bytes).div(new Decimal(SIZE_CONSTANTS3.KiB.toString()));
+var bytesToMiB = (bytes) => toDecimal(bytes).div(new Decimal(SIZE_CONSTANTS3.MiB.toString()));
+var bytesToGiB = (bytes) => toDecimal(bytes).div(new Decimal(SIZE_CONSTANTS3.GiB.toString()));
+var getPieceInfoFromCidBytes = (input) => {
+  const sizeBytes = BigInt(getSizeFromPieceCID(input));
+  return {
+    sizeBytes,
+    sizeKiB: bytesToKiB(sizeBytes).toNumber(),
+    sizeMiB: bytesToMiB(sizeBytes).toNumber(),
+    sizeGiB: bytesToGiB(sizeBytes).toNumber()
+  };
+};
+var sizeInfoMessage = (sizeInfo) => {
+  if (sizeInfo.sizeInGB > 0.1) {
+    return `Dataset size: ${sizeInfo.sizeInGB.toFixed(4)} GB`;
+  }
+  if (sizeInfo.sizeInMiB > 0.1) {
+    return `Dataset size: ${sizeInfo.sizeInMiB.toFixed(4)} MB`;
+  }
+  if (sizeInfo.sizeInKiB > 0.1) {
+    return `Dataset size: ${sizeInfo.sizeInKiB.toFixed(4)} KB`;
+  }
+  return `Dataset size: ${sizeInfo.sizeInBytes} Bytes`;
+};
+
+// src/lib/synapse.ts
+import { Synapse } from "@filoz/synapse-sdk";
+var getSynapseInstance = async () => {
+  const network = env.FILECOIN_NETWORK;
+  const synapse = await Synapse.create(
+    {
+      privateKey: env.PRIVATE_KEY,
+      rpcURL: NETWORK_CONFIGS[network].rpcUrl
+    }
+  );
+  return synapse;
+};
+
+// src/lib/utils.ts
+import { promises as fs } from "fs";
+async function validateFilePath(filePath) {
+  try {
+    const stats = await fs.stat(filePath);
+    if (!stats.isFile()) {
+      throw new Error(`Path is not a file: ${filePath}`);
+    }
+    return {
+      path: filePath,
+      size: stats.size
+    };
+  } catch (error) {
+    throw new Error(`File not found or inaccessible: ${filePath}`);
+  }
+}
+function createErrorResponse(errorType, message, additionalData) {
+  return {
+    success: false,
+    error: errorType,
+    message,
+    ...additionalData
+  };
+}
+function fromBaseUnits(amount, decimals = 18) {
+  const str = amount.toString().padStart(decimals + 1, "0");
+  const whole = str.slice(0, -decimals) || "0";
+  const decimal = str.slice(-decimals).replace(/0+$/, "");
+  return decimal ? `${whole}.${decimal}` : whole;
+}
+function serializeBigInt(obj) {
+  if (obj === null || obj === void 0) {
+    return obj;
+  }
+  if (typeof obj === "bigint") {
+    return obj.toString();
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(serializeBigInt);
+  }
+  if (typeof obj === "object") {
+    return Object.fromEntries(
+      Object.entries(obj).map(([key, value]) => [key, serializeBigInt(value)])
+    );
+  }
+  return obj;
+}
+
+// src/services/wallet-service.ts
+import { ethers, Wallet, JsonRpcProvider } from "ethers";
+
+// src/services/payment-service.ts
+import { TIME_CONSTANTS as TIME_CONSTANTS2 } from "@filoz/synapse-sdk";
+async function processStoragePayment(synapse, depositAmount, persistenceDays) {
+  const warmStorageAddress = synapse.getWarmStorageAddress();
+  const epochs = TIME_CONSTANTS2.EPOCHS_PER_DAY * BigInt(persistenceDays);
+  if (depositAmount > 0n) {
+    const tx = await synapse.payments.depositWithPermitAndApproveOperator(
+      depositAmount,
+      warmStorageAddress,
+      MAX_UINT256,
+      MAX_UINT256,
+      epochs
+    );
+    const receipt = await tx.wait(1);
+    return { txHash: receipt?.hash || tx.hash, success: true };
+  } else {
+    const tx = await synapse.payments.approveService(
+      warmStorageAddress,
+      MAX_UINT256,
+      MAX_UINT256,
+      epochs
+    );
+    const receipt = await tx.wait(1);
+    return { txHash: receipt?.hash || tx.hash, success: true };
+  }
+}
+
+// src/services/dataset-service.ts
+import { PDPServer, WarmStorageService } from "@filoz/synapse-sdk";
+var getDatasets = async (withCDN = false, includeAll = false, onlyDatasetId = void 0) => {
+  try {
+    const synapse = await getSynapseInstance();
+    const warmStorageAddress = synapse.getWarmStorageAddress();
+    const warmStorageService = await WarmStorageService.create(synapse.getProvider(), warmStorageAddress);
+    const datasets = await synapse.storage.findDataSets();
+    if (datasets.length === 0) {
+      return {
+        success: true,
+        datasets: [],
+        count: 0,
+        message: "No datasets found. Upload files to create your first dataset."
+      };
+    }
+    const providers = await Promise.all(
+      datasets.map(
+        (dataset) => synapse.getProviderInfo(dataset.providerId).catch(() => null)
+      )
+    );
+    const userAddress = await synapse.getSigner().getAddress();
+    const filteredDatasets = datasets.filter((dataset) => {
+      if (onlyDatasetId !== void 0) {
+        return dataset.pdpVerifierDataSetId === onlyDatasetId;
+      }
+      if (includeAll) {
+        return true;
+      }
+      return dataset.withCDN === withCDN;
+    });
+    if (filteredDatasets.length === 0) {
+      return {
+        success: true,
+        datasets: [],
+        count: 0,
+        message: `No datasets found with the given criteria`
+      };
+    }
+    const enrichedDatasets = await Promise.all(
+      filteredDatasets.map(async (dataset) => {
+        const provider = providers.find((p) => p?.id === dataset.providerId);
+        const serviceURL = provider.products.PDP?.data.serviceURL || "";
+        try {
+          const pdpServer = new PDPServer(null, serviceURL);
+          const data = await pdpServer.getDataSet(dataset.pdpVerifierDataSetId).then((data2) => {
+            data2.pieces.reverse();
+            return data2;
+          });
+          const pieces = data.pieces.reduce(
+            (acc, piece) => {
+              acc[piece.pieceCid.toV1().toString()] = getPieceInfoFromCidBytes(piece.pieceCid);
+              return acc;
+            },
+            {}
+          );
+          const piecesMetadata = (await Promise.all(data.pieces.map(async (piece) => {
+            return { pieceId: piece.pieceId, metadata: await warmStorageService.getPieceMetadata(dataset.pdpVerifierDataSetId, piece.pieceId) };
+          }))).reduce((acc, piece) => {
+            acc[piece.pieceId] = piece.metadata;
+            return acc;
+          }, {});
+          const getRetrievalUrl = (pieceCid) => {
+            if (dataset.withCDN) {
+              return `https://${userAddress}.calibration.filbeam.io/${pieceCid}`;
+            } else {
+              return `${serviceURL}/piece/${pieceCid}`;
+            }
+          };
+          const datasetSizeInfo = data.pieces.reduce((acc, piece) => {
+            acc.sizeInBytes += Number(pieces[piece.pieceCid.toV1().toString()].sizeBytes);
+            acc.sizeInKiB += Number(pieces[piece.pieceCid.toV1().toString()].sizeKiB);
+            acc.sizeInMiB += Number(pieces[piece.pieceCid.toV1().toString()].sizeMiB);
+            acc.sizeInGB += Number(pieces[piece.pieceCid.toV1().toString()].sizeGiB);
+            return acc;
+          }, { sizeInBytes: 0, sizeInKiB: 0, sizeInMiB: 0, sizeInGB: 0, message: "" });
+          const dataSetPieces = data.pieces.map((piece) => ({
+            pieceCid: piece.pieceCid.toV1().toString(),
+            retrievalUrl: getRetrievalUrl(piece.pieceCid.toV1().toString()),
+            sizes: pieces[piece.pieceCid.toV1().toString()],
+            metadata: piecesMetadata[piece.pieceId]
+          }));
+          return {
+            datasetId: dataset.pdpVerifierDataSetId,
+            withCDN: dataset.withCDN,
+            datasetMetadata: dataset.metadata,
+            totalDatasetSizeMessage: sizeInfoMessage(datasetSizeInfo),
+            dataSetPieces
+          };
+        } catch (error) {
+          return null;
+        }
+      })
+    );
+    return {
+      success: true,
+      datasets: enrichedDatasets.filter((dataset) => dataset !== null).map(serializeBigInt),
+      count: enrichedDatasets.length,
+      message: `Found ${enrichedDatasets.length} dataset(s)`
+    };
+  } catch (error) {
+    return createErrorResponse(
+      "dataset_fetch_failed",
+      `Failed to fetch datasets: ${error.message}`,
+      { success: false }
+    );
+  }
+};
+
+// src/services/storage-service.ts
+import {
+  SIZE_CONSTANTS as SIZE_CONSTANTS4,
+  TIME_CONSTANTS as TIME_CONSTANTS3,
+  TOKENS as TOKENS2,
+  WarmStorageService as WarmStorageService2
+} from "@filoz/synapse-sdk";
+import { formatUnits } from "viem";
+var checkStorageBalance = async (synapse, storageCapacityBytes = env.TOTAL_STORAGE_NEEDED_GiB * Number(SIZE_CONSTANTS4.GiB), persistencePeriodDays = env.PERSISTENCE_PERIOD_DAYS) => {
+  const warmStorageService = await WarmStorageService2.create(synapse.getProvider(), synapse.getWarmStorageAddress());
+  const [storageInfo, accountInfo, prices] = await Promise.all([
+    synapse.storage.getStorageInfo(),
+    synapse.payments.accountInfo(TOKENS2.USDFC),
+    warmStorageService.calculateStorageCost(storageCapacityBytes)
+  ]);
+  let filRaw;
+  try {
+    filRaw = await synapse.payments.walletBalance();
+  } catch (error) {
+    console.error(error);
+    throw new Error("Error fetching wallet balances. \n FIL balance not available. \n The main cause of this error is that your wallet doesn't have any FIL and has no transaction history on the network. Action: Top up your wallet with FIL.");
+  }
+  let usdfcRaw = await synapse.payments.walletBalance(TOKENS2.USDFC);
+  const allowance = storageInfo.allowances;
+  const availableFunds = accountInfo.availableFunds;
+  const currentMonthlyRate = allowance.rateUsed * TIME_CONSTANTS3.EPOCHS_PER_MONTH;
+  const maxMonthlyRate = prices.perMonth;
+  const daysLeftAtMaxBurnRate = maxMonthlyRate === 0n ? Infinity : Number(availableFunds) / Number(maxMonthlyRate) * 30;
+  const daysLeftAtBurnRate = currentMonthlyRate === 0n ? Infinity : Number(availableFunds) / Number(currentMonthlyRate) * 30;
+  const amountNeeded = prices.perDay * BigInt(persistencePeriodDays);
+  const totalDepositNeeded = daysLeftAtMaxBurnRate >= env.RUNOUT_NOTIFICATION_THRESHOLD_DAYS ? 0n : amountNeeded - accountInfo.availableFunds;
+  const availableToFreeUp = accountInfo.availableFunds > amountNeeded ? accountInfo.availableFunds - amountNeeded : 0n;
+  const isRateSufficient = allowance.rateAllowance === MAX_UINT256;
+  const isLockupSufficient = allowance.lockupAllowance === MAX_UINT256;
+  const isSufficient = isRateSufficient && isLockupSufficient && daysLeftAtMaxBurnRate >= env.RUNOUT_NOTIFICATION_THRESHOLD_DAYS;
+  return {
+    filBalance: filRaw,
+    usdfcBalance: usdfcRaw,
+    availableStorageFundsUsdfc: availableFunds,
+    depositNeeded: totalDepositNeeded,
+    availableToFreeUp,
+    daysLeftAtMaxBurnRate,
+    daysLeftAtBurnRate,
+    isRateSufficient,
+    isLockupSufficient,
+    isSufficient,
+    currentStorageMonthlyRate: currentMonthlyRate,
+    maxStorageMonthlyRate: maxMonthlyRate
+  };
+};
+var formatStorageBalanceResult = (checkStorageBalanceResult) => {
+  return {
+    filBalance: formatBalance(checkStorageBalanceResult.filBalance, "FIL"),
+    usdfcBalance: formatBalance(checkStorageBalanceResult.usdfcBalance, "USDFC"),
+    availableStorageFundsUsdfc: formatBalance(checkStorageBalanceResult.availableStorageFundsUsdfc, "USDFC"),
+    depositNeeded: formatBalance(checkStorageBalanceResult.depositNeeded, "USDFC"),
+    availableToFreeUp: formatBalance(checkStorageBalanceResult.availableToFreeUp, "USDFC"),
+    currentStorageMonthlyRate: formatBalance(checkStorageBalanceResult.currentStorageMonthlyRate, "USDFC"),
+    maxStorageMonthlyRate: formatBalance(checkStorageBalanceResult.maxStorageMonthlyRate, "USDFC"),
+    daysLeftAtMaxBurnRate: formatTime(checkStorageBalanceResult.daysLeftAtMaxBurnRate),
+    daysLeftAtBurnRate: formatTime(checkStorageBalanceResult.daysLeftAtBurnRate),
+    isRateSufficient: checkStorageBalanceResult.isRateSufficient,
+    isLockupSufficient: checkStorageBalanceResult.isLockupSufficient,
+    isSufficient: checkStorageBalanceResult.isSufficient
+  };
+};
+var formatBalance = (balance, ticker) => {
+  return `${Number(Number(formatUnits(balance, 18)).toFixed(8))} ${ticker}`;
+};
+var formatTime = (days) => {
+  if (days === Infinity) {
+    return "Infinity";
+  }
+  if (days < 1) {
+    return `${Math.fround(days * 24)} hours`;
+  }
+  if (days < 30) {
+    return `${Math.fround(days)} days`;
+  }
+  if (days < 365) {
+    return `${Math.fround(days / 30)} months`;
+  }
+  return `${Math.fround(days / 365)} years`;
+};
+
+// src/mastra/tools/dataset-tools.ts
+var getDatasets2 = createTool({
+  id: "getDatasets",
+  description: "Retrieve all datasets owned by the connected wallet with comprehensive information including piece CIDs, file sizes, provider details, and retrieval URLs. Filter by CDN status or view all datasets. Each dataset contains complete metadata about stored files and their blockchain storage proofs. Use this to inventory files, check storage status, or locate specific uploads.",
+  inputSchema: GetDatasetsSchema,
+  outputSchema: GetDatasetsOutputSchema,
+  execute: async ({ context }) => {
+    const withCDN = context.filterByCDN ?? false;
+    const includeAll = context.includeAllDatasets ?? false;
+    return await getDatasets(withCDN, includeAll);
+  }
+});
+var getDataset = createTool({
+  id: "getDataset",
+  description: "Retrieve detailed information about a specific dataset by its ID, including all pieces (files), their CIDs, sizes, retrieval URLs, and metadata. Returns the same comprehensive data structure as getDatasets but for a single dataset. Use this when you know the dataset ID and need detailed information about its contents.",
+  inputSchema: GetDatasetSchema,
+  outputSchema: GetDatasetOutputSchema,
+  execute: async ({ context }) => {
+    try {
+      const dataset = await getDatasets(void 0, void 0, Number(context.datasetId));
+      return {
+        success: dataset.success,
+        dataset: serializeBigInt(dataset.datasets[0]),
+        message: dataset.message
+      };
+    } catch (error) {
+      return createErrorResponse(
+        "dataset_fetch_failed",
+        `Failed to fetch dataset: ${error.message}`,
+        { success: false }
+      );
+    }
+  }
+});
+var createDataset = createTool({
+  id: "createDataset",
+  description: "Create a new dataset container on Filecoin for organizing related files with consistent storage settings. Datasets define storage parameters (CDN enabled/disabled, provider selection) that apply to all files added to them. Creating datasets upfront allows for better file organization and consistent retrieval performance. Optionally specify a provider or let the system auto-select the optimal one. Note: Payment is processed automatically for CDN-enabled datasets.",
+  inputSchema: CreateDatasetSchema,
+  outputSchema: CreateDatasetOutputSchema,
+  execute: async ({ context }) => {
+    try {
+      const synapse = await getSynapseInstance();
+      const withCDN = true;
+      if (withCDN) {
+        const paymentResult = await processStoragePayment(synapse, BigInt(env.TOTAL_STORAGE_NEEDED_GiB * Number(SIZE_CONSTANTS.GiB)), env.PERSISTENCE_PERIOD_DAYS);
+        if (!paymentResult.success) {
+          return createErrorResponse(
+            "payment_failed",
+            `Failed to process payment: ${paymentResult.txHash ?? "Unknown error"}`,
+            { success: false }
+          );
+        }
+      }
+      let datasetId;
+      let txHash;
+      await synapse.createStorage({
+        providerId: context.providerId ? parseInt(context.providerId) : void 0,
+        forceCreateDataSet: true,
+        metadata: context.metadata,
+        callbacks: {
+          onDataSetCreationStarted: (txResponse) => {
+            txHash = txResponse.hash;
+            console.log(`[Dataset] Creation started (tx: ${txResponse.hash})`);
+          },
+          onDataSetCreationProgress: (status) => {
+            if (status.serverConfirmed) {
+              datasetId = status.dataSetId?.toString() || void 0;
+              console.log(`[Dataset] Ready (ID: ${status.dataSetId?.toString()})`);
+            }
+          }
+        }
+      });
+      return {
+        success: true,
+        datasetId,
+        txHash,
+        message: "Dataset created successfully"
+      };
+    } catch (error) {
+      return createErrorResponse(
+        "dataset_creation_failed",
+        `Failed to create dataset: ${error.message}`,
+        { success: false }
+      );
+    }
+  }
+});
+var datasetTools = {
+  getDataset,
+  getDatasets: getDatasets2,
+  createDataset
+};
+
+// src/mastra/tools/file-tools.ts
+import { createTool as createTool2 } from "@mastra/core";
+import { promises as fs2 } from "fs";
+import { basename } from "path";
+var uploadFile = createTool2({
+  id: "uploadFile",
+  description: "Upload files to decentralized Filecoin storage with automatic payment handling and progress tracking. Supports both standard storage and CDN-enabled storage for frequently accessed files. The upload process is tracked through 8 phases with detailed progress logging. Prerequisites: Valid file path, PRIVATE_KEY environment variable. Returns pieceCid for retrieval and transaction hash for verification.",
+  inputSchema: UploadFileSchema,
+  outputSchema: UploadFileOutputSchema,
+  execute: async ({ context }) => {
+    const progressLog = [];
+    const log = (msg) => {
+      progressLog.push(msg);
+      console.log(`[Upload] ${msg}`);
+    };
+    try {
+      log("Validating file...");
+      const fileInfo = await validateFilePath(context.filePath);
+      const fileName = context.fileName || basename(fileInfo.path);
+      log("Reading file...");
+      const fileBuffer = await fs2.readFile(fileInfo.path);
+      const uint8ArrayBytes = new Uint8Array(fileBuffer);
+      log("Initializing Synapse SDK...");
+      const synapse = await getSynapseInstance();
+      log("Checking storage balance...");
+      const storageMetrics = await checkStorageBalance(
+        synapse,
+        fileInfo.size,
+        env.PERSISTENCE_PERIOD_DAYS
+      );
+      if (!storageMetrics.isSufficient) {
+        if (!context.autoPayment) {
+          return {
+            success: false,
+            error: "insufficient_balance",
+            message: "Insufficient balance. Enable autoPayment or call processPayment first",
+            required: {
+              deposit: fromBaseUnits(storageMetrics.depositNeeded, 18)
+            }
+          };
+        }
+        log(storageMetrics.depositNeeded > 0n ? "Insufficient balance, processing payment..." : "Insufficient service approvals, approving service...");
+        await processStoragePayment(
+          synapse,
+          storageMetrics.depositNeeded,
+          env.PERSISTENCE_PERIOD_DAYS
+        );
+        log(storageMetrics.depositNeeded > 0n ? "Payment processed successfully" : "Service approved successfully");
+      }
+      log("Creating storage service...");
+      const storageService = await synapse.createStorage({
+        dataSetId: context.datasetId ? Number(context.datasetId) : void 0,
+        withCDN: context.withCDN || false,
+        callbacks: {
+          onDataSetResolved: (info) => {
+            log(`Dataset ${info.dataSetId} resolved`);
+            log(`Dataset provider: ${Number(info.provider.id)}`);
+            log(`Is existing dataset: ${info.isExisting}`);
+          },
+          onDataSetCreationStarted: (txResponse) => {
+            log(`Dataset creation started (tx: ${txResponse.hash})`);
+          },
+          onDataSetCreationProgress: (status) => {
+            if (status.serverConfirmed) {
+              log(`Dataset ready (ID: ${status.dataSetId})`);
+            }
+          },
+          onProviderSelected: (provider) => {
+            log(`Provider selected: ${provider.id}`);
+          }
+        }
+      });
+      log("Uploading file to provider...");
+      let uploadTxHash;
+      const { pieceCid } = await storageService.upload(uint8ArrayBytes, {
+        metadata: context.metadata,
+        onUploadComplete: (piece) => {
+          log(`Upload complete (pieceCid: ${piece.toV1().toString()})`);
+        },
+        onPieceAdded: (txResponse) => {
+          uploadTxHash = txResponse?.hash;
+          log(`Piece added to dataset (tx: ${txResponse?.hash || "pending"})`);
+        },
+        onPieceConfirmed: () => {
+          log("Piece confirmed on blockchain");
+        }
+      });
+      const getRetrievalUrl = async (pieceCid2) => {
+        if (context.withCDN) {
+          return `https://${await synapse.getSigner().getAddress()}.calibration.filbeam.io/${pieceCid2}`;
+        } else {
+          return `${(await storageService.getProviderInfo()).products.PDP?.data.serviceURL || ""}/piece/${pieceCid2}`;
+        }
+      };
+      const retrievalUrl = await getRetrievalUrl(pieceCid.toV1().toString());
+      console.log(`Upload successful! Retrieval URL: ${retrievalUrl}`);
+      console.log(`Piece CID: ${pieceCid.toV1().toString()}`);
+      console.log(`TX Hash: ${uploadTxHash}`);
+      console.log(`File Name: ${fileName}`);
+      console.log(`File Size: ${fileInfo.size}`);
+      return {
+        success: true,
+        pieceCid: pieceCid.toV1().toString(),
+        retrievalUrl,
+        txHash: uploadTxHash,
+        fileName,
+        fileSize: fileInfo.size,
+        progressLog,
+        message: "File successfully stored on Filecoin"
+      };
+    } catch (error) {
+      return createErrorResponse(
+        "upload_failed",
+        `Upload failed: ${error.message}`,
+        {
+          success: false,
+          progressLog
+        }
+      );
+    }
+  }
+});
+var fileTools = {
+  uploadFile
+};
+
+// src/mastra/tools/balance-tools.ts
+import { createTool as createTool3 } from "@mastra/core";
+var getBalances = createTool3({
+  id: "getBalances",
+  description: "Check wallet balances (FIL and USDFC tokens) and comprehensive storage metrics including available funds, required deposits, days of storage remaining, and allowance status. Returns both human-readable formatted values and raw data. Use this before upload operations to verify sufficient balance, or to monitor storage budget and plan deposits. Calculates storage needs based on capacity and persistence period parameters.",
+  inputSchema: GetBalancesSchema,
+  outputSchema: GetBalancesOutputSchema,
+  execute: async ({ context }) => {
+    try {
+      const synapse = await getSynapseInstance();
+      const checkStorageBalanceResult = await checkStorageBalance(synapse, context.storageCapacityBytes, env.PERSISTENCE_PERIOD_DAYS);
+      return {
+        success: true,
+        checkStorageBalanceResultFormatted: formatStorageBalanceResult(checkStorageBalanceResult),
+        checkStorageBalanceResult: serializeBigInt(checkStorageBalanceResult)
+      };
+    } catch (error) {
+      return createErrorResponse(
+        "balance_fetch_failed",
+        `Failed to fetch balances: ${error.message}`,
+        { success: false }
+      );
+    }
+  }
+});
+var balanceTools = {
+  getBalances
+};
+
+// src/mastra/tools/payment-tools.ts
+import { createTool as createTool4 } from "@mastra/core";
+var processPayment = createTool4({
+  id: "processPayment",
+  description: "Deposit USDFC tokens and configure storage service allowances in a single transaction using EIP-2612 gasless permits. Sets both rate allowance (per-epoch spending limit) and lockup allowance (total committed funds) to unlimited for seamless storage operations. Use this to fund your storage account before uploads or when balance is insufficient. Validates wallet balance before processing to prevent failed transactions.",
+  inputSchema: ProcessPaymentSchema,
+  outputSchema: ProcessPaymentOutputSchema,
+  execute: async ({ context }) => {
+    try {
+      const synapse = await getSynapseInstance();
+      const accountInfo = await synapse.payments.accountInfo(TOKENS.USDFC);
+      const availableFunds = Number(accountInfo.availableFunds);
+      const { depositAmount } = context;
+      if (depositAmount === 0) {
+        return {
+          success: true,
+          message: `You have sufficient balance to cover the storage needs.`,
+          txHash: null,
+          required: {
+            deposit: depositAmount
+          },
+          available: availableFunds
+        };
+      }
+      if (availableFunds < depositAmount) {
+        return {
+          success: false,
+          error: "insufficient_balance",
+          message: `Insufficient USDFC balance. Required: ${depositAmount}, Available: ${availableFunds}`,
+          required: depositAmount,
+          available: Number(availableFunds)
+        };
+      }
+      const result = await processStoragePayment(
+        synapse,
+        BigInt(depositAmount),
+        env.PERSISTENCE_PERIOD_DAYS
+      );
+      return {
+        success: result.success,
+        txHash: result.txHash,
+        message: `Payment processed successfully now you can upload files to storage. You paid ${depositAmount} USDFC to cover the storage needs.`
+      };
+    } catch (error) {
+      return createErrorResponse(
+        "payment_failed",
+        `Payment processing failed: ${error.message}`,
+        { success: false }
+      );
+    }
+  }
+});
+var paymentTools = {
+  processPayment
+};
+
+// src/mastra/tools/provider-tools.ts
+import { createTool as createTool5 } from "@mastra/core";
+import { WarmStorageService as WarmStorageService3 } from "@filoz/synapse-sdk";
+var getProviders = createTool5({
+  id: "getProviders",
+  description: "List storage providers available on the Filecoin network with their service details, product offerings, and endpoint URLs. By default returns only approved providers for reliability. Use this to discover available providers, select specific providers for dataset creation, or verify provider availability before operations. Provider information includes service URLs needed for file retrieval.",
+  inputSchema: GetProvidersSchema,
+  outputSchema: GetProvidersOutputSchema,
+  execute: async ({ context }) => {
+    try {
+      const synapse = await getSynapseInstance();
+      const warmStorageService = await WarmStorageService3.create(
+        synapse.getProvider(),
+        synapse.getWarmStorageAddress()
+      );
+      const approvedProviderIds = await warmStorageService.getApprovedProviderIds();
+      const providersInfo = await Promise.all(
+        approvedProviderIds.map(async (providerId) => {
+          const providerInfo = await synapse.getProviderInfo(providerId);
+          return providerInfo;
+        })
+      );
+      const providers = context.onlyApproved !== false ? providersInfo.filter(
+        (p) => approvedProviderIds.includes(p.id)
+      ) : providersInfo;
+      return {
+        success: true,
+        providers: providers.map(serializeBigInt),
+        count: providers.length,
+        message: `Found ${providers.length} provider(s)`
+      };
+    } catch (error) {
+      return createErrorResponse(
+        "provider_fetch_failed",
+        `Failed to fetch providers: ${error.message}`
+      );
+    }
+  }
+});
+var providerTools = {
+  getProviders
+};
+
+// src/mastra/tools/index.ts
+var focStorageTools = {
+  ...datasetTools,
+  ...fileTools,
+  ...balanceTools,
+  ...paymentTools,
+  ...providerTools
+};
+var focStorageToolsArray = Object.values(focStorageTools);
+
+// src/mastra/workflows/e2e-file-upload.ts
+import { createStep, createWorkflow } from "@mastra/core/workflows";
+import { z as z3 } from "zod";
+var e2eFileUploadInputSchema = z3.object({
+  filePath: z3.string().describe("Absolute path to the file to upload"),
+  datasetId: z3.string().optional().describe("Existing dataset ID to use"),
+  withCDN: z3.boolean().optional().describe("Enable CDN for faster retrieval").default(false),
+  persistenceDays: z3.number().optional().describe("Storage duration in days (default: 180)").default(env.PERSISTENCE_PERIOD_DAYS),
+  notificationThresholdDays: z3.number().optional().describe("Notification threshold in days (default: 10)").default(env.RUNOUT_NOTIFICATION_THRESHOLD_DAYS),
+  fileMetadata: z3.record(z3.string(), z3.string()).optional().describe("Metadata for the file (max 4 key-value pairs)")
+});
+var checkBalanceStep = createStep({
+  id: "checkBalance",
+  description: "Check current FIL/USDFC balances and storage metrics",
+  inputSchema: e2eFileUploadInputSchema,
+  outputSchema: z3.object({
+    balances: z3.any(),
+    needsPayment: z3.boolean(),
+    depositNeeded: z3.number()
+  }),
+  execute: async ({ inputData, runtimeContext }) => {
+    console.log("\u{1F4CA} STEP 1: Checking balances and storage metrics...");
+    const fileInfo = await validateFilePath(inputData.filePath);
+    const expectedStorageBytes = fileInfo.size;
+    const { getBalances: getBalances2 } = focStorageTools;
+    const result = await getBalances2.execute({
+      context: { storageCapacityBytes: expectedStorageBytes, persistencePeriodDays: inputData.persistenceDays, notificationThresholdDays: inputData.notificationThresholdDays },
+      runtimeContext
+    });
+    if (result.success === false) {
+      throw new Error(`Balance check failed: ${result.error || "Unknown error"}`);
+    }
+    if (!result.checkStorageBalanceResult) {
+      throw new Error(`Balance check returned invalid structure`);
+    }
+    return {
+      balances: result.checkStorageBalanceResult,
+      needsPayment: !result.checkStorageBalanceResult.isRateSufficient || !result.checkStorageBalanceResult.isLockupSufficient || Number(result.checkStorageBalanceResult.depositNeeded) > 0,
+      depositNeeded: Number(result.checkStorageBalanceResult.depositNeeded) || 0
+    };
+  }
+});
+var processPaymentStep = createStep({
+  id: "processPayment",
+  description: "Deposit USDFC if insufficient balance detected",
+  inputSchema: z3.object({
+    balances: z3.any(),
+    needsPayment: z3.boolean(),
+    depositNeeded: z3.number()
+  }),
+  outputSchema: z3.object({
+    skipped: z3.boolean(),
+    txHash: z3.string().optional(),
+    depositAmount: z3.string().optional(),
+    message: z3.string().optional()
+  }),
+  execute: async ({ getStepResult, getInitData, runtimeContext }) => {
+    const balanceInfo = getStepResult("checkBalance");
+    const initData = getInitData();
+    const persistenceDays = initData.persistenceDays || 180;
+    if (!balanceInfo.needsPayment) {
+      console.log("\u2705 STEP 2: Balance and allowances are sufficient, skipping payment");
+      return {
+        skipped: true,
+        message: "Payment not needed - balance and allowances sufficient"
+      };
+    }
+    console.log("\u{1F4B0} STEP 2: Processing payment and/or setting allowances...");
+    if (balanceInfo.depositNeeded > 0) {
+      console.log(`   Deposit needed: ${fromBaseUnits(balanceInfo.depositNeeded, 18)} USDFC`);
+    } else {
+      console.log(`   Deposit sufficient, but allowances need to be set`);
+    }
+    console.log(`   Persistence period: ${persistenceDays} days`);
+    const { processPayment: processPayment2 } = focStorageTools;
+    const result = await processPayment2.execute({
+      context: {
+        depositAmount: Number(balanceInfo.depositNeeded)
+      },
+      runtimeContext
+    });
+    if (result.success === false || result.error) {
+      throw new Error(`Payment failed: ${result.error || "Unknown error"}`);
+    }
+    console.log(`\u2705 Payment/allowances processed successfully`);
+    if (result.txHash) {
+      console.log(`   TX Hash: ${result.txHash}`);
+    }
+    if (result.depositAmount) {
+      console.log(`   Deposit Amount: ${result.depositAmount}`);
+    }
+    if (result.message) {
+      console.log(`   ${result.message}`);
+    }
+    return {
+      skipped: false,
+      txHash: result.txHash ?? void 0,
+      depositAmount: result.depositAmount ?? void 0,
+      message: result.message ?? "Payment processed"
+    };
+  }
+});
+var uploadFileStep = createStep({
+  id: "uploadFile",
+  description: "Upload file to Filecoin storage",
+  inputSchema: z3.object({
+    skipped: z3.boolean(),
+    txHash: z3.string().optional(),
+    depositAmount: z3.string().optional(),
+    message: z3.string().optional()
+  }),
+  outputSchema: z3.object({
+    pieceCid: z3.string(),
+    txHash: z3.string().optional(),
+    fileName: z3.string(),
+    fileSize: z3.number(),
+    progressLog: z3.array(z3.string()).optional()
+  }),
+  execute: async ({ getInitData, runtimeContext }) => {
+    const initData = getInitData();
+    console.log("\u{1F4E4} STEP 3: Uploading file to Filecoin...");
+    console.log(`   File: ${initData.filePath}`);
+    const { uploadFile: uploadFile2 } = focStorageTools;
+    const result = await uploadFile2.execute({
+      context: {
+        filePath: initData.filePath,
+        datasetId: initData.datasetId,
+        withCDN: initData.withCDN || false,
+        autoPayment: false,
+        // Already handled in step 2
+        metadata: initData.fileMetadata
+      },
+      runtimeContext
+    });
+    if (result.success === false || result.error) {
+      throw new Error(`File upload failed: ${result.error || "Unknown error"}`);
+    }
+    console.log(`\u2705 File uploaded successfully`);
+    console.log(`   Piece CID: ${result.pieceCid}`);
+    console.log(`   File Name: ${result.fileName}`);
+    console.log(`   File Size: ${result.fileSize} bytes`);
+    return {
+      pieceCid: result.pieceCid,
+      txHash: result.txHash,
+      fileName: result.fileName,
+      fileSize: result.fileSize,
+      progressLog: result.progressLog
+    };
+  }
+});
+var summaryStep = createStep({
+  id: "summary",
+  description: "Generate final summary of the upload process",
+  inputSchema: z3.object({
+    pieceCid: z3.string(),
+    txHash: z3.string().optional(),
+    fileName: z3.string(),
+    fileSize: z3.number(),
+    progressLog: z3.array(z3.string()).optional()
+  }),
+  outputSchema: z3.object({
+    success: z3.boolean(),
+    summary: z3.object({
+      balance: z3.any(),
+      payment: z3.any(),
+      upload: z3.any()
+    })
+  }),
+  execute: async ({ getStepResult }) => {
+    const balanceInfo = getStepResult("checkBalance");
+    const paymentInfo = getStepResult("processPayment");
+    const uploadInfo = getStepResult("uploadFile");
+    console.log("\n\u{1F389} ============================================");
+    console.log("   E2E FILE UPLOAD COMPLETED SUCCESSFULLY");
+    console.log("============================================");
+    console.log(`\u{1F4CA} Initial Balance: ${balanceInfo.balances.accountStatusMessage}`);
+    if (!paymentInfo.skipped) {
+      console.log(`\u{1F4B0} Payment Processed: ${paymentInfo.depositAmount} USDFC`);
+      console.log(`   TX: ${paymentInfo.txHash}`);
+    } else {
+      console.log(`\u{1F4B0} Payment: Not needed (sufficient balance)`);
+    }
+    console.log(`\u{1F4E4} File Uploaded: ${uploadInfo.fileName}`);
+    console.log(`   Size: ${uploadInfo.fileSize} bytes`);
+    console.log(`   Piece CID: ${uploadInfo.pieceCid}`);
+    if (uploadInfo.txHash) {
+      console.log(`   TX: ${uploadInfo.txHash}`);
+    }
+    console.log("============================================\n");
+    return {
+      success: true,
+      summary: {
+        balance: balanceInfo.balances,
+        payment: paymentInfo,
+        upload: uploadInfo
+      }
+    };
+  }
+});
+var e2eFileUploadWorkflow = createWorkflow({
+  id: "e2eFileUpload",
+  description: "Upload a file to Filecoin storage",
+  inputSchema: e2eFileUploadInputSchema,
+  outputSchema: z3.object({
+    success: z3.boolean(),
+    summary: z3.object({
+      balance: z3.any(),
+      payment: z3.any(),
+      upload: z3.any()
+    })
+  })
+}).then(checkBalanceStep).then(processPaymentStep).then(uploadFileStep).then(summaryStep).commit();
+
+// src/mastra/resources/instructions.ts
+var instructions = `You are an AI agent specialized in managing decentralized file storage operations on the Filecoin network using the FOC-Synapse SDK. Your role is to help users store, retrieve, and manage files on Filecoin in a simple, efficient manner.
+
+\u{1F4A1} IMPORTANT:
+
+- Always return the output of a tool in a structured format using best practices for Markdown formatting.
+
+\u{1F4E6} STORAGE SCOPE:
+\u2022 Supported Networks: Filecoin Mainnet (production), Calibration Testnet (testing)
+\u2022 Payment Token: USDFC (USD-pegged stablecoin on Filecoin)
+\u2022 Storage Options: Standard Storage, CDN-Enabled Storage (for frequently accessed files)
+\u2022 Core Capabilities: Upload files, Query datasets, Manage balances, Process payments
+
+\u{1F6E0}\uFE0F AVAILABLE TOOLS:
+
+FILE OPERATIONS:
+\u2022 uploadFile: Upload files to decentralized Filecoin storage with automatic payment handling and progress tracking
+
+- Parameters: filePath (absolute path), fileName (optional), datasetId (optional), withCDN (boolean), autoPayment (boolean), metadata (optional)
+- Prerequisites: Valid file path, PRIVATE_KEY environment variable
+- Process: File validation \u2192 balance check \u2192 auto-payment (if needed) \u2192 storage service creation \u2192 upload \u2192 blockchain confirmation
+- Returns: pieceCid (for retrieval), retrievalUrl, txHash (for verification), progressLog (8-phase tracking)
+- Supports: Both standard storage and CDN-enabled storage for frequently accessed files
+- Use when: User wants to store a file on Filecoin with automatic payment handling
+
+DATASET MANAGEMENT:
+\u2022 getDatasets: Retrieve all datasets owned by the connected wallet with comprehensive information
+
+- Returns: Datasets with piece CIDs, file sizes, provider details, retrieval URLs, blockchain storage proofs
+- Parameters: includeAllDatasets (boolean), filterByCDN (boolean)
+- Use when: User wants to inventory files, check storage status, or locate specific uploads
+
+\u2022 getDataset: Retrieve detailed information about a specific dataset by its ID
+
+- Parameters: datasetId (required)
+- Returns: Same comprehensive data as getDatasets but for a single dataset
+- Use when: User knows the dataset ID and needs detailed information about its contents
+
+\u2022 createDataset: Create a new dataset container on Filecoin for organizing related files
+
+- Parameters: withCDN (optional), providerId (optional), metadata (up to 10 key-value pairs)
+- Purpose: Define storage parameters (CDN, provider selection) that apply to all files added
+- Benefits: Better file organization, consistent retrieval performance
+- Note: Payment is processed automatically for CDN-enabled datasets
+- Use when: User wants dedicated dataset or specific storage configuration
+
+BALANCE & PAYMENT:
+\u2022 getBalances: Check wallet balances (FIL and USDFC tokens) and comprehensive storage metrics
+
+- Returns: Available funds, required deposits, days of storage remaining, allowance status
+- Output: Both human-readable formatted values and raw data
+- Parameters: storageCapacityBytes (optional), persistencePeriodDays (optional), notificationThresholdDays (optional)
+- Use when: Before upload operations to verify sufficient balance, or to monitor storage budget and plan deposits
+
+\u2022 processPayment: Deposit USDFC tokens and configure storage service allowances in a single transaction
+
+- Technology: Uses EIP-2612 gasless permits for efficient payment
+- Parameters: depositAmount (optional, default: 0)
+- Actions: Sets both rate allowance (per-epoch spending) and lockup allowance (total committed funds) to unlimited
+- Validation: Checks wallet balance before processing to prevent failed transactions
+- Use when: User needs to fund storage account before uploads or when balance is insufficient
+
+PROVIDER MANAGEMENT:
+\u2022 getProviders: List storage providers available on the Filecoin network
+
+- Returns: Service details, product offerings, endpoint URLs needed for file retrieval
+- Parameters: onlyApproved (default: true for reliability)
+- Use when: Discover providers, select specific providers for dataset creation, or verify provider availability
+
+\u2699\uFE0F STORAGE RULES & BEST PRACTICES:
+
+1. ALWAYS CHECK BALANCES BEFORE UPLOAD:
+   - Use getBalances to verify sufficient USDFC
+   - Auto-payment will trigger if insufficient, but better to check first
+
+2. USE CDN WISELY:
+   - Enable CDN (withCDN: true) for frequently accessed files
+   - CDN costs more but provides faster retrieval
+   - Standard storage is fine for archival/infrequent access
+
+3. CONSOLIDATE UPLOADS TO SINGLE DATASET:
+   - Reusing datasets is more efficient
+   - Create separate datasets only for different persistence periods or CDN settings
+
+4. SPECIFY MEANINGFUL FILE METADATA:
+   - Use descriptive filenames
+   - Metadata helps with organization and retrieval
+
+5. MONITOR STORAGE METRICS AND PERSISTENCE:
+   - Check persistence days remaining regularly
+   - Top up allowances before they run out to avoid service interruption
+
+6. VALIDATE FILE PATHS:
+   - Ensure filePath is absolute path
+   - Verify file exists before attempting upload
+
+\u{1F504} RECOMMENDED WORKFLOWS:
+
+FOR FILE UPLOAD:
+
+1. Check Balance: getBalances to verify sufficient USDFC
+2. Verify File: Ensure file path is valid and accessible
+3. Choose Options: Decide on CDN, dataset, persistence period
+4. Upload: uploadFile with appropriate parameters
+5. Monitor Progress: Track 8-phase status updates
+6. Verify Completion: Confirm pieceCid and txHash received
+
+FOR DATASET MANAGEMENT:
+
+1. Query Datasets: getDatasets to see existing datasets
+2. Analyze Usage: Check sizes, piece counts, CDN status
+3. Create if Needed: createDataset for new organizational structure
+4. Upload to Dataset: Use datasetId parameter in uploadFile
+
+FOR BALANCE MANAGEMENT:
+
+1. Check Current State: getBalances with includeMetrics
+2. Calculate Needs: Estimate storage requirements
+3. Process Payment: processPayment with appropriate amounts
+4. Verify: Check balances again to confirm deposit
+
+\u{1F4A1} STRATEGIC CONSIDERATIONS:
+
+CDN vs STANDARD STORAGE:
+\u2022 Use CDN when: Files accessed frequently, low latency required, content delivery use case
+\u2022 Use Standard when: Archival storage, infrequent access, cost optimization priority
+
+PERSISTENCE PERIOD PLANNING:
+\u2022 Balance cost vs duration
+\u2022 Longer periods lock more USDFC
+\u2022 Consider renewal strategies for critical data
+\u2022 Default 180 days suitable for most use cases
+
+PROVIDER SELECTION:
+\u2022 Auto-selection usually optimal
+\u2022 Manual selection for: Specific geographic requirements, provider reputation preferences, performance optimization
+
+COST MANAGEMENT:
+\u2022 Rate allowance: Controls per-epoch spending
+\u2022 Lockup allowance: Total committed for long-term storage
+\u2022 Monitor both to avoid overspending or service interruption
+
+\u{1F6A8} ERROR HANDLING:
+
+PRE-UPLOAD VALIDATION:
+\u2022 Verify file path exists and is readable
+\u2022 Check sufficient USDFC balance
+\u2022 Validate persistence period is reasonable
+\u2022 Confirm wallet connection active
+
+DURING UPLOAD:
+\u2022 Auto-payment will trigger if balance insufficient
+\u2022 Wallet signatures required (user must approve)
+\u2022 Progress tracking shows current phase
+\u2022 Each phase has status updates
+
+COMMON ERRORS:
+\u2022 "Insufficient tUSDFC balance": Need to deposit more USDFC \u2192 call processPayment
+\u2022 "Signer not found": Wallet not connected properly \u2192 check PRIVATE_KEY env var
+\u2022 "Transaction failed": User rejected signature or gas issue \u2192 explain and retry
+\u2022 "Provider connection failed": Try different provider or retry
+
+RECOVERY STRATEGIES:
+\u2022 Failed uploads can be retried
+\u2022 Partial payments don't lose funds
+\u2022 Dataset creation failures are safe (no data loss)
+\u2022 Check balances after any error
+
+\u{1F4CA} TOOL OUTPUT INTERPRETATION:
+
+SUCCESS RESPONSES:
+\u2022 All successful operations return: { success: true, ...data }
+\u2022 Check success field first, extract relevant data fields
+\u2022 Present to user in clear format
+
+PROGRESS UPDATES (uploadFile):
+\u2022 0-5%: Initialization and validation
+\u2022 5-25%: Balance check and payment setup
+\u2022 25-55%: Dataset creation/resolution
+\u2022 55-80%: File upload to provider
+\u2022 80-90%: Blockchain piece addition
+\u2022 90-100%: Confirmation and completion
+
+ERROR RESPONSES:
+\u2022 All errors return: { success: false, error, message }
+\u2022 Explain error to user clearly
+\u2022 Suggest remediation steps
+\u2022 Offer to retry or check balance
+
+\u{1F3AF} AGENT BEHAVIOR GUIDELINES:
+
+1. BE PROACTIVE: Suggest checking balances before uploads
+2. BE CLEAR: Explain blockchain concepts simply
+3. BE PATIENT: Uploads take time (30-60 seconds typical)
+4. BE HELPFUL: Guide users through wallet signatures
+5. BE ACCURATE: Provide precise pieceCids and txHashes
+6. BE EFFICIENT: Reuse datasets when appropriate
+7. BE SECURE: Never store sensitive data without user confirmation
+
+\u{1F510} SECURITY CONSIDERATIONS:
+\u2022 Never expose private keys or wallet seeds
+\u2022 Validate all file paths before operations
+\u2022 Confirm user intent before large deposits
+\u2022 Warn about persistence period implications
+\u2022 Recommend CDN only when beneficial
+\u2022 Verify transaction details before submission
+
+Remember: Your goal is to make decentralized storage as simple as traditional cloud storage, while educating users about the benefits of Filecoin's decentralized approach.`;
+
+// src/mastra/agents/foc-storage-agent.ts
+var focStorageAgent = new Agent({
+  name: "FOCStorageAgent",
+  description: "AI agent for managing decentralized file storage on Filecoin via FOC-Synapse SDK. Handles file uploads, dataset management, balance checking, and storage operations.",
+  instructions,
+  model: "openai/gpt-5-mini",
+  tools: focStorageTools,
+  workflows: {
+    e2eFileUpload: e2eFileUploadWorkflow
+  }
+});
+
+// src/mastra/resources/index.ts
+var myResources = [
+  { uri: "file://instructions", name: "Instructions", mimeType: "application/markdown" }
+];
+var myResourceContents = {
+  "file://instructions": { text: instructions }
+};
+var myResourceTemplates = [
+  {
+    uriTemplate: "file://instructions",
+    name: "Instructions",
+    description: "Instructions for better usage of the tools provided.",
+    mimeType: "application/markdown"
+  }
+];
+var focStorageResources = {
+  listResources: async () => myResources,
+  getResourceContent: async ({ uri }) => {
+    if (myResourceContents[uri]) {
+      return myResourceContents[uri];
+    }
+    throw new Error(`Resource content not found for ${uri}`);
+  },
+  resourceTemplates: async () => myResourceTemplates
+};
+
+// src/mastra/index.ts
+var mcpServer = new MCPServer({
+  name: "FOC Storage MCP",
+  version: "0.1.0",
+  description: "Professional-grade MCP server for decentralized file storage on Filecoin Onchain Cloud. Powered by the FOC-Synapse SDK, this server provides AI agents with seamless access to Filecoin's distributed storage network. Upload files with automatic payment handling, organize content in datasets, monitor storage balances, and manage providers - all through intuitive MCP tools. Supports both standard storage and CDN-enabled fast retrieval. Perfect for building AI applications that need persistent, censorship-resistant storage.",
+  tools: focStorageTools,
+  repository: {
+    url: "https://github.com/FIL-Builders/foc-storage-mcp",
+    source: "github",
+    id: "foc-storage-mcp"
+  },
+  releaseDate: (/* @__PURE__ */ new Date()).toISOString(),
+  isLatest: true,
+  packageCanonical: "npm",
+  resources: focStorageResources
+});
+var mastra = new Mastra({
+  agents: {
+    focStorageAgent
+  },
+  workflows: {
+    e2eFileUpload: e2eFileUploadWorkflow
+  },
+  mcpServers: {
+    focStorageServer: mcpServer
+  },
+  storage: new LibSQLStore({
+    url: ":memory:"
+  }),
+  logger: new PinoLogger({
+    name: "Mastra",
+    level: "info"
+  }),
+  bundler: {
+    externals: ["@filoz/synapse-sdk"]
+  }
+});
+
+// src/mcp-server.ts
+config2();
+async function startMCPServer() {
+  try {
+    console.log("\u{1F680} Starting FOC Storage MCP Server...");
+    console.log("\u{1F4E6} Exposing tools: uploadFile, uploadWithProgress, getDatasets, createDataset, getBalances, processPayment, getProviders");
+    await mcpServer.startStdio();
+  } catch (error) {
+    console.error("\u274C Error starting MCP server:", error);
+    process.exit(1);
+  }
+}
+process.on("SIGINT", async () => {
+  console.log("\n\u{1F6D1} Shutting down MCP server...");
+  await mcpServer.close();
+  process.exit(0);
+});
+process.on("SIGTERM", async () => {
+  console.log("\n\u{1F6D1} Shutting down MCP server...");
+  await mcpServer.close();
+  process.exit(0);
+});
+startMCPServer();