Vivid MCP 服务器

关键词

模型上下文JSON-RPC运行时控制图形与音频上下文LLM 集成

使用说明书（Markdown 版）

  • 项目简介

    • 该仓库实现了一个 MCP 服务器，用于把大语言模型等客户端通过 JSON-RPC 的方式接入 Vivid 的控制运行时。核心功能包括：通过 MCP 标准暴露对资源的访问（Resources）、注册与执行 Tools、以及对 Prompt 模板的定义与渲染等能力。服务器端负责会话管理、能力声明，以及对多种传输通道的支持，确保 LLM 应用可以安全、可扩展地获取图形/音频/控制域上下文。

  • 主要功能点

    • MCP 命令暴露和实现
      • 资源与数据访问：读取图的状态、图节点、端口、参数等（如 inspect_graph、list_types、list_nodes、inspect_node 等工具）。
      • 修改与执行能力：添加/删除节点、连接/断开端口、设置参数、执行保存/加载图等操作（add_node、remove_node、connect、disconnect、set_param、get_param、save_graph、load_graph、undo、redo、scaffold_operator 等）。
      • 图包与插件操作：浏览/安装/卸载操作包、读取包文档、运行包自带测试等（package_catalog、install_package、uninstall_package、package_operator_docs、test_package 等）。
      • 高级控制：版本化快照（save_variation、recall_variation、update_variation、rename_variation、remove_variation、list_variations、queue_variation、set_state_preset、remove_state_preset、clear_state_presets、inspect_state_presets 等）、以及对状态机、变体、预设的管理。
    • 运行时集成
      • MCP 服务器通过 HTTP 调用 vivid 控制端点（VIVID_URL，默认为 http://127.0.0.1:9876），将 MCP 客户端的请求转换为对运行时的控制操作。
    • 传输与扩展
      • 该实现基于 FastMCP 等框架，理论上支持多种传输通道（如 Stdio、SSE、WebSocket），以配合不同的客户端接入场景。
    • 会话与能力声明
      • 提供会话管理与能力声明能力，确保 LLM 客户端能够感知服务能力范围和会话状态。

  • 安装与运行步骤

    • 依赖与前置
      • 确保本机已安装 Python3，且 Vivid 控制端正在运行并监听 VIVID_URL 指定的地址（默认 http://127.0.0.1:9876）。
      • 需要安装 MCP 框架相关依赖（仓内 mcp/server/fastmcp 组件依赖）。
    • 启动命令
      • 启动 MCP 服务器，以便客户端通过 JSON-RPC 连接并调用工具。
      • 样例（描述性，不包含具体代码块）：在合适的工作目录下运行 Python 脚本来启动 vivid_mcp 服务，该脚本会通过环境变量 VIVID_URL 与 Vivid 控制端建立连接并注册工具。
    • 运行环境变量
      • VIVID_URL: 指向 Vivid 控制端 HTTP 控制服务器的地址，默认 http://127.0.0.1:9876。
      • 其他运行时参数如传输方式等，由 MCP 框架的运行时配置决定。

  • 服务器配置（MCP 客户端所需信息）

    • 该配置用于 MCP 客户端以 JSON-RPC 的方式连接到 MCP 服务器，描述服务器的名称、启动命令及参数等信息。
    • 示例（以文本描述形式给出配置要点，实际请将下述信息组织为一个 JSON 对象并在客户端配置中使用）：
      • server_name: "VividMCPServer"
      • command: ["python3", "mcp/vivid_mcp.py"]
      • args: []
      • env: {"VIVID_URL": "http://127.0.0.1:9876"}
      • 备注: MCP 客户端无需了解底层运行时实现细节，仅通过上述服务器信息建立连接，并通过 MCP 框架的接口向服务器发出 JSON-RPC 请求，例如调用 inspect_graph、add_node、set_param 等操作。服务器端将把请求转发到 Vivid 控制服务器以执行相应操作。
    • 说明：
      • 以上配置是为了确保 MCP 客户端能够启动并连接到服务器，以及让服务器在运行时知道如何定位 Vivid 控制端。服务器自身提供的端点和工具通过 MCP 框架暴露给客户端，客户端无需理解底层实现细节即可发起请求。

  • 基本使用方法

    • 连接与调用
      • 通过 MCP 客户端建立与服务器的连接后，可以使用 JSON-RPC 调用暴露的工具，例如读取图的状态、添加节点、设置参数、保存/加载图等。
    • 日常工作流示例（概念性说明）
      • 列出可用的运算类型（list_types）；
      • 新建节点（add_node）并连接（connect）；
      • 调整参数（set_param）；
      • 保存或加载图（save_graph、load_graph）；
      • 在同一会话中撤销/重做操作（undo/redo）；
      • 使用包管理命令安装、卸载插件包（install_package、uninstall_package）；
      • 针对 LLM 的提示模板或 Prompt 渲染由相应的 MCP 工具提供支持（Prompts 模块）
    • 调试与日志
      • MCP 服务器会通过日志和错误信息反馈运行状态，确保在复杂的 LLM 交互场景中能快速诊断问题。

  • 重要提示

    • MCP 客户端与服务器的通信应遵循 MCP 的授权与认证机制，确保会话安全性与权限控制。
    • MCP 服务器作为“后端服务”，应具备对 Vivid 控制端的健壮容错能力，尤其在网络波动或 Vivid 控制端重启时保持可用性。

  • 额外信息

    • 本实现的核心代码文件为 mcp/vivid_mcp.py，基于 mcp.server.fastmcp 提供的工具暴露能力，实现对 Vivid 控制端接口的包装与暴露。

服务器信息

访问项目