内容
# Lovense MCP 服务器
## 概述
**模型上下文协议（MCP）** 服务器，用于通过 Lovense Remote 应用的游戏模式控制 Lovense 玩具。该服务器遵循 [MCP 规范](https://modelcontextprotocol.io/) 并使用 Python MCP SDK。
## 主要功能
**MCP 合规性：**
- ✅ HTTP 传输，使用 FastAPI
- ✅ 流式响应，实现高效数据传输
- ✅ 完整的协议支持：工具、资源和提示
- ✅ JSON-RPC 2.0 合规
**Lovense 集成：**
- 🎮 **5 种控制工具**：振动、旋转、抽动、停止、模式
- 📊 **2 种资源**：连接玩具状态、API 配置
- 🎯 **3 种提示模板**：控制玩具、快速振动、模式播放
- 🔒 带有适当错误处理的异步 HTTP 客户端
**生产就绪：**
- 🐳 Docker 容器化
- 🔐 非 root 用户执行
- 🚀 异步/等待贯穿始终
- 📝 全面的日志记录
## 先决条件
- **Docker** 和 Docker Compose
- **Lovense Remote 应用**，启用游戏模式
- 访问 Lovense 玩具的本地网络
- Python 3.11+（用于本地开发）
## 快速入门
### 1. 克隆仓库
```bash
git clone <仓库网址>
cd lovense-mcp-server
```
### 2. 配置环境
```bash
cp .env.example .env
nano .env # 使用您的设置进行编辑
```
**必需的环境变量：**
```env
GAME_MODE_IP=192.168.1.100 # 您的 Lovense Remote 本地 IP
GAME_MODE_PORT=30010 # HTTPS 端口（默认：30010）
MCP_AUTH_TOKEN=您的秘密令牌 # MCP 端点的身份验证令牌
PORT=8000 # HTTP 服务器端口（默认：8000）
```
### 3. 获取游戏模式 IP 地址
1. 打开 **Lovense Remote** 应用
2. 启用 **游戏模式**
3. 记录显示的本地 IP（例如 `192.168.1.100`）
4. 在 `.env` 文件中使用此 IP
### 4. 使用 Docker 运行
```bash
# 构建和启动
docker-compose up -d
# 查看日志
docker-compose logs -f lovense-mcp
# 停止
docker-compose down
```
## 用法
这是一个使用 FastAPI 通过 **HTTP** 进行通信的 MCP 服务器。它公开了一个接受 JSON-RPC 2.0 请求并返回流式响应的 `/mcp` 端点。
### API 端点
- **POST `/mcp`**：主要 MCP 端点（需要 Bearer 令牌身份验证）
- **GET `/health`**：健康检查端点（不需要身份验证）
### 身份验证
所有发送到 `/mcp` 的请求必须在 Authorization 头中包含 Bearer 令牌：
```bash
curl -X POST http://localhost:8000/mcp \
-H "Authorization: Bearer 您的秘密令牌" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
```
### 连接到 MCP 客户端
配置您的 MCP 客户端连接到 HTTP 端点：
```json
{
"lovense": {
"url": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Bearer 您的秘密令牌"
}
}
}
```
## 可用工具
### 1. `vibrate`
向 Lovense 玩具发送振动命令。
**参数：**
- `toy`（字符串，可选）：玩具 ID 或为空表示所有玩具
- `intensity`（整数，必填）：振动级别 0-20
- `duration`（整数，必填）：持续时间（秒）（1-60）
**示例：**
```json
{
"name": "vibrate",
"arguments": {
"intensity": 15,
"duration": 5
}
}
```
### 2. `rotate`
向具有旋转功能的玩具发送旋转命令。
**参数：**
- `toy`（字符串，可选）：玩具 ID 或为空表示所有玩具
- `intensity`（整数，必填）：旋转级别 0-20
- `duration`（整数，必填）：持续时间（秒）（1-60）
### 3. `pump`
向具有抽动功能的玩具发送抽动命令。
**参数：**
- `toy`（字符串，可选）：玩具 ID 或为空表示所有玩具
- `intensity`（整数，必填）：抽动级别 0-3
- `duration`（整数，必填）：持续时间（秒）（1-60）
### 4. `stop`
立即停止所有正在运行的功能。
**参数：**
- `toy`（字符串，可选）：玩具 ID 或为空表示所有玩具
### 5. `pattern`
播放预设的振动模式。
**参数：**
- `toy`（字符串，可选）：玩具 ID 或为空表示所有玩具
- `pattern`（字符串，必填）：`pulse`、`wave`、`fireworks` 或 `earthquake` 之一
- `duration`（整数，必填）：持续时间（秒）（1-60）
## 可用资源
资源提供有关 Lovense 设置的实时信息。
### 1. `lovense://toys/connected`
列出所有当前连接的 Lovense 玩具及其状态。
### 2. `lovense://config/api`
查看当前的 API 配置和连接详细信息。
## 可用提示
提示提供引导交互模板。
### 1. `control_toy`
用于控制具有引导参数的玩具的交互提示。
**参数：**
- `action`：要执行的操作（vibrate、rotate、pump、stop、pattern）
- `intensity`：强度级别（可选）
- `duration`：持续时间（秒）（可选）
### 2. `quick_vibrate`
具有预设强度的快速振动。
**参数：**
- `level`：强度级别（low、medium、high）
### 3. `pattern_play`
播放振动模式。
**参数：**
- `pattern_name`：模式名称（pulse、wave、fireworks、earthquake）
- `duration`：持续时间（秒）（可选）
## 开发
### 本地设置
```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # 在 Windows 上：venv\Scripts\activate
# 安装依赖项
pip install -r requirements.txt
# 设置环境变量
export GAME_MODE_IP=192.168.1.100
export GAME_MODE_PORT=30010
# 运行服务器
python server.py
```
### 项目结构
```
lovense-mcp-server/
├── server.py # 主要的 MCP 服务器实现
├── requirements.txt # Python 依赖项
├── Dockerfile # Docker 容器配置
├── docker-compose.yml # Docker Compose 协调
├── .env.example # 环境变量模板
├── .gitignore # Git 忽略规则
├── LICENSE # MIT 许可证
├── README.md # 此文件
└── REQUIREMENTS.md # 原始项目需求
```
## 安全功能
- **非 root 容器**：以用户 `mcpuser`（UID 1000）运行
- **异步 HTTP 客户端**：使用具有适当超时处理的 httpx
- **输入验证**：验证所有工具参数
- **错误处理**：全面错误处理和日志记录
- **无硬编码秘密**：所有配置通过环境变量
## 故障排除
### 服务器无法启动
```bash
# 检查日志
docker-compose logs lovense-mcp
# 验证环境变量
docker-compose config
```
### 无法连接到玩具
- 验证游戏模式已在 Lovense Remote 应用中启用
- 检查 `GAME_MODE_IP` 是否与应用中显示的 IP 匹配
- 确保服务器和玩具在同一个本地网络上
- 验证端口 30010 是否可访问
### MCP 客户端无法连接
- 验证 MCP 客户端是否正确配置
- 检查 stdio 通信是否正常
- 查看服务器日志中的错误
- 确保容器具有 stdin/stdout 访问权限
## 其他资源
- [MCP 协议文档](https://modelcontextprotocol.io/)
- [Lovense 游戏模式 API](https://developer.lovense.com/)
- [MCP Python SDK](https://github.com/anthropics/anthropic-mcp-python)
## 许可证
该项目根据 MIT 许可证授权。有关详细信息，请参见 [LICENSE](LICENSE) 文件。
