Guitar Pro Mcp

Guitar Pro MCP サーバー

Guitar Pro ファイルを操作するための Message Control Protocol (MCP) サーバーです。このサーバーは、標準化されたインターフェースを通じて Guitar Pro ファイルを開く、変更する、保存するためのツール群を提供します。

注意: 現在、テスト済みなのは Guitar Pro 5 (.gp5) 形式のみです。その他の形式 (.gp3、.gp4) のサポートは限定的であるか、未テストの可能性があります。

機能

• Guitar Pro ファイルの読み込みと保存
• 曲の情報 (タイトル、アーティスト、トラックなど) の取得
• トラックからのノートの抽出
• 新しい曲の作成とトラックの追加
• トラックプロパティの操作
• MIDI 形式へのエクスポート
• JSON 形式へのエクスポート/JSON 形式からのインポート

要件

• Python 3.10 以上
• PyGuitarPro ライブラリ
• MCP サーバーフレームワーク
• MIDI サポート (mido ライブラリ)
• uv (パッケージ管理に推奨)

インストール

uv を使用する場合 (推奨)

1. まだインストールしていない場合は uv をインストールします:

pip install uv

2. 仮想環境を作成して有効化します:

# Create virtual environment
uv venv

# Activate virtual environment
# On Unix/macOS:
source .venv/bin/activate
# On Windows(cmd):
call .venv\Scripts\activate.bat

3. パッケージをインストールします:

uv pip install .

サーバーの実行

uv を使用してサーバーを直接実行できます:

uv --directory <project_path> run -m src.run_mcp_server

たとえば Windows では:

uv --directory C:\path\to\guitar_pro_mcp2 run -m src.run_mcp_server

または、インストール後に Python モジュールとして直接実行することもできます:

python -m src.run_mcp_server

pip を使用する場合

pip install guitar-pro-mcp

ソースから

1. リポジトリをクローンします:

git clone https://github.com/yourusername/guitar-pro-mcp.git
cd guitar-pro-mcp

2. パッケージをインストールします:

# Install in development mode with all dependencies
pip install -e ".[dev]"

# Or install without development dependencies
pip install -e .

2. MCP クライアントを使用してサーバーに接続します。

使用方法 (直接実行)

1. MCP サーバーを起動します:

python src/run_mcp_server.py

2. MCP クライアントを使用してサーバーに接続します。

利用可能な MCP ツール

ファイル操作

• load_guitar_pro: Guitar Pro ファイルを読み込みます

  • パラメータ: file_path (.gp5 ファイルへのパス)
  • 戻り値: 成功/エラーメッセージ

• save_guitar_pro: 現在の曲を Guitar Pro ファイルに保存します

  • パラメータ: file_path (ファイルの保存先パス)
  • 戻り値: 成功/エラーメッセージ

曲の情報

• get_song_info: 現在読み込まれている曲の基本情報を取得します

  • 戻り値: タイトル、アーティスト、アルバム、著作権、サブタイトル、注意事項、トラック数を含む辞書

• get_song_statistics: 現在の曲に関する詳細な統計情報を取得します

  • 戻り値: トラック数、小節数、ノート数、および詳細なトラック情報を含む辞書

トラック操作

• get_gp_tracks: 現在の Guitar Pro 曲内のトラック一覧を取得します

  • 戻り値: 名前、インデックス、弦、楽器を含むトラックのリスト

• get_track_notes: 特定のトラックからすべてのノートを取得します

  • パラメータ: track_index (トラックのインデックス)
  • 戻り値: プロパティ (小節、ビート、弦、値など) を含むノートのリスト

• add_gp_track: Guitar Pro 曲に新しいトラックを追加します

  • パラメータ: name (トラックの名前)
  • 戻り値: 成功メッセージとトラックインデックス

• set_track_properties: トラックのプロパティを設定します

  • パラメータ:
    • track_index: トラックのインデックス
    • name: 新しいトラック名 (任意)
    • instrument: 楽器 ID (任意)
    • volume: 音量レベル (任意)
    • pan: パン位置 (任意)
  • 戻り値: 成功/エラーメッセージ

小節操作

• add_gp_measure: Guitar Pro 曲に新しい小節を追加します

  • 戻り値: 成功メッセージと小節インデックス

• set_gp_time_signature: 小節の拍子を設定します

  • パラメータ: measure_index、numerator、denominator
  • 戻り値: 成功/エラーメッセージ

• set_gp_key_signature: 小節の調号を設定します

  • パラメータ: measure_index、key
  • 戻り値: 成功/エラーメッセージ

• set_gp_tempo: 小節のテンポを設定します

  • パラメータ: measure_index、tempo
  • 戻り値: 成功/エラーメッセージ

ノート操作

• add_gp_note: 特定のトラックと小節にノートを追加します
  • パラメータ:
    • track_index: トラックのインデックス
    • measure_index: 小節のインデックス
    • string: 弦番号
    • fret: フレット番号
    • duration: ノートの長さ (デフォルト: 4)
    • voice_index: ボイスインデックス (デフォルト: 0)
    • beat_index: ビートインデックス (デフォルト: 0)
  • 戻り値: 成功/エラーメッセージ

エクスポート/インポート操作

• export_to_midi: 現在の曲を MIDI 形式でエクスポートします

  • パラメータ: file_path
  • 戻り値: 成功/エラーメッセージ

• export_to_json: 現在の曲を JSON 形式でエクスポートします

  • パラメータ: file_path
  • 戻り値: 成功/エラーメッセージ

• import_from_json: JSON 形式から曲をインポートします

  • パラメータ: file_path
  • 戻り値: 成功/エラーメッセージ

タブ操作

• get_track_tab: トラックの ASCII タブ表現を生成します
  • パラメータ: track_index
  • 戻り値: ASCII タブ表現（文字列）

曲構造の管理

• add_repeat_group: 曲にリピートグループを追加します

  • パラメータ:
    • start_measure: 開始小節インデックス
    • end_measure: 終了小節インデックス
    • repeat_type: リピートの種類（"normal"、"alternate"、"repeat_1st"、"repeat_2nd"）
    • repeat_count: リピートする回数（デフォルト: 2）
    • endings: エンディング番号のリスト（オプション）
  • 戻り値: 成功/エラーメッセージ

• get_repeat_groups: 曲内のすべてのリピートグループを取得します

  • 戻り値: プロパティを含むリピートグループオブジェクトのリスト

• add_section: 曲にセクションを追加します

  • パラメータ:
    • start_measure: 開始小節インデックス
    • end_measure: 終了小節インデックス
    • name: セクション名
    • text: オプションのセクションテキスト
    • color: オプションのセクションカラー（RGB タプル）
  • 戻り値: 成功/エラーメッセージ

• get_sections: 曲内のすべてのセクションを取得します

  • 戻り値: プロパティを含むセクションオブジェクトのリスト

• add_coda: 小節にコーダマーカーを追加します

  • パラメータ: measure_index
  • 戻り値: 成功/エラーメッセージ

• add_double_bar: 小節に複縦線を追加します

  • パラメータ: measure_index
  • 戻り値: 成功/エラーメッセージ

• get_song_structure: 曲の完全な構造を取得します

  • 戻り値: 以下を含む辞書:
    • sections: すべてのセクションのリスト
    • repeat_groups: すべてのリピートグループのリスト
    • markers: すべてのマーカー（コーダ、複縦線など）のリスト

メタデータと歌詞

• set_lyrics: 現在の曲の歌詞を設定します

  • パラメータ: lyrics（歌詞を含む文字列）
  • 戻り値: 成功/エラーメッセージ

• get_lyrics: 現在の曲の歌詞を取得します

  • 戻り値: 歌詞（文字列）

• set_page_setup: 現在の曲のページ設定を設定します

  • パラメータ: page_setup（ページ設定プロパティを含む辞書）
  • プロパティには以下が含まれます: pageSize、pageMargin、scoreSizeProportion、headerAndFooter、title、subtitle、artist、album、words、music、wordsAndMusic、copyright、pageNumber
  • 戻り値: 成功/エラーメッセージ

• get_page_setup: 現在の曲のページ設定を取得します

  • 戻り値: ページ設定プロパティを含む辞書

• set_advanced_metadata: 現在の曲の詳細メタデータを設定します

  • パラメータ: metadata（メタデータプロパティを含む辞書）
  • プロパティには以下が含まれます: subtitle、words、music、tab、instructions、notice
  • 戻り値: 成功/エラーメッセージ

• get_advanced_metadata: 現在の曲の詳細メタデータを取得します

  • 戻り値: メタデータプロパティを含む辞書

コード操作

• add_chord: 特定の拍にコードを追加します

  • パラメータ:
    • track_index: トラックのインデックス
    • measure_index: 小節のインデックス
    • beat_index: 拍のインデックス
    • chord_data: コードプロパティを含む辞書
  • コードプロパティには以下が含まれます: name、root、type、extension、bass、tonality、fifth、ninth、eleventh、firstFret、strings、barres、fingerings
  • 戻り値: 成功/エラーメッセージ

• get_chord: 特定の拍からコードを取得します

  • パラメータ:
    • track_index: トラックのインデックス
    • measure_index: 小節のインデックス
    • beat_index: 拍のインデックス
  • 戻り値: コードプロパティを含む辞書

Claude の設定（uv run を使用）:

{
    "mcpServers": {
        "guitar-pro-mcp": {
            "type": "stdio",
            "command": "uv",
            "args": [
                "--directory",
                "<path to folder>",
                "run",
                "-m",
                "src.run_mcp_server"
            ]
        }
    }
}

Claude の設定（直接使用）:

{
    "mcpServers": {
        "guitar-pro-mcp": {
            "type": "stdio",
            "command": "python",
            "args": [
                "<path to folder>\\src\\run_mcp_server.py"
            ]
        }
    }
}

Claude の設定（uv run を使用）:

{
    "mcpServers": {
        "guitar-pro-mcp": {
            "type": "stdio",
            "command": "uv",
            "args": [
                "--directory",
                "<path to folder>",
                "run",
                "-m",
                "src.run_mcp_server"
            ]
        }
    }
}

実装の詳細

実装では、PyGuitarPro ライブラリを使用して Guitar Pro ファイルを解析および操作します。MCP サーバーは、PyGuitarPro ライブラリの機能にアクセスするためのシンプルな API を提供します。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。