内容
# ShotGrid MCP 服务器（精简版）
一个 **模型上下文协议** 服务器，允许 LLM 代理（Claude Desktop、Claude Code、Cursor 等）通过 **小型、精选、代理优先的工具界面**，完全访问 **ShotGrid / Autodesk Flow Production Tracking** API。这是一个更精简、只允许写入的安全性重打包版本，基于 [`loonghao/shotgrid-mcp-server`](https://github.com/loonghao/shotgrid-mcp-server)（下方致谢）。
> ShotGrid 是基于模式驱动的，因此少数 **通用 CRUD + 查询工具** 即可访问每种实体类型。该服务器充分利用了这一点：**16 个工具，一个 CRUD 家族，每个写入操作都有 `dry_run` 安全门**。
## 建立在 `loonghao/shotgrid-mcp-server` 的基础上
本项目极大地依赖于 **[`loonghao/shotgrid-mcp-server`](https://github.com/loonghao/shotgrid-mcp-server)**（MIT）——第一个可靠、设计良好的 ShotGrid MCP。我们大量使用了它，它运行良好：连接池、模式缓存、`error_handler` 和基于 `mockgun` 的测试都是正确的，并且证明了这个概念。**请为它点赞。** 本服务器与其说是替代品，不如说是相同想法的 **更精简、更加强化** 的重打包，专门为 **自主代理** 调整——在这种情况下，更紧凑、更安全的工具界面比广度更重要。
### 我们做出的改变，以使其更加稳固
三个改变，每个改变都旨在使代理的生命周期更安全、更可预测：
| 在原始版本中 | 我们在这里做了什么——以及为什么更稳固 |
|---|---|
| **约 60 个工具，分布在两个重叠的 CRUD 家族中**（`sg_find`/`find_one_entity`、`sg_create`/`create_entity`、`sg_batch`/`batch_operations`）**以及 `_tool` 别名重复项**。 | **合并为一个 CRUD 家族**——`find` / `find_one` / `create` / `update` / `delete` / `revive` / `batch`，**共 16 个工具**。工具数量更少、明确性更高 = 模型每次都能选择正确的工具，并且在选择时花费的上下文大大减少。 |
| **写入操作立即提交**；防止意外 `delete`/`update` 的唯一保护措施是文档字符串文本。 | **在每个写入操作中添加 `dry_run` 标志**（`create`、`update`、`delete`、`batch`）。如果 `dry_run=true`，则返回实际会发生的情况，但不提交任何内容——因此代理（或人类）可以在操作前进行预览。`delete` 也是一个 **可逆转的退休**（使用 `revive` 撤销），并有相应的文档说明。 |
| **核心中的特定于工作室的工具**（`find_vendor_users`、`find_vendor_versions`、`create_vendor_playlist`）+ 浅层罐装过滤器包装器（`find_recent_playlists`、`find_project_playlists`等），假设一个商店的模式/约定。 | **已删除**——它们所做的一切都可以通过显式过滤器实现。不会对站点的状态列表或命名做出任何假设，因此它在任何 ShotGrid 实例上表现相同。 |
结果是：**相同的 100% 访问权限**（两者都针对 ShotGrid 的模式进行了泛化），工具数量的三分之一，以及 **默认安全的写入操作**。原始版本优化了人类的便利性和广度，而这个版本则针对需要正确选择且不会破坏事物的代理进行了优化。
## 16 个工具
**通用强力工具（对每种实体类型具有完全访问权限）：**
- `find` · `find_one` — 使用 ShotGrid 过滤器 + 字段投影进行查询
- `create` · `update` · `delete` · `revive` — 单实体写入（`delete` = 可逆转的退休）
- `batch` — 原子多操作创建/更新/删除
**模式和发现（以便代理可以首先了解站点）：**
- `schema_entity_read` — 所有实体类型
- `schema_field_read` — 字段 + 实体类型的类型
- `summarize` — 服务器端聚合 / 状态汇总（不拉取行）
- `text_search` — 跨实体类型的全局文本搜索
**高价值助手（不仅仅是一个罐装过滤器）：**
- `whoami` — 连接 + 服务器信息
- `find_projects` — 常见的入口点
- `project_summary` — 一个 **规范化** 的项目快照（计数 + 按镜头计算的演员/状态/缩略图，规范状态）用于跨跟踪器验证/差异
- `download_thumbnail` — 将实体的缩略图/电影片段拉取到磁盘
- `upload` — 附加文件 / 设置缩略图 / 填充媒体字段
每个写入工具都接受 `dry_run`（默认为 `false`）。`create` / `update` / `delete` 支持 **两个预览级别**：`dry_run="plan"`（客户端回声，无服务器联系）和 **`dry_run="preflight"`** — 一个真正的干运行，解析每个引用的实体与实时数据，验证 `sg_status_list` 值与实时模式，返回更新的前后差异，以及 `ok`/`would_fail` 的判决——**不写入**。设置 `MCP_PLAN_LOG=/path.jsonl` 以捕获每个计划/预检为可审查的计划文件。（其他写入工具接受 `dry_run` 作为纯布尔值。）
## 安装
```bash
pip install -r requirements.txt # fastmcp, shotgun_api3, requests
```
## 配置（凭证）
在 ShotGrid 中创建一个 **脚本**（管理员 ▸ 脚本 ▸ *+ 添加脚本*），并设置三个环境变量（或在 MCP 客户端配置中传递它们）：
| 变量 | 值 |
|---|---|
| `SHOTGRID_URL` | `https://yourstudio.shotgrid.autodesk.com` |
| `SHOTGRID_SCRIPT_NAME` | 脚本名称 |
| `SHOTGRID_API_KEY` | 该脚本的 **应用程序密钥** |
在本地开发过程中，您可以将其放入靠近 `server.py` 的 `.env` 中（gitignored — 参见 `.env.example`）。
## 运行 / 连接到客户端
```bash
python3 server.py # 标准输入输出传输
```
Claude Code：
```bash
claude mcp add shotgrid -- python3 /path/to/shotgrid-mcp/server.py
```
Claude Desktop / Cursor（`mcpServers` 条目）：
```json
{
"mcpServers": {
"shotgrid": {
"command": "python3",
"args": ["/path/to/shotgrid-mcp/server.py"],
"env": {
"SHOTGRID_URL": "https://yourstudio.shotgrid.autodesk.com",
"SHOTGRID_SCRIPT_NAME": "mcp",
"SHOTGRID_API_KEY": "••••"
}
}
}
}
```
## 示例（代理调用）
```python
# 项目中的所有正在进行中的镜头，附带受指派者
find("Shot",
[["project","is",{"type":"Project","id":85}], ["sg_status_list","is","ip"]],
["code","sg_status_list","task_template"])
# 状态汇总，无需拉取行
summarize("Task", [["project","is",{"type":"Project","id":85}]],
[{"field":"id","type":"count"}],
grouping=[{"field":"sg_status_list","type":"exact","direction":"asc"}])
# 在提交前预览写入操作
create("Shot", {"project":{"type":"Project","id":85}, "code":"sh010"}, dry_run=True)
```
## 跟踪器-MCP 五元组的一部分 — 在平台之间迁移项目
这是 **五个兄弟跟踪器 MCP** 之一，每个跟踪器 MCP 都有相同的形状（通用 CRUD + 模式 + 类型便利，具有 `dry_run` 门控）：[`shotgrid-mcp`](https://github.com/huikku/shotgrid-mcp)（此仓库），[`ftrack-mcp`](https://github.com/huikku/ftrack-mcp)，以及
[`kitsu-mcp`](https://github.com/huikku/kitsu-mcp)，和 [`ayon-mcp`](https://github.com/huikku/ayon-mcp)，和 [`nim-mcp`](https://github.com/huikku/nim-mcp)。它们都使用相同的生产模型（项目 → 序列/资产 → 镜头 → 任务 → 版本/状态），因此 **具有两个已加载的代理可以迁移项目从一个跟踪器到另一个** — 从源 MCP 读取结构，通过目标的 `create`/`new_*` 工具重新创建，无需定制迁移脚本。这三者源于在所有三个平台上复制一个项目。
📊 **参见 [`COMPARISON.md`](COMPARISON.md)** 以比较四个跟踪器（数据模型，状态词汇）和 **迁移不兼容性** 需要注意（例如，投射无法通过 ftrack 循环；状态必须映射；媒体/笔记/自定义字段还不支持）。
🧪 **参见 [`TESTING.md`](TESTING.md)** 以了解这些服务器如何被验证 — 实况往返测试，两级干运行检查和跨跟踪器迁移矩阵（包括尚未涵盖的内容，明确说明）。
## 致谢
- **[`loonghao/shotgrid-mcp-server`](https://github.com/loonghao/shotgrid-mcp-server)**（MIT）— 本项目建立在此基础上的原始 ShotGrid MCP。设计和许多 API 优雅性都源自该项目；请给予致谢和点赞。
- Autodesk 的 **[`shotgun_api3`](https://github.com/shotgunsoftware/python-api)** — 底层 Python API。
- 伴侣项目 **[`ftrack-mcp`](https://github.com/huikku/ftrack-mcp)**。
MIT 许可。如果原始版本的额外广度更适合您，请使用它 — 这只是更精简、更加强化的剪辑。
---
由 **John Huikku** · [alienrobot.com](https://alienrobot.com) 构建
