Music21 MCP Server

Music21分析-多接口音乐服务器

     

具有4种不同界面的专业音乐分析 -MCP服务器、HTTP API、CLI工具和Python库。基于功能强大的music21库，具有独立于协议的架构，可实现最大的可靠性。

🎯 为什么有多个接口？

根据2025年的研究显示 MCP的生产成功率为40-50%，该项目提供 多种途径 同样强大的music21分析功能：

• 📡 MCP 服务器 -用于AI助手集成（Claude、Gemini、Codex、Qwen）
• 🌐 HTTP API -用于web应用程序（可靠备份）
• 💻 CLI工具 -自动化（始终有效）
• 🐍 Python库 -用于直接编程访问

🎵 核心音乐分析功能

分析工具（13个可用）

• 进出口：MusicXML、MIDI、ABC、Lilypond、music21语料库
• 关键分析：多种算法（Krumhansl、Aarden、Bellman Budge）
• 和谐分析：罗马数字、和弦进行、节奏检测
• 语音引导：并行运动检测、语音交叉分析
• 模式识别：旋律、节奏和和声模式

高性能

• 协调巴赫合唱与爵士风格的和谐
• 对位：物种对位世代（1-5）
• 风格模仿：学习和创作作曲家风格的音乐
• 分数操纵：换位、时间拉伸、编排

🚀 快速开始

安装

从PyPI安装（推荐）

# Install the package
pip install music21-mcp-server

# Start the server
music21-mcp-server --mode mcp   # For Claude Desktop
music21-mcp-server --mode http  # REST API at localhost:8000
music21-mcp-server --mode cli   # Interactive CLI

从源代码安装

# Clone repository
git clone https://github.com/brightlikethelight/music21-mcp-server.git
cd music21-mcp-server

# Install with UV (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# Or with pip
pip install -r requirements.txt

# Configure music21 corpus
python -m music21.configure

用法-选择您的界面

🎯 显示所有可用界面

python -m music21_mcp.launcher

📡 MCP服务器（用于AI助手）

适用于 克劳德、双子座、Codex和Qwen。参见 MCP安装指南 详细设置。

# Start MCP server
python -m music21_mcp.launcher mcp

每个平台的快速设置：

Claude Code / Claude Desktop

添加 .mcp.json 在项目根目录中（或使用 claude mcp add):

{
  "mcpServers": {
    "music21": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/music21-mcp-server", "python", "-m", "music21_mcp.server_minimal"]
    }
  }
}

或者通过CLI：

claude mcp add music21 -- uv run --directory /path/to/music21-mcp-server python -m music21_mcp.server_minimal

Gemini CLI

添加 .gemini/settings.json:

{
  "mcpServers": {
    "music21": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/music21-mcp-server", "python", "-m", "music21_mcp.server_gemini"]
    }
  }
}

用途 server_gemini 通过延迟初始化实现更快的工具发现。

OpenAI Codex CLI

添加 ~/.codex/config.toml:

[mcp_servers.music21]
command = "uv"
args = ["run", "--directory", "/path/to/music21-mcp-server", "python", "-m", "music21_mcp.server_minimal"]

或者通过CLI：

codex mcp add music21 -- uv run --directory /path/to/music21-mcp-server python -m music21_mcp.server_minimal

Qwen Code

添加 .qwen/settings.json:

{
  "mcpServers": {
    "music21": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/music21-mcp-server", "python", "-m", "music21_mcp.server_gemini"]
    }
  }
}

用途 server_gemini （惰性初始化格式与Gemini CLI相同）。

🌐 HTTP API服务器（用于web应用程序）

# Start HTTP API server
python -m music21_mcp.launcher http
# Opens: http://localhost:8000
# API docs: http://localhost:8000/docs

# Example usage:
curl -X POST "http://localhost:8000/scores/import" \
  -H "Content-Type: application/json" \
  -d '{"score_id": "chorale", "source": "bach/bwv66.6", "source_type": "corpus"}'

curl -X POST "http://localhost:8000/analysis/key" \
  -H "Content-Type: application/json" \
  -d '{"score_id": "chorale"}'

💻 CLI工具（用于自动化）

# Show CLI status
python -m music21_mcp.launcher cli status

# Import and analyze a Bach chorale
python -m music21_mcp.launcher cli import chorale bach/bwv66.6 corpus
python -m music21_mcp.launcher cli key-analysis chorale
python -m music21_mcp.launcher cli harmony chorale roman

# List all tools
python -m music21_mcp.launcher cli tools

🐍 Python库（用于编程）

from music21_mcp.adapters import create_sync_analyzer

# Create analyzer
analyzer = create_sync_analyzer()

# Import and analyze
analyzer.import_score("chorale", "bach/bwv66.6", "corpus")
key_result = analyzer.analyze_key("chorale")
harmony_result = analyzer.analyze_harmony("chorale", "roman")

print(f"Key: {key_result}")
print(f"Harmony: {harmony_result}")

# Quick comprehensive analysis
analysis = analyzer.quick_analysis("chorale")

🧪 测试与开发

运行测试

# Reality-based test suite (95% core, 5% adapter)
python tests/run_reality_tests.py

# Core music21 tests (must pass)
python -m pytest tests/core/ -v

# MCP adapter tests (may fail - that's expected)
python -m pytest tests/adapters/ -v

开发设置

# Install development dependencies
uv sync --dev

# Set up pre-commit hooks
pre-commit install

# Run linting
ruff check src/
ruff format src/

# Type checking
mypy src/

🏗️ 建筑

独立于协议的设计

Core Value Layer:
├── services.py              # Music21 analysis service (protocol-independent)
└── tools/                   # 13 music analysis tools

Protocol Adapter Layer:
├── adapters/mcp_adapter.py   # MCP protocol isolation
├── adapters/http_adapter.py  # HTTP/REST API
├── adapters/cli_adapter.py   # Command-line interface  
└── adapters/python_adapter.py # Direct Python access

Unified Entry Point:
└── launcher.py              # Single entry point for all interfaces

设计理念

• 核心价值第一：Music21分析与协议问题无关
• 方案启示生存：即使MCP发生故障，也能正常工作（30-40%的时间）
• 多个逃生舱：始终有一个工作界面
• 基于现实：专为当今的MCP生态系统而设计，而非企业梦想

📊 接口可靠性

📚 文档

• docs/architecture.md -系统架构概述
• docs/getting-started.md -快速入门指南
• 示例/ -工作代码示例
• API文件: http://localhost:8000/docs（HTTP服务器运行时）

Discord Webhook集成

• **** -完整的Discord webhook设置指南
• docs/webhook-integration.md -高级webhook配置
• scripts/test-webhook.sh -测试webhook连接
• 脚本/setup-webhook.sh -自动webhook设置

🔧 配置

环境变量

# Optional configuration
export MUSIC21_MCP_LOG_LEVEL=INFO
export MUSIC21_MCP_CACHE_SIZE=100
export MUSIC21_MCP_TIMEOUT=30

Music21设置

# Configure corpus path (one-time setup)
python -m music21.configure

🛠️ 可用的分析工具

1. import_score -从语料库、文件、URL导入
2. list_score -列出所有导入的分数
3. get_score_info -详细的分数信息
4. export_score -导出到MIDI、MusicXML等。
5. delete_score -从存储中删除分数
6. 分析密钥 -密钥签名分析
7. 分析时钟 -和弦进程分析
8. 分析和谐 -罗马数字/函数和谐
9. 分析语音阅读 -语音领先质量分析
10. 识别模式 -旋律/节奏模式
11. 和声音乐 -自动协调
12. 发电机对位 -计数器点生成
13. 模仿风格 -风格模仿与生成

🚀 快速示例

分析巴赫合唱

# CLI approach
python -m music21_mcp.launcher cli import chorale bach/bwv66.6 corpus
python -m music21_mcp.launcher cli key-analysis chorale

# Python approach  
analyzer = create_sync_analyzer()
analyzer.import_score("chorale", "bach/bwv66.6", "corpus")
print(analyzer.analyze_key("chorale"))

启动服务

# For Claude Desktop
python -m music21_mcp.launcher mcp

# For web development
python -m music21_mcp.launcher http

# For command-line work
python -m music21_mcp.launcher cli status

🔄 从v1.0迁移

以前的企业版本是 简化以提高可靠性:

• ✅ 保留：所有music21分析功能
• ✅ 添加：HTTP API、CLI、Python库接口
• ❌ 移除：Docker、K8s、复杂的身份验证、监控（对MCP生态系统来说太不稳定）
• 🔄 改变：通过多个接口专注于核心价值交付

🔔 Discord Webhook集成

获取CI/CD管道状态、拉取请求和发布的实时通知：

• 📖 Webhook设置指南
• 🛠️ 快速设置脚本
• 🧪 测试你的Webhook
• 📚 高级配置

🤝 贡献

我们欢迎捐款！请查看我们的 贡献指南 有关以下内容的详细信息：

• 开发设置和要求
• 代码风格指南（Ruff、MyPy）
• 测试要求（保持>76%的覆盖率）
• 拉取请求流程
• 分支保护规则

快速启动：

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/amazing-feature
3. 运行测试： pytest tests/ --cov=src/music21_mcp --cov-fail-under=76
4. 提交更改： git commit -m 'feat: Add amazing feature'
5. 推送分支： git push origin feature/amazing-feature
6. 提交拉取请求

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 建立在卓越之上 音乐21 图书馆
• 用途 FastMCP 用于MCP协议支持
• 受到对可靠音乐分析工具需求的启发

______________________________________________________________________

选择适合您的界面。所有这些都提供了同样强大的music21分析功能！ 🎵