@fil-b/foc-storage-mcp 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +136 -163
  2. package/dist/mcp-server.js +1094 -429
  3. package/package.json +4 -2
package/README.md CHANGED
@@ -6,32 +6,51 @@
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7
7
  [![Node Version](https://img.shields.io/node/v/@fil-b/foc-storage-mcp)](https://nodejs.org)
8
8
 
9
- ## Overview
9
+ **@fil-b/foc-storage-mcp** provides AI agents with seamless access to Filecoin's decentralized storage network through the Model Context Protocol (MCP). Store files persistently with automatic payment handling, CDN support, and comprehensive dataset management.
10
10
 
11
- **@fil-b/foc-storage-mcp** is a Model Context Protocol (MCP) server that provides AI agents with seamless access to Filecoin's decentralized storage network. Powered by the FOC-Synapse SDK, it enables intelligent applications to store files persistently on Filecoin with automatic payment handling, CDN support, and comprehensive dataset management.
11
+ ## Features
12
12
 
13
- Perfect for building AI applications that need persistent, censorship-resistant storage without managing blockchain complexity.
13
+ - 🛠️ **10 MCP Tools** - Upload, manage, and price storage operations
14
+ - 📁 **Dataset Organization** - Group related files efficiently
15
+ - 💳 **Automatic Payments** - Built-in USDFC handling with gasless permits
16
+ - ⚡ **CDN Support** - Fast retrieval for frequently accessed files
17
+ - 💰 **Cost Estimation** - Calculate costs, explain pricing, convert units
18
+ - 🤖 **AI-Ready** - Designed for Claude, Cursor, and MCP clients
14
19
 
15
- ## Features
20
+ ## Configuration
21
+
22
+ **Required:**
23
+ - `PRIVATE_KEY` - Your Filecoin wallet private key (0x...)
24
+
25
+ **Optional:**
26
+ - `FILECOIN_NETWORK` - `mainnet` (production) or `calibration` (testing, default)
27
+ - `TOTAL_STORAGE_NEEDED_GiB` - Default storage capacity for calculations (default: 150 GiB)
28
+ - `PERSISTENCE_PERIOD_DAYS` - Data retention duration (default: 365 days)
29
+ - `RUNOUT_NOTIFICATION_THRESHOLD_DAYS` - Balance warning threshold (default: 45 days, **recommended >30**)
30
+
31
+ > **Note:** Filecoin warm storage requires 30 days paid upfront. Keep balance above 30 days to maintain service.
32
+
33
+ ## Installation
16
34
 
17
- - 🛠️ **7 MCP Tools**: Complete file storage operations via Model Context Protocol
18
- - 📁 **Dataset Organization**: Group and manage related files efficiently
19
- - 💳 **Automatic Payment**: Built-in USDFC payment handling with EIP-2612 gasless permits
20
- - ⚡ **CDN Support**: Optional fast retrieval for frequently accessed files
21
- - 📊 **Balance Monitoring**: Comprehensive storage metrics and wallet tracking
22
- - 🔧 **Provider Selection**: Choose from approved Filecoin storage providers
23
- - 🤖 **AI-Ready**: Designed for AI agents and MCP clients
24
- - 🔒 **Censorship-Resistant**: Leverage Filecoin's decentralized storage network
35
+ **Jump to:** [Cursor](#cursor) | [Claude Code](#claude-code) | [Claude Desktop](#claude-desktop) | [VS Code](#vs-code) | [Windsurf](#windsurf) | [Codex](#openai-codex) | [Other](#other-tools)
25
36
 
26
- ## Quick Start
37
+ ### Cursor
38
+
39
+ [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=foc-storage&config=eyJlbnYiOnsiUFJJVkFURV9LRVkiOiJ5b3VyX3ByaXZhdGVfa2V5X2hlcmUifSwiY29tbWFuZCI6Im5weCAteSBAZmlsLWIvZm9jLXN0b3JhZ2UtbWNwIn0%3D)
40
+
41
+ After installation, update `PRIVATE_KEY` in your config. [Learn more](https://cursor.com/de/docs/context/mcp)
42
+
43
+ ### Claude Code
44
+
45
+ ```bash
46
+ claude mcp add foc-storage -- npx -y @fil-b/foc-storage-mcp
47
+ ```
27
48
 
28
- ### Using with MCP Clients
49
+ Edit `.mcp.json` to add `PRIVATE_KEY`. [Learn more](https://docs.claude.com/en/docs/claude-code/mcp)
29
50
 
30
- Add the following configuration to your MCP client:
51
+ ### Claude Desktop
31
52
 
32
- - **Claude Desktop**: `claude_desktop_config.json`
33
- - **Cursor**: `mcp.json`
34
- - **Claude Code**: `.mcp.json`
53
+ Add to `claude_desktop_config.json`:
35
54
 
36
55
  ```json
37
56
  {
@@ -40,204 +59,158 @@ Add the following configuration to your MCP client:
40
59
  "command": "npx",
41
60
  "args": ["-y", "@fil-b/foc-storage-mcp"],
42
61
  "env": {
43
- "PRIVATE_KEY": "your_private_key_here"
62
+ "PRIVATE_KEY": "your_private_key_here",
63
+ "FILECOIN_NETWORK": "calibration"
44
64
  }
45
65
  }
46
66
  }
47
67
  }
48
68
  ```
49
69
 
50
- ### Configuration
51
-
52
- | Variable | Required | Default | Description |
53
- | ------------------------------------ | -------- | ------------- | --------------------------------------------------------------- |
54
- | `PRIVATE_KEY` | **Yes** | - | Wallet private key for transaction signing (must start with 0x) |
55
- | `FILECOIN_NETWORK` | No | `calibration` | Network: `mainnet` for production, `calibration` for testing |
56
- | `TOTAL_STORAGE_NEEDED_GiB` | No | `1024` | Storage capacity in GiB for balance calculations |
57
- | `PERSISTENCE_PERIOD_DAYS` | No | `365` | Data retention duration in days |
58
- | `RUNOUT_NOTIFICATION_THRESHOLD_DAYS` | No | `10` | Balance warning threshold in days |
59
-
60
- ## MCP Tools Reference
61
-
62
- Seven tools to interact with Filecoin storage through your AI agent. Simply ask Claude, Cursor, or your MCP client naturally.
63
-
64
- ### `uploadFile`
65
-
66
- Upload files to decentralized storage with automatic payment handling.
67
-
68
- **Key inputs:** `filePath` (required), `withCDN`, `metadata`, `datasetId`
69
-
70
- **How to use:**
71
-
72
- ```
73
- "Upload my presentation.pdf to Filecoin with CDN enabled"
74
- "Store /docs/report.pdf to dataset 123 with metadata category=financial"
75
- "Upload this file to permanent storage"
76
- ```
77
-
78
- ### `getDatasets`
70
+ [Learn more](https://modelcontextprotocol.io/quickstart/user)
79
71
 
80
- List all your stored datasets with file information and retrieval URLs.
72
+ ### VS Code
81
73
 
82
- **Key inputs:** `includeAllDatasets`, `filterByCDN`
74
+ Create `.vscode/mcp.json`:
83
75
 
84
- **How to use:**
85
-
86
- ```
87
- "Show me all my datasets"
88
- "List my CDN-enabled datasets"
89
- "What files have I stored on Filecoin?"
76
+ ```json
77
+ {
78
+ "servers": {
79
+ "foc-storage": {
80
+ "type": "stdio",
81
+ "command": "npx",
82
+ "args": ["-y", "@fil-b/foc-storage-mcp"],
83
+ "env": {
84
+ "PRIVATE_KEY": "your_private_key_here",
85
+ "FILECOIN_NETWORK": "calibration"
86
+ }
87
+ }
88
+ }
89
+ }
90
90
  ```
91
91
 
92
- ### `getDataset`
93
-
94
- Get detailed information about a specific dataset including all files.
92
+ Enable: Settings → Chat → MCP. Click "start" in `mcp.json` (Agent mode only). [Learn more](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
95
93
 
96
- **Key inputs:** `datasetId` (required)
94
+ ### Windsurf
97
95
 
98
- **How to use:**
96
+ Edit `~/.codeium/windsurf/mcp_config.json`:
99
97
 
98
+ ```json
99
+ {
100
+ "mcpServers": {
101
+ "foc-storage": {
102
+ "command": "npx",
103
+ "args": ["-y", "@fil-b/foc-storage-mcp"],
104
+ "env": {
105
+ "PRIVATE_KEY": "your_private_key_here",
106
+ "FILECOIN_NETWORK": "calibration"
107
+ }
108
+ }
109
+ }
110
+ }
100
111
  ```
101
- "Show me dataset 123"
102
- "Get details for my Q4 reports dataset"
103
- "What's in dataset abc123?"
104
- ```
105
-
106
- ### `createDataset`
107
-
108
- Create a new container to organize related files together.
109
112
 
110
- **Key inputs:** `withCDN`, `providerId`, `metadata`
113
+ Restart Windsurf. [Learn more](https://docs.windsurf.com/windsurf/cascade/mcp)
111
114
 
112
- **How to use:**
115
+ ### OpenAI Codex
113
116
 
117
+ ```bash
118
+ codex mcp add foc-storage -- npx -y @fil-b/foc-storage-mcp
114
119
  ```
115
- "Create a new dataset with CDN for my project files"
116
- "Make a dataset called 'Q4-Reports' with metadata project=quarterly"
117
- "Create a storage dataset for organizing my documents"
118
- ```
119
-
120
- ### `getBalances`
121
120
 
122
- Check your wallet balance and storage metrics.
121
+ Edit config to add environment variables. Verify: `codex mcp list`. [Learn more](https://developers.openai.com/codex/mcp)
123
122
 
124
- **Key inputs:** `storageCapacityBytes`, `persistencePeriodDays`, `notificationThresholdDays`
123
+ ### Other Tools
125
124
 
126
- **How to use:**
125
+ Most MCP tools support this format:
127
126
 
128
- ```
129
- "Check my storage balance"
130
- "How much USDFC do I have?"
131
- "Show my wallet balance and storage status"
127
+ ```json
128
+ {
129
+ "mcpServers": {
130
+ "foc-storage": {
131
+ "type": "stdio",
132
+ "command": "npx",
133
+ "args": ["-y", "@fil-b/foc-storage-mcp"],
134
+ "env": {
135
+ "PRIVATE_KEY": "your_private_key_here",
136
+ "FILECOIN_NETWORK": "calibration"
137
+ }
138
+ }
139
+ }
140
+ }
132
141
  ```
133
142
 
134
- ### `processPayment`
143
+ ## Pricing
135
144
 
136
- Deposit USDFC tokens to fund storage operations.
145
+ **Storage:** $2.50/TiB/month (pay-per-epoch: 30 seconds) • Min: $0.06/month
137
146
 
138
- **Key inputs:** `depositAmount`
147
+ **CDN Egress:** $7/TiB downloaded • 1 USDFC = ~146 GiB credits
139
148
 
140
- **How to use:**
149
+ **Example:** 150 GiB for 1 year ≈ 0.44 USDFC ($0.44)
141
150
 
142
- ```
143
- "Deposit 100 USDFC for storage"
144
- "Add funds to my storage wallet"
145
- "Process payment of 50 USDFC"
146
- ```
147
-
148
- ### `getProviders`
151
+ 💡 Ask your agent: *"How much to store 500 GiB for 6 months?"*
149
152
 
150
- List available Filecoin storage providers.
153
+ ## Tools
151
154
 
152
- **Key inputs:** `onlyApproved`
155
+ Ask naturally in Claude, Cursor, or any MCP client:
153
156
 
154
- **How to use:**
157
+ **File Operations**
158
+ - `uploadFile` - Upload files with auto-payment
159
+ - `getDatasets` - List all stored datasets
160
+ - `getDataset` - Get dataset details
161
+ - `createDataset` - Create new dataset container
155
162
 
156
- ```
157
- "Show me available storage providers"
158
- "List approved Filecoin providers"
159
- "What providers can I use?"
160
- ```
163
+ **Balance & Payments**
164
+ - `getBalances` - Check wallet and storage metrics
165
+ - `processPayment` - Deposit USDFC tokens
161
166
 
162
- ## Common Workflows
167
+ **Providers & Pricing**
168
+ - `getProviders` - List storage providers
169
+ - `estimateStoragePricing` - Calculate costs
170
+ - `getStoragePricingInfo` - Explain pricing models
171
+ - `convertStorageSize` - Convert units
163
172
 
164
- ### First-Time File Upload
173
+ ## Usage Examples
165
174
 
166
175
  ```
167
- You: "Check my storage balance"
168
- Agent: Shows 0 USDFC available
169
-
170
- You: "Deposit 100 USDFC for storage"
171
- Agent: Processes payment, shows updated balance
172
-
173
- You: "Upload /documents/report.pdf with CDN enabled"
174
- Agent: Uploads file, returns retrieval URL
176
+ "Check my storage balance"
177
+ "Upload presentation.pdf with CDN enabled"
178
+ "How much to store 2 TB for 1 year?"
179
+ "Create a dataset for Q4 reports"
180
+ "Show all my datasets"
175
181
  ```
176
182
 
177
- ### Organized Storage with Datasets
183
+ ## Troubleshooting
178
184
 
179
- ```
180
- You: "Create a dataset with CDN called Q4-Reports"
181
- Agent: Creates dataset, returns ID: 123
185
+ **Server not found:** Verify `npx --version`, check JSON syntax, restart IDE
182
186
 
183
- You: "Upload /reports/q4-summary.pdf to dataset 123"
184
- Agent: Uploads first file to dataset
187
+ **"PRIVATE_KEY is required":** Add to `env` section, must start with `0x`
185
188
 
186
- You: "Upload /reports/q4-details.pdf to dataset 123"
187
- Agent: Uploads second file to dataset
189
+ **Transaction fails:** Check FIL for gas, verify network setting, confirm USDFC balance
188
190
 
189
- You: "Show me dataset 123"
190
- Agent: Lists all files in the Q4-Reports dataset
191
- ```
191
+ ## Security
192
192
 
193
- ### Monitoring Storage
194
-
195
- ```
196
- You: "Check my storage balance and metrics"
197
- Agent: Shows FIL/USDFC balances, storage days remaining
193
+ - Never commit private keys or `.env` files
194
+ - Test on Calibration network before mainnet
195
+ - Keep balance >30 days (Filecoin warm storage requirement)
196
+ - Monitor balance regularly with `getBalances`
197
+ - Use hardware wallets for production
198
198
 
199
- You: "List all my datasets"
200
- Agent: Displays all stored datasets with file counts
201
-
202
- You: "What's my storage status?"
203
- Agent: Reports current usage and alerts if balance is low
204
- ```
205
-
206
- ## Security Notes
207
-
208
- 🔐 **Important Security Considerations:**
199
+ ## Links
209
200
 
210
- - **Never commit `.env` files** or expose private keys in code repositories
211
- - **Use environment variables** for all sensitive configuration
212
- - **Test on Calibration network** before mainnet deployment to avoid real funds loss
213
- - **Validate file paths** before upload operations to prevent unauthorized access
214
- - **Monitor balance regularly** to avoid service interruptions
215
- - **Review transaction details** before confirming operations
216
- - **Use hardware wallets** for production deployments with significant funds
217
- - **Limit private key exposure** by using separate wallets for storage operations
201
+ - [GitHub](https://github.com/FIL-Builders/foc-storage-mcp)
202
+ - [NPM](https://www.npmjs.com/package/@fil-b/foc-storage-mcp)
203
+ - [Filecoin Docs](https://docs.filecoin.io/)
204
+ - [MCP Protocol](https://modelcontextprotocol.io/)
218
205
 
219
206
  ## Contributing
220
207
 
221
- Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
208
+ Contributions welcome! Open an issue for major changes.
222
209
 
223
210
  ## License
224
211
 
225
212
  MIT © [@nijoe1](https://github.com/nijoe1)
226
213
 
227
- ## Links
228
-
229
- - **GitHub Repository**: [FIL-Builders/foc-storage-mcp](https://github.com/FIL-Builders/foc-storage-mcp)
230
- - **NPM Package**: [@fil-b/foc-storage-mcp](https://www.npmjs.com/package/@fil-b/foc-storage-mcp)
231
- - **Filecoin Documentation**: [docs.filecoin.io](https://docs.filecoin.io/)
232
- - **Synapse SDK**: [filecoin-project/synapse-sdk](https://github.com/FilOzone/synapse-sdk)
233
- - **Model Context Protocol**: [modelcontextprotocol.io](https://modelcontextprotocol.io/)
234
- - **Mastra Framework**: [mastra.ai](https://mastra.ai)
235
-
236
- ## Support
237
-
238
- - **Issues**: [GitHub Issues](https://github.com/FIL-Builders/foc-storage-mcp/issues)
239
- - **Discussions**: [GitHub Discussions](https://github.com/FIL-Builders/foc-storage-mcp/discussions)
240
-
241
214
  ---
242
215
 
243
- Built with ❤️ from @FILBuilers for the Filecoin ecosystem
216
+ Built with ❤️ by @FILBuilders for the Filecoin ecosystem