# reasonix-multimodal-mcp

Reasonix 多模态 MCP 服务器：让 Reasonix 具备处理**图片 / PDF / 音频 / 视频 / Office 文档**的能力。

- 图片：本地 OCR（rapidocr）+ 硅基流动视觉模型（Qwen3-VL）语义理解
- PDF：文本提取（pymupdf），扫描件自动 OCR 兜底
- 音频：faster-whisper 本地转写（无需联网）
- 视频：ffmpeg 抽帧 → 视觉模型 + 音轨 whisper 转写
- Office：docx / xlsx / pptx 结构化提取
- 剪贴板图片：截图后直接分析，无需保存文件（WSL 下自动读取 Windows 剪贴板）

## 工具列表

| 工具 | 说明 |
| --- | --- |
| `describe_image` | 理解一张图片（OCR + 视觉描述） |
| `describe_clipboard_image` | 分析剪贴板里的图片（截图后直接用） |
| `extract_pdf` | 提取 PDF 文本（含扫描件 OCR） |
| `transcribe_audio` | 转写音频（faster-whisper 本地） |
| `analyze_video` | 视频抽帧 + 音轨转写 |
| `extract_office` | 提取 docx / xlsx / pptx |
| `extract_text` | 万能入口，按扩展名自动分派 |
| `mcp_list_capabilities` | 查看配置状态 |

## 安装

前置要求：Python 3.10+、已安装 Reasonix、ffmpeg（音频/视频功能，`sudo apt install ffmpeg`）。

```bash
git clone https://github.com/GeeniTiming/reasonix-multimodal-mcp.git
cd reasonix-multimodal-mcp
SILICONFLOW_API_KEY=sk-你的key bash install.sh
```

脚本会自动：复制文件到 `~/.reasonix/mcp-multimodal/`、创建虚拟环境、安装依赖、
注册 `[[plugins]]` 到 `~/.reasonix/config.toml`、写入 API key、验证安装。

然后在 Reasonix 里**开新会话**，即可使用 `mcp__multimodal__*` 工具。

## 配置

API key 放在 `~/.reasonix/.env`：

```
SILICONFLOW_API_KEY=sk-xxx
```

可选环境变量（写在 `server.py` 顶部注释）：
- `SILICONFLOW_VL_MODEL`：视觉模型，默认 `Qwen/Qwen3-VL-32B-Instruct`
- `WHISPER_MODEL`：whisper 模型，默认本地 `~/.reasonix/whisper-models/small`（首次使用自动从 hf-mirror 下载）

## 使用示例

在 Reasonix 聊天框里**直接写文件路径**（不要用 `@` 引用图片，那会把二进制字节塞进上下文）：

```
分析这张图：images/screenshot.png
C:\Users\xxx\Desktop\报错截图.png 里有什么错误？
这个视频讲了什么：/home/xxx/videos/demo.mp4
提取这个 PDF 的内容：论文.pdf
```

路径支持：工作区相对路径、WSL 路径（`/home/...`）、Windows 路径（`C:\...` 自动转 `/mnt/c/...`）。

**剪贴板图片**：截图（Win+Shift+S）后直接说"分析剪贴板里的图片"即可，无需保存文件。

## 平台说明

| 平台 | 剪贴板图片 | 说明 |
| --- | --- | --- |
| WSL | ✅ | 自动通过 powershell.exe 读取 Windows 剪贴板 |
| 原生 Linux | ✅（需装 wl-clipboard 或 xclip/xsel） | 自动回退到 wl-paste / xclip / xsel |
| macOS | ❌ | 暂不支持剪贴板图片 |

## 故障排查

- **视觉 API 偶发 `HTTP 500 code 50507`**：硅基流动服务端偶发错误，重试一次即可
- **`@images/xxx.png` 显示乱码**：`@` 引用会注入文件原始字节，图片请直接写路径
- **Reasonix 扩展 `+` 菜单附加图片无效**：Reasonix ACP 后端声明 `image: false`（不支持 image block），这是后端设计限制，用路径/剪贴板方式替代