Hooktheory MCP Server

Hooktheory MCP服务器

模型上下文协议（MCP）服务器，使人工智能代理能够与Hooketheory API交互，用于和弦进行生成、歌曲分析和音乐理论数据检索。

快速开始

只需3个简单步骤即可启动并运行：

1. 设置身份验证 使用您的Hooktheory帐户凭据：

   export HOOKTHEORY_USERNAME="your-username"
   export HOOKTHEORY_PASSWORD="your-password"

1. 安装并运行：

   uvx hooktheory-mcp

1. 用你的AI助手试试这些例子：

- “查找和弦顺序为I-V-vi-IV的歌曲” - 解析Oasis的歌曲《Wonderwall》 - “给我看C大调流行的和弦进行曲” - “查找与披头士乐队的《Let It Be》相似的歌曲”

就是这样！你的人工智能现在可以访问音乐理论数据和和弦进行。

常见用法示例

按和弦级数搜索歌曲

Find songs using the progression 1,5,6,4 in the key of C major

分析任何歌曲

What are the chords in "Someone Like You" by Adele?

发现热门进展

What are the most common chord progressions in pop music?

查找相似歌曲

Find songs that have similar chord progressions to "Hotel California"

特性

服务器提供以下用于音乐分析和生成的工具：

• 和弦进程搜索：查找具有特定和弦进行的歌曲
• 歌曲分析：分析特定歌曲以获取和弦进行和关键信息
• 大众进步：探索最受欢迎的和弦进行曲
• 类似歌曲：查找和弦进行相似的歌曲
• 进步生成：根据音乐理论模式生成和弦进行曲

安装

先决条件

• Python 3.11或更高版本
• Hooktheory帐户（注册https://www.hooktheory.com)

设置

1. 使用uvx安装（推荐）：

   uvx hooktheory-mcp

1. 或者从源代码安装：

   git clone 
   cd hooktheory-mcp
   uv sync

1. 设置身份验证：

   export HOOKTHEORY_USERNAME="your-username"
   export HOOKTHEORY_PASSWORD="your-password"

或者创建一个 .env 文件：

   HOOKTHEORY_USERNAME=your-username
   HOOKTHEORY_PASSWORD=your-password

1. 测试安装：

   uvx hooktheory-mcp --help
   # Or if installed from source:
   uv run hooktheory-mcp --help

用法

命令行

服务器可以在不同的模式下运行：

标准MCP模式（标准传输）：

uvx hooktheory-mcp
# Or from source: uv run hooktheory-mcp

用于web集成的流式HTTP模式：

uvx hooktheory-mcp --transport streamable-http
# Or from source: uv run hooktheory-mcp --transport streamable-http

服务器发送事件（SSE）模式：

uvx hooktheory-mcp --transport sse
# Or from source: uv run hooktheory-mcp --transport sse

MCP客户端配置

对于Claude Desktop，请将以下内容添加到您的配置中：

{
  "mcpServers": {
    "hooktheory": {
      "command": "uvx",
      "args": ["hooktheory-mcp"],
      "env": {
        "HOOKTHEORY_USERNAME": "your-username",
        "HOOKTHEORY_PASSWORD": "your-password"
      }
    }
  }
}

开发/本地安装的替代方案：

{
  "mcpServers": {
    "hooktheory": {
      "command": "uv",
      "args": ["run", "hooktheory-mcp"],
      "cwd": "/path/to/hooktheory-mcp",
      "env": {
        "HOOKTHEORY_USERNAME": "your-username",
        "HOOKTHEORY_PASSWORD": "your-password"
      }
    }
  }
}

可用工具

1. get_chord_progressions

搜索具有特定和弦进行的歌曲。

参数：

• cp （必填）：罗马数字表示法中的和弦级数（例如，“1,5,6,4”）
• key （可选）：音乐键（例如“C”、“Am”）
• mode （可选）：缩放模式（“主要”、“次要”）
• artist （可选）：按艺术家姓名筛选
• song （可选）：按歌曲标题筛选

例子：

Find songs with the progression I-V-vi-IV in the key of C major

2. analyze_song

分析一首特定的歌曲，以获得其和弦进程和音乐理论数据。

参数：

• artist （必填）：艺人名称
• song （必填）：歌曲标题

例子：

Analyze "Wonderwall" by Oasis

3. get_popular_progressions

从数据库中获取最受欢迎的和弦进行。

参数：

• key （可选）：按音乐键过滤
• mode （可选）：按比例模式过滤
• limit （可选）：最大结果（默认值：20）

例子：

Show me the most popular chord progressions in C major

4. find_similar_songs

查找与参考歌曲具有相似和弦进行的歌曲。

参数：

• artist （必填）：参考艺术家姓名
• song （必填）：参考歌曲标题
• similarity_threshold （可选）：相似性得分0.0-1.0（默认值：0.7）

例子：

Find songs similar to "Let It Be" by The Beatles

5. generate_progression

根据音乐理论模式生成和弦进行曲。

参数：

• key （可选）：启动键（默认：“C”）
• mode （可选）：缩放模式（默认：“major”）
• length （可选）：和弦数（默认值：4）
• style （可选）：音乐风格提示（“流行”、“摇滚”、“爵士”）

例子：

Generate a 4-chord pop progression in A minor

API集成

服务器使用OAuth 2.0身份验证与Hooketheory API集成：

• 基本URL: https://www.hooktheory.com/api
• 认证：带用户名/密码的OAuth 2.0→ 持有者代币
• 速率限制：1.5个请求/秒，指数回退
• 许可证管理：自动令牌缓存和刷新（24小时到期）
• 错误恢复：自动重试，在速率限制和身份验证失败时进行回退

身份验证流程

1. 服务器通过以下方式为Bearer令牌交换用户名/密码 POST /users/auth
2. 令牌被缓存并在过期时自动刷新
3. 所有API请求都使用承载令牌身份验证
4. 速率限制通过智能退避防止超过API限制

发展

项目结构

hooktheory-mcp/
├── src/hooktheory_mcp/
│   └── __init__.py          # Main MCP server implementation
├── pyproject.toml           # Project configuration
├── uv.lock                  # Dependency lock file
└── README.md               # This file

添加新工具

要添加新工具，请编辑 src/hooktheory_mcp/__init__.py 并添加新的装饰功能 @mcp.tool():

@mcp.tool()
async def your_new_tool(param1: str, param2: Optional[int] = None) -> str:
    """
    Description of your tool.

    Args:
        param1: Description of parameter
        param2: Optional parameter description

    Returns:
        Description of return value
    """
    # Implementation here
    return result

测试

# Run basic connectivity test
uv run python -c "
import asyncio
from hooktheory_mcp import hooktheory_client
asyncio.run(hooktheory_client._make_request('test'))
"

故障排除

常见问题

1. 未设置身份验证凭据

   Error: HOOKTHEORY_USERNAME and HOOKTHEORY_PASSWORD environment variables are required

解决方案：两者都设置 HOOKTHEORY_USERNAME 和 HOOKTHEORY_PASSWORD 环境变量

1. HTTP 401未经授权

   HTTP error calling https://www.hooktheory.com/api/trends/...: 401

解决方案：验证您的用户名和密码是否正确。服务器将自动重试身份验证。

1. 速率限制（HTTP 429）

   Rate limited. Waiting X seconds before retry

解决方案：这很正常-服务器会自动处理指数回退的速率限制

1. 连接错误

   HTTP error calling https://www.hooktheory.com/api/trends/...: ConnectError

解决方案：检查互联网连接和Hooktheory API状态

调试模式

启用调试日志记录：

export PYTHONPATH=src
python -c "
import logging
logging.basicConfig(level=logging.DEBUG)
from hooktheory_mcp import main
main()
"

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

链接

• 虎克理论API文档
• 模型上下文协议规范
• MCP Python SDK