Shotgrid MCP Rs

🚀 shotgrid-mcp-rs

shotgrid-mcp-rsは、ShotGrid/Flow Production Tracking REST APIクライアントの最新のRust実装で、ネイティブのMCP (Model Context Protocol)サーバーをサポートしています。これにより、大規模言語モデルが直接ShotGridとやり取りできるようになります。

⚠️ 重要な注意

これはテスト/実験プロジェクトであり、決して本番環境で使用しないでください。ソフトウェアは「現状のまま」提供され、明示的または黙示的ないかなる保証もありません。作者は、このソフトウェアの使用に起因する損害、データ損失、または問題について、一切の責任を負いません。自己責任で使用してください。

作者: Alex Khalyavin joss13@gmail.com

ベースとなるプロジェクト: LaikaStudios/shotgrid-rs（LAIKA StudiosのOwen Nelson、Alex Widener、Marina Wildingによる）

このフォークは、彼らの優れた基盤にMCPサーバーの実装と最新のツールを追加しています。RustによるShotGrid統合の先駆的な仕事をした元の作者たちに特別な感謝を申し上げます。

🚀 クイックスタート

Rustライブラリとしての使用

Cargo.tomlに以下を追加します。

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

詳細なコード例とAPIドキュメントについては、README.dev.mdを参照してください。

MCPサーバーとしての使用（推奨）

LLMがModel Context Protocolを介してあなたの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]

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ポート [default: 8000]
  -b, --bind <ADDRESS>      ストリームモードのバインドアドレス [default: 127.0.0.1]
  --log [<FILE>]            ファイルログを有効にする [default: 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 (Model Context Protocol)

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 - 単一のプロンプトからLLMによって作成されたレポートの例
• README.dev.md - 完全なAPIドキュメント、コード例、および開発ガイド
• README.mcp.md - MCPサーバーのドキュメント
• README.codegen.md - ORMコード生成のドキュメント
• CHANGELOG.md - バージョン履歴と変更点

🔧 技術詳細

トランスポートモード

MCPサーバーは2つのトランスポートモードをサポートしています。

1. stdio（デフォルト） - ローカルモード

• 使用対象: Claude Desktop、Claude Code、Codex、およびその他のローカルMCPクライアント
• プロトコル: stdin/stdoutを介したJSON-RPC
• ログ: デフォルトではサイレント（stderrログはMCPハンドシェイクを中断する）
• ファイルログ: --logフラグで利用可能

2. HTTPストリーム - リモート/ウェブモード

• 使用対象: ウェブクライアント、リモートアクセス、デバッグ、開発
• プロトコル: HTTPを介したServer-Sent Events (SSE)
• エンドポイント:
  • /mcp - MCPプロトコルエンドポイント
  • /health - ヘルスチェック（"OK"を返す）
• ログ: コンソール + オプションのファイルログ
• セッション管理: 組み込みのセッション処理

モードの切り替え: -s/--streamフラグを使用してHTTPモードを有効にします。

入力検証とサニタイズ

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エラーを防止 - 空白による「フィールドが存在しない」エラーがなくなります。
• ✅ 透過的 - 自動的に動作し、コードの変更は必要ありません。
• ✅ ログ付き - サニタイズが行われたときにデバッグログが表示されます。
• ✅ 包括的 - ネストされた構造と複雑なフィルターを処理します。

エラー防止の例

サニタイズ前:

Error: API read() Task. sg_status_list doesn't exist.
Value: {" sg_status_list": " does not exist..."}

サニタイズ後:

Success: Field names automatically trimmed, query executes correctly

テスト

# 単体テスト
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 - スードテスト用のHumanUserログイン
• TEST_SG_PROJECT_ID - テストプロジェクトのID

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

コントリビューション

明示的に別の記載がない限り、あなたが意図的にこの作品に含めるために提出したコントリビューションは、追加の条件なしにMITライセンスの下でライセンスされるものとします。

リンク

• ShotGrid
• Model Context Protocol
• 元のプロジェクト