# Flix MCP Server

> 🚀 MCP (Model Context Protocol) 服务器实现，为 Flix 局域网文件传输应用提供 AI 模型调用接口。

[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ 特性亮点

- 🔍 **设备发现** - 自动发现局域网内的 Flix 设备
- 📨 **消息传输** - 发送/接收文本消息
- 📁 **文件传输** - 支持断点续传的文件收发
- 📋 **剪贴板同步** - 跨设备剪贴板同步
- 🔒 **设备管理** - 设备配对、黑名单管理
- 🤖 **AI 集成** - 与 Claude Desktop 等 AI 客户端无缝集成

## 📦 快速开始

### 安装和构建

```bash
# 克隆项目
git clone <repository-url>
cd flix-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 启动服务
npm start
```

### 验证运行

```bash
# 检查健康状态
curl http://localhost:8765/health

# 预期输出
{"status":"ok","deviceId":"...","deviceName":"Flix MCP Server"}
```

## 配置

创建 `.env` 文件：

```env
# 服务配置
PORT=8765
DEVICE_NAME=Flix MCP Server

# 文件传输配置
MAX_FILE_SIZE=10737418240  # 10GB
AUTO_RECEIVE=false
DOWNLOAD_DIR=./downloads

# 安全配置
REQUIRE_PAIRING=true
```

## 🤖 与 Claude Desktop 集成

在 Claude Desktop 配置文件中添加：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "flix": {
      "command": "node",
      "args": ["/absolute/path/to/flix-mcp/dist/index.js"],
      "env": {
        "DEVICE_NAME": "Claude Flix",
        "AUTO_RECEIVE": "true"
      }
    }
  }
}
```

重启 Claude Desktop 后，你就可以：

```
用户: 发现局域网内的 Flix 设备
Claude: [调用 flix_discover_devices 工具]

用户: 把文件 ~/Documents/report.pdf 发送到我的 iPad
Claude: [调用 flix_send_file 工具]

用户: 同步剪贴板到我的 iPhone
Claude: [调用 flix_sync_clipboard 工具]
```

## MCP Tools

### 设备管理

- `flix_discover_devices` - 发现局域网设备
- `flix_get_device` - 获取设备详情
- `flix_pair_device` - 设备配对
- `flix_block_device` - 拉黑设备
- `flix_unblock_device` - 解除拉黑

### 消息传输

- `flix_send_text` - 发送文本消息
- `flix_get_messages` - 获取消息列表

### 文件传输

- `flix_send_file` - 发送文件
- `flix_receive_file` - 接收文件
- `flix_get_transfer_status` - 查询传输状态
- `flix_cancel_transfer` - 取消传输
- `flix_pause_transfer` - 暂停传输
- `flix_resume_transfer` - 恢复传输

### 剪贴板同步

- `flix_sync_clipboard` - 同步剪贴板
- `flix_get_clipboard` - 获取剪贴板内容

## 📚 文档

- 🚀 [快速开始指南](./QUICKSTART.md) - 5分钟快速上手
- 📖 [详细使用文档](./USAGE.md) - 完整的配置和使用说明
- 🎬 [使用场景演示](./DEMO_SCENARIOS.md) - 实际使用示例
- ✅ [完成清单](./CHECKLIST.md) - 项目实现清单
- 📋 [项目总结](./PROJECT_SUMMARY.md) - 项目概览

## 🛠️ 开发

```bash
# 开发模式（自动重载）
npm run dev

# 运行测试
npm test

# 代码检查
npm run lint

# 构建
npm run build
```

## 🐳 Docker 部署

```bash
# 使用 Docker Compose（推荐）
docker-compose up -d

# 或手动构建
docker build -t flix-mcp .
docker run -d --network host -v $(pwd)/downloads:/app/downloads flix-mcp
```

**注意**: 使用 `--network host` 以支持 UDP 组播发现。

## 📊 项目状态

✅ **完全实现** - 所有核心功能已完成
✅ **生产就绪** - 完善的错误处理和测试
✅ **文档完善** - 详细的使用文档和示例
✅ **构建成功** - TypeScript 编译通过

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

---

**🎉 项目已完成，可以立即投入使用！**

如有问题，请查看 [USAGE.md](./USAGE.md) 的故障排查章节。