fpt-mcp

使用模型上下文协议（MCP）将Claude连接到Autodesk Flow生产跟踪（ShotGrid）进行生产管理

\[！警告\] 实验项目——使用风险自负。 这是一个独立的、非官方的实验，由克劳德代码确实如此不以任何方式隶属于Autodesk、得到Autodesk认可或得到Autodesk官方支持。ShotGrid/Flow Production Tracking的名称和商标属于Autodesk，股份有限公司。允许对实时ShotGrid实例进行人工智能生成的操作会带来真正的风险： 意外的数据修改、意外的实体删除、不正确的发布或元数据损坏。 始终先对专用沙盒项目进行测试。在不了解正在执行的操作的情况下，切勿对生产数据运行此操作。作者对因使用数据而导致的数据丢失、损坏或任何其他损害不承担任何责任。

MCP服务器 Autodesk Flow生产跟踪 （前身为ShotGrid）。

为任何兼容MCP的AI助手（Claude Desktop、Claude Code或任何MCP客户端）提供对ShotGrid API、Toolkit路径解析和防止常见API幻觉的RAG-powered知识引擎的完全访问。

Claude Desktop / Claude Code / any MCP client
└── fpt-mcp
        ├── stdio         → Claude Desktop / Claude Code
        ├── HTTP          → scripts, inter-service calls
        └── Qt console    → native chat app via fpt-mcp:// protocol handler

特性

不受限制的ShotGrid API访问

fpt-mcp公开了完整的 shotgun_api3 Python SDK，不锁定实体类型或字段。任何实体——资产、镜头、序列、版本、任务、已发布文件或自定义实体——都可以通过一组一致的工具进行查询、创建、更新、删除或批处理。这很重要，因为生产管道差异很大：服务器从不假设工作室使用哪种实体类型或字段名称。

Toolkit路径解析

当项目在ShotGrid中具有高级设置时，服务器会查询 PipelineConfiguration 实体，读取 roots.yml 和 templates.yml 直接从已安装的Toolkit配置中，并使用项目的真实模板定义解析发布路径。没有路径是硬编码的——该解析使用安装的任何tk配置，无论是默认的、自定义的还是分叉的。没有PipelineConfiguration的项目仍然可以通过显式路径回退获得完全的发布支持。

RAG防幻觉发动机

LLM不断幻觉ShotGrid API的详细信息-无效的筛选器运算符、错误的实体引用格式、不存在的Toolkit模板令牌。fpt-mcp通过混合检索系统来应对这一点：在查询时， search_sg_docs 对三个经过验证的API参考文档执行语义搜索（ChromaDB+BAAI/bg-target-en-v.1.5）和词汇搜索（BM25），将排名与RRF融合，并将最相关的块注入Claude的上下文中。第一次尝试的结果是正确的过滤器语法和有效的实体格式，而不是第三次。

安全层

这 safety.py 该模块在执行之前根据十二个正则表达式模式扫描每个工具调用，这些正则表达式模式涵盖了最具破坏性的操作：没有特定ID的批量删除、没有限制的未过滤查询、发布路径中的路径遍历、PublishedFile删除、无效的过滤运算符、大批量操作和模式修改。被阻止的操作返回带有安全替代方案的警告-它们永远不会到达ShotGrid API。

Qt控制台和协议处理程序

fpt-mcp提供了一个原生PySide6聊天窗口，该窗口通过Claude Code CLI路由消息，并在完全支持Markdown的情况下呈现响应。控制台注册 fpt-mcp:// macOS上的自定义URL方案，这意味着ShotGrid操作菜单项可以通过单击打开一个聊天窗口，其中预先填充了完整的实体上下文（实体类型、ID、项目），无需浏览器选项卡，也无需复制粘贴ID。

需求

Python>=3.10
macOS（用于协议处理程序；Qt控制台也可以在没有协议处理程序的Linux/Windows上工作）
shotgun_api3 （ShotGrid Python API）
mcp[cli] （带FastMCP的MCP Python SDK）
pydantic >= 2.0
PySide6 >=6.6（Python的Qt）
python-dotenv
httpx
pyyaml （Toolkit配置解析）
chromadb >=0.5.0（RAG矢量数据库）
sentence-transformers >=2.2.0（RAG嵌入——BAAI/bge-large-en-v1.5）
rank-bm25 >=0.2.2（RAG词汇搜索）
克劳德代码CLI(npm install -g @anthropic-ai/claude-code)

可选--使用Ollama进行本地/自由推理：

奥拉玛 >= 0.17.6

- macOS： brew install ollama && brew services start ollama - Linux：https://ollama.com/download/linux（系统d） - 验证： ollama --version

创建 qwen3.5-mcp 型号（Ollama后端所需）：

  ollama pull qwen3.5:9b
  cat > /tmp/Modelfile.qwen35mcp  \[！重要\]
> 跑步 `setup_venv.sh` 或 `install.sh` 就其本身而言 **不够**.
> 安装程序创建 `.env` 从模板中删除，但保留字段
> 保存占位符值。直到你编辑 `.env` 与你的真实
> ShotGrid凭据，每次MCP调用都会因SSL而失败
> `CERTIFICATE_VERIFY_FAILED` 错误。

复制 `.env.example` → `.env` （或让安装人员来做）并更换
**每** 字段中包含您的真实值：

SHOTGRID_URL=https://your-actual-site.shotgrid.autodesk.com SHOTGRID_SCRIPT_NAME=your-actual-script-name SHOTGRID_SCRIPT_KEY=your-actual-application-key SHOTGRID_PROJECT_ID=123


**每个字段的来源**:

- `SHOTGRID_URL` --您通过浏览器登录ShotGrid网站时使用的确切URL，格式为 `https://.shotgrid.autodesk.com`.
- `SHOTGRID_SCRIPT_NAME` -在中注册的API脚本的名称 **ShotGrid管理员→ 脚本**。如果您没有具有所需权限的程序，请先在那里创建。
- `SHOTGRID_SCRIPT_KEY` --the **应用键** 显示在同一管理页面中脚本名称旁边。
- `SHOTGRID_PROJECT_ID` --您最常参与的项目的整数ID。用作默认筛选器 `sg_find`, `sg_create`, `sg_upload`，并作为Toolkit的关键 `PipelineConfiguration` 查找。设置为 `0` 禁用默认筛选器（然后每次调用都必须显式指定项目）。

编辑后 `.env`，重新启动任何正在运行的fpt-mcp进程（Qt控制台、mcp服务器），使其获取新值。

安装程序脚本现在可以检测中留下的占位符值 `.env` 并在安装结束时发出可见警告。MCP服务器本身也将拒绝启动，并显示一条明确的错误消息，指向 `.env` 如果占位符仍然存在。这两种保护措施都是为了防止在第一次实际调用时出现混淆的SSL错误。

### 验证凭据

编辑后 `.env`，运行医生以验证端到端的连接：

./install.sh --doctor


医生进行五次独立检查——claude.json注册， `.env` 占位符检测、供应商可导入性、实时ShotGrid API连接和Qt依赖性可用性。任何 `FAIL` 该行包含一个具体的补救句。

**常见陷阱：**

- **占位符值保留在 `.env`** --最常见的原因 `CERTIFICATE_VERIFY_FAILED` 首次使用时出现错误。医生会自动检测到这些。
- **`SHOTGRID_PROJECT_ID=0`** --禁用默认项目范围。每 `sg_find`, `sg_create`，以及 `sg_upload` 然后，调用必须显式指定项目筛选器。这适用于多项目工作流，但不适用于单项目设置。
- **脚本密钥与用户凭据** --the `.env` 钥匙是一个 **API脚本密钥** 来自管理员→ 脚本，而不是您的个人登录密码。
- **陈旧的 `.env` 站点迁移后** --如果ShotGrid站点URL更改（例如在Autodesk ID迁移期间），请更新 `SHOTGRID_URL` 并重新运行 `--doctor`.

## 用法

配置后，fpt-mcp可以通过Claude Code、Claude Desktop或Qt控制台使用。连接到ShotGrid实例并开始对话：

You: "Find all Character assets in the Sunrise project that are currently in Pending Review" Claude → search_sg_docs (filter syntax for Asset) → sg_find (entity=Asset, filters=[project, sg_asset_type, sg_status_list]) → Returns asset list with name, status, and assigned tasks

You: "Create a new Shot called sh0150 in sequence SQ010 for project Sunrise, cut in 1001 cut out 1024" Claude → search_sg_docs (Shot entity format) → sg_create (entity=Shot, fields={code, sg_sequence, project, sg_cut_in, sg_cut_out}) → Shot created and linked to sequence

You: "Publish /jobs/sunrise/assets/char_hero/maya/publish/char_hero_v003.ma to the Rigging task on asset Hero" Claude → search_sg_docs (publish pattern) → tk_resolve_path (PipelineConfiguration lookup) → tk_publish (copy file, find/create PublishedFileType, link Task, register PublishedFile) → Publish registered in ShotGrid

You: "How do I filter Versions by review status using the ShotGrid Python API?" Claude → search_sg_docs (status filter operators, Version entity) → Returns verified filter syntax, valid operator names, and a working code example from the RAG knowledge base


## 工具（14个MCP工具注册——调度器模式）

没有实体限制的通用工具——适用于任何ShotGrid实体类型和字段。批量和报告操作被整合到两个调度工具后面，以减少LLM的工具数量开销。

### ShotGrid API-直接工具（6个工具）

|工具|说明|
|------|-------------|
| `sg_find` |使用任何筛选器和字段搜索任何实体类型|
| `sg_create` |使用任何字段创建任何实体（项目自动链接）|
| `sg_update` |更新任何实体上的任何字段|
| `sg_schema` |检查任何实体类型的可用字段|
| `sg_upload` |将文件上传到任何实体字段（缩略图、电影、附件）|
| `sg_download` |从任何实体字段下载附件|

### ShotGrid API-批量调度程序(`fpt_bulk` --1个工具，3个动作）

|动作|描述|
|--------|-------------|
| `fpt_bulk(action="delete")` |软删除（退役）任何实体。可以从垃圾中恢复|
| `fpt_bulk(action="revive")` |恢复以前退役的实体|
| `fpt_bulk(action="batch")` |事务性批量操作——全部成功或全部失败|

### ShotGrid API-报告调度程序(`fpt_reporting` --1个工具，4个动作）

|动作|描述|
|--------|-------------|
| `fpt_reporting(action="text_search")` |同时跨多个实体类型进行全文搜索|
| `fpt_reporting(action="summarize")` |服务器端聚合：计数、总和、平均值、最小值、最大值，带分组|
| `fpt_reporting(action="note_thread")` |阅读包含所有嵌套回复的笔记的完整回复线程|
| `fpt_reporting(action="activity")` |读取实体的活动流（更新、状态更改、注释）|

### 工具包（2个工具）

|工具|说明|
|------|-------------|
| `tk_resolve_path` |从项目的真实PipelineConfiguration解析发布路径|
| `tk_publish` |发布文件：解析路径、复制文件、查找/创建PublishedFileType、链接任务、在ShotGrid中注册|

### 启动器（1个工具）

|工具|说明|
|------|-------------|
| `fpt_launch_app` |启动一个作用域为ShotGrid实体的DCC（今天是Maya）。操作系统首次发现，Toolkit `tank` 在可用时进行路由， `open -a` 退路。返回包含以下内容的启动计划 `pid`, `argv`, `launch_method`, `warnings`。参见 [启动器先决条件](#launcher-prerequisites) 首次使用前。 |

### RAG-API知识引擎（3个工具）

|工具|说明|
|------|-------------|
| `search_sg_docs` |通过ShotGrid API文档（ChromaDB+BM25+HyDE+RRF）进行混合搜索。返回相关的API模式、正确的筛选器语法和实体格式示例。 **在复杂查询之前自动调用** |
| `learn_pattern` |持久化验证API模式到知识库中。模型信任门：Sonnet/Opus直接编写，其他模型阶段候选人供人工审查|
| `session_stats` |令牌使用统计：调用、令牌进出、RAG节省、缓存命中率、效率比|

## 方法

通过以下方式完全访问ShotGrid API `shotgun_api3` 没有实体限制。

### 工具包路径解析

**具有高级设置的项目** （存在流水线配置）：

服务器查询 `PipelineConfiguration` ShotGrid中的实体，读取本地 `roots.yml` 和 `templates.yml`，并使用项目的真实Toolkit配置解析发布路径。这适用于本地配置， `dev` 描述符和分布式配置。没有硬编码的模板——路径来自实际的tk配置。

**没有高级设置的项目：**

如果没有 `PipelineConfiguration` 发现， `tk_publish` 要求明确的发布路径。文件被复制到给定位置，并在ShotGrid中注册为PublishedFile→ 文件管理→ 本地文件存储），路径将可从ShotGrid web UI解析。如果没有本地存储，路径仍存储在PublishedFile中 `path` 字段，任何读取它的脚本或加载器都可以访问。

这 `tk_config.py` 模块读取安装的任何Toolkit配置——默认、自定义或分叉。

### 启动器先决条件

`fpt_launch_app` 使用操作系统优先解析器(`software_resolver.py`)在本地计算机上查找DCC二进制文件，然后将启动升级为通过Toolkit的路由 `tank` 当项目具有高级设置PipelineConfiguration时，使用CLI。在新机器上，在工具可以在上下文中启动DCC之前，需要两个一次性设置步骤：

**1.Tank CLI身份验证（每个用户、每个站点）**

工具箱 `tank` CLI有自己的基于浏览器的身份验证，独立于ShotGrid Python API使用的脚本密钥。缓存的会话会定期过期。首次使用时（或过期后），您必须以交互方式运行一次：

/path/to/PipelineConfiguration/tank


CLI将打开Autodesk SSO浏览器，进行批准，会话令牌将缓存在 `~/Library/Caches/Shotgun//`之后，所有后续的坦克调用，包括 `fpt_launch_app` 产卵——非交互式工作。

如果你看到一个错误，比如 `EOF when reading a line` 或 `Authentication ... expired` 通话时 `fpt_launch_app`，您的坦克训练需要通过上述手动步骤进行刷新。

**2. `bundle_cache_fallback_roots` 在pipeline_configuration.yml中**

由创建的经典高级设置配置 `setup_project` 期望捆绑包（引擎、应用程序、框架）能够生存 `/install/engines/`, `/install/apps/`等等。当配置设置时没有运行包缓存步骤，或者当它通过全局ShotGrid缓存与其他项目共享包时，本地 `install/` 目录将仅包含 `core/` 油箱将出现故障 `Cannot start engine! tk-shell v does not exist on disk`.

通过添加回退路径来修复 `/config/core/pipeline_configuration.yml`:

pc_id:

pc_name: Primary project_id:

project_name:

published_file_entity_type: PublishedFile use_shotgun_path_cache: true bundle_cache_fallback_roots: - /Users//Library/Caches/Shotgun/bundle_cache


这是一个附加的变化：经典的本地化捆绑包 `/install/` 在场时仍然获胜；回退仅适用于不在本地安装目录中但存在于之前FPT桌面同步的全局ShotGrid缓存中的捆绑包。

**3.坦克指挥命名约定**

`tk-multi-launchapp` 根据管道的不同，在两个常用名称下注册其启动器命令：

- `launch_` --当管道公开单个DCC版本时的默认值。
- `_` --管道为每个安装的版本注册一个启动器时的惯例(`maya_2027`, `nuke_16.0v4`等等）。

`fpt_launch_app` 当操作系统扫描从安装路径解析版本时，首选特定于版本的形式，并回退到 `launch_` 否则。具有另一种约定的管道将需要一个映射到正确油箱命令的包装器。

## RAG——抗幻觉引擎

fpt-mcp包括一个混合Retrieval-AugedGeneration（RAG）系统，该系统在查询时为Claude提供经过验证的ShotGrid API知识，消除了常见的幻觉，如无效的过滤器运算符、错误的实体引用格式和错误的Toolkit模板令牌。

### 建筑

User query → search_sg_docs tool ↓ ┌───────┴───────┐ │ HyDE Expander │ ← Adaptive: detects shotgun_api3 / Toolkit / REST └───────┬───────┘ ↓ ┌───────────┼───────────┐ │ │ │ ChromaDB BM25 Index In-session (semantic) (lexical) Cache │ │ └─────┬─────┘ ↓ RRF Fusion (k=60) ↓ Top-N chunks + relevance score


### 技术栈

|组件|技术|目的|
|-----------|-----------|---------|
|矢量数据库|色度数据库（持久）|余弦相似度语义搜索|
|嵌入|BAAI/bge-large-en-v1.5|文档和查询编码（~570 MB模型）|
|词汇搜索|BM25Okapi（rank_bm25）|Exact API方法名称匹配|
|查询扩展|HyDE（自适应）|在嵌入之前生成特定领域的假设代码|
|排名融合|RRF（k=60）|结合语义+BM25排名，无需分数校准|
|安全| 12+正则表达式模式|执行前检测危险操作|
|令牌跟踪|会话统计|衡量RAG使用的令牌与保存的令牌，计算效率|
|自我学习|学习模式+模型门|从经过验证的模式中扩展知识库|
|缓存|会话内字典|避免会话内冗余的ChromaDB查询|

### 知识库

RAG索引了涵盖不同领域的三个ShotGrid API参考文档：

|文档|内容|大小|
|----------|---------|------|
| `docs/SG_API.md` |shotgun_api3 Python SDK--方法、按字段类型筛选运算符、实体格式规则、反模式|~7 KB|
| `docs/TK_API.md` |Toolkit（sgtk）--PipelineConfiguration发现、模板标记（区分大小写）、描述符类型、路径解析|~7KB|
| `docs/REST_API.md` |REST API-比较表与Python SDK，过滤语法差异|~2.5 KB|

### HyDE自适应扩展

与一般的HyDE不同，fpt-mcp检测查询的目标API域，并生成特定于域的假设文档：

- **工具包查询** （模板、发布路径、roots.yml）→ 生成 `import sgtk` 代码框架
- **REST API查询** （oauth、承载者、端点）→ 生成 `import requests` HTTP框架
- **默认** （大多数查询）→ 生成 `from shotgun_api3 import Shotgun` 骨架

这产生了更接近相关语料库部分的嵌入，提高了检索精度。

### 危险模式检测

这 `safety.py` 模块在执行前扫描工具参数，并阻止或警告危险操作：

- 无特定ID的批量删除
- 无限制的未过滤搜索（返回整个数据库）
- 实体引用格式错误（int而不是 `{type, id}` 字典
- 发布路径中的路径遍历(`../`)
- 模式修改（字段创建/删除）
- 已发布文件删除（中断Toolkit引用）
- 无效的筛选运算符（LLM产生幻觉）
- 大批量操作（>100个实体）
- 模板令牌不正确

### 构建RAG指数

安装依赖项后，从文档语料库构建ChromaDB索引：

From the project directory, with venv activated:

source .venv/bin/activate python -m fpt_mcp.rag.build_index


这将创建持久的ChromaDB数据库和BM25 corpus.json。第一次运行下载BAAI/bge-large-en-v1.5嵌入模型（约570 MB）。只有当文档文件位于 `docs/` 改变。

## 自我学习

当 `search_sg_docs` 返回低相关性得分（低于60%），但操作成功，Claude可以调用 `learn_pattern` 将工作模式持久化到知识库中，以备将来会议使用。 **模型信任门** 控制谁可以直接写：十四行诗和Opus立即写到语料库；其他模型阶段候选人 `rag/candidates.json` 在晋升前进行人工审核。RAG分数低的失败操作记录到 `rag/failed.json` 作为知识空白，可以很容易地确定哪些API领域需要更好的文档覆盖。

## 令牌跟踪

每次工具调用都会跟踪代币的进出。这 `session_stats` 该工具报告了完整的会话细分：总调用数、使用的令牌、RAG保存的令牌（与加载原始文档相比）、缓存命中率、学习的模式和效率比。这使得RAG的节省是可衡量和可见的，而不是隐含的。

## 运输

### stdio（克劳德桌面/克劳德代码）

默认模式。服务器通过标准输入/输出作为子流程进行通信。

python -m fpt_mcp.server


### HTTP（服务间、脚本）

在网络端口上运行，因此Maya、Flame和脚本可以通过TCP连接。

python -m fpt_mcp.server --http # port 8090 (default) python -m fpt_mcp.server --http --port 9000 # custom port


## Qt控制台（原生聊天应用程序）

原生PySide6聊天窗口，通过Claude Code CLI路由消息。用适当的桌面应用程序替换基于浏览器的AMI控制台。

特征：

- Markdown渲染（粗体、斜体、代码、标题、列表）
- 深色主题与ShotGrid美学相匹配
- 协议处理程序(`fpt-mcp://`)用于从ShotGrid AMI直接发射
- ShotGrid实体上下文通过URL参数自动传递
- 轻负载支持（从EventLogEntry API获取完整上下文）
- 无HTTP服务器依赖性——作为独立应用程序启动

### 发射

Direct

fpt-console

With entity context

fpt-console --entity-type Shot --entity-id 456 --project-id 123

Via protocol handler (from ShotGrid AMI or terminal)

open "fpt-mcp://chat?entity_type=Asset&selected_ids=123&project_id=456"


### ShotGrid AMI设置

管理员→ 操作菜单项→ Add:

- **标题**：FPT控制台
- **实体类型**：资源、镜头、序列、版本、任务（或任何）
- **统一资源定位符**: `fpt-mcp://chat`

ShotGrid自动附加实体上下文参数(`entity_type`, `selected_ids`, `project_id`, `project_name`, `user_login`)到自定义协议URL。不要添加 `{placeholder}` 令牌——它们仅用于替换 `http://` 和 `https://` URL。

如果 **轻型有效载荷** 在AMI配置中启用，ShotGrid仅发送 `event_log_entry_id` 而不是完整的实体上下文。Qt控制台自动检测到这一点，并通过 `EventLogEntry.meta.ami_payload`。这需要中的有效ShotGrid API凭据 `.env`.

在ShotGrid中更改AMI URL后，您可能需要硬刷新浏览器（Cmd+Shift+R）以清除缓存的AMI配置。

当从AMI启动时，实体上下文显示在标题徽章中，并包含在发送给Claude的每条消息中。

## 客户端配置

### 克劳德桌面版

添加 `~/Library/Application Support/Claude/claude_desktop_config.json`:

{ "mcpServers": { "fpt-mcp": { "command": "/path/to/fpt-mcp/.venv/bin/python", "args": ["-m", "fpt_mcp.server"], "cwd": "/path/to/fpt-mcp", "env": { "SHOTGRID_URL": "https://yoursite.shotgrid.autodesk.com", "SHOTGRID_SCRIPT_NAME": "your_script_name", "SHOTGRID_SCRIPT_KEY": "your_key", "SHOTGRID_PROJECT_ID": "123" } } } }


这 `cwd` 字段是必需的，以便服务器可以找到 `.env` 文件并正确解析相对路径。

### 克劳德代码

克劳德代码使用 **两个单独的文件** 对于MCP配置：

**1.MCP服务器定义** — `~/.claude.json` （注意：文件在home目录中，而不是内部 `~/.claude/`):

Add the server via CLI (recommended):

claude mcp add fpt-mcp -s user -e SHOTGRID_URL=https://yoursite.shotgrid.autodesk.com -e SHOTGRID_SCRIPT_NAME=your_script_name -e SHOTGRID_SCRIPT_KEY=your_key -- /path/to/fpt-mcp/.venv/bin/python -m fpt_mcp.server

Or edit ~/.claude.json manually:

{ "mcpServers": { "fpt-mcp": { "command": "/path/to/fpt-mcp/.venv/bin/python", "args": ["-m", "fpt_mcp.server"], "env": { "SHOTGRID_URL": "https://yoursite.shotgrid.autodesk.com", "SHOTGRID_SCRIPT_NAME": "your_script_name", "SHOTGRID_SCRIPT_KEY": "your_key" } } } }


**2.工具权限** — `~/.claude/settings.json`:

{ "permissions": { "allow": [ "mcp__fpt-mcp__sg_find", "mcp__fpt-mcp__sg_create", "mcp__fpt-mcp__sg_update", "mcp__fpt-mcp__sg_schema", "mcp__fpt-mcp__sg_upload", "mcp__fpt-mcp__sg_download", "mcp__fpt-mcp__fpt_bulk", "mcp__fpt-mcp__fpt_reporting", "mcp__fpt-mcp__fpt_launch_app", "mcp__fpt-mcp__tk_resolve_path", "mcp__fpt-mcp__tk_publish", "mcp__fpt-mcp__search_sg_docs", "mcp__fpt-mcp__learn_pattern", "mcp__fpt-mcp__session_stats" ] } }


> **重要提示：** `mcpServers` 必须在 `~/.claude.json`，不在 `~/.claude/settings.json`The `settings.json` 该文件仅用于权限和其他设置。如果你把 `mcpServers` 在错误的文件中， `claude mcp list` 不会显示服务器。

这 `permissions.allow` list会自动批准所有fpt-mcp工具，这样Claude Code（以及内部使用Claude Code CLI的Qt控制台）每次都可以调用它们，而无需手动确认。

## 跨MCP编排（可选）

fpt-mcp可以独立工作，但当与同一Claude会话中的其他mcp服务器结合时，Claude可以自动编排多工具工作流。例如，使用与fpt-MCP一起配置的DCC MCP服务器，Claude可以在一次对话中查询ShotGrid以获取资产数据、下载引用和注册发布。

## 自动启动launchd（macOS）

这 `setup_venv.sh` 脚本（遗留）处理launchd和Qt控制台设置：

1. 创建venv并安装依赖项
1. 生成并安装MCP服务器launchd-plist（端口8090上的HTTP模式）
1. 使用协议处理程序注册构建Qt console.app捆绑包
1. 在macOS启动服务中注册协议处理程序

对于大多数用户来说， `install.sh` 是推荐的入口点（处理venv、deps、RAG索引、Claude Code注册和工具权限）。使用 `setup_venv.sh` 仅当您需要launchd自动启动或Qt console.app捆绑包时。

./setup_venv.sh


管理MCP服务器：

- `launchctl stop com.fpt-mcp.server` --停止
- `launchctl start com.fpt-mcp.server` --开始
- `launchctl unload ~/Library/LaunchAgents/com.fpt-mcp.server.plist` --卸载

日志： `/tmp/fpt-mcp.log` 和 `/tmp/fpt-mcp.err`
Qt控制台日志： `/tmp/fpt-console.log`

## 建筑

ShotGrid AMI click → fpt-mcp://chat (macOS appends entity params automatically) → macOS opens FPT-MCP Console.app (protocol handler via Apple Events) → QFileOpenEvent delivers the URL to the Qt app → If Light Payload: fetch real context from EventLogEntry API → Qt chat window with entity context badge → User types natural language → Claude Code CLI (claude -p "message" --output-format text) → Claude calls fpt-mcp tools via MCP (stdio) → ShotGrid API response → Markdown rendered in Qt chat window


## 项目结构

fpt-mcp/ ├── pyproject.toml # Package metadata and dependencies ├── install.sh # One-step installation script ├── setup_venv.sh # Virtual environment setup ├── com.abrahamadsk.fpt-mcp.plist # launchd plist for MCP server daemon ├── com.abrahamadsk.fpt-ami.plist # launchd plist for AMI URL handler ├── .env.example # Environment variables template ├── src/ │ └── fpt_mcp/ │ ├── __init__.py │ ├── server.py # MCP server entry point (FastMCP) │ ├── client.py # ShotGrid API client wrapper │ ├── safety.py # Safety module — blocks dangerous write patterns │ ├── paths.py # Path resolution utilities │ ├── tk_config.py # Toolkit (ShotGrid Toolkit) config loader │ ├── ami/ │ │ ├── __init__.py │ │ ├── handler.py # AMI URL protocol handler (fpt-mcp://) │ │ └── console.html # AMI console HTML template │ ├── qt/ │ │ ├── __init__.py │ │ ├── app.py # Qt application entry point │ │ ├── chat_window.py # Chat window widget │ │ ├── claude_worker.py # Async Claude subprocess worker thread │ │ └── build_app_bundle.py # macOS .app bundle builder script │ ├── rag/ │ │ ├── __init__.py │ │ ├── build_index.py # RAG index builder (run to rebuild) │ │ ├── config.py # RAG configuration (chunk size, model) │ │ ├── corpus.json # Parsed documentation corpus │ │ ├── search.py # Semantic search over RAG index │ │ └── index/ # auto-generated (ChromaDB vector store) │ ├── tools/ │ │ ├── __init__.py │ │ ├── assets.py # Asset management MCP tools │ │ ├── publish.py # Publish MCP tools (tk_publish) │ │ ├── sequences.py # Sequence MCP tools │ │ ├── shots.py # Shot MCP tools │ │ └── versions.py # Version MCP tools │ ├── docs/ │ │ ├── REST_API.md # ShotGrid REST API documentation corpus │ │ ├── SG_API.md # ShotGrid Python API documentation corpus │ │ └── TK_API.md # Toolkit API documentation corpus │ └── skills/ │ └── asset-creation/ │ └── SKILL.md # Claude skill for asset creation workflows └── tests/ ├── conftest.py ├── fixtures/ │ └── templates.yml # Mock Toolkit templates for tests ├── test_rag_search.py ├── test_safety.py ├── test_sg_operations.py ├── test_tk_publish.py └── test_toolkit_paths.py


## 故障排除

**在ShotGrid API上拒绝连接**

- 验证 `SHOTGRID_URL` 和 `SHOTGRID_SCRIPT_KEY` 在 `.env`
- 检查脚本应用程序是否在ShotGrid管理中处于活动状态→ 脚本
- 测试连接性： `curl -s https://YOUR_SITE.shotgrid.autodesk.com/api/v1`

**未找到RAG索引**

- 跑 `python -m fpt_mcp.rag.build_index` 重建
- 检查一下 `docs/` 目录包含ShotGrid API文档语料库

**Toolkit路径解析失败**

- 验证ShotGrid中是否存在该项目的PipelineConfiguration实体
- 检查 `roots.yml` 和 `templates.yml` PipelineConfiguration中的路径 `descriptor` 领域
- 对于分布式配置，仅 `dev` 当前支持描述符类型

## 生态系统

`fpt-mcp` 是四组件VFX管道的一部分。每个组件都有一个定义的角色：

|代表|角色|
|------|------|
| [火焰mcp](https://github.com/abrahamADSK/flame-mcp) |控制Autodesk Flame进行合成、符合和精加工|
| [maya mcp](https://github.com/abrahamADSK/maya-mcp) |控制Autodesk Maya进行三维建模、动画和渲染|
| [fpt-mcp](https://github.com/abrahamADSK/fpt-mcp) |连接到Autodesk Flow生产跟踪（ShotGrid）进行生产跟踪、资产管理和发布|
| [视觉3d](https://github.com/abrahamADSK/vision3d) |用于AI驱动的3D生成的GPU推理服务器——maya-mcp图像到3D和文本到3D工具的远程后端|

`fpt-mcp` 是管道的生产骨干。它为其他工具提供资产元数据、任务分配、路径解析和发布注册。 `maya-mcp` 和 `flame-mcp` 两者都消费 `fpt-mcp` data——Maya用于资源上下文和发布目标，Flame用于镜头和序列查找。 `vision3d` 与没有直接联系 `fpt-mcp`.

## 许可证

[麻省理工学院](LICENSE)

fpt MCP

快速接入

详细介绍

fpt-mcp

特性

不受限制的ShotGrid API访问

Toolkit路径解析

RAG防幻觉发动机

安全层

Qt控制台和协议处理程序

需求

From the project directory, with venv activated:

Direct

With entity context

Via protocol handler (from ShotGrid AMI or terminal)

Add the server via CLI (recommended):

Or edit ~/.claude.json manually:

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP