IPFS MCP Enhanced Service

一个功能强大的基于 Model Context Protocol (MCP) 的 IPFS 服务，允许 AI 代理与 IPFS 网络进行交互，实现完整的分布式存储和检索解决方案。

✨ 功能特性

🔧 IPFS 安装和验证

• 🚀 自动安装: 自动检测、下载、安装和初始化 IPFS
• 🔍 健康检查: 全面的系统健康状态检查
• ⚙️ 守护进程管理: 启动/停止 IPFS 守护进程
• 🌐 跨平台支持: Windows、macOS、Linux 全平台支持

📁 文件管理

• 🔄 内容上传: 支持文本内容和本地文件上传到 IPFS
• 📥 内容获取: 从 IPFS 网络获取内容
• 📦 批量操作: 支持批量上传多个文件
• 📌 固定管理: 固定和取消固定内容到本地节点
• 📋 文件列表: 列出 IPFS 中的文件和目录

🔍 CID 工具

• 🧩 CID 解析: 解析 CID 并获取详细信息
• 🔄 格式转换: 转换 CID 格式（v0 到 v1 或 v1 到 v0）
• ✅ CID 验证: 验证 CID 格式是否正确

🖼️ 媒体处理

• 🖼️ 图片处理: 上传并处理图片（调整尺寸、格式转换、质量设置）
• 🎵 音频处理: 上传并处理音频（格式转换、比特率调整）
• 📊 媒体信息: 获取图片和音频的详细信息

💡 智能提示

• 📖 上传指南: IPFS 文件上传指南
• 🔍 CID 帮助: CID 使用帮助
• 🎨 媒体处理指南: 媒体文件处理指南

🛠️ MCP 标准

• ✅ 完全兼容: 符合 Model Context Protocol 标准
• 🔧 21 个工具: 提供丰富的工具集
• 💬 3 个提示: 智能交互提示

🚀 快速开始

方法1: 使用 npm 安装（推荐）

# 全局安装
npm install -g ipfs-mcp-enhanced

# 或本地安装
npm install ipfs-mcp-enhanced

方法2: 从源码构建

# 克隆仓库
git clone https://github.com/yourusername/ipfs-mcp-enhanced.git
cd ipfs-mcp-enhanced

# 安装依赖
npm install

# 构建项目
npm run build

# 启动服务
npm start

🔧 IPFS 自动安装

无需手动安装 IPFS！ 本服务会自动处理：

• ✅ 检测系统平台和架构
• ✅ 自动下载对应版本的 IPFS
• ✅ 自动解压和安装
• ✅ 自动初始化和配置
• ✅ 自动启动守护进程

支持平台：

• 🪟 Windows (amd64)
• 🍎 macOS (amd64, arm64)
• 🐧 Linux (amd64, arm64)

📖 使用方法

1. 作为 MCP 服务器运行

# 全局安装后
ipfs-mcp-enhanced

# 或从源码运行
node dist/index.js

2. 在 MCP 客户端中配置

Claude Desktop 配置

在 Claude Desktop 的配置文件中添加：

{
  "mcpServers": {
    "ipfs-enhanced": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/ipfs-mcp-enhanced"
    }
  }
}

通用 MCP 配置

{
  "mcpServers": {
    "ipfs-enhanced": {
      "command": "ipfs-mcp-enhanced",
      "args": [],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

3. 启动脚本

我们提供了便捷的启动脚本：

# Windows
start-mcp.bat

# PowerShell
.\start-mcp.ps1

# 或直接使用 npm
npm start

🛠️ 可用工具 (21个)

🔧 IPFS 安装和验证工具

| 工具名称 | 描述 | 主要参数 | |---------|------|----------| | check_ipfs_installation | 检查IPFS是否已安装 | 无 | | install_ipfs | 自动安装IPFS | 无 | | auto_setup_ipfs | 自动设置IPFS（检查、安装、启动） | autoStart | | health_check | IPFS系统健康检查 | 无 | | start_ipfs_daemon | 启动IPFS守护进程 | background | | stop_ipfs_daemon | 停止IPFS守护进程 | 无 |

📁 文件管理工具

| 工具名称 | 描述 | 主要参数 | |---------|------|----------| | upload_content | 上传文本或二进制内容到IPFS | content, fileName, isBase64 | | upload_file | 上传本地文件到IPFS | filePath, fileName | | fetch_content | 从IPFS获取内容 | cid | | batch_upload | 批量上传多个文件到IPFS | filePaths, baseFileName | | list_files | 列出IPFS中的文件（通过目录CID） | cid | | pin_content | 固定内容到本地IPFS节点 | cid | | unpin_content | 取消固定内容 | cid | | get_node_info | 获取IPFS节点信息 | 无 |

🔍 CID 工具

| 工具名称 | 描述 | 主要参数 | |---------|------|----------| | parse_cid | 解析CID并获取详细信息 | cid | | convert_cid | 转换CID格式（v0到v1或v1到v0） | cid, targetVersion | | validate_cid | 验证CID格式是否正确 | cid |

🖼️ 媒体处理工具

| 工具名称 | 描述 | 主要参数 | |---------|------|----------| | upload_image | 上传并处理图片到IPFS | imagePath, options | | get_image_info | 获取IPFS中图片的详细信息 | cid | | upload_audio | 上传并处理音频到IPFS | audioPath, options | | get_audio_info | 获取IPFS中音频的详细信息 | cid |

💡 可用提示 (3个)

| 提示名称 | 描述 | 参数 | |---------|------|------| | upload_guide | IPFS文件上传指南 | file_type | | cid_help | CID使用帮助 | 无 | | media_processing | 媒体文件处理指南 | 无 |

🧪 测试

运行测试

# 运行完整功能测试
node test-enhanced-complete.js

# 运行简化测试
node test-enhanced-simple.js

# 运行基础测试
npm run test:new

测试覆盖

• ✅ IPFS 安装和验证工具
• ✅ 文件上传和下载
• ✅ CID 解析和验证
• ✅ 媒体处理功能
• ✅ 提示功能
• ✅ 错误处理

⚙️ 配置

环境变量

| 变量名 | 默认值 | 描述 | |--------|--------|------| | NODE_ENV | production | 运行环境 | | IPFS_PATH | ./.ipfs | IPFS 数据目录 | | IPFS_API | /ip4/127.0.0.1/tcp/5001 | IPFS API 地址 |

自定义配置

可以通过环境变量或修改源代码来调整配置：

# 设置自定义 IPFS 路径
export IPFS_PATH="/custom/path/to/ipfs"

# 设置自定义 API 地址
export IPFS_API="/ip4/192.168.1.100/tcp/5001"

🔧 故障排除

常见问题

1. IPFS 安装失败

# 检查网络连接
ping dist.ipfs.tech

# 手动下载 IPFS
# 从 https://dist.ipfs.tech/kubo/ 下载对应版本

2. 权限问题

# Windows: 以管理员身份运行
# Linux/macOS: 检查文件权限
chmod +x ipfs

3. 端口冲突

# 检查端口占用
netstat -an | grep 5001

# 修改 IPFS 配置
ipfs config Addresses.API /ip4/127.0.0.1/tcp/5002

4. 内存不足

# 增加 Node.js 内存限制
node --max-old-space-size=4096 dist/index.js

获取帮助

• 📖 查看 MCP-USAGE.md 详细使用指南
• 🐛 提交 Issue
• 💬 参与 Discussions

📄 许可证

MIT License - 详见 LICENSE 文件

🤝 贡献

我们欢迎所有形式的贡献！

贡献方式

1. 🍴 Fork 项目
2. 🌿 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 💾 提交更改 (git commit -m 'Add some AmazingFeature')
4. 📤 推送到分支 (git push origin feature/AmazingFeature)
5. 🔄 创建 Pull Request

开发指南

# 安装开发依赖
npm install

# 运行开发模式
npm run dev

# 运行测试
npm test

# 构建项目
npm run build

📈 更新日志

v2.0.0 (当前版本)

• 🚀 重大更新: 完全重写，增强版功能
• 🔧 新增: IPFS 自动安装和验证工具
• 🖼️ 新增: 图片和音频处理功能
• 🔍 新增: CID 解析、转换和验证工具
• 💡 新增: 智能提示功能
• 📁 新增: 文件管理和固定功能
• 🌐 改进: 跨平台支持 (Windows/macOS/Linux)
• 🛠️ 改进: 21个工具 + 3个提示
• 📊 改进: 完整的健康检查和错误处理

v1.0.0

• 🎉 初始版本发布
• 📤 支持基本的文件上传和下载功能
• 📦 支持批量文件操作
• 🔄 自动 IPFS 节点检测和启动

🌟 致谢

感谢以下开源项目：

• IPFS - 分布式文件系统
• Model Context Protocol - AI 代理协议
• kubo-rpc-client - IPFS JavaScript 客户端
• Sharp - 高性能图像处理
• FFmpeg - 音视频处理

⭐ 如果这个项目对你有帮助，请给我们一个 Star！