使用说明

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

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

🎯 为什么有多个接口？

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

📡 MCP 服务器 -用于Claude Desktop集成（当它工作时）
🌐 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          # MCP server for Claude Desktop
music21-http         # REST API at localhost:8000
music21-cli          # Interactive CLI
music21-analysis mcp          # Unified launcher (positional arg)

从源代码安装

# 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 .

# Configure music21 corpus
python -m music21.configure

用法-选择您的界面

🎯 显示所有可用界面

python -m music21_mcp.launcher

📡 MCP服务器（用于克劳德桌面）

# Start MCP server
python -m music21_mcp.launcher mcp

# Configure Claude Desktop with:
# ~/.config/claude-desktop/config.json
{
  "mcpServers": {
    "music21-analysis": {
      "command": "python",
      "args": ["-m", "music21_mcp.server_minimal"],
      "env": {
        "PYTHONPATH": "/path/to/music21-mcp-server/src"
      }
    }
  }
}

🌐 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 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")

🧪 测试与开发

运行测试

# Run all tests
python -m pytest tests/ -v

# Run with coverage threshold
python -m pytest tests/ --cov=src/music21_mcp --cov-fail-under=82

开发设置

# 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生态系统而设计，而非企业梦想

📊 接口可靠性

界面	成功率	最适合
主控程序	40-50%	人工智能助手集成
超文本传输协议	95%以上	Web应用程序
命令行界面	99%+	自动化和脚本
python	99%+	直接编程

📚 文档

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

Discord Webhook集成

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

🔧 配置

环境变量

# Server host and port (used by HTTP adapter and launcher)
export MUSIC21_MCP_HOST=127.0.0.1
export MUSIC21_MCP_PORT=8000

# Operation timeouts (seconds)
export MUSIC21_MCP_TIMEOUT=30          # General async operation timeout
export MUSIC21_TOOL_TIMEOUT=30         # Per-tool execution timeout
export MUSIC21_CHORD_ANALYSIS_TIMEOUT=60  # Chord analysis timeout
export MUSIC21_BATCH_TIMEOUT=30        # Batch processing timeout

# CORS origins for HTTP adapter (comma-separated)
export MUSIC21_CORS_ORIGINS="http://localhost:*"

Music21设置

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

🛠️ 可用的分析工具

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

🚀 快速示例

分析巴赫合唱

# 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管道状态、拉取请求和发布的实时通知：

🤝 贡献

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

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

快速启动：

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

📄 许可证

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

🙏 致谢

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

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