内容
# 感官融合 MCP 服务器（TypeScript）
TypeScript 实现的模型上下文协议（MCP）服务器，用于控制 **感官融合** 照明和视觉软件。这提供了一种类型安全、现代化的替代 Python 实现，具有相同的功能。
## ✨ 功能特点
- **类型安全**：完整的 TypeScript 实现，严格的类型检查
- **11 种 MCP 工具**：通过 OSC 协议完全控制感官融合
- **现代化架构**：基于 Promise 的 async/await 模式
- **强大的错误处理**：全面的验证和错误恢复
- **开发工具**：热重载、代码检查、测试和调试
- **OSC 通信**：高效的双向 OSC 消息处理
- **连接管理**：自动重新连接和连接池
## 🏗️ 架构
该项目由两个主要组件组成：
1. **OSC 守护进程** (`src/osc-daemon.ts`)：桥接 TCP 连接到与感官融合的 OSC 通信
2. **MCP 服务器** (`src/mcp-server.ts`)：为 Claude Desktop 集成提供 11 种工具
## ⚡ 快速开始
```bash
# 安装依赖
npm install
# 启动 OSC 守护进程（在一个终端中）
npm run daemon
# 测试连接（在另一个终端中）
npm run test-connection
# 启动 MCP 服务器进行开发
npm run dev
```
参见 [QUICK_SETUP.md](docs/QUICK_SETUP.md) 以获取详细的设置说明。
## 🛠️ 可用的 MCP 工具
| 工具 | 描述 | 示例用法 |
|------|-------------|---------------|
| `control_synesthesia` | 直接 OSC 控制 | 设置亮度、颜色、位置 |
| `launch_scene` | 启动场景和预设 | 启动 "hexarray" 场景 |
| `control_playlist` | 播放列表导航 | 下一首、上一首、播放、停止 |
| `control_media` | 媒体选择 | 按名称或位置选择 |
| `randomize_controls` | 随机化控制库 | 随机化场景或元控制 |
| `set_rendering` | 启用/禁用渲染 | 暂停或恢复输出 |
| `trigger_preset` | 激活预设 | 加载保存的控制状态 |
| `create_preset` | 保存当前状态 | 创建新预设 |
| `trigger_favslot` | 激活收藏夹 | 快速访问场景 |
| `reset_controls` | 重置为默认值 | 清除当前值 |
| `test_connection` | 验证设置 | 检查守护进程连接 |
## 📝 开发
[开发提示](./DEVELOPMENT_TIPS.md)
### 脚本
```bash
# 快速启动（推荐）
npm run all # 同时运行守护进程和 MCP 服务器
npm run all:dev # 在开发模式下运行，并启用热重载
# 开发
npm run dev # 启动 MCP 服务器，启用热重载
npm run daemon # 只启动 OSC 守护进程
npm run build # 构建生产环境
npm start # 运行生产环境构建
# 测试和验证
npm test # 运行测试套件
npm run test-connection # 测试守护进程连接
npm run validate # 验证设置
# 代码质量
npm run lint # 检查代码风格
npm run lint:fix # 修复代码风格问题
npm run format # 格式化代码
```
### 项目结构
```
src/
├── mcp-server.ts # 主要的 MCP 服务器，包含 11 种工具
├── osc-daemon.ts # OSC 守护进程服务
├── synesthesia-client.ts # 守护进程通信客户端
├── types/
│ ├── osc.ts # OSC 协议类型
│ ├── synesthesia.ts # 感官融合特定类型
│ └── mcp.ts # MCP 相关类型
└── utils/
├── validation.ts # 输入验证的 Zod 模式
└── logging.ts # 结构化日志记录工具
```
## 🔧 配置
### 默认端口
- **MCP ↔ 守护进程**：TCP 端口 7654
- **守护进程 → 感官融合**：UDP 端口 7000（OSC 输出）
- **感官融合 → 守护进程**：UDP 端口 7001（OSC 输入）
### 环境变量
```bash
LOG_LEVEL=1 # 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR
```
### 自定义配置
修改源文件中的配置对象：
```typescript
// 在 src/mcp-server.ts 中
const clientConfig: ConnectionConfig = {
host: '127.0.0.1',
port: 7654,
timeoutMs: 5000,
};
// 在 src/osc-daemon.ts 中
const config: OSCDaemonConfig = {
socketHost: '127.0.0.1',
socketPort: 7654,
synesthesiaHost: '127.0.0.1',
synesthesiaPort: 7000,
receivePort: 7001,
};
```
## 🧪 测试
### 单元测试
```bash
npm test
```
### 手动测试
```bash
# 测试守护进程连接
npm run test-connection
# 验证完整设置
npm run validate
```
### 集成测试
启动守护进程，并使用 Claude Desktop 或直接工具调用进行测试。
## 📚 API 参考
### 示例工具用法
```javascript
// 控制亮度
await control_synesthesia({
address: "/controls/meta/brightness",
value: 0.75
});
// 启动场景和预设
await launch_scene({
scene_name: "hexarray",
preset_name: "warm"
});
// 控制播放列表
await control_playlist({
action: "next"
});
// 随机化场景控制
await randomize_controls({
bank: "scene",
group: "color"
});
```
参见 [Python 文档](../SYNESTHESIA_OSC_API.md) 以获取完整的 OSC API 参考。
## 🔄 与 Python 版本的差异
### 优势
- **类型安全**：编译时错误检查和 IntelliSense
- **现代化异步**：原生 Promise-based async/await 模式
- **更好的工具支持**：热重载、先进的调试、全面代码检查
- **性能**：高效的 V8 JavaScript 引擎
- **生态系统**：丰富的 Node.js 生态系统和软件包
### 兼容性
- **相同的功能**：所有 11 种 MCP 工具功能相同
- **相同的 OSC 协议**：与现有的感官融合设置兼容
- **相同的配置**：使用相同的端口号和设置过程
## 🚀 部署
### 生产环境构建
```bash
npm run build
npm start
```
### Claude Desktop 配置
在后台运行 `npm run daemon` （待办：合并到单个 Node 脚本中）
```json
{
"mcpServers": {
"感官融合控制器": {
"command": "node",
"args": ["C:/full/path/to/synesthesia-mcp/dist/mcp-server.js"]
}
}
}
```
## 🤝 贡献
1. 分叉仓库
2. 创建功能分支：`git checkout -b feature/amazing-feature`
3. 进行更改并使用正确的 TypeScript 类型
4. 为新功能添加测试
5. 确保所有测试通过：`npm test`
6. 代码检查和格式化：`npm run lint:fix && npm run format`
7. 提交更改：`git commit -m 'Add amazing feature'`
8. 推送到分支：`git push origin feature/amazing-feature`
9. 打开拉取请求
## 📄 许可证
该项目使用 MIT 许可证 - 参见 [LICENSE](../LICENSE) 文件以获取详细信息。
## 🙏 致谢
- Synesthesia MCP 团队的原始 Python 实现
- [模型上下文协议（MCP）](https://modelcontextprotocol.io) 规范
- [node-osc](https://github.com/MylesBorins/node-osc) 以实现 OSC 协议
- [Zod](https://zod.dev) 以实现运行时类型验证
- TypeScript 和 Node.js 社区
## 📞 获取帮助
- **设置问题**：查看 [QUICK_SETUP.md](docs/QUICK_SETUP.md)
- **OSC 命令**：参考 [SYNESTHESIA_OSC_API.md](../SYNESTHESIA_OSC_API.md)
- **开发**：运行 `npm run validate` 以验证设置
- **连接问题**：运行 `npm run test-connection`
---
**状态**：✅ 已准备好用于生产环境
**TypeScript 版本**：5.3+
**Node.js 版本**：18+
**MCP 协议**：与 Claude Desktop 兼容
