Shotgrid MCP Rs

🚀 shotgrid-mcp-rs

shotgrid-mcp-rs 是基于 Rust 语言开发的 ShotGrid/Flow 生产跟踪 REST API 客户端，具备原生 MCP（模型上下文协议）服务器支持，可让大语言模型直接与 ShotGrid 交互。本项目为实验性项目，请勿用于生产环境。

⚠️ 重要提示

这是一个测试/实验性项目，绝不能在生产环境中使用。软件按“原样”提供，不附带任何形式的明示或暗示保证。作者对使用本软件所导致的任何损害、数据丢失或问题不承担任何责任。使用风险自负。

作者：Alex Khalyavin joss13@gmail.com

基于项目：由 LAIKA 工作室的 Owen Nelson、Alex Widener 和 Marina Wilding 开发的 LaikaStudios/shotgrid-rs。 本分支在他们优秀的基础上扩展了 MCP 服务器实现和现代工具。特别感谢原作者在 Rust ShotGrid 集成方面的开创性工作。

🚀 快速开始

1. 作为 Rust 库使用

在您的 Cargo.toml 文件中添加以下内容：

[dependencies]
shotgrid-mcp-rs = { version = "0.9", features = ["mcp"] }

详细的代码示例和 API 文档请参考 README.dev.md。

2. 作为 MCP 服务器使用（推荐）

通过模型上下文协议使大语言模型能够与您的 ShotGrid 实例进行交互。

安装

选项 1：从 crates.io 安装

cargo install shotgrid-mcp-rs --all-features

选项 2：从源代码安装

# 克隆仓库
git clone https://github.com/ssoj13/shotgrid-mcp-rs
cd shotgrid-mcp-rs

# 设置环境变量（ORM 代码生成需要）
export SG_SERVER="https://yoursite.shotgrid.autodesk.com"
export SG_SCRIPT_NAME="your_script_name"
export SG_SCRIPT_KEY="your_script_key"

# 生成 ORM 模型并安装
./bootstrap.ps1 codegen
cargo install --path . --all-features

安装完成后，shotgrid-mcp-rs 二进制文件将全局可用，路径为 ~/.cargo/bin/。

选项 3：仅构建（不安装）

cargo build --release --bin shotgrid-mcp-rs --features=mcp

二进制文件位置：

• Windows：target/release/shotgrid-mcp-rs.exe
• Linux/macOS：target/release/shotgrid-mcp-rs

CLI 选项

shotgrid-mcp-rs [OPTIONS]

选项:
  --url <URL>                ShotGrid 服务器 URL（覆盖 SG_SERVER 环境变量）
  --script-name <NAME>       脚本名称（覆盖 SG_SCRIPT_NAME 环境变量）
  --script-key <KEY>         脚本密钥（覆盖 SG_SCRIPT_KEY 环境变量）
  -s, --stream              启用 HTTP 流模式（默认：stdio）
  -p, --port <PORT>         HTTP 流模式端口 [默认值: 8000]
  -b, --bind <ADDRESS>      HTTP 流模式绑定地址 [默认值: 127.0.0.1]
  --log [<FILE>]            启用文件日志记录 [默认值: shotgrid-mcp-rs.log]
  -h, --help                打印帮助信息
  -V, --version             打印版本信息

使用示例

stdio 模式（默认）：

# 使用环境变量
export SG_SERVER="https://yoursite.shotgrid.autodesk.com"
export SG_SCRIPT_NAME="your_script_name"
export SG_SCRIPT_KEY="your_script_key"
shotgrid-mcp-rs

# 使用 CLI 参数
shotgrid-mcp-rs \
  --url https://yoursite.shotgrid.autodesk.com \
  --script-name your_script_name \
  --script-key your_script_key

# 启用文件日志记录
shotgrid-mcp-rs --log my-server.log

HTTP 流模式：

# 默认端口 8000
shotgrid-mcp-rs -s

# 自定义端口和绑定地址
shotgrid-mcp-rs -s -p 3000 -b 0.0.0.0

# 启用日志记录
shotgrid-mcp-rs -s --log

# 测试服务器
curl http://127.0.0.1:8000/health  # 应返回 "OK"

配置 Claude Desktop

在您的 Claude Desktop 配置文件 (claude_desktop_config.json) 中添加以下内容：

位置：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "shotgrid": {
      "command": "shotgrid-mcp-rs",
      "env": {
        "SG_SERVER": "https://yoursite.shotgrid.autodesk.com",
        "SG_SCRIPT_NAME": "your_script_name",
        "SG_SCRIPT_KEY": "your_script_key"
      }
    }
  }
}

Windows（使用绝对路径）：

{
  "mcpServers": {
    "shotgrid": {
      "command": "C:\\Users\\YourName\\.cargo\\bin\\shotgrid-mcp-rs.exe",
      "env": {
        "SG_SERVER": "https://yoursite.shotgrid.autodesk.com",
        "SG_SCRIPT_NAME": "your_script_name",
        "SG_SCRIPT_KEY": "your_script_key"
      }
    }
  }
}

配置 Claude Code / Codex

在您的 Claude Code MCP 设置中添加以下内容：

{
  "mcpServers": {
    "shotgrid": {
      "command": "shotgrid-mcp-rs",
      "env": {
        "SG_SERVER": "https://yoursite.shotgrid.autodesk.com",
        "SG_SCRIPT_NAME": "your_script_name",
        "SG_SCRIPT_KEY": "your_script_key"
      }
    }
  }
}

可用的 MCP 工具（14 个工具）

基本 CRUD 操作（8 个工具）

• schema_read - 获取实体字段模式
• search_entities - 使用过滤器/分页进行搜索
• find_one - 查找单个实体
• read_entity - 通过 ID 读取实体
• create_entity - 创建新实体
• update_entity - 更新现有实体
• delete_entity - 软删除实体
• revive_entity - 恢复已删除的实体

TimeLog 管理（2 个工具）

• read_timelogs - 查询时间记录
• timelog_stats - 汇总统计信息

高级操作（4 个工具）

• text_search - 跨实体搜索
• summarize - 类似 SQL 的聚合操作
• batch - 批量操作
• note_thread_read - 完整的对话线程

✨ 主要特性

🆕 新特性（本分支）

• 🤖 原生 MCP 服务器 - 14 个全面的工具用于大语言模型集成，已通过 Anthropic Claude Code 和 OpenAI Codex 测试。
• ⚡ 现代异步/等待机制 - 基于 tokio 的完整异步运行时。
• 🔧 增强的错误处理 - 全面的错误类型和更好的诊断信息。
• 🧹 自动输入清理 - 自动去除过滤器中字段名的空格，防止常见的 API 错误。
• 📊 TimeLog 工具 - 专门用于时间跟踪和统计的工具。
• 🧪 广泛的测试 - 涵盖单元测试和集成测试。
• 📝 完整的文档 - 全面的 API 文档和示例。
• 🛠️ 可选的 ORM 层 - 通过代码生成提供类型安全的实体模型。
• 🔄 批量操作 - 高效的批量处理。

核心功能

• 完整的 CRUD 操作（创建、读取、更新、删除、恢复）
• 支持复杂过滤器的高级搜索（AND/OR/NOT 逻辑）
• 跨多个实体类型的文本搜索（类似 Google）
• 用于批量处理的批量操作
• 汇总和聚合（GROUP BY、COUNT、SUM、AVG、MIN、MAX）
• 带有回复和附件的注释线程
• 模式内省
• TimeLog 跟踪和统计
• 自动输入验证和清理 - 去除字段名、对象键和过滤器参数中的前导和尾随空格，防止 ShotGrid API 错误

MCP（模型上下文协议）

mcp 特性启用了包含所有 14 个工具的 MCP 服务器。这是本分支的主要使用场景。

shotgrid-mcp-rs = { version = "0.9", features = ["mcp"] }

ORM 层

orm 特性通过从您的 ShotGrid 模式生成代码，提供类型安全的实体模型。

shotgrid-mcp-rs = { version = "0.9", features = ["orm"] }

生成模型：

# 设置环境变量
export SG_SERVER=https://yoursite.shotgrid.autodesk.com
export SG_SCRIPT_NAME=your_script_name
export SG_SCRIPT_KEY=your_script_key

# 从模式生成模型
cargo xtask codegen

ORM 使用示例请参考 README.dev.md。

📚 详细文档

• Monument2_Production_Report_5Days.md - 大语言模型根据单个提示生成的示例报告
• README.dev.md - 完整的 API 文档、代码示例和开发指南
• README.mcp.md - MCP 服务器文档
• README.codegen.md - ORM 代码生成文档
• CHANGELOG.md - 版本历史和变更记录

🔧 技术细节

输入验证与清理

MCP 服务器包含自动输入清理功能，以防止因字段名和过滤器参数中的空格而导致的常见错误。此功能用于处理不同 MCP 客户端（Claude Code、Codex 等）的不一致性。

清理内容

过滤器中的字段名：

// 清理前（会导致 API 错误）
[" sg_status_list", "is", "ip"]

// 清理后（正常工作）
["sg_status_list", "is", "ip"]

对象键：

// 清理前
{" project": {"type": "Project", "id": 123}}

// 清理后
{"project": {"type": "Project", "id": 123}}

字段列表：

// 清理前
["id", " name ", " sg_status_list "]

// 清理后
["id", "name", "sg_status_list"]

应用位置

清理功能会自动应用于以下操作：

• search_entities / find_one - filters 和 fields 参数
• create_entity / update_entity - data 参数中的对象键和 return_fields
• read_entity - fields 参数
• summarize - filters 和 summary_fields 参数
• text_search - entity_filters 参数
• batch - 所有请求参数
• read_timelogs - fields 参数

优点

• ✅ 防止 API 错误 - 避免因空格导致的 "字段不存在" 错误。
• ✅ 透明性 - 自动工作，无需更改代码。
• ✅ 可记录 - 调试日志显示清理操作何时发生。
• ✅ 全面性 - 处理嵌套结构和复杂过滤器。

错误预防示例

清理前：

错误: API read() Task. sg_status_list 不存在。
值: {" sg_status_list": " 不存在..."}

清理后：

成功: 字段名自动去除空格，查询正常执行

传输模式

MCP 服务器支持两种传输模式：

1. stdio（默认） - 本地模式

• 适用场景：Claude Desktop、Claude Code、Codex 和其他本地 MCP 客户端
• 协议：通过 stdin/stdout 的 JSON-RPC
• 日志记录：默认静默（stderr 日志会破坏 MCP 握手）
• 文件日志：使用 --log 标志启用

2. HTTP 流 - 远程/网络模式

• 适用场景：Web 客户端、远程访问、调试、开发
• 协议：通过 HTTP 的服务器发送事件（SSE）
• 端点：
  • /mcp - MCP 协议端点
  • /health - 健康检查（返回 "OK"）
• 日志记录：控制台 + 可选的文件日志
• 会话管理：内置会话处理

切换模式：使用 -s/--stream 标志启用 HTTP 模式。

🧪 测试

# 单元测试
cargo test

# HTTP 传输测试
cargo test --test http_transport

# 集成测试（需要运行中的 ShotGrid 服务器）
cargo test --features integration-tests

# MCP 特定测试
cargo test --lib mcp::tests

# 所有测试
cargo test --all

HTTP 传输测试： tests/http_transport.rs 模块包含了 HTTP 流模式的测试：

• 服务器健康检查端点
• MCP 端点可达性
• 自定义端口和绑定地址
• 文件日志功能

注意：HTTP 测试会启动一个真实的服务器进程，因此需要：

• 环境变量中的 ShotGrid 凭证
• 可用的网络端口（自动查找空闲端口）
• 由于服务器启动时间，大约需要 10 秒

集成测试所需的环境变量：

• TEST_SG_SERVER - ShotGrid 服务器 URL
• TEST_SG_SCRIPT_NAME - API 用户名
• TEST_SG_SCRIPT_KEY - API 密钥
• TEST_SG_HUMAN_USER_LOGIN - 用于 sudo 测试的 HumanUser 登录名
• TEST_SG_PROJECT_ID - 测试项目 ID

📄 许可证

本项目采用 MIT 许可证，请参阅 LICENSE 文件了解详细信息。

🤝 贡献

除非您明确声明，否则您有意提交以包含在本项目中的任何贡献都将按照 MIT 许可证进行许可，无需任何额外的条款或条件。

链接：

• ShotGrid
• 模型上下文协议
• 原项目