ipfs-mcp/README.md

MCP service to interact with an IPFS node for file storage and retrieval.

# 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 安装（推荐）

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

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

### 方法2: 从源码构建

```bash
# 克隆仓库
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 服务器运行

```bash
# 全局安装后
ipfs-mcp-enhanced

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

### 2. 在 MCP 客户端中配置

#### Claude Desktop 配置

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

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

#### 通用 MCP 配置

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

### 3. 启动脚本

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

```bash
# 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` | 媒体文件处理指南 | 无 |

## 🧪 测试

### 运行测试

```bash
# 运行完整功能测试
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 地址 |

### 自定义配置

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

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

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

## 🔧 故障排除

### 常见问题

#### 1. IPFS 安装失败
```bash
# 检查网络连接
ping dist.ipfs.tech

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

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

#### 3. 端口冲突
```bash
# 检查端口占用
netstat -an | grep 5001

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

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

### 获取帮助

- 📖 查看 [MCP-USAGE.md](./MCP-USAGE.md) 详细使用指南
- 🐛 提交 [Issue](https://github.com/yourusername/ipfs-mcp-enhanced/issues)
- 💬 参与 [Discussions](https://github.com/yourusername/ipfs-mcp-enhanced/discussions)

## 📄 许可证

MIT License - 详见 [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

### 开发指南

```bash
# 安装开发依赖
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](https://ipfs.io/) - 分布式文件系统
- [Model Context Protocol](https://modelcontextprotocol.io/) - AI 代理协议
- [kubo-rpc-client](https://github.com/ipfs/js-kubo-rpc-client) - IPFS JavaScript 客户端
- [Sharp](https://sharp.pixelplumbing.com/) - 高性能图像处理
- [FFmpeg](https://ffmpeg.org/) - 音视频处理

---

<div align="center">

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

[![GitHub stars](https://img.shields.io/github/stars/yourusername/ipfs-mcp-enhanced?style=social)](https://github.com/yourusername/ipfs-mcp-enhanced)
[![npm version](https://img.shields.io/npm/v/ipfs-mcp-enhanced)](https://www.npmjs.com/package/ipfs-mcp-enhanced)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

</div>