musicwire-mcp

musicwire-mcp

musicwire-mcp は、Musicwire 向けの Model Context Protocol サーバーです。MCP クライアントに次の 5 つのツールを提供します。

• musicwire_compose_guide - 無料の MusicXML 作成ガイドを取得します。
• musicwire_validate - 詳細な MusicXML 検証を有料で実行します。
• musicwire_render - MusicXML のレンダリングを有料でキューに追加します。
• musicwire_get_job - レンダリングを確認するか、完了までポーリングします。
• musicwire_verify_provenance - 成果物の SHA-256 を署名付きレンダリングレシートと照合する無料チェックです。

Claude Code や Cursor などのローカル MCP クライアントは、このパッケージを stdio 経由で実行します。

npx -y musicwire-mcp

Claude Connectors や Smithery などのホスト型 MCP クライアントは、Musicwire API が提供するパブリックな Streamable HTTP エンドポイントを使用します。

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

このホスト型エンドポイントは同じツールを公開しており、Smithery のセッション設定は不要です（表示される設定スキーマは空のオブジェクトです）。購入者のウォレットは保持しません。musicwire_validate と musicwire_render は、POST /v1/validate および POST /v1/render と同じ x402 の見積もりを含む HTTP 402 Payment Required を返します。Payment-Signature を付けて、同一の MCP リクエストを再試行してください。作成ガイド、ジョブのポーリング、来歴の検証は引き続き無料です。

ホスト型エンドポイントでは、1 回の長時間の wait_for_completion 待機ではなく、短い呼び出しを繰り返して musicwire_get_job をポーリングしてください。ホスト型エンドポイントの前段にあるゲートウェイは、約 29 秒後にリクエストをタイムアウトしますが、レンダリング処理は継続し、引き続きポーリングできます。stdio 経由であれば、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 で stdio サーバーを直接実行するか、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（デフォルト）、またはループバック API 用のテスト専用 stub モードです。

サーバーはキーなしで起動し、無料ツールを提供します。有料の呼び出しが実際に 402 Payment Required を受け取った場合にのみキーが読み込まれます。その時点でキーが設定されていない場合、設定するよう促すエラーが発生し、ツール呼び出しは失敗します。Smithery のホスト型リスティングでは、これらの変数は収集されません。セッションフィールドは宣言せず、各 musicwire_validate / musicwire_render 呼び出しで Payment-Signature を使って支払ってください。

stub モードは、秘密情報を含まないテスト用認証でチャレンジを再試行します。また、MUSICWIRE_API_URL が localhost、127.0.0.1、または ::1 を指していない場合は拒否されます。これは Musicwire の明示的なローカルスタブプロファイル専用です。リモート API では絶対に使用しないでください。ホスト型の /mcp エンドポイントではスタブの自動支払いは有効にならず、サーバー側で購入者キーを保持することもありません。

対象デプロイで告知されているネットワーク上で購入者ウォレットに資金を用意してください。ホスト型デプロイでは Base メインネット上の実際の USDC、ローカル環境では Base Sepolia 上のテスト用 USDC を使用します。このパッケージ自体がネットワークを選択することはないため、サーバーが提示していないネットワークでは支払えません。また、この 2 つ以外のネットワークが告知された場合は拒否します。秘密鍵は秘密情報として扱ってください。クライアントの環境変数を通じて設定し、リポジトリやクライアント設定ファイルには記載しないでください。漏えいした場合はローテーションしてください。

Claude Code

デプロイ済みの API URL に置き換えて、プロジェクトの .mcp.json に以下を追加します。このファイルにコミットするのではなく、Claude Code を起動するシェル環境に秘密鍵を設定してください。

{
  "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 設定ファイルにキーを保存しないでください。

ローカルでの無料開発

Musicwire を本番環境以外で使用する明示的なスタブプロファイルで実行し、スタブモードで 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 を呼び出し元のエージェントに返します。

idempotency_key は、有料の 2 つのツールで利用できます。リクエストを再試行する際は、同じ支払者で同じキーを再利用すると、Musicwire が新たな支払い承認を作成するのではなく、元の結果を再送するようにできます。同じ支払者に対して異なるペイロードで再利用すると、HTTP 409 が返され、請求は発生しません。