# Local-MMCP

> 本地多模态 MCP Server — 为 Claude Code / Codex / Cline 等 AI 客户端提供视觉、文档、音频、视频、GUI 自动化能力

[![版本](https://img.shields.io/badge/version-0.3.0-blue)](./CHANGELOG.md)
[![Python](https://img.shields.io/badge/python-3.11+-green)](./pyproject.toml)
[![架构](https://img.shields.io/badge/arch-Apple_Silicon-silver)](./ARCHITECTURE.md)
[![测试](https://img.shields.io/badge/tests-57%2F57-brightgreen)](./tests/)

## 项目简介

**Local-MMCP** 是一个基于 MCP (Model Context Protocol) 的本地多模态服务器，通过 stdio transport 向 AI 客户端暴露 **9 个多模态工具**。

核心设计理念：**本地优先、隐私安全、优雅降级**。所有数据处理在本地完成，无需将图片/文档/音频上传到第三方服务。

## 架构总览

```
MCP Client (Claude Code / Codex / Cline / Roo / OpenCode 等)
        │
        ▼
Local-MMCP MCP Server (stdio transport)
        │
        ├── oMLX 视觉/文本模型 (本地 Apple Silicon)
        │   ├── gemma-4-31B-it-Uncensored-MAX-MLX (视觉)
        │   └── Huihui-Qwen3.6-35B-A3B-Claude-4.7-Opus-abliterated-mlx-8bit (文本)
        │
        ├── MinerU / PaddleOCR (文档解析)
        ├── Qwen3-ASR / mlx-audio (语音转写)
        ├── ffmpeg (视频处理)
        └── Playwright / ADB / macOS Accessibility (GUI 自动化)
```

### 分层架构

```
Server (MCP Protocol Handler)
    └── Tools (9 个工具模块)
        ├── Clients (oMLX API 客户端 + 模型生命周期管理)
        ├── Adapters (外部工具适配器)
        └── Utils (图片处理 / 安全 / JSON 工具)
```

## 工具清单

| 工具 | 用途 | 依赖 | 需确认 |
|------|------|------|--------|
| `health_check` | 检查所有组件可用性（支持 deep 模式验证 VLM） | 无 | ❌ |
| `vision_inspect` | 分析图片：截图理解、UI 分析、图表、错误诊断 | oMLX VLM | ❌ |
| `vision_crop_verify` | 裁剪图片局部放大复核 | oMLX VLM | ❌ |
| `vision_diff` | 比较两张图片差异（像素 + 语义） | oMLX VLM | ❌ |
| `doc_parse` | 文档转 Markdown/JSON（PDF/DOCX/PPTX/XLSX/图片） | MinerU 或 PaddleOCR | ❌ |
| `audio_transcribe` | 音频转写（WAV/MP3/M4A/FLAC） | mlx-audio (Qwen3-ASR) | ❌ |
| `video_index` | 视频时间线索引（抽帧 + ASR + VLM 理解） | ffmpeg + oMLX + mlx-audio | ❌ |
| `gui_observe` | 观察 GUI 状态（浏览器/Android/macOS） | Playwright / ADB / AppKit | ❌ |
| `gui_act` | 执行 GUI 动作（点击/输入/滑动等） | Playwright / ADB / AppKit | ✅ |

## 快速开始

### 1. 环境要求

- **硬件**: Mac with Apple Silicon (M1+), 推荐 128GB+ 统一内存
- **系统**: macOS 14+
- **Python**: 3.11+
- **oMLX**: [omlx.ai](https://omlx.ai) 本地模型推理服务
- **包管理**: [uv](https://docs.astral.sh/uv/)

### 2. 安装

```bash
git clone https://github.com/rorojiao/local-mmcp.git
cd local-mmcp
uv sync

# 可选依赖（按需安装）
uv pip install mlx-audio          # 语音转写
uv pip install pyautogui           # macOS 桌面自动化
```

### 3. 配置

```bash
cp config.example.yaml config.yaml
# 编辑 config.yaml，调整 omlx 端口、模型名、安全路径等
```

> ⚠️ `config.yaml` 含本地路径和 API 密钥，已在 `.gitignore` 中排除，不会被提交。

### 4. 配置 MCP Client

#### Claude Code

在 `~/.claude/settings.json` 中添加：

```json
{
  "mcpServers": {
    "local-mmcp": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/ABSOLUTE/PATH/local-mmcp",
        "python",
        "-m",
        "local_mmcp.server"
      ],
      "env": {
        "MMCP_CONFIG": "/ABSOLUTE/PATH/local-mmcp/config.yaml"
      }
    }
  }
}
```

#### 其他 MCP Client

修改对应配置文件，使用相同 command/args/env 结构即可。

### 5. 运行检查

```bash
# 直接运行 MCP Server（测试用）
MMCP_CONFIG=config.yaml uv run python -m local_mmcp.server

# 运行诊断脚本
bash scripts/doctor.sh
```

## 安全设计

### 路径白名单

只允许访问 `config.yaml` 中 `security.allowed_roots` 列出的目录：

```yaml
security:
  allowed_roots:
    - "~/Projects"
    - "~/Desktop"
    - "~/Downloads"
    - "~/working"
    - "~/Pictures"
    - "/tmp"
    - "~/.claude"
```

### 路径黑名单

自动拒绝包含以下模式的路径：`.ssh`、`.gnupg`、`Library/Keychains`、`.env`、`id_rsa`、`id_ed25519`

### 确认令牌机制

高风险 GUI 操作（`gui_act`、`adb_install` 等）需要一次性确认令牌，TTL 300 秒。

### macOS 文件图标检测

当用户从 Finder 复制文件并粘贴到 AI 客户端时，系统可能传递文件图标而非真实图片内容。Local-MMCP 会：

1. **检测**：通过灰度 + alpha 多样性 + 尺寸综合评分识别文件图标
2. **自动替换**：三层策略找到原始文件（剪贴板路径 → 剪贴板图片数据 → 文件系统搜索）
3. **不阻塞**：检测失败时仅警告，不阻断分析流程

## 设计说明

详细的架构文档和设计说明请参考：

| 文档 | 内容 |
|------|------|
| [ARCHITECTURE.md](./ARCHITECTURE.md) | 完整架构文档：数据流、模块详解、性能数据 |
| [local-mmcp-dev-doc.md](./local-mmcp-dev-doc.md) | 原始设计文档：功能定义、接口设计、实现计划 |
| [CHANGELOG.md](./CHANGELOG.md) | 版本变更记录 |

### 核心设计模式

1. **单一 image_source 参数**：对齐 ZhiPu MCP 设计，自动识别 URL / base64 / 本地路径
2. **模型生命周期管理**：`ModelManager` 单模型互斥 + 空闲超时自动卸载（300 秒）
3. **优雅降级**：VLM 不可用时降级为 OCR 模式，不会因单一组件崩溃
4. **最小图像处理**：不做 normalize/resize，直接传原始文件给 VLM API

## 测试

```bash
# 运行所有单元测试（57 个测试用例）
uv run pytest tests/ -v

# 运行特定测试
uv run pytest tests/test_all.py -v         # 全量集成测试
uv run pytest tests/test_model_manager.py  # 模型管理器测试
```

### 测试覆盖

| 测试类别 | 用例数 | 覆盖内容 |
|----------|--------|----------|
| health_check | 9 | 所有组件状态检查 |
| vision_inspect | 3 | 本地路径/URL/base64 |
| 安全路径校验 | 12 | 合法路径/非法路径/deny 列表 |
| 确认令牌 | 6 | 创建/验证/重用/过期 |
| 文件图标检测 | 5 | 真实照片/海报/模拟图标 |
| OmlxClient | 10 | 初始化/JSON/data URL |
| vision_crop_verify | 1 | 裁剪数学验证 |
| vision_diff | 1 | 像素+语义差异 |
| 错误路径 | 12 | 空参数/非法路径/不存在 |

## 已知限制

1. **Apple Silicon only** — 依赖 omlx + MLX 框架，不支持 Intel Mac 或 Linux
2. **内存需求高** — 视觉模型 (gemma-4-31B) 约 58GB，推荐 128GB+ 统一内存
3. **模型加载延迟** — 冷启动加载模型约 20 秒，后续请求复用已加载模型
4. **MinerU/PaddleOCR** — 需单独安装，未安装时 doc_parse 返回安装建议
5. **macOS 权限** — GUI 自动化需要辅助功能权限（System Preferences → Privacy → Accessibility）
6. **剪贴板时效性** — macOS 文件图标替换依赖剪贴板内容，复制后需立即使用

## 项目结构

```
local-mmcp/
├── local_mmcp/
│   ├── server.py           # MCP 服务器入口
│   ├── config.py           # Pydantic 配置模型
│   ├── security.py         # 路径安全校验
│   ├── schemas.py          # 数据模型
│   ├── errors.py           # 错误处理
│   ├── tools/              # 9 个工具实现
│   │   ├── vision.py       # vision_inspect / crop_verify / diff
│   │   ├── document.py     # doc_parse
│   │   ├── audio.py        # audio_transcribe
│   │   ├── video.py        # video_index
│   │   ├── gui.py          # gui_observe / gui_act
│   │   └── health.py       # health_check
│   ├── clients/
│   │   └── omlx_client.py  # oMLX API 客户端 + ModelManager
│   ├── adapters/           # 外部工具适配器
│   │   ├── paddleocr_adapter.py
│   │   ├── mineru_adapter.py
│   │   ├── qwen_asr_adapter.py
│   │   ├── ffmpeg_adapter.py
│   │   ├── playwright_adapter.py
│   │   ├── adb_adapter.py
│   │   ├── macos_adapter.py
│   │   └── ui_tars_adapter.py
│   ├── utils/
│   │   ├── images.py       # 图片处理 + 图标检测/替换
│   │   ├── files.py        # 文件工具
│   │   ├── json_tools.py   # JSON 提取
│   │   └── subprocesses.py # 子进程管理
│   └── prompts/            # 工具 prompt 模板
├── tests/                  # 57 个测试用例
├── scripts/
│   ├── doctor.sh           # 诊断脚本
│   └── run_mcp.sh          # 运行脚本
├── config.example.yaml     # 配置模板
├── ARCHITECTURE.md         # 架构文档
├── local-mmcp-dev-doc.md   # 原始设计文档
└── pyproject.toml          # 项目配置
```

## License

MIT