Mm2024 MCP

MediaMonkey 2024 MCP

基于Python的模型上下文协议（MCP）服务器，通过官方COM自动化界面代理MediaMonkey 2024/MediaMonkey 5。MCP工具公开了播放控制、音量/寻道管理、队列检查以及围绕 runJSCode MediaMonkey文档中描述的桥。

该软件包发布于 PyPI，因此您可以使用以下命令在系统范围内安装它 pip install mm2024-mcp 或者直接在当地收银台工作。

参考文献

• 从外部应用程序控制MM5
• SDB应用程序自动化参考
• SDBPlayer/SDBSongData对象模型
• ISDBUI:：菜单简编（菜单范围）
• SDBIniFile参考（配置设置）

需求

• 安装了MediaMonkey 5+/2024的Windows主机。
• Python 3.11+（MCP SDK需要3.10+，我们的目标是3.11）。
• pywin32 （通过自动安装 pyproject.toml).
• modelcontextprotocol Python SDK 1.0.1+。

注： 当COM启动时，MediaMonkey会自动启动 SongsDB5.SDBApplication 对象已创建。MCP服务器保持 ShutdownAfterDisconnect = False 因此，当服务器退出时，MediaMonkey不会强制关闭。

安装

从PyPI安装

pip install mm2024-mcp

这将安装 mm2024-mcp 控制台入口点加上MCP工具，这样任何兼容的主机都可以在不克隆存储库的情况下启动服务器。

本地可编辑安装

uv venv
uv pip install -e .

如果你不使用 uv，替换为 python -m venv 和 pip install -e ..

运行MCP服务器

uv run mm2024-mcp

或者直接执行：

python -m mm2024_mcp.server

服务器通过stdio与MCP通信。配置您的MCP主机（Claude for Desktop、VS Code MCP客户端等）以启动 mm2024-mcp 控制台命令或 python -m mm2024_mcp.server 在这个存储库中。

使用VS Code作为MCP主机

Visual Studio Code 1.102+与GitHub Copilot原生支持MCP服务器（请参阅 VS代码“使用MCP服务器”指南).此存储库包括一个即用型工作区配置，位于 .vscode/mcp.json.

1. 安装最新的VS代码并登录到Copilot。
2. 启用MCP库(chat.mcp.gallery.enabled)或打开命令面板并运行 MCP：打开工作区文件夹配置.
3. 检查 .vscode/mcp.json，如果您的存储库位于其他位置，请更新路径 ${workspaceFolder}，并进行调整 env 条目（例如，覆盖 MM2024_COM_PROGID).
4. 打开聊天视图（Ctrl+Alt+I），选择 mm2024 在工具选择器中选择服务器，并在VS Code首次启动服务器时批准信任提示。
5. 在开发MediaMonkey插件时，直接从聊天中调用MCP工具（例如， #get_playback_state, #list_now_playing，或 #run_javascript)在不离开编辑器的情况下验证COM行为。

工作空间配置使用 scripts/mm2024-mcp.ps1，哪个更喜欢 uv run mm2024-mcp 但回落到 python -m mm2024_mcp.server 如果 uv 不在PATH上。

提示：

• VS代码缓存工具元数据。使用 MCP：重置缓存工具 在中添加新MCP工具后的命令 server.py.
• 启用 MCP：重置信任 如果您更改了服务器命令，而VS Code拒绝重新启动它。
• 开发模式已在中配置 .vscode/mcp.json 所以编辑 src/**/*.py 自动重启VS Code启动的MCP服务器。

可用工具

所有工具结果都使用下定义的Pydantic模型进行序列化 src/mm2024_mcp/models.py.

菜单自动化

invoke_menu_item 使用中列出的菜单范围 ISDBUI:：菜单简编.提供作用域名称（例如 Menu_Tools)以及在该范围内要遍历的标题列表(["Options..."]).通过删除与号符号和尾随椭圆来规范字幕，您可以通过以下方式放宽匹配 match_strategy="startswith" 或 match_strategy="contains"一些菜单树是按需生成的；如果路径失败，请在MediaMonkey中打开一次目标菜单进行预热，然后再次调用该工具。经过 allow_disabled=True 对于诊断场景很有用，但要小心——MediaMonkey仍然可能阻止UI中禁用的项目的执行。

配置助手

set_config_value 包裹 SDB.IniFile （见 SDBIniFile参考)所以你可以修改 MediaMonkey.ini 远程。选择一个 value_type (string, int，或 bool)，提供新值，并可选择 persist_mode="flush" 或 persist_mode="apply" 强制MediaMonkey立即写入或重新加载ini文件。该工具尽可能返回之前的值，以便您确认更改已被接受。某些设置只有在重新启动MediaMonkey后才能生效——有关每个设置的注意事项，请参阅MediaMonkey维基。

插件开发工作流程

1. 正常启动MediaMonkey 2024，使其COM自动化层预热。
2. 在VS Code中打开此存储库，启用捆绑 mm2024 MCP服务器（聊天→ 工具→ 服务器），并将MCP聊天面板停靠在您的附加源文件旁边。
3. 编辑MediaMonkey插件时，使用聊天提示，如 Run list_now_playing to confirm the testing playlist 或 Call run_javascript with the playlist enumerator snippet 实时验证行为。
4. 在内部迭代COM更改后 media_monkey_client.py，跑 uv run mm2024-mcp 如果您需要在VS Code的代理视图之外进行调试，请在终端中执行。

包装和发布

本地建筑

1. 安装打包工具（这使用可选工具 dev 额外定义于 pyproject.toml):

   uv pip install -e .[dev]

1. 构建源分发和轮：

   python -m build --sdist --wheel

1. 上传前验证元数据：

   python -m twine check dist/*

1. 发布到PyPI（需要在PyPI帐户中创建API令牌）：

   $env:TWINE_USERNAME = "__token__"
   $env:TWINE_PASSWORD = "pypi-xxxxxxxxxxxxxxxx"
   python -m twine upload dist/*

工件被发射到 dist/ （已被忽略 .gitignore).如果要彻底重建，请在两个版本之间删除该文件夹。

GitHub操作工作流

• .github/workflows/publish.yml 在手动调度上运行，带注释的标签推送与语义匹配 vMAJOR.MINOR.PATCH 标签，以及 release GitHub发布时的事件。
• 工作流构建轮子和sdist，运行 twine check，上传 dist/ 内容作为工作流工件，并可选择通过以下方式推送到PyPI pypa/gh-action-pypi-publish.
• PyPI发布使用 可信发布者 因此，GitHub Actions直接与PyPI交换OIDC令牌，不需要PAT密钥。
• 典型的发布流程：插入版本 pyproject.toml，标记提交(git tag v0.2.0 && git push origin v0.2.0)，然后观看工作流完成。仅语义标签(vMAJOR.MINOR.PATCH)触发自动PyPI上传，因此通过以下方式重新运行工作流 行动→ 构建和发布→ 运行工作流 如果你需要工件而不需要推送新标签。

故障排除

• 如果MCP主机报告 pywin32 is not available，确保您在Windows Python环境中安装依赖项。
• 如果无法创建COM自动化对象，请确认已安装MediaMonkey，并且 SongsDB5.SDBApplication ProgID存在。通过以下方式覆盖 MM2024_COM_PROGID 如果需要的话。
• run_javascript 将有效载荷包裹起来 runJSCode_callback 返回JSON。对于自行管理回调的原始脚本，请传递 expect_callback=False 以避免双重包装。