Simple Osc Mcp Server

シンプルな OSC MCP サーバー

AI エージェントが OSC（Open Sound Control）エンドポイントを作成し、OSC メッセージを受信できるようにする Model Context Protocol（MCP）サーバーです。このサーバーは、AI エージェントと SuperCollider、Max/MSP、TouchOSC などの OSC 対応アプリケーションや、その他の音楽・オーディオソフトウェアをつなぐブリッジを提供します。

機能

• OSC エンドポイント管理：OSC メッセージを受信するための複数の UDP エンドポイントを作成・管理します
• メッセージバッファリング：設定可能なバッファサイズで、受信した OSC メッセージを保存・検索します
• パターンフィルタリング：OSC アドレスパターンでメッセージをフィルタリングし、対象を絞ったデータ収集を行います
• VSCode との統合：VSCode の MCP クライアントと完全に互換性があり、スムーズな開発ワークフローを実現します
• リアルタイム監視：エンドポイントの状態とメッセージの流れをリアルタイムで追跡します
• 型安全性：TypeScript で構築されており、堅牢な型チェックと優れた開発者エクスペリエンスを実現します

インストール

npx ですぐに利用（推奨）

npx osc-mcp-server

グローバルインストール

npm install -g osc-mcp-server
osc-mcp-server

ローカルインストール

npm install osc-mcp-server
npx osc-mcp-server

要件

• Node.js：18.0.0 以降
• オペレーティングシステム：Windows、macOS、Linux
• ネットワーク：OSC 通信には UDP ポートへのアクセスが必要です（ポート 1024-65535）

使い方

VSCode との統合

OSC MCP Server は VSCode の MCP クライアントとスムーズに連携するように設計されています。次の手順で設定します。

1. MCP 拡張機能をインストールします（まだインストールされていない場合）

2. VSCode の設定またはワークスペースの .vscode/settings.json に、サーバー設定を追加します。

{
  "mcp.servers": {
    "osc-server": {
      "command": "npx",
      "args": ["osc-mcp-server"],
      "env": {}
    }
  }
}

3. サーバーを読み込むために、VSCode を再起動します

4. VSCode の MCP パネルで接続を確認します。「osc-server」がアクティブとして表示されます

利用可能なツール

このサーバーは、OSC とのやり取りに使用できる 4 つの主要なツールを提供します。

1. create_osc_endpoint

受信メッセージを待ち受ける新しい OSC エンドポイントを作成します。

パラメーター：

• port（必須）：UDP ポート番号（1024-65535）
• bufferSize（任意）：保存するメッセージの最大数（デフォルト：1000、最大：10000）
• addressFilters（任意）：メッセージをフィルタリングする OSC アドレスパターンの配列

例：

{
  "port": 8000,
  "bufferSize": 500,
  "addressFilters": ["/synth/*", "/effects/reverb"]
}

2. stop_osc_endpoint

既存の OSC エンドポイントを停止し、削除します。

パラメーター：

• endpointId（必須）：停止するエンドポイントの ID

例：

{
  "endpointId": "endpoint_8000_1234567890"
}

3. get_osc_messages

エンドポイントから受信した OSC メッセージを検索します。

パラメーター：

• endpointId（任意）：特定のエンドポイント ID（省略した場合は、すべてのエンドポイントを検索します）
• addressPattern（任意）：メッセージをフィルタリングする OSC アドレスパターン
• timeWindowSeconds（任意）：秒単位の時間範囲（現在から過去にさかのぼります）
• limit（任意）：返すメッセージの最大数（最大：1000）

例：

{
  "endpointId": "endpoint_8000_1234567890",
  "addressPattern": "/synth/freq",
  "timeWindowSeconds": 30,
  "limit": 50
}

4. get_endpoint_status

OSC エンドポイントの状態情報を取得します。

パラメーター：

• endpointId（任意）：特定のエンドポイント ID（省略した場合は、すべてのエンドポイントを返します）

例：

{
  "endpointId": "endpoint_8000_1234567890"
}

コマンドラインでの使い方

サーバーを直接実行すると、MCP 通信のために stdio モードで起動します。

# Start the server
npx osc-mcp-server

# The server will output startup information to stderr
# and handle MCP communication via stdin/stdout

使用例のワークフロー

OSC MCP Server を使用する一般的なワークフローは次のとおりです。

1. OSC メッセージを待ち受けるエンドポイントを作成します。

   {
     "tool": "create_osc_endpoint",
     "parameters": {
       "port": 8000,
       "bufferSize": 1000,
       "addressFilters": ["/synth/*"]
     }
   }
   

2. アプリケーション（SuperCollider、Max/MSP など）から localhost:8000 に OSC メッセージを送信します

3. 受信したメッセージを検索します。

   {
     "tool": "get_osc_messages",
     "parameters": {
       "timeWindowSeconds": 60,
       "limit": 100
     }
   }
   

4. エンドポイントの状態を確認します。

   {
     "tool": "get_endpoint_status",
     "parameters": {}
   }
   

5. 作業が終わったら、エンドポイントを停止します。

   {
     "tool": "stop_osc_endpoint",
     "parameters": {
       "endpointId": "endpoint_8000_1234567890"
     }
   }
   

開発

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

トラブルシューティング

よくある問題

サーバー接続の問題

問題：VSCode で「osc-server」が切断状態になっている、または一覧に表示されない

• 解決方法：Node.js 18 以降がインストールされ、利用可能であることを確認してください
• 解決方法：VSCode の設定で MCP の構成を確認してください
• 解決方法：構成を変更した後、VSCode を再起動してください
• 解決方法：VSCode の出力パネルで MCP 関連のエラーメッセージを確認してください

問題：npx の使用時に「Command not found」エラーが発生する

• 解決方法：npm がインストールされ、最新の状態であることを確認してください：npm install -g npm@latest
• 解決方法：npm のキャッシュをクリアしてください：npm cache clean --force
• 解決方法：まずグローバルにインストールしてみてください：npm install -g osc-mcp-server

OSC エンドポイントの問題

問題：「Port already in use」エラーが発生する

• 解決方法：別のポート番号（1024〜65535）を選択してください
• 解決方法：ポートを使用しているプロセスを確認してください：netstat -an | grep :8000（8000 を使用するポートに置き換えてください）
• 解決方法：同じポートを使用しているほかのアプリケーションを停止してください

問題：ポート番号が小さい場合に「Permission denied」エラーが発生する

• 解決方法：1024 以上のポートを使用してください（1024 未満のポートには管理者権限が必要です）
• 解決方法：Linux/macOS では、絶対に必要な場合に限り sudo で実行してください

問題：OSC メッセージが受信されない

• 解決方法：送信元のアプリケーションが、正しい IP とポートに送信するよう構成されていることを確認してください
• 解決方法：ファイアウォールの設定を確認し、指定したポートで UDP トラフィックが許可されていることを確認してください
• 解決方法：TouchOSC や SuperCollider などのシンプルな OSC 送信ツールでテストしてください
• 解決方法：アドレスフィルターの条件が厳しすぎないことを確認してください

メッセージクエリの問題

問題：メッセージが存在するはずなのに、結果が空になる

• 解決方法：時間範囲を確認してください。メッセージが指定した timeWindowSeconds より古い可能性があります
• 解決方法：アドレスパターンの一致を確認してください。OSC パターンでは大文字と小文字が区別されます
• 解決方法：エンドポイントのバッファーサイズを超えていないか確認してください（古いメッセージは削除されます）

問題：「Endpoint not found」エラーが発生する

• 解決方法：get_endpoint_status を使用して、利用可能なエンドポイント ID を一覧表示してください
• 解決方法：エンドポイントが停止していない、またはクラッシュしていないことを確認してください
• 解決方法：エンドポイント ID に誤字がないか確認してください

パフォーマンスに関する考慮事項

高頻度のメッセージ

1 秒あたりに多数の OSC メッセージを受信する場合：

• メッセージの損失を防ぐため、バッファーサイズを増やしてください：「bufferSize": 5000」
• 処理のオーバーヘッドを軽減するため、アドレスフィルターを使用してください
• バッファーのオーバーフローを防ぐため、メッセージをより頻繁にクエリしてください
• メッセージの種類ごとに複数のエンドポイントを使用することを検討してください

メモリ使用量

• バッファーサイズを監視してください。バッファーが大きいほど、使用するメモリも増えます
• 大きな応答を避けるため、メッセージクエリに適切な上限を設定してください
• リソースを解放するため、使用していないエンドポイントを停止してください

ネットワーク構成

ファイアウォールの設定

Windows：

# Allow UDP traffic on port 8000 (replace with your port)
netsh advfirewall firewall add rule name="OSC MCP Server" dir=in action=allow protocol=UDP localport=8000

macOS：

# Check if firewall is blocking the port
sudo pfctl -sr | grep 8000

Linux（Ubuntu/Debian）：

# Allow UDP traffic on port 8000
sudo ufw allow 8000/udp

OSC 通信のテスト

以下のツールを使用して、OSC メッセージの送信をテストしてください：

SuperCollider：

// Send a test message
n = NetAddr("127.0.0.1", 8000);
n.sendMsg("/test", 440, "hello");

Max/MSP：

[udpsend 127.0.0.1 8000]
|
[/test 440 hello(

Python（python-osc）：

from pythonosc import udp_client

client = udp_client.SimpleUDPClient("127.0.0.1", 8000)
client.send_message("/test", [440, "hello"])

デバッグモード

詳細なログを確認するには、サーバーの実行時に stderr の出力を確認してください：

npx osc-mcp-server 2> debug.log

これにより、分析用にすべてのデバッグメッセージがファイルに記録されます。

ヘルプの利用

ここに記載されていない問題が発生した場合：

1. GitHub Issues を確認してください：https://github.com/username/osc-mcp-server/issues
2. 以下の情報を添えて新しい issue を作成してください：
   • 使用しているオペレーティングシステムと Node.js のバージョン
   • エラーメッセージの全文
   • 問題を再現する手順
   • MCP の構成

ドキュメント

API リファレンス

• API リファレンス全文 - すべての MCP ツールとそのパラメーターに関する詳細なドキュメント

例とワークフロー

• 例の概要 - 利用可能なすべての例と設定
• VSCode の設定 - VSCode MCP クライアントのセットアップ例
• OSC 送信元 - さまざまなプラットフォーム向けの OSC メッセージ送信元のテスト
• ワークフローの例 - 手順ごとの使用ワークフロー

個別のワークフロー

• 基本的なワークフロー - 単一のエンドポイントを使った開始方法
• 複数エンドポイントのワークフロー - 複数の OSC ソースの管理

開発

• CI/CD ドキュメント - 継続的インテグレーションとデプロイの詳細

CI/CD パイプライン

このプロジェクトでは、継続的インテグレーションとデプロイに GitHub Actions を使用しています。

• 自動テスト：Node.js 18、20、22 で実行
• コード品質：ESLint、Prettier、TypeScript のチェック
• セキュリティスキャン：npm audit と脆弱性スキャン
• カバレッジレポート：80% のカバレッジしきい値が必須
• 自動公開：タグ付きリリース時に npm に公開

リリースプロセス

git タグをプッシュして新しいリリースを作成します。

git tag v1.0.0
git push origin v1.0.0

または、PowerShell のリリーススクリプトを使用します。

.\scripts\release.ps1 patch  # or minor, major, prerelease

CI/CD の詳細なドキュメントについては、docs/CI-CD.md を参照してください。

ライセンス

MIT