Metadata-Version: 2.4
Name: dcc-mcp-fpt
Version: 0.1.1
Summary: A ShotGrid (Flow Production Tracking) adapter for the DCC-MCP ecosystem, bridging AI assistants to ShotGrid data through typed MCP tools.
Project-URL: Homepage, https://github.com/dcc-mcp/dcc-mcp-fpt
Project-URL: Repository, https://github.com/dcc-mcp/dcc-mcp-fpt
Project-URL: Bug Tracker, https://github.com/dcc-mcp/dcc-mcp-fpt/issues
Author-email: Long Hao <hal.long@outlook.com>
License: MIT
License-File: LICENSE
Keywords: ai,dcc,flow-production-tracking,fpt,llm,mcp,model-context-protocol,pipeline,shotgrid,shotgun,vfx
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: dcc-mcp-core<1.0.0,>=0.17.54
Requires-Dist: pydantic>=2.0
Requires-Dist: shotgun-api3>=3.4.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: hatchling; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# dcc-mcp-fpt

**ShotGrid (Flow Production Tracking) adapter for the DCC-MCP ecosystem.**

[![CI](https://github.com/dcc-mcp/dcc-mcp-fpt/actions/workflows/ci.yml/badge.svg)](https://github.com/dcc-mcp/dcc-mcp-fpt/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue)]()

Bridges AI assistants (Claude, Cursor, VS Code Copilot) to ShotGrid data through
typed, progressively-loaded MCP tools built on [dcc-mcp-core](https://github.com/dcc-mcp/dcc-mcp-core).

> This is a fresh re-implementation of the [shotgrid-mcp-server](https://github.com/loonghao/shotgrid-mcp-server)
> using the dcc-mcp framework — providing the same ShotGrid integration surface
> with gateway routing, skill-based progressive loading, and multi-DCC
> observability built in.

## Why Use It

| Feature | Description |
|---------|-------------|
| **20+ Typed Tools** | CRUD, search, batch, notes, schema — all with validated schemas |
| **Progressive Loading** | Bootstrap tools eager-loaded; advanced tools loaded on demand |
| **Gateway Ready** | Plugs into the dcc-mcp gateway for unified multi-service routing |
| **Skill-First** | Every tool is a typed skill with `tools.yaml`, schemas, and annotations |
| **Connection Pooling** | Reuses authenticated sessions for performance |
| **Schema Caching** | Entity field schemas cached with configurable TTL |
| **Multi-Transport** | stdio, HTTP, and ASGI — works anywhere |
| **Docker Ready** | Single-command container deployment |

## Quick Start

### Install

```bash
pip install dcc-mcp-fpt
```

Or with uv:
```bash
uv pip install dcc-mcp-fpt
```

### Configure

Set your ShotGrid credentials:

```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"
```

### Run Locally

The shortest local path is:

```bash
uvx dcc-mcp-fpt
```

By default this starts the adapter at `http://127.0.0.1:8765/mcp` and enables
the dcc-mcp gateway on `http://127.0.0.1:9765/mcp`. If a healthy gateway is
already running on that port, this FPT adapter registers into it; otherwise the
core gateway election path can own the gateway port for the local session.

Use standalone mode only when you do not want gateway registration:

```bash
uvx dcc-mcp-fpt --no-gateway
# Same as: uvx dcc-mcp-fpt --gateway-port 0
```

Development checkout:

```bash
python -m dcc_mcp_fpt
just serve-gateway
just serve-standalone
```

ASGI mode for uvicorn/gunicorn remains available:

```bash
uvicorn dcc_mcp_fpt.asgi:app --host 0.0.0.0 --port 8000
```

### IDE MCP Config

For IDEs that support Streamable HTTP MCP, point the IDE at the gateway URL:

```json
{
  "mcpServers": {
    "shotgrid": {
      "url": "http://127.0.0.1:9765/mcp"
    }
  }
}
```

If your IDE only supports stdio MCP, use `uvx` directly:

```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

After `uvx dcc-mcp-fpt` is running, smoke-test through the gateway:

```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
```

You can also import the same `mcpServers` JSON used by your IDE:

```bash
mcpcall config import --from ./mcp.json --output ./mcpcall.json
mcpcall list --config ./mcpcall.json --server shotgrid --json
```

## Tool Surface

### Bootstrap (eager-loaded)
| Skill | Tools |
|-------|-------|
| `shotgrid-discovery` | `check_connection`, `list_entity_types`, `get_server_info` |
| `shotgrid-setup` | `generate_agent_config`, `validate_runtime_config` |
| `shotgrid-schema` | `get_schema`, `get_field_schema`, `list_entity_types` |

### Scene (loaded on demand)
| Skill | Tools |
|-------|-------|
| `shotgrid-crud` | `find_entities`, `find_one_entity`, `create_entity`, `update_entity`, `delete_entity` |
| `shotgrid-search` | `search_entities`, `search_by_name` |

### Authoring
| Skill | Tools |
|-------|-------|
| `shotgrid-note` | `create_note`, `find_notes`, `update_note` |

### Pipeline
| Skill | Tools |
|-------|-------|
| `shotgrid-batch` | `batch_operations` |

## Architecture

```
AI Agent (Claude, Cursor, Copilot)
        │
        │ MCP Protocol (stdio / HTTP / ASGI)
        ▼
┌───────────────────────────────┐
│     ShotGridMcpServer         │
│   (DccServerBase adapter)     │
│                               │
│  ┌─────────────────────────┐  │
│  │   Skill Catalog          │  │
│  │  (progressive loading)   │  │
│  └───────────┬─────────────┘  │
│              │                │
│  ┌───────────▼─────────────┐  │
│  │   HostExecutionBridge    │  │
│  │   → ShotGridClient       │  │
│  └───────────┬─────────────┘  │
│              │                │
│  ┌───────────▼─────────────┐  │
│  │  ConnectionPool          │  │
│  │  SchemaCache             │  │
│  └───────────┬─────────────┘  │
└──────────────┼────────────────┘
               │
               │ shotgun_api3 (REST)
               ▼
     ┌─────────────────┐
     │  ShotGrid API    │
     │  (Autodesk FPT)  │
     └─────────────────┘
```

## Configuration

| Variable | Required | Description |
|----------|----------|-------------|
| `SHOTGRID_URL` | Yes | ShotGrid server URL |
| `SHOTGRID_SCRIPT_NAME` | Yes | Script/API user name |
| `SHOTGRID_SCRIPT_KEY` | Yes | Script/API user key |
| `SHOTGRID_PROJECT` | No | Default project name, code, or tank name for scoped tools |
| `SHOTGRID_PROJECT_ID` | No | Default project ID; overrides `SHOTGRID_PROJECT` when set |
| `SHOTGRID_PERMISSION_LEVEL` | No | Fallback permission level: `read`, `write`, or `admin` |
| `SHOTGRID_PROJECT_PERMISSIONS` | No | JSON or CSV per-project permission allowlist |
| `SHOTGRID_READ_ONLY` | No | Set to `1` to block create/update/delete regardless of level |
| `DCC_MCP_GATEWAY_PORT` | No | dcc-mcp gateway port; set `0` to run standalone |
| `DCC_MCP_REGISTRY_DIR` | No | Shared gateway registry directory |
| `DCC_MCP_FPT_GATEWAY_SCENE` | No | Gateway context label; defaults to `project:<SHOTGRID_PROJECT>` |
| `DCC_MCP_FPT_GATEWAY_DISPLAY_NAME` | No | Human-readable label shown in gateway/admin surfaces |
| `DCC_MCP_FPT_ENABLE_GATEWAY_FAILOVER` | No | Set `0` to disable core gateway election/failover |
| `DCC_MCP_FPT_SKILL_PATHS` | No | FPT-specific custom skill roots (`;` on Windows, `:` on Unix) |
| `DCC_MCP_SKILL_PATHS` | No | Global custom skill roots shared by all dcc-mcp adapters |
| `DCC_MCP_SHOTGRID_MINIMAL` | No | Comma-separated minimal mode skill list |
| `DCC_MCP_SHOTGRID_DEFAULT_TOOLS` | No | Comma-separated default tools to activate |

### Project Scoping and Permissions

CRUD and batch tools accept optional `project`, `project_id`, and
`project_scoped` inputs. When a default project is configured, reads add a
ShotGrid `project` filter, creates inject `data.project` when missing, and
updates/deletes validate project ownership before mutating data.

Permission levels are intentionally simple:

| Level | Allows |
|-------|--------|
| `read` | `find`, `find_one`, schema, connection checks |
| `write` | `read` plus create/update and non-delete batch items |
| `admin` | `write` plus delete/retire |

Examples:

```bash
export SHOTGRID_PROJECT="my_project_code"
export SHOTGRID_PERMISSION_LEVEL="write"
export SHOTGRID_PROJECT_PERMISSIONS='{"my_project_code":"write","id:456":"read"}'
```

### Gateway Integration

The adapter uses the same `DccServerOptions.from_env(...)` gateway contract as
the Maya, Blender, Houdini, and 3ds Max adapters. When `DCC_MCP_GATEWAY_PORT`
or `--gateway-port` is set to a positive value, the server publishes an FPT
runtime entry with a safe display name, project-aware scene label, version, and
gateway election diagnostics.

```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
```

Use `--gateway-port 0` or `just serve-standalone` for local standalone testing.
The `shotgrid-discovery__get_server_info` tool includes a `gateway` diagnostics
object so agents and CI can confirm whether this instance joined the gateway.

### Agent Setup Skill

`shotgrid-setup` is eager-loaded so agents can bootstrap configuration without
guessing repo conventions:

```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
```

The generated config includes `uvx dcc-mcp-fpt`, HTTP/stdio IDE snippets,
mcpcall commands, Docker examples, and custom skill path environment variables.
Secret values are redacted by default.

### Custom Skills

Point `DCC_MCP_FPT_SKILL_PATHS` at a skill package directory or a parent
directory containing multiple skill package folders:

```bash
# Windows uses semicolon between multiple roots.
set DCC_MCP_FPT_SKILL_PATHS=C:\studio\fpt-skills;C:\show\fpt-skills

# Linux/macOS uses colon.
export DCC_MCP_FPT_SKILL_PATHS=/studio/fpt-skills:/show/fpt-skills

uvx dcc-mcp-fpt
```

Use `DCC_MCP_SKILL_PATHS` for shared cross-adapter skills. The gateway admin
skill path registry is also picked up by dcc-mcp-core on startup/reload.

### Container Deployment

Build and run locally:

```bash
docker build -t dcc-mcp-fpt .
docker run --rm \
  -p 8765:8765 \
  -p 9765:9765 \
  --env-file .env \
  dcc-mcp-fpt
```

Inject custom skills by mounting a directory to `/skills`; the image sets
`DCC_MCP_FPT_SKILL_PATHS=/skills` by default:

```bash
docker run --rm \
  -p 8765:8765 \
  -p 9765:9765 \
  --env-file .env \
  -v /studio/fpt-skills:/skills:ro \
  dcc-mcp-fpt
```

Minimal compose:

```yaml
services:
  dcc-mcp-fpt:
    image: dcc-mcp-fpt
    ports:
      - "8765:8765"
      - "9765:9765"
    env_file:
      - .env
    volumes:
      - /studio/fpt-skills:/skills:ro
```

## Development

```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/
```

### Local Live CRUD Smoke

Copy `.env.example` to `.env`, fill in local credentials, and keep the file
untracked. The dry-run command verifies configuration and skips mutations:

```bash
just install-dev
just live-crud-smoke-dry
```

To run a real local create/find/update/delete cycle against the configured
project, set an admin-capable policy for that project and run:

```bash
export SHOTGRID_PERMISSION_LEVEL="admin"
export SHOTGRID_LIVE_CRUD_CONFIRM=1
just live-crud-smoke
```

The smoke creates a temporary entity, updates it, and retires it on cleanup.

## CI/CD

- `CI` runs Python 3.8-3.12 across Linux, Windows, and macOS.
- Lint, format check, bundled skill metadata lint, CLI smoke, package build,
  and Docker build are separate gates.
- `Release` uses release-please, builds wheel/sdist artifacts, publishes via
  PyPI Trusted Publishing, and attaches the dist files to the GitHub Release.
- `Live ShotGrid Smoke` is manual-only and uses GitHub Secrets; it defaults to
  dry-run behavior unless CRUD confirmation is enabled.

## Requirements

- Python 3.8+
- [dcc-mcp-core](https://github.com/dcc-mcp/dcc-mcp-core) >= 0.17.54
- [shotgun_api3](https://github.com/shotgunsoftware/python-api) >= 3.4.0

## License

MIT — see [LICENSE](LICENSE).

## Related

- [dcc-mcp-core](https://github.com/dcc-mcp/dcc-mcp-core) — Core runtime and shared tooling
- [shotgrid-mcp-server](https://github.com/loonghao/shotgrid-mcp-server) — Original FastMCP-based implementation
- [dcc-mcp-maya](https://github.com/dcc-mcp/dcc-mcp-maya) — Maya adapter reference
- [dcc-mcp-blender](https://github.com/dcc-mcp/dcc-mcp-blender) — Blender adapter reference
