Pure Data MCP Server

Pure Data MCP サーバー

このプロジェクトは、Model Context Protocol（MCP）を通じてClaude AIとPure Dataを連携させます。この連携により、Claudeは自然言語を使ってPure Dataのパッチを動的に作成、変更、制御できます。

概要

このシステムは、次の3つの主要コンポーネントで構成されています。

1. MCP サーバー（mcp_server.py）：Claude向けのModel Context Protocolインターフェースを実装します
2. OSCデーモン（osc_daemon.py）：Pure DataとのOSC通信を処理します
3. Pure Dataパッチ（example_patch.pd）：OSCメッセージを受信する動的なパッチングソリューションです

機能

• 動的なオブジェクト作成：Claudeを通じて、必要に応じて任意のPure Dataオブジェクトを作成します
• 接続管理：オブジェクト同士を接続し、複雑な信号フローを構築します
• ワークスペース管理：clear_workspaceですべてのオブジェクトを消去し、状態をリセットします
• DSP制御：オーディオ処理をリモートで開始・停止します
• パラメーター制御：オブジェクトのパラメーターをリアルタイムで変更します
• グローバルオブジェクト追跡：インデックスベースの信頼性の高い接続システムです
• エラー処理：堅牢なエラー検出と報告機能を備えています
• デバッグツール：包括的なログシステムを備えています

最近の更新

インストール

前提条件

• Python 3.7+
• Pure Data（vanilla）0.51+
• 必要なPythonパッケージ：
  • python-osc
  • fastmcp
  • jsonschema
• uvパッケージマネージャー

uvのインストール

macOSおよびLinuxの場合：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows（PowerShell）の場合：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

詳細はこちら：astral-sh/uv

---

🛠️ 使用方法

リポジトリのクローン

git clone https://github.com/nikmaniatis/Pd-MCP-Server.git

Claude Desktopとの連携

1. 次を開きます：

Claude > Settings > Developer > Edit Config > claude_desktop_config.json

2. 次のブロックを追加します：

{
    "mcpServers": {
      "Pure Data MCP Server": {
        "command": "uv",
        "args": [
          "--directory",
          "PATH_TO_PD_MCP_SERVER",
          "run",
          "main.py"
        ],
        "env": {
          "PD_OSC_HOST": "127.0.0.1",
          "PD_OSC_PORT": "5000",
          "PD_FEEDBACK_PORT": "5001"
        }
      }
    }
  }

注： uvコマンドが見つからない場合は、which uv（Unix）またはGet-Command uv（PowerShell）を実行し、"command"フィールドにフルパスを指定してください。

---

簡単な例

MCPサーバーが接続され、Pdパッチが待ち受けている状態で、自然言語を使ってClaudeにパッチの作成を依頼できます。

「440 Hzのoscを作成し、dacに接続して、DSPを開始してください。」

ClaudeはMCPツールを呼び出し、次のような処理を行います。

create_object("osc~", ["440"], {"x": 100, "y": 50})   → index 0
create_object("*~",   ["0.25"], {"x": 100, "y": 110})  → index 1
create_object("dac~", [],       {"x": 100, "y": 170})  → index 2

connect_objects({"id": "osc~_100_50",  "port": 0}, {"id": "*~_100_110",  "port": 0})
connect_objects({"id": "*~_100_110",   "port": 0}, {"id": "dac~_100_170", "port": 0})
connect_objects({"id": "*~_100_110",   "port": 0}, {"id": "dac~_100_170", "port": 1})

start_dsp()

これにより、ワークスペースのサブパッチに次のパッチが作成されます。

  osc~ 440
     |
  *~ 0.25 (volume)
    / \
  dac~ L+R

その後、会話を通じてClaudeにパッチの変更、エフェクトの追加、周波数の変更、またはより複雑な信号チェーンの構築を依頼できます。

アーキテクチャ

メッセージフロー

1. Claudeがユーザーのリクエストに基づいてMCPツールを実行します
2. MCPサーバーがツール呼び出しを処理します
3. OSCメッセージが整形され、Pure Dataに送信されます
4. Pure Dataが動的パッチを介してコマンドを実行します
5. フィードバック（ある場合）はOSCコールバックを介して返されます

トラブルシューティング

よくある問題

1. オブジェクトの作成に失敗する：Pure Dataが起動しており、パッチが開いていることを確認してください
2. 接続の問題：オブジェクトIDがcreate_objectから返された値と完全に一致していることを確認してください
3. ポートの競合：ポート5000がすでに使用されていないか確認してください
4. メッセージ形式のエラー：メッセージ形式がPure Dataパッチで想定されている形式と一致していることを確認してください
5. オブジェクトが見つからない：オブジェクト追跡が正しく機能しなくなった場合は、MCPサーバーとPure Dataの両方を再起動してみてください

既知の制限事項

• 削除または切断はサポートされていません：Pdパッチ（example_patch.pd）が処理するのは/pd/create、/pd/connect、/pd/dsp、/pd/clearのみです。オブジェクトや接続を個別に削除することはできません。代わりにclear_workspaceを使ってワークスペース全体をリセットしてください。
• 引数がゼロ個のシグナルオブジェクト：動的パッチングで+~や*~などのシグナルオブジェクトを0引数付きで作成すると（例：obj 100 100 +~ 0）、Pd 0.55+では2つ目のインレットがシグナルインレットではなくフロートインレットとして扱われ、シグナル接続が機能しなくなります。この問題を避けるため、MCPサーバーはシグナルオブジェクトの末尾にあるゼロ引数を自動的に削除します。

ライセンス

このプロジェクトはMIT Licenseのもとでライセンスされています。詳細はLICENSEファイルをご覧ください。

謝辞

• Pure Data - オープンソースのビジュアルプログラミング言語
• Model Context Protocol - AI ツールを可能にするプロトコル
• Python-OSC - OSC の Python 実装