MCP合成器控制器
这个项目实现了一个基于Python的 模型上下文协议（MCP）服务器 设计用于允许大型语言模型（LLM）实时控制JUCE合成器的参数。
MCP服务器公开结构化 *工具* LLM可以调用，这些工具调用被转换为OSC消息，发送给正在运行的JUCE插件或应用程序。
此存储库包含 仅Python端相应的JUCE合成器必须实现能够处理以下消息的OSC接收器：
/setParameter
JUCE的实施正在单独开发中：https://github.com/TYLERSFOSTER/MIDIControl001
______________________________________________________________________
项目概述
该项目提供：
- 一个工作的MCP服务器(
mcp_server.py) - 定义LLM如何交互的工具模式(
schemas.py) - 实现这些工具的Python函数(
tools.py) - 用于与JUCE合成器通信的OSC桥(
juce_bridge.py) - 确保正确性的测试套件(
tests/)
目标是启用以下工作流：
- 语音转文本系统将口头命令转换为文本。
- 文本被馈送到LLM。
- LLM通过调用MCP工具进行响应，例如
setParameter. - MCP服务器接收工具调用并执行相应的Python函数。
- 该函数向JUCE合成器发送OSC消息，实时修改参数。
这种架构允许使用语音或文本对合成器进行富有表现力的自然语言控制。
______________________________________________________________________
目录结构
mcp_synth_controller/
├── pyproject.toml
├── README.md
├── src/
│ └── server/
│ ├── config.py
│ ├── juce_bridge.py
│ ├── mcp_server.py
│ ├── schemas.py
│ └── tools.py
├── tests/
│ ├── test_osc_client_init.py
│ ├── test_list_parameters.py
│ ├── test_set_parameter_message_format.py
│ ├── test_mcp_initialize.py
│ └── test_mcp_tool_call.py
└── examples/
└── test_send_osc.py______________________________________________________________________
依赖管理
此项目使用 紫外线 用于Python依赖管理。\ 要安装依赖项，请执行以下操作：
uv sync要运行MCP服务器，请执行以下操作：
uv run python src/server/mcp_server.py要运行测试套件，请执行以下操作：
uv run pytest______________________________________________________________________
MCP服务器
MCP服务器：
- 处理MCP初始化握手。
- 向LLM宣传可用的工具。
- 接收来自LLM的工具调用。
- 将这些调用分派给正确的Python函数。
- 返回结构化工具结果。
服务器按照MCP协议，使用JSON通过STDIN/STDOUT进行通信。
______________________________________________________________________
工具
每个工具都对应于LLM可用的可调用操作。\ 目前实施的工具：
setParameter(param: str, value: float)
通过OSC设置合成器参数。
getParameter(param: str)
占位符实现（返回一个虚拟值）。\ 稍后可能会添加真正的双向通信。
listParameters()
返回已知参数的列表。\ 稍后可以扩展此功能以动态查询JUCE合成器。
______________________________________________________________________
OSC桥
juce_bridge.py 用途 python-osc 向JUCE发送消息。\ 默认情况下，消息遵循以下格式：
/setParameter
必须实现相应的JUCE OSCReceiver。\ 请参阅下一节。
______________________________________________________________________
JUCE实施要求
为了完成这个系统，JUCE合成器必须：
- 创建一个
OSCReceiver - 绑定到中指定的同一端口
config.py - 为添加侦听器
/setParameter - 解析传入消息并将参数名称映射到实际的JUCE参数
JUCE方面的职责示例：
- 初始化OSCReceiver(
connect(9001)) - 为添加侦听器
/setParameter - 从OSCMessage中提取参数名称和浮点值
- 使用以下方式应用该值
setValueNotifyingHost
JUCE实现属于单独的存储库：
https://github.com/TYLERSFOSTER/MIDIControl001
______________________________________________________________________
OSC测试示例
要手动验证OSC传输：
uv run python examples/test_send_osc.py这将发送：
/setParameter testParam 0.42如果JUCE OSCReceiver处于活动状态，它应该出现在调试输出中。
______________________________________________________________________
测试
该项目包括一个完整的pytest套件，用于验证：
- OSC客户端初始化
- OSC消息格式
- MCP初始化握手
- 工具调用调度逻辑
- 参数列表行为
使用以下工具运行测试：
uv run pytest所有测试都应该通过。
______________________________________________________________________
未来工作
- 与JUCE实现双向OSC或TCP通信
- 从JUCE添加动态参数发现
- 添加斜坡、平滑和调制实用程序
- 与语音转文本管道集成
- 在Claude Desktop或类似软件中提供实时LLM代理控制
______________________________________________________________________
许可证
MIT许可证。