使用说明（Markdown 版）

• 项目简介

  • 本仓库实现了一个基于 MCP 的服务器端，名称为 fcpxml-mcp-server。它通过 JSON-RPC 向 LLM 客户端提供对 Final Cut Pro X FCPXML 项目的分析、编辑工具、以及预置的 Prompt 工作流等能力。服务器具备资源管理、工具注册与执行、以及 Prompt/Workflow 的渲染能力，旨在为 LLM 应用提供结构化的上下文服务。

• 主要功能点

  • MCP 资源管理与暴露：自动发现并暴露 .fcpxml 文件作为服务器资源，方便客户端读取与分析。
  • 资源读取与摘要：读取指定 FCPXML 文件并返回简要摘要（时长、分辨率、片段、标记等）。
  • MCP Prompts 与 Tools：内置 5 个 Prompts（如 qc-check、youtube-chapters、rough-cut、timeline-summary、cleanup）以及 34 个 Tools（读取、校验、编辑、批量修复、生成等），支持通过工具调用执行复杂工作流。
  • Tools 调用处理：通过统一的 TOOL_HANDLERS 映射，处理具体工具的参数校验与执行，并返回文本内容或错误信息。
  • MCP 通信与入口：使用 stdio 传输实现 MCP 的请求/响应循环，提供 main()/main_sync() 的可执行入口，便于在本地环境直接运行。
  • 会话与能力声明：服务器端实现了注册、查询、执行等能力，适配 MCP 客户端的对话式交互模式。
  • 可扩展性：Prompts、Tools、以及核心处理逻辑分离，便于后续扩展新的工具或工作流。

• 安装与运行步骤

  • 环境与依赖
    • 需要 Python 3.10+。
    • 安装本仓库的依赖（通常包含 mcp 框架及本项目代码所需依赖）。
  • 安装与安装后运行
    • 克隆仓库并安装为本地包：
      • git clone https://github.com/DareDev256/fcpxml-mcp-server.git
      • 进入目录后执行：pip install -e .
    • 配置 FCP 项目目录环境变量
      • FCP_PROJECTS_DIR 指向本地存放 FCPXML 文件的目录，例如 /Users/you/Movies。可通过环境变量 FCP_PROJECTS_DIR 指定。
    • 启动服务器
      • 直接运行 server.py，例如：python server.py
      • 或者使用 Claude Desktop (或任意 MCP 客户端) 连接的方式启动（下方提供客户端配置示例）。
  • 与 Claude Desktop 的配置（由 MCP 客户端使用）
    • 本仓库提供的配置示例用于 Claude Desktop，便于将服务器作为一个 MCP 服务接入 Claude：
    • 使用 uv 启动（推荐，非必需，按需选择）：
      • command: uv
      • args: ["--directory", "/path/to/fcp-mcp-server", "run", "server.py"]
      • env: {"FCP_PROJECTS_DIR": "/Users/you/Movies"}
    • 使用 pip 安装后直接运行（另一种常见方式）：
      • command: python
      • args: ["/path/to/fcp-mcp-server/server.py"]
      • env: {"FCP_PROJECTS_DIR": "/Users/you/Movies"}
    • 上述配置仅用于示例，请将 /path/to/fcp-mcp-server 替换为实际的仓库目录。
  • 基本使用方法
    • 启动后，客户端可以通过 MCP 的 JSON-RPC 接口向服务器请求：
      • 列出资源、读取资源摘要、列出 Prompts、获取 Prompt、列出 Tools、调用 Tool 等。
    • 常见操作包括：
      • 发现并读取 FCPXML 项目资源，获取项目摘要信息。
      • 调用预置工具完成 batch 编辑、标记、分割、导出等任务。
      • 通过 Prompts 调用组合工具链，执行 QC、生成粗略剪辑、生成 YouTube 章节等工作流。
    • 如遇到错误，服务器将返回相应的错误信息，便于定位参数或文件路径等问题。

• 重要提示

  • MCP 客户端需要与服务器建立连接并按 MCP 规范发送请求。服务器通过标准输入输出 (stdio) 实现通信。
  • FCP_PROJECTS_DIR 指定的目录应包含可分析的 .fcpxml 文件，且对客户端具有可读权限。
  • 本实现包含大量工具与示例代码，务必在受控环境中测试，确保对敏感素材没有意外修改。

• 备注

  • 若你需要在 Claude Desktop 之外的环境中使用，请参阅本仓库中的 server.py、tools、prompts、以及 fcpxml 子模块的实现细节，了解各工具的输入输出结构与权限控制。