内容
# 媒体处理服务器
MCP 服务器（可流式 HTTP + 可选的标准输入/输出）用于通过 **OpenCV 5.0**、**FFmpeg** 和 **ONVIF** 进行媒体处理。
## 快速开始（开发）
```powershell
cd MediaMCPServer
.\install.ps1
```
然后，在您的客户端刷新 MCP，并确保 HTTP 服务器正在运行（参见 [docs/INSTALLATION.md](docs/INSTALLATION.md)）。
## 快速开始（生产包）
解压 `dist\media-mcp-server-*.zip`，然后：
```powershell
.\install.ps1
```
在您的 MCP 客户端中打开提取的文件夹作为工作区，并刷新服务器列表。
## 项目布局
```
MediaMCPServer/
├── README.md
├── install.ps1 # 入口点（开发）
├── build.ps1 # 入口点（开发）
├── src/ # Delphi 源代码（.pas, .dpr）
├── scripts/
│ ├── install.ps1
│ ├── build.ps1
│ ├── package.ps1 # 创建生产 ZIP
│ ├── dist_install.ps1 # 分发版中的安装程序
│ ├── setup_mcp.ps1
│ ├── verify_install.ps1
│ └── tests/
├── config/
│ └── mcp.json.template
├── docs/
│ ├── INSTALLATION.md # MCP 客户端设置（所有支持的 IDE）
│ ├── WSL.md # WSL 客户端 + Windows 服务器（HTTP）
│ ├── EXAMPLES.md # 复杂的用例和代理工作流
│ ├── DISTRIBUTION.md
│ └── models-readme.txt
├── data/media/ # 用户捕获、输出、面部、视频
├── bin/ # 运行时（exe, dll, 模型）— gitignored
└── dist/ # 生产包 — gitignored
```
## 构建机器的要求
| 组件 | 目的 |
|-----------|---------|
| Windows 10/11 x64 | 平台 |
| RAD Studio / Delphi dcc64 | 构建服务器 |
| MSVC + CMake | 构建 `opencv_delphi_wrapper.dll`（如果需要） |
| OpenCV 5.0 已构建 | 通过 `OpenCV_DIR` 的原生 DLL |
| 兄弟仓库（编译） | `OpenCV\OpenCV 5.0`，`Delphi-FFMPEG`，`Delphi-ONVIF` |
| 网络 | 通过 `scripts\download_deps.ps1` 直接下载模型/DLL |
## 脚本
| 命令 | 描述 |
|---------|-------------|
| `.\install.ps1` | 完整安装（下载依赖 + 构建 + MCP 配置） |
| `.\build.ps1` | 仅构建 |
| `.\scripts\download_deps.ps1` | 下载模型 + FFmpeg + OpenCV 运行时到 `bin\` |
| `.\scripts\download_models.ps1` | 仅 ONNX 模型 |
| `.\scripts\download_ffmpeg_dll.ps1` | 仅 FFmpeg DLL |
| `.\scripts\download_opencv_runtime.ps1` | OpenCV DLL + 构建 `opencv_delphi_wrapper.dll` |
| `.\scripts\package.ps1` | 在 `dist\` 中创建精简 ZIP（默认） |
| `.\scripts\package.ps1 -Variant full` | 创建离线完整 ZIP |
| `.\scripts\release.ps1 -Version X -Publish` | 打包 + GitHub 发布 |
| `.\scripts\setup_mcp.ps1` | 重新生成项目 MCP 配置（HTTP，启动服务器） |
| `.\scripts\setup_mcp.ps1 -Stdio` | 标准输入/输出 MCP 配置代替 HTTP |
| `.\scripts\setup_mcp.ps1 -Wsl` | WSL HTTP 设置（Windows 端） |
| `.\scripts\setup_wsl_http.ps1` | 检测 WSL 网络，启动 HTTP，编写代码片段 |
| `bash scripts/setup_wsl_mcp.sh` | 在 WSL 中配置 MCP（在 WSL 中运行） |
| `.\scripts\verify_install.ps1` | 检查安装 |
| `.\scripts\tests\test_http_mcp.ps1` | 通过 Streamable HTTP 进行烟雾测试（默认） |
| `.\scripts\tests\test_tools.ps1` | 通过标准输入/输出（`--stdio`）进行烟雾测试 |
| `bash scripts/tests/test_http_mcp_wsl.sh` | 来自 WSL 的 HTTP 烟雾测试 |
### install.ps1 选项
```powershell
.\install.ps1 -OpenCvDir "C:\opencv\build"
.\install.ps1 -Force -SkipDownload
.\install.ps1 -StrictVerify
```
## MCP 客户端
支持的 MCP 客户端和每个 IDE 的设置： **[docs/INSTALLATION.md](docs/INSTALLATION.md)**。
**复杂工作流示例**（网络研讨会回顾；ONVIF/RTSP 仓库监控；USB 网络摄像头访问控制）： **[docs/EXAMPLES.md](docs/EXAMPLES.md)**。
快速配置（Streamable HTTP — 默认）：
```powershell
.\bin\MediaMCPServer.exe
# 或： .\bin\launch_http.cmd
```
客户端配置： `"url": "http://127.0.0.1:8765/mcp"` — 参见 `config/mcp.json.template` 和 [docs/INSTALLATION.md](docs/INSTALLATION.md)。
### 标准输入/输出（可选）
使用 `--stdio` 运行服务器，并在客户端配置中使用 `command` + `cwd` — 参见 `config/mcp.stdio.json.template`.
**WSL:** WSL 中的客户端，Windows 上的服务器 — [docs/WSL.md](docs/WSL.md).
## 环境变量
| 变量 | 目的 |
|----------|---------|
| `OpenCV_DIR` | OpenCV 构建的 CMake 路径 |
| `OPENCV_MODELS_PATH` / `MEDIA_MCP_MODELS_PATH` | ONNX 模型目录 |
| `MEDIA_MCP_DATA_PATH` | 重写 `data\media\` |
| `MEDIA_MCP_DEBUG=1` | 输出到标准错误 |
| `MEDIA_MCP_TRANSPORT=stdio` | 强制标准输入/输出模式（默认是 HTTP） |
| `MEDIA_MCP_HTTP_HOST` | HTTP 绑定主机（默认 `127.0.0.1`） |
| `MEDIA_MCP_HTTP_PORT` | HTTP 端口（默认 `8765`） |
| `MEDIA_MCP_HTTP_PATH` | HTTP 路径（默认 `/mcp`） |
## 工具（47）
**FFmpeg:** `video_probe`，`video_grab_frame`，`video_scene_detect`，`video_trim`，…
**OpenCV:** `image_detect_objects`，`image_detect_faces`，`face_enroll`，`face_identify`，…
**摄像头：** `webcam_list`，`webcam_grab_frame`，`video_track_object`
**ONVIF:** `camera_discover`，`onvif_get_stream_uri`，…
## 生产版本
在具有完整构建的 **开发机器** 上：
```powershell
.\install.ps1
.\scripts\release.ps1 -Version "1.0.3"
```
创建 `dist\media-mcp-server-<version>-win64-lite.zip`（GitHub 默认）。
可选的离线完整 ZIP：`-Variant both`。发布：`-Publish`（需要 `gh` CLI）。
参见 **[docs/RELEASE.md](docs/RELEASE.md)** 以获取完整的维护者工作流。
在 **目标机器** （无 Delphi）上：
```powershell
# 从 GitHub Releases 下载精简 ZIP，解压，然后：
.\install.ps1
```
参见 [docs/DISTRIBUTION.md](docs/DISTRIBUTION.md) 以获取部署详情。
## 故障排除
| 问题 | 修复 |
|-------|-----|
| MCP 连接被拒绝 | 启动 HTTP 服务器： `cd bin; .\launch_http.cmd` |
| MCP JSON 错误 | 运行 `.\scripts\setup_mcp.ps1` |
| 黄色 MCP 状态 | 等待或重新加载窗口；检查 MCP 面板中的工具数量 |
| 缺少模型 | `.\scripts\download_models.ps1 -Force` |
| 缺少 FFmpeg | `.\scripts\download_ffmpeg_dll.ps1 -Force` |
| OpenCV 加载错误 | `.\scripts\download_opencv_runtime.ps1 -Force` |
| DLL 加载失败（包） | 提取完整 ZIP；不要仅复制 `.exe` |
