Claude AI Music Skills State MCP 服务器

关键词

状态缓存JSON-RPC音乐项目管理本地服务会话上下文

使用说明（Markdown 格式）

  • 项目简介

    • 该仓库实现了一个用于 Claude AI Music Skills 的状态数据 MCP 服务器，提供对音乐项目中专辑、轨道、想法以及会话上下文等资源的统一访问接口，并通过 MCP 客户端与 LLM 进行高效交互。

  • 主要功能点

    • 提供对音乐状态的查询与修改：查找专辑、列出专辑、获取轨道详情、获取与更新会话上下文、重建状态缓存、获取配置信息及想法数据、查询待验证的轨道等。
    • 通过标准的 MCP 服务器模式与客户端通信，默认传输为标准输入输出（stdio），方便在 Claude Code 等环境中接入。
    • 服务器端实现了完整的后端逻辑：从本地 Markdown/yaml 数据文件解析状态、专辑与轨道信息，维护一个内存缓存，并持久化到本地缓存文件。
    • 对外暴露的工具接口包括 find_album、list_albums、get_track、get_session、update_session、rebuild_state、get_config、get_ideas、get_pending_verifications 等，方便 LLM 调用。
    • 具备启动脚本与运行环境兼容性：支持在系统 Python 环境或虚拟环境中运行，自动定位合适的 Python 解释器。

  • 安装步骤

    • 确保系统安装了 Python 3.x。
    • 安装 MCP 相关依赖（推荐做法）：
      • pip install "mcp[cli]>=1.2.0" pyyaml
    • 获取代码并进入项目根目录。
    • 使用提供的启动脚本启动服务器：
      • 在不使用虚拟环境时：直接执行 python3 servers/state-server/server.py（此方法仅作为参考，实际启动通常通过 run.py 完成）
      • 如果使用虚拟环境，请创建并激活虚拟环境，然后执行相应的启动命令（确保虚拟环境中的 Python 版本与依赖安装完毕）。
    • 启动示例（推荐）：
      • 运行脚本：python3 servers/state-server/run.py
      • 该脚本会自动选择可用的 Python 解释器，并通过 MCP 客户端与服务器建立通信。若使用虚拟环境，请将运行命令指向该虚拟环境中的 Python。
    • 运行要求与环境变量
      • 运行时可能需要设置 CLAUDE_PLUGIN_ROOT 环境变量，指向仓库根目录，以便服务器能够正确定位插件结构和数据文件。
      • 若使用自定义 Python 路径，请确保命令参数中的 Python 路径指向正确的解释器。

  • 服务器配置（MCP 客户端需要的最小配置） 客户端配置示例（JSON 格式，非代码片段，便于理解）： { "server_name": "bitwize-music-state", "command": "python3", "args": ["servers/state-server/run.py"], "transport": "stdio", "description": "MCP 状态服务：提供专辑、轨道、想法和会话数据的访问与管理", "notes": "如使用虚拟环境，请将 command 指向虚拟环境中的 Python，并确保 CLAUDE_PLUGIN_ROOT 指向仓库根目录，以便访问插件数据和工具。" }

    说明

    • 以上配置仅用于 MCP 客户端与服务器建立连接的示意，具体在你的 MCP 客户端实现中可能需要按客户端的接口要求传递更多字段或以不同形式描述。
    • MCP 客户端不需要直接运行服务器代码，仅需要通过该配置知道如何启动服务器以及如何连接。

  • 基本使用方法

    • 启动后，客户端即可通过 MCP 的 JSON-RPC 请求调用以下功能：
      • 查找专辑：find_album(name)
      • 列出所有专辑摘要：list_albums()
      • 获取某个专辑中某轨道的详细信息：get_track(album_slug, track_slug)
      • 获取当前会话上下文：get_session()
      • 更新会话上下文（如设置当前专辑、轨道、阶段或添加待办事项）：update_session(...)
      • 强制重建状态缓存：rebuild_state()
      • 获取配置信息：get_config()
      • 获取创意/想法数据：get_ideas()
      • 获取待验证的轨道信息：get_pending_verifications()
    • 使用示例（操作简述）
      • 启动 MCP 客户端后，请求服务器以获取当前专辑列表，选择一个后续查询轨道详情。
      • 调用 rebuild_state 以在数据变更后重新加载状态缓存。
      • 通过 get_config 获取当前配置，了解数据根路径与艺术家信息等。
    • 注意事项
      • MCP 请求和响应都遵循 JSON-RPC 的约定，具体请求字段请参照客户端实现的 JSON-RPC 规范。
      • 服务端在本地硬盘读取数据文件（README、SOURCES 等）并缓存到内存，若数据文件变更，调用 rebuild_state 可刷新缓存。

  • 关键词 状态缓存, JSON-RPC, 音乐项目管理, 本地服务, 会话上下文

  • 分类ID 6

服务器信息

访问项目