内容
# dcc-mcp-fpt
<p align="center">
<img src="docs/assets/dcc-mcp-shotgrid.svg" alt="DCC-MCP · SHOTGRID" width="600">
</p>
## 代理工作流
AI 代理应通过 `dcc-mcp-cli` 使用共享网关；IDE 用户可以继续使用 MCP 端点。优先使用类型化的技能和工具，而不是原始脚本。
### 安装或更新 CLI
`dcc-mcp-cli` 是每个 shell-capable 代理的首选控制路径。如果它丢失了，请在安装最新官方版本之前询问用户：
```bash
# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-core/main/scripts/install-cli.sh | sh
# Windows PowerShell
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-core/main/scripts/install-cli.ps1 | iex"
```
通过发布清单保持官方构建的最新状态：
```bash
dcc-mcp-cli update check
dcc-mcp-cli update apply
```
`update apply` 下载并阶段最新的 CLI 以供下次启动。它不会更新正在运行的 `dcc-mcp-server`；在自己的环境中更新该服务器。
```bash
dcc-mcp-cli dcc-types
dcc-mcp-cli list
dcc-mcp-cli search --query "<task>" --dcc-type shotgrid
dcc-mcp-cli describe <tool-slug>
dcc-mcp-cli call <tool-slug> --json '{"key":"value"}'
```
`dcc-types` 报告发布目录支持；`list` 报告实时会话。如果工具属于非活动渐进式技能，请在重试之前调用 `dcc-mcp-cli load-skill <skill-name> --dcc-type shotgrid`。
**ShotGrid（Flow Production Tracking）适配器，用于 DCC-MCP 生态系统。**
[](https://github.com/dcc-mcp/dcc-mcp-fpt/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
[]()
通过 [dcc-mcp-core](https://github.com/dcc-mcp/dcc-mcp-core) 构建的基于类型、渐进加载的 MCP 工具，将 AI 助手（Claude、Cursor、VS Code Copilot）连接到 ShotGrid 数据。
> 这是 [shotgrid-mcp-server](https://github.com/loonghao/shotgrid-mcp-server) 的全新重新实现，使用 dcc-mcp 框架提供相同的 ShotGrid 集成表面，具有网关路由、基于技能的渐进加载和多 DCC 可观察性。
## 为什么使用它
| 功能 | 描述 |
|---------|-------------|
| **20+ 类型化工具** | CRUD、搜索、批量、注释 - 所有工具都具有验证的模式 |
| **渐进加载** | 基础工具预加载；高级工具按需加载 |
| **网关就绪** | 插入 dcc-mcp 网关以实现统一的多服务路由 |
| **技能优先** | 每个工具都是具有 `tools.yaml`、模式和注释的类型化技能 |
| **连接池** | 重用身份验证会话以提高性能 |
| **模式缓存** | 实体字段模式缓存，带有可配置的 TTL |
| **多传输** | stdio、HTTP 和 ASGI - 任何地方都适用 |
| **Docker 就绪** | 单命令容器部署 |
## 快速开始
### 安装
```bash
pip install dcc-mcp-fpt
```
或使用 uv：
```bash
uv pip install dcc-mcp-fpt
```
### 配置
设置您的 ShotGrid 凭证：
```bash
export SHOTGRID_URL="https://mysite.shotgrid.autodesk.com"
export SHOTGRID_SCRIPT_NAME="my_script_name"
export SHOTGRID_SCRIPT_KEY="my_script_key"
export SHOTGRID_PROJECT="my_project_code"
export SHOTGRID_PERMISSION_LEVEL="read"
```
### 本地运行
最短的本地路径是：
```bash
uvx dcc-mcp-fpt
```
默认情况下，适配器绑定一个 OS-assigned 实例端口，并在 `http://127.0.0.1:9765/mcp` 启用稳定的本地网关。使用 `dcc-mcp-cli list` 检查直接端点。如果网关已在该端口上运行，则此 FPT 适配器注册到它；否则，核心网关选举路径可以为本地会话拥有网关端口。
仅在不需要网关注册时使用独立模式：
```bash
uvx dcc-mcp-fpt --no-gateway
# 与以下命令相同：uvx dcc-mcp-fpt --gateway-port 0
```
开发检查：
```bash
python -m dcc_mcp_fpt
just serve-gateway
just serve-standalone
```
ASGI 模式适用于 uvicorn/gunicorn：
```bash
uvicorn dcc_mcp_fpt.asgi:app --host 0.0.0.0 --port 8000
```
### IDE MCP 配置
对于支持 Streamable HTTP MCP 的 IDE，请将 IDE 指向网关 URL：
```json
{
"mcpServers": {
"shotgrid": {
"url": "http://127.0.0.1:9765/mcp"
}
}
}
```
如果您的 IDE 只支持 stdio MCP，请直接使用 `uvx`:
```json
{
"mcpServers": {
"shotgrid": {
"command": "uvx",
"args": ["dcc-mcp-fpt", "stdio", "--no-gateway"],
"env": {
"SHOTGRID_URL": "https://mysite.shotgrid.autodesk.com",
"SHOTGRID_SCRIPT_NAME": "my_script_name",
"SHOTGRID_SCRIPT_KEY": "my_script_key",
"SHOTGRID_PROJECT": "my_project_code",
"SHOTGRID_PERMISSION_LEVEL": "read"
}
}
}
}
```
### mcpcall
在 `uvx dcc-mcp-fpt` 运行后，通过网关进行烟雾测试：
```bash
mcpcall doctor --url http://127.0.0.1:9765/mcp --json
mcpcall list --url http://127.0.0.1:9765/mcp --json
mcpcall call --url http://127.0.0.1:9765/mcp shotgrid-discovery__check_connection
mcpcall call --url http://127.0.0.1:9765/mcp shotgrid-discovery__get_server_info
```
您还可以导入 IDE 使用的相同 `mcpServers` JSON：
```bash
mcpcall config import --from ./mcp.json --output ./mcpcall.json
mcpcall list --config ./mcpcall.json --server shotgrid --json
```
## 工具表面
### 基础（预加载）
| 技能 | 工具 |
|-------|-------|
| `shotgrid-discovery` | `check_connection`, `list_entity_types`, `get_server_info` |
| `shotgrid-setup` | `generate_agent_config`, `validate_runtime_config` |
| `shotgrid-users` | `whoami` |
| `shotgrid-schema` | `get_schema`, `get_field_schema`, `list_entity_types` |
### 场景（按需加载）
| 技能 | 工具 |
|-------|-------|
| `shotgrid-crud` | `find_entities`, `find_one_entity`, `create_entity`, `update_entity`, `delete_entity` |
| `shotgrid-search` | `search_entities`, `search_by_name` |
### 作者
| 技能 | 工具 |
|-------|-------|
| `shotgrid-note` | `create_note`, `find_notes`, `update_note` |
### 管道
| 技能 | 工具 |
|-------|-------|
| `shotgrid-batch` | `batch_operations` |
## 架构
```
AI 代理（Claude、Cursor、Copilot）
│
│ MCP 协议（stdio / HTTP / ASGI）
▼
┌───────────────────────────────┐
│ ShotGridMcpServer │
│ （DccServerBase 适配器） │
│ │
│ ┌─────────────────────────┐ │
│ │ 技能目录 │ │
│ │ （渐进加载） │ │
│ └───────────┬─────────────┘ │
│ │ │
│ ┌───────────▼─────────────┐ │
│ │ 主机执行桥 │ │
│ │ → ShotGridClient │ │
│ └───────────┬─────────────┘ │
│ │ │
│ ┌───────────▼─────────────┐ │
│ │ 连接池 │ │
│ │ 模式缓存 │ │
│ └───────────┬─────────────┘ │
└──────────────┼────────────────┘
│
│ shotgun_api3（REST）
▼
┌─────────────────┐
│ ShotGrid API │
│ （Autodesk FPT） │
└─────────────────┘
```
## 配置
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `SHOTGRID_URL` | 是 | ShotGrid 服务器 URL |
| `SHOTGRID_SCRIPT_NAME` | 是 | 脚本/API 用户名 |
| `SHOTGRID_SCRIPT_KEY` | 是 | 脚本/API 用户密钥 |
| `SHOTGRID_PROJECT` | 否 | 默认项目名称、代码或 tank 名称，用于作用域工具 |
| `SHOTGRID_PROJECT_ID` | 否 | 默认项目 ID；设置时覆盖 `SHOTGRID_PROJECT` |
| `SHOTGRID_PERMISSION_LEVEL` | 否 | 回退权限级别：`read`、`write` 或 `admin` |
| `SHOTGRID_PROJECT_PERMISSIONS` | 否 | JSON 或 CSV 每项目权限允许列表 |
| `SHOTGRID_READ_ONLY` | 否 | 设置为 `1` 以阻止 create/update/delete，独立于级别 |
| `DCC_MCP_GATEWAY_PORT` | 否 | dcc-mcp 网关端口；设置为 `0` 以运行独立 |
| `DCC_MCP_REGISTRY_DIR` | 否 | 共享网关注册目录 |
| `DCC_MCP_FPT_GATEWAY_SCENE` | 否 | 网关上下文标签；默认为 `project:<SHOTGRID_PROJECT>` |
| `DCC_MCP_FPT_GATEWAY_DISPLAY_NAME` | 否 | 网关/admin 界面中显示的人类可读标签 |
| `DCC_MCP_FPT_ENABLE_GATEWAY_FAILOVER` | 否 | 设置为 `0` 以禁用核心网关选举/故障转移 |
| `DCC_MCP_FPT_SKILL_PATHS` | 否 | FPT 特定自定义技能根（Windows 上为 `;`，Unix 上为 `:`） |
| `DCC_MCP_SKILL_PATHS` | 否 | 所有 dcc-mcp 适配器共享的全局自定义技能根 |
| `DCC_MCP_SHOTGRID_MINIMAL` | 否 | 以逗号分隔的最小模式技能列表 |
| `DCC_MCP_SHOTGRID_DEFAULT_TOOLS` | 否 | 以逗号分隔的默认激活工具列表 |
### 项目范围和权限
CRUD 和批量工具接受可选的 `project`、`project_id` 和 `project_scoped` 输入。当配置了默认项目时，读取添加 ShotGrid `project` 过滤器，创建时注入 `data.project`（如果缺少），更新/删除在修改数据之前验证项目所有权。
权限级别故意简单：
| 级别 | 允许 |
|-------|--------|
| `read` | `find`、`find_one`、模式、连接检查 |
| `write` | `read` 加上 create/update 和非 delete 批量项目 |
| `admin` | `write` 加上 delete/retire |
示例：
```bash
export SHOTGRID_PROJECT="my_project_code"
export SHOTGRID_PERMISSION_LEVEL="write"
export SHOTGRID_PROJECT_PERMISSIONS='{"my_project_code":"write","id:456":"read"}'
```
### 网关集成
适配器使用与 Maya、Blender、Houdini 和 3ds Max 适配器相同的 `DccServerOptions.from_env(...)` 网关合约。当 `DCC_MCP_GATEWAY_PORT` 或 `--gateway-port` 设置为正值时，服务器发布 FPT 运行时条目，具有安全显示名称、项目感知场景标签、版本和网关选举诊断。
```bash
export SHOTGRID_PROJECT="my_project_code"
export DCC_MCP_GATEWAY_PORT=9765
export DCC_MCP_FPT_GATEWAY_DISPLAY_NAME="FPT my_project_code"
just serve-gateway
```
使用 `--gateway-port 0` 或 `just serve-standalone` 进行本地独立测试。`shotgrid-discovery__get_server_info` 工具包括一个 `gateway` 诊断对象，以便代理和 CI 可以确认此实例是否加入了网关。
### 请求范围凭证
HTTP MCP 客户端不会将 `mcp.json.env` 注入到已经运行的网关中。对于共享网关部署，请在适配器端配置文件中保留 ShotGrid 机密，并通过 MCP `_meta` 传递请求上下文。核心 PIP-520，调用者身份位于 `_meta.agent_context` 下，而凭证和策略控制位于顶级 `_meta` 字段：
```json
{
"_meta": {
"agent_context": {
"requester_id": "hallong",
"requester_type": "human"
},
"credential_profile": "sg-read-zombie",
"permission_hint": "read",
"project_scope": "my_project_code"
}
}
```
旧客户端仍然发送 `credential_profile`、`permission_hint` 或 `project_scope` 进入 `_meta.agent_context` 作为后备，但新代理应使用上面的 PIP-520 顶级 `_meta` 形状。
配置文件可以作为 JSON 提供 `DCC_MCP_FPT_CREDENTIAL_PROFILES` 或通过 `DCC_MCP_FPT_CREDENTIAL_PROFILES_FILE` 中的 JSON 文件：
```json
{
"sg-read-zombie": {
"url": "https://mysite.shotgrid.autodesk.com",
"script_name": "sg_read_bot",
"script_key": "<secret stored outside chat>",
"permission_level": "read",
"read_only": true,
"project": "my_project_code"
}
}
```
`permission_hint` 只能降低有效策略。它与 env/profile 策略通过最低权限合并，因此代理无法将 read 配置文件变成 write/admin。内联凭证被拒绝，除非 `DCC_MCP_ALLOW_INLINE_CREDENTIALS=1` 为本地开发设置。
### 代理设置技能
`shotgrid-setup` 预加载，以便代理可以在猜测存储库约定的情况下进行配置：
```bash
mcpcall call --url http://127.0.0.1:9765/mcp shotgrid-setup__validate_runtime_config
mcpcall call --url http://127.0.0.1:9765/mcp shotgrid-setup__generate_agent_config target=all
```
生成的配置包括 `uvx dcc-mcp-fpt`、HTTP/stdio IDE 代码片段、`mcpcall` 命令、Docker 示例和自定义技能路径环境变量。机密值默认情况下会被遮蔽。
### 自定义技能
将 `DCC_MCP_FPT_SKILL_PATHS` 指向技能包目录或包含多个技能包文件夹的父目录：
```bash
# Windows 使用分号分隔多个根目录。
set DCC_MCP_FPT_SKILL_PATHS=C:\studio\fpt-skills;C:\show\fpt-skills
# Linux/macOS 使用冒号。
export DCC_MCP_FPT_SKILL_PATHS=/studio/fpt-skills:/show/fpt-skills
uvx dcc-mcp-fpt
```
使用 `DCC_MCP_SKILL_PATHS` 适用于共享跨适配器的技能。网关管理员技能路径注册表也会被 dcc-mcp-core 在启动/重新加载时拾取。
### 容器部署
构建并本地运行：
```bash
docker build -t dcc-mcp-fpt .
docker run --rm \
-p 9765:9765 \
--env-file .env \
dcc-mcp-fpt
```
将自定义技能注入到 `/skills` 目录中；镜像默认设置 `DCC_MCP_FPT_SKILL_PATHS=/skills`：
```bash
docker run --rm \
-p 9765:9765 \
--env-file .env \
-v /studio/fpt-skills:/skills:ro \
dcc-mcp-fpt
```
Docker Compose（包括健康检查和优雅关闭）：
```bash
docker compose -f docker-compose.yml up -d
```
对于每个用户凭证配置文件，请使用配置文件叠加层：
```bash
# 1. Create fpt-credential-profiles.json (see Per-User Access below)
# 2. Launch with profiles compose file
docker compose -f docker-compose.yml -f docker-compose.profiles.yml up -d
```
### 健康检查
稳定的网关公开 `/health` 供容器探针和平台监控使用：
```bash
curl http://localhost:9765/health
# {"status": "ok", "version": "dcc-mcp-fpt/0.1.2", "sg_configured": true}
```
- `sg_configured: true` 表示 ShotGrid 凭证可用。
- 没有机密被暴露 — 该字段是一个布尔值，源自 `SHOTGRID_URL` 的存在。
- 只要 `dcc-mcp-core` 没有安装，端点就有效。
### 代理平台部署
适配器设计用于在 OpenClaw、Harness 和其他 MCP 兼容的代理平台上运行。参见 `deployment/OPENCLAW.md` 和 `deployment/HARNESS.md` 以获取平台特定的配置指南。
关键平台功能：
- **优雅关闭**：处理 `SIGTERM` 以实现干净的编排停止。
- **健康端点**：`/health` 用于 Kubernetes 存活/就绪探针。
- **无状态 + 配置文件**：部署一个实例；通过 `_meta` 为每个请求选择凭证。
- **网关注册**：可选地加入 dcc-mcp 网关以实现统一路由。
### 使用 whoami 进行用户访问
`shotgrid-users` 技能提供了一个 `whoami` 工具，用于在不暴露机密的情况下报告有效的 ShotGrid 身份。使用它来确认哪个凭证配置文件和权限级别处于活动状态：
```bash
mcpcall call --url http://127.0.0.1:9765/mcp shotgrid-users__whoami
```
使用请求范围配置文件：
```bash
mcpcall call --url http://127.0.0.1:9765/mcp shotgrid-users__whoami \
--meta '{"credential_profile":"sg-read-zombie","project_scope":"demo"}'
```
响应包括 `script_name`、`url`、`permission_level`、`credential_profile` 和 `credential_source` — 但永远不会是 `api_key`。
## 开发
```bash
git clone https://github.com/dcc-mcp/dcc-mcp-fpt.git
cd dcc-mcp-fpt
# Install with dev deps
uv pip install -e ".[dev]"
# Run tests
pytest --cov=src/dcc_mcp_fpt --cov-report=term
# Lint
ruff check src/ tests/
# Format
ruff format src/ tests/
```
### 本地实时 CRUD 烟雾测试
复制 `.env.example` 到 `.env`，填写本地凭证，并保持文件不跟踪。干运行命令验证配置并跳过突变：
```bash
just install-dev
just live-crud-smoke-dry
```
要在配置的项目上运行真正的本地创建/查找/更新/删除循环，请设置一个具有管理员权限的策略，并运行：
```bash
export SHOTGRID_PERMISSION_LEVEL="admin"
export SHOTGRID_LIVE_CRUD_CONFIRM=1
just live-crud-smoke
```
烟雾测试会在清理时创建临时实体，更新它，并在完成后删除它。
## CI/CD
- `CI` 在 Linux、Windows 和 macOS 上运行 Python 3.8-3.12。
- 校验、格式检查、捆绑技能元数据校验、CLI 烟雾测试、包构建、Docker 构建是单独的关卡。
- `Release` 使用 release-please，构建 wheel/sdist 工件，发布到 PyPI Trusted Publishing，并将 dist 文件附加到 GitHub Release。
- `Live ShotGrid Smoke` 是手动的，仅使用 GitHub Secrets；它默认为 dry-run 行为，除非启用 CRUD 确认。
- E2E 测试涵盖所有 8 个技能包、服务器生命周期、健康端点、凭证配置文件加载和权限策略解析。
## 需求
- Python 3.8+
- [dcc-mcp-core](https://github.com/dcc-mcp/dcc-mcp-core) >= 0.18.2,<1.0.0
- [shotgun_api3](https://github.com/shotgunsoftware/python-api) >= 3.4.0
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
## 相关
- [dcc-mcp-core](https://github.com/dcc-mcp/dcc-mcp-core) — 核心运行时和共享工具
- [shotgrid-mcp-server](https://github.com/loonghao/shotgrid-mcp-server) — 原始 FastMCP 实现
- [dcc-mcp-maya](https://github.com/dcc-mcp/dcc-mcp-maya) — Maya 适配器参考
- [dcc-mcp-blender](https://github.com/dcc-mcp/dcc-mcp-blender) — Blender 适配器参考
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器