FOC Storage Agent 🚀

A decentralized file storage AI agent built with Mastra AI framework for Filecoin via FOC-Synapse SDK. Upload files, manage datasets, check balances, and interact with Filecoin storage through simple natural language commands.

🎯 Overview

This AI agent makes decentralized storage on Filecoin as simple as talking to a chatbot:

• Decentralized Storage: Store files permanently on Filecoin network
• AI-Powered Interface: Natural language commands for all operations
• Auto-Payment Handling: Automatic balance checking and payment processing
• CDN Support: Optional CDN for faster file retrieval
• Dataset Management: Organize files into datasets
• Blockchain Integration: Full wallet integration with ethers.js
• MCP Protocol: Works with Claude Desktop and other MCP clients

✨ Key Features

• 📁 Upload Files: Store files on Filecoin with automatic payment
• 📊 Manage Datasets: Create and query datasets with piece information
• 💰 Balance Checking: Monitor FIL and USDFC balances
• 💳 Payment Processing: Deposit USDFC and configure storage allowances
• 🌐 Provider Selection: Choose storage providers or auto-select
• 🔐 Secure: Wallet-based authentication with private key signing
• 📈 Progress Tracking: Real-time upload progress through 8 phases

🚀 Quick Start

```bash

Install dependencies

pnpm install

Configure environment

cp .env.example .env

Edit .env with your private key and OpenAI API key

Build the project

pnpm build

Run MCP server (for Claude Desktop integration)

pnpm mcp ```

🔧 Environment Setup

Create a `.env` file with:

```env

OpenAI Configuration

OPENAI_API_KEY=your_openai_api_key_here

Wallet Configuration (REQUIRED)

PRIVATE_KEY=your_private_key_without_0x_prefix

Network Configuration

FILECOIN_NETWORK=calibration # or "mainnet" for production

Optional: Custom RPC URL

FILECOIN_RPC_URL=

Optional: Storage Configuration

DEFAULT_PERSISTENCE_DAYS=180 DEFAULT_CDN_ENABLED=false ```

🔐 Getting Your Private Key

For Testing (Calibration Testnet):

1. Create a new wallet in MetaMask
2. Switch to Filecoin Calibration Testnet
3. Export private key: Settings → Security & Privacy → Show Private Key
4. Get test FIL and USDFC from Calibration Faucet

For Production (Mainnet):

• Use a dedicated wallet with only necessary funds
• Consider hardware wallet for additional security
• Never share your private key

🔌 MCP Server Features

The FOC Storage MCP server exposes prompts and resources to help users configure and use the server:

Available Prompts

1. setup-environment Get comprehensive guide for setting up environment variables:

Use prompt: setup-environment

Shows required environment variables, setup instructions, and security best practices.

2. quick-start Step-by-step guide for common operations:

Use prompt: quick-start

Learn how to check balances, upload files, manage datasets, and calculate costs.

Available Resources

1. config-status Check current environment configuration:

Read resource: foc://config/status

Returns JSON with:

• Which environment variables are configured
• Current network setting
• Ready status

2. env-template Get .env file template:

Read resource: foc://config/env-template

Returns a complete .env template with all variables and descriptions.

Using MCP Features in Claude Desktop

After installing the MCP server in Claude Desktop:

1. Check Configuration Status:

   Read the config-status resource to check my setup

2. Get Setup Instructions:

   Show me the setup-environment prompt

3. Get Started Guide:

   Show me the quick-start prompt

4. Get .env Template:

   Show me the env-template resource

📚 Usage Examples

Upload a File

``` "Upload /path/to/my/document.pdf to Filecoin" "Store /Users/me/photo.jpg with CDN enabled" ```

Check Balance

``` "Check my storage balance" "How much USDFC do I have?" ```

Manage Datasets

``` "Show me all my stored files" "Create a new dataset for my project" ```

Add Funds

``` "Add 10 USDFC to my storage balance" "Deposit 5 USDFC for 90 days of storage" ```

🏗️ Architecture

``` ┌─────────────────┐ MCP Protocol ┌──────────────────┐ FOC-Synapse SDK ┌──────────────────┐ │ Claude Desktop │ ◄─────────────────► │ Mastra MCP │ ───────────────────► │ Filecoin Network│ │ Integration │ │ Server │ │ (via Provider) │ └─────────────────┘ └──────────────────┘ └──────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────────────────────────────────┐ │ MODULAR STORAGE SYSTEM │ ├─────────────────┬──────────────────────────┬──────────────────────────────────────────────┤ │ AGENT │ TOOLS │ COMPONENTS │ │ │ │ │ │ • FOC Storage │ • Dataset Tools │ • Wallet Manager (ethers.js) │ │ Agent │ - getDatasets │ • Synapse Client (FOC-Synapse SDK) │ │ │ - createDataset │ • Session Manager (auth) │ │ • Natural │ • File Tools │ • Storage Utilities │ │ Language │ - uploadFile │ • Type System (Zod schemas) │ │ Instructions │ • Balance Tools │ • Constants & Configuration │ │ │ - getBalances │ │ │ • Auto-Payment │ • Payment Tools │ │ │ • Progress │ - processPayment │ │ │ Tracking │ • Provider Tools │ │ │ │ - getProviders │ │ └─────────────────┴──────────────────────────┴──────────────────────────────────────────────┘ ```

🛠️ Tools Available

Dataset Management

• getDatasets: Fetch all datasets with file information
• createDataset: Create new storage dataset

File Operations

• uploadFile: Upload files with auto-payment (8-phase process)

Balance & Payment

• getBalances: Check FIL/USDFC balances and storage metrics
• processPayment: Deposit USDFC and configure storage allowances

Provider Management

• getProviders: List available storage providers

See USAGE.md for comprehensive usage guide.

📊 Configuration

Storage parameters in `src/constants.ts`:

• Network Configurations: Mainnet and Calibration testnet settings
• Token Constants: USDFC and FIL token definitions
• Time Constants: Filecoin epoch and block configurations
• Storage Defaults: Persistence periods, CDN settings, file size limits
• Cost Estimates: Base costs and CDN multipliers

🔐 Security

• Private keys stored in `.env` (never commit to git)
• File path validation to prevent traversal attacks
• Sensitive file detection and warnings
• Transaction confirmation before submission
• Wallet signature required for all operations

📖 Documentation

• USAGE.md - Comprehensive usage guide with examples
• Transformation Plan - Detailed implementation roadmap

🔗 Resources

• FOC-Synapse SDK
• Filecoin Calibration Faucet
• Filecoin Documentation
• Mastra AI Framework

📝 License

ISC

Built with ❤️ using Mastra AI Framework and FOC-Synapse SDK