@fil-b/foc-storage-mcp 0.1.6 → 0.1.8

package/README.md

@@ -19,10 +19,13 @@
 
 ## Configuration
 
-**Required:**
+**Requirements:**
+
+- Node.js >= 20.10.0 ([Check version](https://nodejs.org/): `node --version`)
 - `PRIVATE_KEY` - Your Filecoin wallet private key (0x...)
 
 **Optional:**
+
 - `FILECOIN_NETWORK` - `mainnet` (production) or `calibration` (testing, default)
 - `TOTAL_STORAGE_NEEDED_GiB` - Default storage capacity for calculations (default: 150 GiB)
 - `PERSISTENCE_PERIOD_DAYS` - Data retention duration (default: 365 days)
@@ -148,23 +151,26 @@ Most MCP tools support this format:
 
 **Example:** 150 GiB for 1 year ≈ 0.44 USDFC ($0.44)
 
-💡 Ask your agent: *"How much to store 500 GiB for 6 months?"*
+💡 Ask your agent: _"How much to store 500 GiB for 6 months?"_
 
 ## Tools
 
 Ask naturally in Claude, Cursor, or any MCP client:
 
 **File Operations**
+
 - `uploadFile` - Upload files with auto-payment
 - `getDatasets` - List all stored datasets
 - `getDataset` - Get dataset details
 - `createDataset` - Create new dataset container
 
 **Balance & Payments**
+
 - `getBalances` - Check wallet and storage metrics
 - `processPayment` - Deposit USDFC tokens
 
 **Providers & Pricing**
+
 - `getProviders` - List storage providers
 - `estimateStoragePricing` - Calculate costs
 - `getStoragePricingInfo` - Explain pricing models
@@ -182,12 +188,30 @@ Ask naturally in Claude, Cursor, or any MCP client:
 
 ## Troubleshooting
 
+**"Unexpected token 'with'" or import syntax error:**
+
+1. Verify Node.js >= 20.10.0: `node --version`
+2. Clear npx cache:
+   - Command: `npx clear-npx-cache`
+   - Windows: Delete `%LOCALAPPDATA%\npm-cache\_npx`
+   - Linux/Mac: Delete `~/.npm/_npx`
+3. Force fresh install: `npx --yes @fil-b/foc-storage-mcp@latest`
+4. Restart your IDE
+5. If issue persists, check IDE is using correct Node version
+
 **Server not found:** Verify `npx --version`, check JSON syntax, restart IDE
 
 **"PRIVATE_KEY is required":** Add to `env` section, must start with `0x`
 
 **Transaction fails:** Check FIL for gas, verify network setting, confirm USDFC balance
 
+**"Invalid Version" or npm dependency errors:**
+
+1. Clear npm cache: `npm cache clean --force`
+2. Clear npx cache: `npx clear-npx-cache`
+3. Update npm: `npm install -g npm@latest`
+4. As last resort, use older npm: `npm install -g npm@10`
+
 ## Security
 
 - Never commit private keys or `.env` files

package/dist/mcp-server.js

@@ -524,6 +524,34 @@ var calculateStorageCost = (prices, sizeInBytes) => {
     perMonth
   };
 };
+var defaultStorageBalanceResult = {
+  filBalance: 0n,
+  usdfcBalance: 0n,
+  availableStorageFundsUsdfc: 0n,
+  depositNeeded: 0n,
+  availableToFreeUp: 0n,
+  daysLeftAtMaxBurnRate: 0,
+  daysLeftAtBurnRate: 0,
+  isRateSufficient: false,
+  isLockupSufficient: false,
+  isSufficient: false,
+  currentStorageMonthlyRate: 0n,
+  maxStorageMonthlyRate: 0n
+};
+var defaultStorageBalanceResultFormatted = {
+  filBalance: "0 FIL",
+  usdfcBalance: "0 USDFC",
+  availableStorageFundsUsdfc: "0 USDFC",
+  depositNeeded: "0 USDFC",
+  availableToFreeUp: "0 USDFC",
+  daysLeftAtMaxBurnRate: "0 days",
+  daysLeftAtBurnRate: "0 days",
+  currentStorageMonthlyRate: "0 USDFC",
+  maxStorageMonthlyRate: "0 USDFC",
+  isRateSufficient: false,
+  isLockupSufficient: false,
+  isSufficient: false
+};
 var checkStorageBalance = async (storageCapacityBytes = env.TOTAL_STORAGE_NEEDED_GiB * Number(SIZE_CONSTANTS3.GiB), persistencePeriodDays = env.PERSISTENCE_PERIOD_DAYS) => {
   const [filRaw, { value: usdfcRaw }, { availableFunds }, prices, operatorApprovals2] = await Promise.all([
     getBalance(client, {
@@ -898,7 +926,7 @@ var fileTools = {
 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 with progress log showing calculation parameters used. CRITICAL: Storage providers consider accounts with less than 30 days of available balance as INSOLVENT and may refuse service. Default notice period is 45 days to ensure safe margin. IMPORTANT AGENT INSTRUCTIONS: (1) Before calling this tool, ASK the user if they want to calculate based on default storage requirements (150 GiB capacity, 365 days persistence, 45 days notice period) or if they have specific requirements. (2) After showing results, ALWAYS ASK the user if they want to see calculations for different storage configurations. (3) If days remaining falls below 45, WARN the user that they are approaching insolvency threshold (30 days) and should deposit funds immediately. Use this before upload operations to verify sufficient balance, or to monitor storage budget and plan deposits.",
+  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 with progress log showing calculation parameters used. \u26A0\uFE0F CRITICAL: Storage providers consider accounts with less than 30 days of available balance as INSOLVENT and may refuse service. Default notice period is 45 days to ensure safe margin. IMPORTANT AGENT INSTRUCTIONS: (1) Before calling this tool, ASK the user if they want to calculate based on default storage requirements (150 GiB capacity, 365 days persistence, 45 days notice period) or if they have specific requirements. (2) After showing results, ALWAYS ASK the user if they want to see calculations for different storage configurations. (3) If days remaining falls below 45, WARN the user that they are approaching insolvency threshold (30 days) and should deposit funds immediately. Use this before upload operations to verify sufficient balance, or to monitor storage budget and plan deposits.",
   inputSchema: GetBalancesSchema,
   outputSchema: GetBalancesOutputSchema,
   execute: async ({ context }) => {
@@ -913,9 +941,9 @@ var getBalances = createTool3({
       const capacityGB = (storageCapacityBytes / (1024 * 1024 * 1024)).toFixed(2);
       const capacityTB = (storageCapacityBytes / (1024 * 1024 * 1024 * 1024)).toFixed(2);
       log(`Calculating balance requirements with:`);
-      log(`> Storage Capacity: ${capacityGB} GB (${capacityTB} TB)`);
-      log(`> Persistence Period: ${persistencePeriodDays} days`);
-      log(`> Notification Threshold: ${notificationThresholdDays} days`);
+      log(`- Storage Capacity: ${capacityGB} GB (${capacityTB} TB)`);
+      log(`- Persistence Period: ${persistencePeriodDays} days`);
+      log(`- Notification Threshold: ${notificationThresholdDays} days`);
       log("Fetching wallet balances from blockchain...");
       const checkStorageBalanceResult = await checkStorageBalance(storageCapacityBytes, persistencePeriodDays);
       log("Calculating storage metrics and requirements...");
@@ -925,12 +953,12 @@ var getBalances = createTool3({
       const daysLeft = checkStorageBalanceResult.daysLeftAtBurnRate;
       if (daysLeft < 45) {
         if (daysLeft < 30) {
-          log(`CRITICAL INSOLVENCY WARNING: Only ${daysLeft.toFixed(1)} days of balance remaining! Storage providers consider accounts with less than 30 days as INSOLVENT and will REFUSE SERVICE. Deposit funds IMMEDIATELY!`);
+          log(`\u26D4 CRITICAL INSOLVENCY WARNING: Only ${daysLeft.toFixed(1)} days of balance remaining! Storage providers consider accounts with less than 30 days as INSOLVENT and will REFUSE SERVICE. Deposit funds IMMEDIATELY!`);
         } else {
-          log(`LOW BALANCE WARNING: Only ${daysLeft.toFixed(1)} days remaining (threshold: 45 days). You are approaching the insolvency threshold (30 days). Please deposit funds soon to avoid service interruption.`);
+          log(`\u26A0\uFE0F LOW BALANCE WARNING: Only ${daysLeft.toFixed(1)} days remaining (threshold: 45 days). You are approaching the insolvency threshold (30 days). Please deposit funds soon to avoid service interruption.`);
         }
       }
-      log("To calculate for different storage requirements, call this tool again with custom storageCapacityBytes and persistencePeriodDays parameters.");
+      log("\u{1F4A1} To calculate for different storage requirements, call this tool again with custom storageCapacityBytes and persistencePeriodDays parameters.");
       return {
         success: true,
         checkStorageBalanceResultFormatted: formattedResult,
@@ -941,7 +969,9 @@ var getBalances = createTool3({
     } catch (error) {
       return {
         success: false,
-        error: "balance_fetch_failed",
+        checkStorageBalanceResultFormatted: defaultStorageBalanceResultFormatted,
+        checkStorageBalanceResult: serializeBigInt(defaultStorageBalanceResult),
+        error: synapseErrorHandler(error),
         message: `Failed to fetch balances: ${error.message}`,
         progressLog
       };
@@ -1103,7 +1133,7 @@ var EstimateStorageCostOutputSchema = z3.object({
 });
 var estimateStoragePricing = createTool6({
   id: "estimateStoragePricing",
-  description: "Calculate storage costs for Filecoin OnchainCloud and explain pricing models. Provides: (1) Cost estimates with monthly/total breakdowns, (2) Comprehensive explanation of storage pricing (pay-per-epoch, $2.50/TiB/month, $0.06 minimum), (3) CDN egress pricing details ($7/TiB downloads, 1 USDFC = ~146 GiB credits). CRITICAL: When explaining budgeting, ALWAYS warn that storage providers consider accounts with less than 30 days of remaining balance as INSOLVENT and may refuse service. Recommend maintaining at least 45 days of balance for safety margin. Use when users ask about storage costs, pricing models, CDN fees, or need to budget for storage. Clarifies that CDN 1 USDFC is NOT a fee but pre-paid egress credits that can be topped up anytime.",
+  description: "Calculate storage costs for Filecoin OnchainCloud and explain pricing models. Provides: (1) Cost estimates with monthly/total breakdowns, (2) Comprehensive explanation of storage pricing (pay-per-epoch, $2.50/TiB/month, $0.06 minimum), (3) CDN egress pricing details ($7/TiB downloads, 1 USDFC = ~146 GiB credits). \u26A0\uFE0F CRITICAL: When explaining budgeting, ALWAYS warn that storage providers consider accounts with less than 30 days of remaining balance as INSOLVENT and may refuse service. Recommend maintaining at least 45 days of balance for safety margin. Use when users ask about storage costs, pricing models, CDN fees, or need to budget for storage. Clarifies that CDN 1 USDFC is NOT a fee but pre-paid egress credits that can be topped up anytime.",
   inputSchema: EstimateStorageCostSchema,
   outputSchema: EstimateStorageCostOutputSchema,
   execute: async ({ context }) => {
@@ -1173,7 +1203,7 @@ var estimateStoragePricing = createTool6({
         `   - ~2,880 epochs per day`,
         `   - ~86,400 epochs per month (30 days)`,
         ``,
-        `CRITICAL INSOLVENCY WARNING:`,
+        `\u26A0\uFE0F CRITICAL - INSOLVENCY WARNING:`,
         `   - Storage providers consider accounts with LESS THAN 30 DAYS of`,
         `     remaining balance as INSOLVENT`,
         `   - Insolvent accounts may be REFUSED SERVICE or have data removed`,
@@ -1330,7 +1360,7 @@ var convertStorageSize = createTool6({
 });
 var getStoragePricingInfo = createTool6({
   id: "getStoragePricingInfo",
-  description: "Get comprehensive information about Filecoin OnchainCloud storage pricing, including cost structure, CDN egress pricing, payment model, and a detailed example of storing 1 TiB for 1 year. CRITICAL: ALWAYS include the insolvency warning (accounts with less than 30 days balance are considered insolvent and may be refused service). Recommend 45-day minimum balance. Use this when users ask general questions about 'how much does storage cost', 'explain storage pricing', 'how does billing work', or want to understand the pricing model before calculating specific costs.",
+  description: "Get comprehensive information about Filecoin OnchainCloud storage pricing, including cost structure, CDN egress pricing, payment model, and a detailed example of storing 1 TiB for 1 year. \u26A0\uFE0F CRITICAL: ALWAYS include the insolvency warning (accounts with less than 30 days balance are considered insolvent and may be refused service). Recommend 45-day minimum balance. Use this when users ask general questions about 'how much does storage cost', 'explain storage pricing', 'how does billing work', or want to understand the pricing model before calculating specific costs.",
   inputSchema: z3.object({
     includeCDNExample: z3.boolean().optional().default(true).describe("Include CDN pricing example. Default: true")
   }),
@@ -1481,7 +1511,7 @@ var getStoragePricingInfo = createTool6({
         `   \u2022 Real-time pricing information available`,
         `   \u2022 No surprise charges or hidden fees`,
         ``,
-        `CRITICAL INSOLVENCY WARNING:`,
+        `\u26A0\uFE0F CRITICAL - INSOLVENCY WARNING:`,
         `   \u2022 Storage providers consider accounts with LESS THAN 30 DAYS of`,
         `     remaining balance as INSOLVENT`,
         `   \u2022 Insolvent accounts may be REFUSED SERVICE or have data removed`,
@@ -1751,17 +1781,17 @@ var e2eFileUploadWorkflow = createWorkflow({
 // 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.
 
-IMPORTANT:
+\u{1F4A1} IMPORTANT:
 
 - Always return the output of a tool in a structured format using best practices for Markdown formatting.
 
-STORAGE SCOPE:
+\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
 
-AVAILABLE TOOLS:
+\u{1F6E0}\uFE0F AVAILABLE TOOLS:
 
 FILE OPERATIONS:
 \u2022 uploadFile: Upload files to decentralized Filecoin storage with automatic payment handling and progress tracking
@@ -1804,7 +1834,7 @@ BALANCE & PAYMENT:
 - Output: Both human-readable formatted values and raw data with progress log showing calculation parameters
 - Parameters: storageCapacityBytes (optional, default: 150 GiB), persistencePeriodDays (optional, default: 365 days), notificationThresholdDays (optional, default: 45 days)
 - Progress Log: Shows exact values used for calculations (capacity, persistence period, threshold)
-- INSOLVENCY WARNING: Storage providers consider accounts with less than 30 days of remaining balance as INSOLVENT and may refuse service or remove data
+- \u26A0\uFE0F INSOLVENCY WARNING: Storage providers consider accounts with less than 30 days of remaining balance as INSOLVENT and may refuse service or remove data
 - Safety Margin: Default notification threshold is 45 days to ensure users have time to deposit before hitting the 30-day insolvency threshold
 - Agent Behavior: ALWAYS ask user before calling if they want default calculations or custom requirements. After showing results, ALWAYS offer to recalculate with different parameters. If days remaining is below 45, WARN user immediately about insolvency risk
 - Use when: Before upload operations to verify sufficient balance, or to monitor storage budget and plan deposits
@@ -1833,7 +1863,7 @@ PROVIDER MANAGEMENT:
 - Parameters: onlyApproved (default: true for reliability)
 - Use when: Discover providers, select specific providers for dataset creation, or verify provider availability
 
-STORAGE RULES & BEST PRACTICES:
+\u2699\uFE0F STORAGE RULES & BEST PRACTICES:
 
 1. ALWAYS CHECK BALANCES BEFORE UPLOAD:
    - Use getBalances to verify sufficient USDFC
@@ -1854,7 +1884,7 @@ STORAGE RULES & BEST PRACTICES:
 
 5. MONITOR STORAGE METRICS AND PERSISTENCE:
    - Check persistence days remaining regularly
-   - CRITICAL: Maintain at least 45 days of balance (insolvency threshold is 30 days)
+   - \u26A0\uFE0F CRITICAL: Maintain at least 45 days of balance (insolvency threshold is 30 days)
    - Storage providers will refuse service if balance falls below 30 days
    - Top up allowances before they run out to avoid service interruption and potential data loss
 
@@ -1862,7 +1892,7 @@ STORAGE RULES & BEST PRACTICES:
    - Ensure filePath is absolute path
    - Verify file exists before attempting upload
 
-RECOMMENDED WORKFLOWS:
+\u{1F504} RECOMMENDED WORKFLOWS:
 
 FOR FILE UPLOAD:
 
@@ -1888,7 +1918,7 @@ FOR BALANCE MANAGEMENT:
 4. Process Payment: processPayment with appropriate depositAmount to maintain 45+ day buffer
 5. Verify: Check balances again to confirm deposit and ensure above insolvency threshold
 
-STRATEGIC CONSIDERATIONS:
+\u{1F4A1} STRATEGIC CONSIDERATIONS:
 
 CDN vs STANDARD STORAGE:
 \u2022 Use CDN when: Files accessed frequently, low latency required, content delivery use case
@@ -1908,10 +1938,10 @@ 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
-\u2022 INSOLVENCY THRESHOLD: Keep balance above 30 days minimum (recommend 45+ days)
+\u2022 \u26A0\uFE0F INSOLVENCY THRESHOLD: Keep balance above 30 days minimum (recommend 45+ days)
 \u2022 Providers refuse service below 30 days - plan deposits accordingly
 
-ERROR HANDLING:
+\u{1F6A8} ERROR HANDLING:
 
 PRE-UPLOAD VALIDATION:
 \u2022 Verify file path exists and is readable
@@ -1938,7 +1968,7 @@ RECOVERY STRATEGIES:
 \u2022 Dataset creation failures are safe (no data loss)
 \u2022 Check balances after any error
 
-TOOL OUTPUT INTERPRETATION:
+\u{1F4CA} TOOL OUTPUT INTERPRETATION:
 
 SUCCESS RESPONSES:
 \u2022 All successful operations return: { success: true, ...data }
@@ -1959,7 +1989,7 @@ ERROR RESPONSES:
 \u2022 Suggest remediation steps
 \u2022 Offer to retry or check balance
 
-AGENT BEHAVIOR GUIDELINES:
+\u{1F3AF} AGENT BEHAVIOR GUIDELINES:
 
 1. BE PROACTIVE: Suggest checking balances before uploads
 2. BE VIGILANT: ALWAYS warn if balance days remaining < 45 (insolvency risk at < 30)
@@ -1971,7 +2001,7 @@ AGENT BEHAVIOR GUIDELINES:
 8. BE SECURE: Never store sensitive data without user confirmation
 9. BE URGENT: Treat insolvency warnings as critical - emphasize immediate action needed
 
-SECURITY CONSIDERATIONS:
+\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
@@ -2022,7 +2052,7 @@ var focStorageResources = {
 // src/mastra/index.ts
 var mcpServer = new MCPServer({
   name: "FOC Storage MCP",
-  version: "0.1.5",
+  version: "0.1.8",
   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: {
@@ -2049,7 +2079,8 @@ var mastra = new Mastra({
     url: ":memory:"
   }),
   logger: new PinoLogger({
-    name: "Mastra"
+    name: "Mastra",
+    level: "silent"
   }),
   bundler: {
     externals: ["@filoz/synapse-sdk"]
@@ -2060,8 +2091,6 @@ var mastra = new Mastra({
 config2();
 async function startMCPServer() {
   try {
-    console.log("Starting FOC Storage MCP Server...");
-    console.log("Exposing tools: uploadFile, uploadWithProgress, getDatasets, createDataset, getBalances, processPayment, getProviders");
     await mcpServer.startStdio();
   } catch (error) {
     console.error("Error starting MCP server:", error);
@@ -2069,12 +2098,12 @@ async function startMCPServer() {
   }
 }
 process.on("SIGINT", async () => {
-  console.log("Shutting down MCP server...");
+  console.error("Shutting down MCP server...");
   await mcpServer.close();
   process.exit(0);
 });
 process.on("SIGTERM", async () => {
-  console.log("Shutting down MCP server...");
+  console.error("Shutting down MCP server...");
   await mcpServer.close();
   process.exit(0);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fil-b/foc-storage-mcp",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "main": "dist/mcp-server.js",
   "bin": {
     "foc-storage-mcp": "./dist/mcp-server.js"
@@ -35,24 +35,24 @@
   "homepage": "https://github.com/FIL-Builders/foc-storage-mcp#readme",
   "type": "module",
   "engines": {
-    "node": ">=20.9.0"
+    "node": ">=20.10.0"
   },
   "dependencies": {
     "@ai-sdk/openai": "^2.0.57",
     "@filoz/synapse-core": "^0.1.2",
     "@filoz/synapse-react": "^0.1.2",
     "@filoz/synapse-sdk": "^0.35.3",
-    "@mastra/core": "latest",
-    "@mastra/libsql": "latest",
-    "@mastra/loggers": "latest",
-    "@mastra/mcp": "latest",
-    "@mastra/memory": "latest",
+    "@mastra/core": "^0.24.0",
+    "@mastra/libsql": "^0.16.2",
+    "@mastra/loggers": "^0.10.19",
+    "@mastra/mcp": "^0.14.2",
+    "@mastra/memory": "^0.15.11",
     "ai": "^5.0.82",
     "axios": "^1.10.0",
     "axios-retry": "^4.5.0",
     "decimal.js": "^10.6.0",
     "ethers": "^6.13.0",
-    "mastra": "latest",
+    "mastra": "^0.18.0",
     "tsup": "^8.5.0",
     "viem": "^2.21.0",
     "zod": "^3.25.76"