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
• 模型上下文協議
• 原項目