Simple Osc Mcp Server

Simple OSC MCP 服务

一个模型上下文协议（MCP）服务，可让 AI Agent 创建 OSC（开放声音控制）端点并接收 OSC 消息。此服务为 AI Agent 与 SuperCollider、Max/MSP、TouchOSC 等支持 OSC 的应用程序和其他音乐／音频软件搭建桥梁。

功能

• OSC 端点管理：创建和管理多个 UDP 端点，用于接收 OSC 消息
• 消息缓冲：存储和查询收到的 OSC 消息，并可配置缓冲区大小
• 模式筛选：按 OSC 地址模式筛选消息，实现有针对性的数据收集
• VSCode 集成：完全兼容 VSCode 的 MCP 客户端，打造无缝开发工作流
• 实时监控：实时跟踪端点状态和消息流
• 类型安全：使用 TypeScript 构建，提供可靠的类型检查和更好的开发者体验

安装

使用 npx 快速开始（推荐）

npx osc-mcp-server

全局安装

npm install -g osc-mcp-server
osc-mcp-server

本地安装

npm install osc-mcp-server
npx osc-mcp-server

要求

• Node.js：18.0.0 或更高版本
• 操作系统：Windows、macOS 或 Linux
• 网络：OSC 通信需要访问 UDP 端口（1024-65535 端口）

使用方法

VSCode 集成

OSC MCP 服务旨在与 VSCode 的 MCP 客户端无缝协作。配置方法如下：

1. 在 VSCode 中安装 MCP 扩展（如果尚未安装）

2. 将服务配置添加到 VSCode 设置或工作区 .vscode/settings.json 中：

{
  "mcp.servers": {
    "osc-server": {
      "command": "npx",
      "args": ["osc-mcp-server"],
      "env": {}
    }
  }
}

3. 重启 VSCode以加载服务

4. 验证连接：检查 VSCode 中的 MCP 面板，应能看到列为活动状态的“osc-server”

可用工具

该服务提供四种用于 OSC 交互的主要工具：

1. create_osc_endpoint

创建一个新的 OSC 端点，以监听传入消息。

参数：

• port（必填）：UDP 端口号（1024-65535）
• bufferSize（可选）：要存储的最大消息数（默认值：1000，最大值：10000）
• addressFilters（可选）：用于筛选消息的 OSC 地址模式数组

示例：

{
  "port": 8000,
  "bufferSize": 500,
  "addressFilters": ["/synth/*", "/effects/reverb"]
}

2. stop_osc_endpoint

停止并移除现有 OSC 端点。

参数：

• endpointId（必填）：要停止的端点 ID

示例：

{
  "endpointId": "endpoint_8000_1234567890"
}

3. get_osc_messages

查询端点收到的 OSC 消息。

参数：

• endpointId（可选）：指定端点 ID（省略时查询所有端点）
• addressPattern（可选）：用于筛选消息的 OSC 地址模式
• timeWindowSeconds（可选）：时间窗口（秒），从现在向前追溯
• limit（可选）：要返回的最大消息数（最大值：1000）

示例：

{
  "endpointId": "endpoint_8000_1234567890",
  "addressPattern": "/synth/freq",
  "timeWindowSeconds": 30,
  "limit": 50
}

4. get_endpoint_status

获取 OSC 端点的状态信息。

参数：

• endpointId（可选）：指定端点 ID（省略时返回所有端点）

示例：

{
  "endpointId": "endpoint_8000_1234567890"
}

命令行用法

直接运行服务时，它会以 stdio 模式启动，用于 MCP 通信：

# Start the server
npx osc-mcp-server

# The server will output startup information to stderr
# and handle MCP communication via stdin/stdout

示例工作流

以下是使用 OSC MCP 服务的典型工作流：

1. 创建端点以监听 OSC 消息：

   {
     "tool": "create_osc_endpoint",
     "parameters": {
       "port": 8000,
       "bufferSize": 1000,
       "addressFilters": ["/synth/*"]
     }
   }
   

2. 从应用程序（SuperCollider、Max/MSP 等）向 localhost:8000 发送 OSC 消息

3. 查询收到的消息：

   {
     "tool": "get_osc_messages",
     "parameters": {
       "timeWindowSeconds": 60,
       "limit": 100
     }
   }
   

4. 检查端点状态：

   {
     "tool": "get_endpoint_status",
     "parameters": {}
   }
   

5. 完成后停止端点：

   {
     "tool": "stop_osc_endpoint",
     "parameters": {
       "endpointId": "endpoint_8000_1234567890"
     }
   }
   

开发

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

故障排除

常见问题

服务连接问题

问题：VSCode 显示“osc-server”已断开连接或未列出

• 解决方案：检查是否已安装 Node.js 18+，且可以正常访问
• 解决方案：确认 VSCode 设置中的 MCP 配置正确
• 解决方案：更改配置后重启 VSCode
• 解决方案：检查 VSCode 的输出面板中是否有与 MCP 相关的错误消息

问题：使用 npx 时出现“Command not found”错误

• 解决方案：确保已安装 npm 且为最新版本：npm install -g npm@latest
• 解决方案：清除 npm 缓存：npm cache clean --force
• 解决方案：尝试先全局安装：npm install -g osc-mcp-server

OSC 端点问题

问题：出现“Port already in use”错误

• 解决方案：选择其他端口号（1024-65535）
• 解决方案：检查端口占用情况：netstat -an | grep :8000（将 8000 替换为你的端口）
• 解决方案：停止使用同一端口的其他应用程序

问题：低端口号出现“Permission denied”错误

• 解决方案：使用 1024 及以上的端口（低于 1024 的端口需要管理员权限）
• 解决方案：在 Linux/macOS 上，只有绝对必要时才使用 sudo 运行

问题：未收到 OSC 消息

• 解决方案：确认发送应用程序已配置为向正确的 IP 和端口发送消息
• 解决方案：检查防火墙设置，确保指定端口允许 UDP 流量
• 解决方案：使用 TouchOSC 或 SuperCollider 等简单的 OSC 发送工具进行测试
• 解决方案：确认地址筛选条件没有过于严格

消息查询问题

问题：有消息时，查询结果却为空

• 解决方案：检查时间范围，消息可能早于指定的 timeWindowSeconds
• 解决方案：确认地址模式匹配正确，OSC 模式区分大小写
• 解决方案：检查端点缓冲区大小是否已超出限制（较早的消息会被移除）

问题：出现“Endpoint not found”错误

• 解决方案：使用 get_endpoint_status 列出可用的端点 ID
• 解决方案：确认端点未停止或崩溃
• 解决方案：检查端点 ID 是否有拼写错误

性能注意事项

高频消息

如果你每秒接收大量 OSC 消息：

• 增大缓冲区大小以避免消息丢失："bufferSize": 5000
• 使用地址筛选以减少处理开销
• 更频繁地查询消息以避免缓冲区溢出
• 考虑为不同消息类型使用多个端点

内存使用

• 监控缓冲区大小——更大的缓冲区会占用更多内存
• 为消息查询设置合适的限制，以避免响应过大
• 停止未使用的端点以释放资源

网络配置

防火墙设置

Windows：

# Allow UDP traffic on port 8000 (replace with your port)
netsh advfirewall firewall add rule name="OSC MCP Server" dir=in action=allow protocol=UDP localport=8000

macOS：

# Check if firewall is blocking the port
sudo pfctl -sr | grep 8000

Linux (Ubuntu/Debian)：

# Allow UDP traffic on port 8000
sudo ufw allow 8000/udp

测试 OSC 通信

使用以下工具测试 OSC 消息发送：

SuperCollider：

// Send a test message
n = NetAddr("127.0.0.1", 8000);
n.sendMsg("/test", 440, "hello");

Max/MSP：

[udpsend 127.0.0.1 8000]
|
[/test 440 hello(

Python (python-osc)：

from pythonosc import udp_client

client = udp_client.SimpleUDPClient("127.0.0.1", 8000)
client.send_message("/test", [440, "hello"])

调试模式

如需详细日志，可以查看运行服务时的 stderr 输出：

npx osc-mcp-server 2> debug.log

这会将所有调试消息保存到文件中以供分析。

获取帮助

如果你遇到此处未涵盖的问题：

1. 查看 GitHub Issues：https://github.com/username/osc-mcp-server/issues
2. 创建新问题，并提供：
   • 你的操作系统和 Node.js 版本
   • 完整的错误消息
   • 重现问题的步骤
   • 你的 MCP 配置

文档

API 参考

• 完整 API 参考 - 所有 MCP 工具及其参数的详细文档

示例和工作流

• 示例概览 - 所有可用示例和配置
• VSCode 配置 - VSCode MCP 客户端设置示例
• OSC 发送端 - 用于各种平台的 OSC 消息发送端测试
• 工作流示例 - 分步使用工作流

特定工作流

• 基本工作流 - 从单个端点开始使用
• 多端点工作流 - 管理多个 OSC 来源

开发

• CI/CD 文档 - 持续集成和部署详情

CI/CD 流水线

本项目使用 GitHub Actions 进行持续集成和部署：

• 自动化测试：在 Node.js 18、20 和 22 上运行
• 代码质量：ESLint、Prettier 和 TypeScript 检查
• 安全扫描：npm audit 和漏洞扫描
• 覆盖率报告：要求覆盖率达到 80%
• 自动发布：在带标签的版本发布时发布到 npm

发布流程

推送 git 标签以创建新版本：

git tag v1.0.0
git push origin v1.0.0

或者使用 PowerShell 发布脚本：

.\scripts\release.ps1 patch  # or minor, major, prerelease

详细的 CI/CD 文档请参阅 docs/CI-CD.md。

许可证

MIT