fpt-mcp: Instructions file for Claude Code

fpt-mcp Project Context for Claude

Reference document that persists across sessions. Update when architecture or workflows change.

---

1. General Architecture

fpt-mcp is an MCP server for Autodesk Flow Production Tracking (ShotGrid). Works standalone or alongside other MCP servers for cross-tool orchestration.

Claude Desktop / Claude Code / Terminal
├── maya-mcp    → 3D modeling, rendering, Vision3D GPU
├── flame-mcp   → compositing
└── fpt-mcp     → production tracking (ShotGrid)
        ├── stdio           → Claude Desktop / Claude Code
        ├── HTTP            → Maya, Flame, scripts, inter-service
        └── Qt console      → native chat app via fpt-mcp:// protocol handler

MCP Server: fpt-mcp (18 @mcp.tool registrations — dispatcher pattern)

ShotGrid API tools (6 direct tools, unrestricted access to any entity):

• sg_find — query entities with filters and fields
• sg_create — create entities (project auto-linked)
• sg_update — update any field
• sg_schema — inspect available fields
• sg_upload — upload files (thumbnail, movie, attachment)
• sg_download — download attachments

Bulk operations dispatcher (fpt_bulk — 1 tool, 5 actions):

• fpt_bulk(action="delete") — soft-delete (retire) entities
• fpt_bulk(action="revive") — restore soft-deleted (retired) entities
• fpt_bulk(action="batch") — transactional batch operations (all-or-nothing)
• fpt_bulk(action="editorial") — deterministic Cut + CutItem auto-calc: pure timecode math (editorial.py::compute_editorial_cut) computes cumulative edit_in/edit_out and cut_item_in/cut_item_out (source range) in Autodesk's importer convention (1-based, inclusive) plus sg_cut_duration; compute_shot_handle_updates puts handles on the Shot (sg_head_in/sg_tail_out), never on the CutItem. A thin creation layer (shotgrid.py::_do_sg_editorial) creates the Cut via sg_create and the CutItems (+ Shot handle updates when handles > 0) via one sg_batch transaction
• fpt_bulk(action="link_task") — link a native tk-flame delivery (version_id + step) to its Task: the Version, its publishes and the Shot's Task-less publishes with the same version number, in one sg_batch. tk-flame leaves them Task-less because tk-core only yields a Task from a Task-typed schema folder (Chat 108). Exactly one Task must match; any record on a different Task aborts the write; idempotent