使用说明
Guitar Pro MCP服务器
用于操纵Guitar Pro文件的消息控制协议（MCP）服务器。此服务器提供了一组工具，用于通过标准化界面打开、修改和保存Guitar Pro文件。
备注：目前，只有Guitar Pro 5（.gp5）格式经过测试。对其他格式（.gp3、.gp4）的支持可能有限或未经测试。
特性
- 加载并保存Guitar Pro文件
- 获取歌曲信息（标题、艺术家、曲目等）
- 从曲目中提取音符
- 创作新歌并添加曲目
- 操纵轨迹属性
- 导出为MIDI格式
- 导出/导入JSON格式
需求
- Python 3.10或更高版本
- PyGuitarPro库
- MCP服务器框架
- MIDI支持（mido库）
- uv（建议用于包装管理）
安装
使用紫外线（推荐）
- 如果您还没有安装uv：
pip install uv
- 创建并激活虚拟环境：
# Create virtual environment
uv venv
# Activate virtual environment
# On Unix/macOS:
source .venv/bin/activate
# On Windows(cmd):
call .venv\Scripts\activate.bat
- 安装软件包：
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
来源
- 克隆存储库：
git clone https://github.com/yourusername/guitar-pro-mcp.git
cd guitar-pro-mcp
- 安装软件包：
# Install in development mode with all dependencies
pip install -e ".[dev]"
# Or install without development dependencies
pip install -e .
- 使用MCP客户端连接到服务器。
用法（直接）
- 启动MCP服务器：
python src/run_mcp_server.py
- 使用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：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：重复类型（“正常”、“交替”、“重复_1st”、“再现_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（包含页面设置属性的词典） - 属性包括：页面大小、页面边距、分数大小比例、页眉和页脚、标题、副标题、艺术家、专辑、单词、音乐、单词和音乐、版权、页码
- 返回：成功/错误消息
- 参数：
-
get_page_setup：获取当前歌曲的页面设置- 返回：包含页面设置属性的字典
-
set_advanced_metadata：为当前歌曲设置高级元数据- 参数：
metadata（包含元数据属性的词典） - 属性包括：字幕、单词、音乐、标签、说明、通知
- 返回：成功/错误消息
- 参数：
-
get_advanced_metadata：获取当前歌曲的高级元数据- 返回：包含元数据属性的字典
和弦操作
-
add_chord：为特定节拍添加和弦- 参数：
track_index：轨道索引measure_index：衡量指标beat_index：节拍指数chord_data：包含和弦属性的词典
- 和弦属性包括：名称、根、类型、延伸、低音、调性、第五、第九、第十一、第一Fret、弦乐、小节、指法
- 返回：成功/错误消息
- 参数：
-
get_chord：从特定节拍中获得和弦- 参数：
track_index：轨道索引measure_index：衡量指标beat_index：节拍指数
- 返回：包含和弦属性的字典
- 参数：
克劳德配置（带紫外线运行）：
{
"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"
]
}
}
}
克劳德配置（带紫外线运行）：
{
"mcpServers": {
"guitar-pro-mcp": {
"type": "stdio",
"command": "uv",
"args": [
"--directory",
"<path to folder>",
"run",
"-m",
"src.run_mcp_server"
]
}
}
}
实现细节
该实现使用PyGuitarPro库来解析和操作Guitar Pro文件。MCP服务器提供了一个简单的API来访问PyGuitarPro库的功能。
许可证
该项目根据MIT许可证获得许可。