musicwire-mcp

musicwire-mcp

musicwire-mcp 是一个面向 Musicwire 的模型上下文协议服务。它为 MCP 客户端提供五种工具：

• musicwire_compose_guide - 获取免费的 MusicXML 创作指南。
• musicwire_validate - 付费进行详细的 MusicXML 验证。
• musicwire_render - 付费将 MusicXML 渲染任务加入队列。
• musicwire_get_job - 检查渲染任务，或轮询直至任务完成。
• musicwire_verify_provenance - 免费检查素材的 SHA-256 是否与已签名的渲染回执相符。

Claude Code 和 Cursor 等本地 MCP 客户端通过标准输入/输出运行此软件包：

npx -y musicwire-mcp

Claude Connectors 和 Smithery 等托管 MCP 客户端使用 Musicwire API 提供的公共 Streamable HTTP 端点：

https://musicwire.5432wire.com/mcp

该托管端点提供相同的工具，无需 Smithery 会话配置（列出的配置架构为空对象）。它不会保存买方钱包。musicwire_validate 和 musicwire_render 会返回 HTTP 402 Payment Required，并提供与 POST /v1/validate 和 POST /v1/render 相同的 x402 报价。使用 Payment-Signature 重试完全相同的 MCP 请求。创作指南、任务轮询和来源验证均免费。

使用托管端点时，请通过多次短调用轮询 musicwire_get_job，而不要使用一次长时间的 wait_for_completion 等待：托管端点前面的网关会在约 29 秒后使请求超时，但渲染任务会继续运行，仍可轮询。通过标准输入/输出时，可以使用较长的 wait_for_completion 等待。

可请求的渲染输出仅包括用于聆听的 MP3 和用于编辑的 MIDI。已完成的渲染还会包含源 MusicXML、NOTICE.txt 和 receipt.json。

付费调用使用 Base 上的 x402 Exact USDC。服务会从已配置的 API 读取 GET /manifest，并在该部署所公布的网络上付款：Base 主网（eip155:8453）或 Base Sepolia（eip155:84532）。遇到 402 Payment Required 响应时，服务会自动附上已签名的付款信息重试，并且绝不会记录或持久化私钥。

安装

此软件包需要 Node.js 22.5 或更高版本。可在 MCP 客户端中通过 npx -y musicwire-mcp 直接运行标准输入/输出服务，或让 Streamable HTTP MCP 客户端连接 https://musicwire.5432wire.com/mcp。

配置

变量	必需	描述
MUSICWIRE_API_URL	否	Musicwire 基础 URL。默认值为 http://127.0.0.1:8787。
MUSICWIRE_X402_PRIVATE_KEY	用于付费 x402 调用	一次性买家私钥，需在目标部署所声明的网络上充值。为兼容性，也接受 X402_PRIVATE_KEY。
MUSICWIRE_MCP_PAYMENT_MODE	否	x402（默认），或仅用于测试的 stub 模式，适用于环回 API。

无需密钥即可启动服务并使用免费工具。只有在付费调用实际收到 402 Payment Required 时才会读取密钥；如果此时缺少密钥，工具调用会失败并提示你设置密钥。Smithery 托管列表不会收集这些变量：不要声明会话字段，然后使用 Payment-Signature 为每次 musicwire_validate / musicwire_render 调用付款。

stub 模式会使用非机密测试授权重试挑战；除非 MUSICWIRE_API_URL 指向 localhost、127.0.0.1 或 ::1，否则会被拒绝。此模式仅适用于 Musicwire 明确提供的本地 stub 配置。切勿用于远程 API。托管的 /mcp 端点不会启用 stub 自动付款，也不会持有服务端买家密钥。

请在目标部署所声明的网络上为买家钱包充值：托管部署使用 Base 主网上的真实 USDC，本地部署使用 Base Sepolia 上的测试 USDC。此软件包不会自行选择网络，因此无法在服务器未报价的网络上付款，并且会拒绝任何其他声明的网络。请将私钥视为机密：通过客户端环境注入，不要将其放入代码仓库或客户端配置文件中；如果密钥泄露，请立即轮换。

Claude Code

将以下内容添加到项目的 .mcp.json，并替换为已部署的 API URL。请将私钥保存在启动 Claude Code 的 shell 环境中，不要将其提交到此文件。

{
  "mcpServers": {
    "musicwire": {
      "command": "npx",
      "args": ["-y", "musicwire-mcp"],
      "env": {
        "MUSICWIRE_API_URL": "https://musicwire.example"
      }
    }
  }
}

启动 Claude Code 前，请导出一个已在部署所声明网络上充值的买家密钥：

export MUSICWIRE_X402_PRIVATE_KEY='0x...'
claude

Cursor

将相同的服务条目添加到 Cursor 的 MCP 配置（项目配置使用 .cursor/mcp.json，也可以使用对应的全局 MCP 配置）：

{
  "mcpServers": {
    "musicwire": {
      "command": "npx",
      "args": ["-y", "musicwire-mcp"],
      "env": {
        "MUSICWIRE_API_URL": "https://musicwire.example"
      }
    }
  }
}

从已导出 MUSICWIRE_X402_PRIVATE_KEY 的环境中启动 Cursor；不要将密钥存储在 JSON 配置中。

本地零成本开发

使用明确的非生产 stub 配置运行 Musicwire，然后以 stub 模式启动 MCP 服务：

ARTIFACT_SIGNING_SECRET='replace-with-a-long-random-secret' docker compose up

MUSICWIRE_API_URL='http://127.0.0.1:8787' \
MUSICWIRE_MCP_PAYMENT_MODE=stub \
npx -y musicwire-mcp

代码仓库中的 test/mcp-e2e.test.js 会使用真实的 stdio MCP 会话测试此付款行为，并覆盖每个工具。它不会创建钱包、使用凭据或发送资金。

付款行为

对于 musicwire_validate 和 musicwire_render，该包会先发送原始请求。如果 Musicwire 返回 402，它会从 GET /manifest 读取公告的支付网络，然后由 x402 客户端读取支付要求，使用已配置的买方钱包在该网络上签署 Exact EVM 授权，并通过 Payment-Signature 重复发送完全相同的请求。Musicwire 会在执行任务前验证授权，并仅在质量控制通过后扣款。作业轮询、编曲指南和来源验证均免费。托管的 Streamable HTTP 端点会将该 402 返回给调用方 Agent，而不会代为付款。

这两个付费工具均支持 idempotency_key。重试请求时，请使用同一个付款方和相同的键，以确保 Musicwire 重放原始结果，而不是创建另一笔支付授权。对于同一付款方，使用该键重试不同的载荷会返回 HTTP 409，且不会扣款。