@fil-b/foc-storage-mcp 0.3.0 → 0.4.0

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 +193 -82
  2. package/dist/stdio.js +60266 -44058
  3. package/package.json +13 -18
package/README.md CHANGED
@@ -1,32 +1,52 @@
1
1
  # Filecoin Onchain Cloud MCP
2
2
 
3
- > ⚠️ **DEPRECATED — This repository is archived and no longer maintained.**
4
- >
5
- > 👉 **Use [`foc-cli`](https://github.com/FIL-Builders/foc-cli) instead.**
6
- >
7
- > `foc-cli` is the official successor. It includes everything this MCP server did, plus a full CLI, AI agent skills, and richer tooling for Filecoin Onchain Cloud.
8
-
9
- [![Status: Archived](https://img.shields.io/badge/status-archived-red)](https://github.com/FIL-Builders/foc-cli)
10
- [![Replacement: foc-cli](https://img.shields.io/badge/replacement-foc--cli-blue)](https://github.com/FIL-Builders/foc-cli)
3
+ > MCP server for decentralized file storage on Filecoin Onchain Cloud
4
+
5
+ [![NPM Version](https://img.shields.io/npm/v/@fil-b/foc-storage-mcp)](https://www.npmjs.com/package/@fil-b/foc-storage-mcp)
11
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7
+ [![Node Version](https://img.shields.io/node/v/@fil-b/foc-storage-mcp)](https://nodejs.org)
12
8
 
13
- ---
9
+ **@fil-b/foc-storage-mcp** lets AI agents store and retrieve files on Filecoin's decentralized network through the Model Context Protocol (MCP), with automatic payment handling, CDN support, and dataset management.
10
+
11
+ ## Features
12
+
13
+ - 🛠️ **11 MCP Tools** - Upload, manage, price, and pay for 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
19
+
20
+ ## Configuration
21
+
22
+ **Requirements:**
23
+
24
+ - Node.js >= 20.10.0 ([Check version](https://nodejs.org/): `node --version`)
25
+ - `PRIVATE_KEY` - Your Filecoin wallet private key (0x...)
26
+
27
+ **Optional:**
28
+
29
+ - `FILECOIN_NETWORK` - `mainnet` (production) or `calibration` (testing, default)
30
+ - `TOTAL_STORAGE_NEEDED_GiB` - Default storage capacity for calculations (default: 150 GiB)
31
+ - `PERSISTENCE_PERIOD_DAYS` - Data retention duration (default: 365 days)
32
+ - `RUNOUT_NOTIFICATION_THRESHOLD_DAYS` - Balance warning threshold (default: 45 days, **recommended >30**)
33
+ - `SYNAPSE_SOURCE` - Source tag identifying this client to Synapse (default: `foc-storage-mcp`)
14
34
 
15
- ## 📣 Migration Notice
35
+ > **Note:** Filecoin warm storage requires 30 days paid upfront. Keep balance above 30 days to maintain service.
16
36
 
17
- `@fil-b/foc-storage-mcp` has been replaced by **[`foc-cli`](https://github.com/FIL-Builders/foc-cli)** — a single package that provides:
37
+ ## Installation
18
38
 
19
- - ✅ **MCP server** — same agent-facing tools you had here, kept in sync with the SDK
20
- - ✅ **CLI** — direct terminal access (`npx foc-cli upload ./file.pdf`)
21
- - ✅ **AI agent skills** via [skills.sh](https://skills.sh) — works with Claude Code, Cursor, Copilot, Codex, Windsurf, and 20+ AI tools
22
- - ✅ **Active maintenance** — built on the latest [Synapse SDK](https://github.com/FilOzone/synapse-sdk)
23
- - ✅ **Expanded features** — multi-upload, redundant copies, structured output (`--json`, `--format yaml`), schema introspection, and more
39
+ **Jump to:** [Cursor](#cursor) | [Claude Code](#claude-code) | [Claude Desktop](#claude-desktop) | [VS Code](#vs-code) | [Windsurf](#windsurf) | [Codex](#openai-codex) | [Other](#other-tools)
24
40
 
25
- If you were using this MCP server, switching takes one command.
41
+ ### Cursor
26
42
 
27
- ### Quick migration
43
+ [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=foc-storage&config=eyJlbnYiOnsiUFJJVkFURV9LRVkiOiJ5b3VyX3ByaXZhdGVfa2V5X2hlcmUiLCJGSUxFQ09JTl9ORVRXT1JLIjoiY2FsaWJyYXRpb24ifSwiY29tbWFuZCI6Im5weCAteSBAZmlsLWIvZm9jLXN0b3JhZ2UtbWNwIn0%3D)
28
44
 
29
- **Before** (this archived repo):
45
+ After installation, update `PRIVATE_KEY` in your config. [Learn more](https://cursor.com/de/docs/context/mcp)
46
+
47
+ ### Claude Code
48
+
49
+ Add to `.mcp.json`:
30
50
 
31
51
  ```json
32
52
  {
@@ -34,109 +54,200 @@ If you were using this MCP server, switching takes one command.
34
54
  "foc-storage": {
35
55
  "command": "npx",
36
56
  "args": ["-y", "@fil-b/foc-storage-mcp"],
37
- "env": { "PRIVATE_KEY": "0x...", "FILECOIN_NETWORK": "calibration" }
57
+ "env": {
58
+ "PRIVATE_KEY": "your_private_key_here",
59
+ "FILECOIN_NETWORK": "calibration"
60
+ }
38
61
  }
39
62
  }
40
63
  }
41
64
  ```
42
65
 
43
- **After** (`foc-cli`):
66
+ [Learn more](https://docs.claude.com/en/docs/claude-code/mcp)
44
67
 
45
- ```bash
46
- # Auto-detect your agent and install
47
- npx foc-cli mcp add
68
+ ### Claude Desktop
69
+
70
+ Add to `claude_desktop_config.json`:
71
+
72
+ ```json
73
+ {
74
+ "mcpServers": {
75
+ "foc-storage": {
76
+ "command": "npx",
77
+ "args": ["-y", "@fil-b/foc-storage-mcp"],
78
+ "env": {
79
+ "PRIVATE_KEY": "your_private_key_here",
80
+ "FILECOIN_NETWORK": "calibration"
81
+ }
82
+ }
83
+ }
84
+ }
85
+ ```
86
+
87
+ [Learn more](https://modelcontextprotocol.io/quickstart/user)
88
+
89
+ ### VS Code
90
+
91
+ Create `.vscode/mcp.json`:
92
+
93
+ ```json
94
+ {
95
+ "servers": {
96
+ "foc-storage": {
97
+ "type": "stdio",
98
+ "command": "npx",
99
+ "args": ["-y", "@fil-b/foc-storage-mcp"],
100
+ "env": {
101
+ "PRIVATE_KEY": "your_private_key_here",
102
+ "FILECOIN_NETWORK": "calibration"
103
+ }
104
+ }
105
+ }
106
+ }
107
+ ```
108
+
109
+ Enable: Settings → Chat → MCP. Click "start" in `mcp.json` (Agent mode only). [Learn more](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
110
+
111
+ ### Windsurf
112
+
113
+ Edit `~/.codeium/windsurf/mcp_config.json`:
48
114
 
49
- # Or target a specific agent
50
- npx foc-cli mcp add --agent claude-code
115
+ ```json
116
+ {
117
+ "mcpServers": {
118
+ "foc-storage": {
119
+ "command": "npx",
120
+ "args": ["-y", "@fil-b/foc-storage-mcp"],
121
+ "env": {
122
+ "PRIVATE_KEY": "your_private_key_here",
123
+ "FILECOIN_NETWORK": "calibration"
124
+ }
125
+ }
126
+ }
127
+ }
51
128
  ```
52
129
 
53
- Or install as an AI agent skill (recommended for Claude Code, Cursor, and similar):
130
+ Restart Windsurf. [Learn more](https://docs.windsurf.com/windsurf/cascade/mcp)
131
+
132
+ ### OpenAI Codex
54
133
 
55
134
  ```bash
56
- npx skills add FIL-Builders/foc-cli
135
+ codex mcp add foc-storage -- npx -y @fil-b/foc-storage-mcp
57
136
  ```
58
137
 
59
- See the [foc-cli README](https://github.com/FIL-Builders/foc-cli) for full setup and command reference.
138
+ Edit config to add environment variables. Verify: `codex mcp list`. [Learn more](https://developers.openai.com/codex/mcp)
60
139
 
61
- ### Tool mapping
140
+ ### Other Tools
62
141
 
63
- Every tool from this MCP server has an equivalent in `foc-cli`:
142
+ Most MCP tools support this format:
64
143
 
65
- | Old MCP tool (`@fil-b/foc-storage-mcp`) | New in `foc-cli` |
66
- | --- | --- |
67
- | `uploadFile` | `foc-cli upload <path>` / MCP `upload` tool |
68
- | `getDatasets` | `foc-cli dataset list` |
69
- | `getDataset` | `foc-cli dataset details -d <id>` |
70
- | `createDataset` | `foc-cli dataset create` |
71
- | `getBalances` | `foc-cli wallet balance` / `wallet summary` |
72
- | `processPayment` | `foc-cli wallet deposit <amount>` |
73
- | `getProviders` | `foc-cli provider list` |
74
- | `estimateStoragePricing` | `foc-cli wallet costs --extraBytes <n> --extraRunway <months>` |
75
- | `getStoragePricingInfo` | `foc-cli docs --prompt "pricing"` |
76
- | `convertStorageSize` | Handled natively by CLI flags |
144
+ ```json
145
+ {
146
+ "mcpServers": {
147
+ "foc-storage": {
148
+ "type": "stdio",
149
+ "command": "npx",
150
+ "args": ["-y", "@fil-b/foc-storage-mcp"],
151
+ "env": {
152
+ "PRIVATE_KEY": "your_private_key_here",
153
+ "FILECOIN_NETWORK": "calibration"
154
+ }
155
+ }
156
+ }
157
+ }
158
+ ```
77
159
 
78
- ---
160
+ ## Pricing
79
161
 
80
- ## About this archive
162
+ Pricing is read from the live Synapse v1 price list. Storage is billed per epoch
163
+ (30 seconds) using the per-TiB monthly rate plus a recurring per-dataset service
164
+ fee for non-empty datasets. Uploads can also include one-time create-dataset and
165
+ add-pieces fees, and CDN egress is usage-based.
81
166
 
82
- The sections below describe `@fil-b/foc-storage-mcp` as it was when this repository was active. They are preserved for reference only — **no further updates, bug fixes, or security patches will be issued**. Please migrate to [`foc-cli`](https://github.com/FIL-Builders/foc-cli).
167
+ 💡 Ask your agent: _"How much to store 500 GiB for 6 months?"_
83
168
 
84
- <details>
85
- <summary><strong>Click to expand original README</strong></summary>
169
+ ## Validation
86
170
 
87
- ### What it was
171
+ ```bash
172
+ npm test
173
+ npx tsc --noEmit
174
+ npm run build:mcp
175
+ npm run smoke:mcp:readonly
176
+ npm run build
177
+ ```
88
178
 
89
- `@fil-b/foc-storage-mcp` provided AI agents with access to Filecoin's decentralized storage network through the Model Context Protocol (MCP). It supported file upload with automatic USDFC payment handling, dataset organization, CDN-backed retrieval, and cost estimation.
179
+ `smoke:mcp:readonly` starts the built stdio server and exercises read-only MCP
180
+ tools for pricing, providers, balances, and datasets. It deliberately skips
181
+ upload, payment, withdrawal, and dataset-creation transactions; run those only
182
+ with an intentionally funded Calibration wallet.
90
183
 
91
- ### Original tools (10)
184
+ ## Tools
92
185
 
93
- **File operations**
186
+ Ask naturally in Claude, Cursor, or any MCP client:
94
187
 
95
- - `uploadFile` — Upload files with auto-payment
96
- - `getDatasets` — List all stored datasets
97
- - `getDataset` — Get dataset details
98
- - `createDataset` — Create new dataset container
188
+ **File Operations**
99
189
 
100
- **Balance & payments**
190
+ - `uploadFile` - Upload files with auto-payment
191
+ - `getDatasets` - List all stored datasets
192
+ - `getDataset` - Get dataset details
193
+ - `createDataset` - Create new dataset container
101
194
 
102
- - `getBalances` — Check wallet and storage metrics
103
- - `processPayment` — Deposit USDFC tokens
195
+ **Balance & Payments**
104
196
 
105
- **Providers & pricing**
197
+ - `getBalances` - Check wallet and storage metrics
198
+ - `processPayment` - Deposit USDFC tokens
199
+ - `processWithdrawal` - Withdraw a specified USDFC amount to your wallet
106
200
 
107
- - `getProviders` — List storage providers
108
- - `estimateStoragePricing` — Calculate costs
109
- - `getStoragePricingInfo` — Explain pricing models
110
- - `convertStorageSize` — Convert units
201
+ **Providers & Pricing**
111
202
 
112
- ### Original configuration
203
+ - `getProviders` - List storage providers
204
+ - `estimateStoragePricing` - Calculate costs
205
+ - `getStoragePricingInfo` - Explain pricing models
206
+ - `convertStorageSize` - Convert units
113
207
 
114
- **Requirements:** Node.js >= 20.10.0, `PRIVATE_KEY` env var (Filecoin wallet, `0x...`)
208
+ ## Usage Examples
115
209
 
116
- **Optional env vars:**
210
+ ```
211
+ "Check my storage balance"
212
+ "Upload presentation.pdf with CDN enabled"
213
+ "How much to store 2 TB for 1 year?"
214
+ "Create a dataset for Q4 reports"
215
+ "Show all my datasets"
216
+ ```
117
217
 
118
- - `FILECOIN_NETWORK` — `mainnet` or `calibration` (default)
119
- - `TOTAL_STORAGE_NEEDED_GiB` — default 150
120
- - `PERSISTENCE_PERIOD_DAYS` — default 365
121
- - `RUNOUT_NOTIFICATION_THRESHOLD_DAYS` — default 45 (recommended >30; Filecoin warm storage requires 30 days paid upfront)
218
+ ## Troubleshooting
122
219
 
123
- ### Original pricing
220
+ **Server not found:** Verify `npx --version`, check JSON syntax, restart IDE
124
221
 
125
- Storage was billed at $2.50/TiB/month, paid per-epoch (30s), with a minimum of $0.06/month. Example: 150 GiB for 1 year ≈ 0.44 USDFC.
222
+ **"PRIVATE_KEY is required":** Add to `env` section, must start with `0x`
126
223
 
127
- These economics are unchanged in `foc-cli`, which uses the same Filecoin Warm Storage Service (FWSS) under the hood.
224
+ **Transaction fails:** Check FIL for gas, verify network setting, confirm USDFC balance
128
225
 
129
- </details>
226
+ **"Invalid Version" or npm dependency errors:**
130
227
 
131
- ---
228
+ 1. Clear npm cache: `npm cache clean --force`
229
+ 2. Clear npx cache: `npx clear-npx-cache`
230
+ 3. Update npm: `npm install -g npm@latest`
231
+ 4. As last resort, use older npm: `npm install -g npm@10`
232
+
233
+ ## Security
234
+
235
+ - Never commit private keys or `.env` files
236
+ - Test on Calibration network before mainnet
237
+ - Keep balance >30 days (Filecoin warm storage requirement)
238
+ - Monitor balance regularly with `getBalances`
239
+ - Use hardware wallets for production
132
240
 
133
241
  ## Links
134
242
 
135
- - 🚀 **Replacement:** [FIL-Builders/foc-cli](https://github.com/FIL-Builders/foc-cli)
136
- - 📦 NPM (replacement): [foc-cli](https://www.npmjs.com/package/foc-cli)
137
- - 📚 [Filecoin Onchain Cloud Docs](https://docs.filecoin.cloud)
138
- - 🤖 [MCP Protocol](https://modelcontextprotocol.io/)
139
- - 🛠 [Skills.sh](https://skills.sh)
243
+ - [GitHub](https://github.com/FIL-Builders/foc-storage-mcp)
244
+ - [NPM](https://www.npmjs.com/package/@fil-b/foc-storage-mcp)
245
+ - [Filecoin Docs](https://docs.filecoin.io/)
246
+ - [MCP Protocol](https://modelcontextprotocol.io/)
247
+
248
+ ## Contributing
249
+
250
+ Contributions welcome! Open an issue for major changes.
140
251
 
141
252
  ## License
142
253
 
@@ -144,4 +255,4 @@ MIT © [@nijoe1](https://github.com/nijoe1)
144
255
 
145
256
  ---
146
257
 
147
- Built with ❤️ by [@FILBuilders](https://github.com/FIL-Builders) for the Filecoin ecosystem.
258
+ Built with ❤️ by @FILBuilders for the Filecoin ecosystem