内容
# Streamfog MCP
<p align="center">
<a href="https://github.com/casey/just"><img src="https://img.shields.io/badge/just-ready_to_go-7c5cfc?style=flat-square&logo=just&logoColor=white" alt="Just"></a>
<a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
<a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.13+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
<a href="https://biomejs.dev"><img src="https://img.shields.io/badge/Linted_with-Biome-60a5fa?style=flat-square&logo=biome&logoColor=white" alt="Biome"></a>
<a href="https://github.com/PrefectHQ/fastmcp"><img src="https://img.shields.io/badge/FastMCP-3.2-7c5cfc?style=flat-square" alt="FastMCP"></a>
</p>
> 📖 **[安装指南](INSTALL.md)** — 快速开始，手动设置和故障排除
**AI驱动的AR镜头协调器，用于实时OBS流媒体。** 通过MCP工具控制Streamfog面部过滤器，AR效果和Vtuber头像，通过本地Streamer.bot WebSocket桥接器。您的AI助手成为流媒体制作人。
| | |
|--:|--|
| **您可能需要此工具如果…** | 您希望您的AI切换AR镜头，切换Vtuber头像或在实时OBS广播期间清除效果 — 由Twitch聊天事件，频道积分或代理自动化控制。 |
| **连接内容** | [Streamfog](https://streamfog.com) 桌面应用程序 → [Streamer.bot](https://streamer.bot) WebSocket → 此MCP服务器 |
| **端口** | 后端 **10994**，仪表盘 **10995** |
| **开始** | `just bootstrap` 然后 `start.ps1` |
## 架构
```
┌─────────────┐ MCP SSE ┌──────────────────┐ WebSocket ┌──────────────┐
│ LLM 代理 │ ───────────────→ │ streamfog-mcp │ ────────────────→ │ Streamer.bot │
│ (Claude, │ ←─────────────── │ :10994 (FastMCP) │ ←──────────────── │ :8080 │
│ Gemini) │ JSON-RPC 标准输入/输出 │ :10995 (React) │ 执行操作 JSON │ │
└─────────────┘ └──────────────────┘ └──────┬────────┘
│ 原生钩子
┌──────▼────────┐
│ Streamfog │
│ 桌面应用程序 │
└──────┬────────┘
│ 浏览器源
┌──────▼────────┐
│ OBS 工作室 │
└───────────────┘
```
## 快速开始
```powershell
uv sync
# 编辑 lenses.json 文件，包含您的 Streamer.bot 操作名称
# 在 .env 文件中设置 STREAMFOG_MCP_STREAMERBOT_TOKEN（如果使用身份验证）
.\start.ps1
```
仅限MCP通过标准输入/输出（适用于Cursor，Claude Desktop）：
```powershell
uv run -m streamfog_mcp --stdio
```
## 先决条件
1. [Streamfog](https://streamfog.com) 已安装并运行
2. [Streamer.bot](https://streamer.bot) 已安装并运行
3. Streamfog → Streamer.bot 集成在Streamfog的集成面板中启用
4. Streamer.bot WebSocket服务器启用（设置 → WebSocket服务器）
5. 在Streamer.bot中创建操作（例如`SetLens_BeautySmooth`，`ClearEffects`，`ToggleAvatar`）
6. `lenses.json` 文件中包含您的操作→镜头映射
## 配置
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `STREAMFOG_MCP_STREAMERBOT_HOST` | `127.0.0.1` | Streamer.bot WebSocket主机 |
| `STREAMFOG_MCP_STREAMERBOT_PORT` | `8080` | Streamer.bot WebSocket端口 |
| `STREAMFOG_MCP_STREAMERBOT_TOKEN` | — | Streamer.bot身份验证令牌 |
| `STREAMFOG_MCP_LENS_MAP_PATH` | `lenses.json` | 镜头→操作映射文件路径 |
| `STREAMFOG_MCP_PORT` | `10994` | 后端端口 |
## 镜头映射（`lenses.json`）
```json
{
"beauty_smooth": "SetLens_BeautySmooth",
"cyber_helmet": "SetLens_CyberHelmet",
"vtuber_avatar": "SetLens_VTuberAvatar"
}
```
键是MCP工具调用中使用的人类可读的镜头标识符。值是相应的Streamer.bot操作名称。
## MCP工具（5）
### 镜头控制
| 工具 | 描述 |
|------|-------------|
| `streamfog_set_lens` | 激活特定的AR镜头或面部过滤器 |
| `streamfog_clear_effects` | 删除所有效果，返回摄像头到基准线 |
| `streamfog_toggle_avatar` | 切换Vtuber风格的头像开启/关闭 |
### 发现 — 只读
| 工具 | 描述 |
|------|-------------|
| `streamfog_list_lenses` | 列出所有配置的镜头来自 lenses.json |
| `streamfog_status` | 桥接连接健康 + 镜头数量 |
## REST API
| 端点 | 方法 | 描述 |
|----------|--------|-------------|
| `/api/v1/status` | GET | 服务器 + 桥接健康状态 |
| `/api/v1/lenses` | GET | 列出所有镜头 |
| `/api/v1/lenses/set` | POST | 激活镜头（`{"lens_identifier": "beauty_smooth"}`） |
| `/api/v1/lenses/reload` | POST | 从磁盘重新加载镜头映射 |
| `/api/v1/effects/clear` | POST | 清除所有效果 |
| `/api/v1/avatar/toggle` | POST | 切换头像 |
## 网络仪表盘
`:10995` 上的单页暗色仪表盘：
- 连接状态指示器（Streamer.bot桥接健康状态）
- 镜头网格，单击激活
- 快速操作按钮（清除效果，切换头像）
- 镜头映射重新加载
- 每5秒自动刷新
## 项目结构
```
streamfog-mcp/
├── src/streamfog_mcp/
│ ├── _mcp.py FastMCP 单例
│ ├── server.py 统一 FastAPI + FastMCP 网关
│ ├── __main__.py CLI 入口（--stdio / --serve）
│ ├── config.py Pydantic 设置（STREAMFOG_MCP_ 前缀）
│ ├── tools/
│ │ ├── __init__.py 混合导入
│ │ └── core_tools.py 5个 @mcp.tool() 装饰器
│ └── services/
│ └── streamerbot.py Streamer.bot WebSocket 客户端
├── webapp/ Vite + React 19 + Tailwind
│ └── src/
│ └── pages/Dashboard.tsx
├── lenses.json 镜头 → 操作映射
├── pyproject.toml
├── start.ps1 / start.bat
├── justfile
└── tests/
└── test_basic.py 5个测试
```
## 已知限制
- Streamfog 不暴露原生CLI或本地API — 所有控制都通过Streamer.bot进行
- 镜头激活是触发并忘记的（Streamer.bot不报告操作的成功/失败）
- 无镜头预览或缩略图检索（Streamfog桌面应用程序是一个黑盒）
- Lumia/Crowd Control桥接路径已记录但尚未作为替代传输实现
