🚀 Bridging LLMs to Decentralized Storage: An Expert's Guide to the MCP IPFS Server 🛰️

This document provides an in-depth look at the MCP IPFS Server, a crucial component for integrating Large Language Models (LLMs) with the decentralized storage capabilities of the storacha.network. This server acts as a bridge, enabling LLMs to leverage IPFS for data storage, retrieval, and management through the standardized Model Context Protocol (MCP).

💡 Understanding the Need

LLMs, while powerful, often lack direct access to external data sources and tools. The Model Context Protocol (MCP) addresses this limitation by providing a standardized interface for LLMs to interact with external systems. This MCP IPFS Server specifically focuses on enabling LLMs to utilize the decentralized storage offered by storacha.network, leveraging the w3 command-line interface.

✨ Core Features and Functionality

This server provides a comprehensive suite of tools, wrapping the w3 CLI to expose storacha.network's functionality to MCP-compliant clients. Key features include:

Authentication and Authorization: Securely manage access to storacha.network resources using w3_login, w3_reset, and w3_account_ls. The w3_login tool requires the W3_LOGIN_EMAIL environment variable for seamless authentication.
Space Management: Organize and manage storage spaces with tools like w3_space_ls, w3_space_use, w3_space_info, w3_space_add, and w3_space_provision. Note that w3_space_create requires manual execution due to interactive prompts.
Data Management: Upload, list, and remove data using w3_up, w3_ls, and w3_rm, respectively.
Sharing and Collaboration: Generate shareable links using w3_open, leveraging w3s.link for easy access to stored data.
Delegations and Proofs: Manage delegations and proofs with tools like w3_delegation_create, w3_delegation_ls, w3_delegation_revoke, w3_proof_add, and w3_proof_ls, enabling fine-grained access control and data integrity verification.
Key and Token Management: Create and manage API keys and tokens using w3_key_create and w3_bridge_generate_tokens.
Advanced Storage Operations: Access advanced storage features through w3 can ... commands, including Blob, CAR, Upload, Index, Access Claim, and Filecoin Info management.
Account and Billing Management: Monitor account usage and manage billing with w3_plan_get, w3_coupon_create, and w3_usage_report.

🛠️ Prerequisites: A Deep Dive

Before deploying the MCP IPFS Server, ensure the following prerequisites are met:

Node.js: Version 22.0.0 or higher is required. Verify your installation with node -v.
w3 CLI: The server relies on the @web3-storage/w3cli for interacting with storacha.network. Install it globally using:
```
npm install -g @web3-storage/w3cli
```
Configure the CLI with your email address:
```
w3 login <[email protected]>
```
Follow the email verification steps to complete the login process.
Environment Variable: The W3_LOGIN_EMAIL environment variable must be set to the same email address used for w3 login. This is crucial for the w3_login tool to function correctly.

🏗️ Project Architecture: A Developer's Perspective

The project's structure is designed for maintainability and extensibility:

src/
├── index.ts          # Main entry point: Server initialization, MCP setup, and request routing.  This file orchestrates the entire server.
├── schemas.ts        # Zod schemas: Defines the structure and validation rules for input arguments for each MCP tool.  Ensures data integrity.
├── tool_handlers.ts  # Implementation logic: Contains the core logic for each MCP tool, handling requests and interacting with the `w3` CLI.
├── utils.ts          # Helper functions: Provides utility functions, such as executing `w3` commands and parsing JSON output.
└── utils/
    └── logger.ts     # Logger configuration: Configures a basic logger for debugging and monitoring server activity.

🚀 Deployment Strategies: NPX vs. Docker

The MCP IPFS Server can be deployed using various methods, each with its own advantages and disadvantages.

NPX (Recommended for Local Development)

NPX provides a simple and convenient way to run the server locally, assuming you have npm and the prerequisites installed.

{
  "mcpServers": {
    "ipfs": {
      "command": "npx",
      "args": ["-y", "mcp-ipfs"],
      "env": {
        "W3_LOGIN_EMAIL": "[email protected]"
      }
    }
  }
}

Docker (Recommended for Production)

Docker provides a containerized environment, ensuring consistency and portability across different platforms.

{
  "mcpServers": {
    "mcp-ipfs": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/project:/path/to/your/project",
        "-e",
        "W3_LOGIN_EMAIL",
        "alexbakers/mcp-ipfs"
      ],
      "env": {
        "W3_LOGIN_EMAIL": "[email protected]"
      }
    }
  }
}

Important Considerations for Paths:

Many w3 commands require absolute filesystem paths. This is crucial for commands like w3_up, w3_delegation_create --output, w3_proof_add, w3_can_blob_add, and w3_can_store_add.

NPX: Use absolute paths from your host machine.
Docker: Use absolute paths inside the container. When interacting with files from your host machine, you must mount the relevant directory into the container using the -v flag. For example:
```
docker run -v /Users/me/project:/Users/me/project ...
```
Then, use the container path (e.g., /Users/me/project/my_file.txt) in the tool arguments.

📦 Building and Running the Server

Clone the Repository:

git clone https://github.com/alexbakers/mcp-ipfs.git
cd mcp-ipfs

Install Dependencies:
```
npm install
```
Build the TypeScript Code:
```
npm run build
```
Run the Server:
```
export W3_LOGIN_EMAIL="[email protected]"
node dist/index.js
```
Alternatively, publish the package to NPM (if you have the necessary permissions):
```
npm publish
```

🐳 Docker Build Instructions

Build the Docker Image:
```
docker build -t alexbakers/mcp-ipfs .
```
Replace alexbakers/mcp-ipfs with your desired username/repository and tag.

🔑 Security Considerations

Environment Variables: Store sensitive information like API keys and email addresses as environment variables instead of hardcoding them in the code.
Input Validation: The server uses Zod schemas to validate input arguments, preventing potential security vulnerabilities.
Least Privilege: Grant the server only the necessary permissions to access storacha.network resources.
Regular Updates: Keep the server and its dependencies up-to-date to patch any security vulnerabilities.

📜 Conclusion

The MCP IPFS Server is a powerful tool for bridging the gap between LLMs and decentralized storage. By understanding its features, architecture, and deployment strategies, developers can leverage this server to build innovative AI-powered applications that utilize the benefits of IPFS and storacha.network. This guide provides the necessary knowledge to effectively deploy and utilize the MCP IPFS Server, enabling a new era of AI applications leveraging decentralized storage.