├── python ├── .python-version ├── src └── shotgrid_mcp_server │ ├── py.typed │ ├── data │ ├── __init__.py │ ├── schema.bin │ └── entity_schema.bin │ ├── __main__.py │ ├── tools │ ├── types.py │ ├── utils_file.py │ ├── base.py │ ├── utils_date.py │ ├── __init__.py │ ├── helper_types.py │ └── read_tools.py │ ├── filters.py │ ├── constants.py │ ├── __init__.py │ ├── logger.py │ ├── exceptions.py │ ├── shotgun_args.py │ ├── cli.py │ ├── http_context.py │ ├── asgi.py │ └── schema_resources.py ├── nox_actions ├── __init__.py ├── utils.py ├── lint.py └── release.py ├── tests ├── __init__.py ├── data │ ├── schema.bin │ └── entity_schema.bin ├── test_imports.py ├── test_asgi.py ├── test_utils.py ├── test_shotgun_args.py ├── test_ssl_fix.py ├── test_api_client.py ├── test_search_tools_return_types.py ├── test_factory.py ├── test_filter_processing.py ├── test_schema_resources.py ├── test_api_models_filters.py └── test_schema_cache.py ├── images ├── logo.png └── sg-mcp.gif ├── requirements-test.txt ├── .hound.yml ├── docs ├── sphinx_source │ ├── modules.rst │ ├── shotgrid_mcp_server.data.rst │ ├── shotgrid_mcp_server.utils.rst │ ├── shotgrid_mcp_server.logger.rst │ ├── shotgrid_mcp_server.models.rst │ ├── shotgrid_mcp_server.server.rst │ ├── shotgrid_mcp_server.filters.rst │ ├── shotgrid_mcp_server.constants.rst │ ├── shotgrid_mcp_server.tools.base.rst │ ├── shotgrid_mcp_server.data_types.rst │ ├── shotgrid_mcp_server.tools.types.rst │ ├── shotgrid_mcp_server.mockgun_ext.rst │ ├── shotgrid_mcp_server.error_handler.rst │ ├── shotgrid_mcp_server.schema_loader.rst │ ├── shotgrid_mcp_server.connection_pool.rst │ ├── shotgrid_mcp_server.tools.read_tools.rst │ ├── shotgrid_mcp_server.tools.create_tools.rst │ ├── shotgrid_mcp_server.tools.delete_tools.rst │ ├── shotgrid_mcp_server.tools.helper_types.rst │ ├── shotgrid_mcp_server.tools.search_tools.rst │ ├── shotgrid_mcp_server.tools.update_tools.rst │ ├── shotgrid_mcp_server.tools.thumbnail_tools.rst │ ├── index.rst │ ├── shotgrid_mcp_server.tools.rst │ └── shotgrid_mcp_server.rst ├── api │ ├── index.md │ ├── shotgrid_mcp_server.tools.md │ ├── shotgrid_mcp_server.utils.md │ ├── shotgrid_mcp_server.filters.md │ ├── shotgrid_mcp_server.models.md │ ├── shotgrid_mcp_server.server.md │ ├── shotgrid_mcp_server.constants.md │ ├── shotgrid_mcp_server.data_types.md │ ├── shotgrid_mcp_server.tools.base.md │ ├── shotgrid_mcp_server.mockgun_ext.md │ ├── shotgrid_mcp_server.tools.entity_tools.md │ ├── shotgrid_mcp_server.tools.schema_tools.md │ ├── shotgrid_mcp_server.tools.search_tools.md │ └── shotgrid_mcp_server.md ├── mintlify.config.js ├── package.json ├── sphinx_conf │ ├── index.rst │ └── conf.py ├── README.md ├── docs.json ├── index.mdx ├── getting-started │ ├── installation.mdx │ ├── welcome.mdx │ └── quickstart.mdx ├── guides │ ├── authentication.mdx │ └── ai-prompts.mdx ├── DEVELOPMENT.md ├── servers │ └── overview.mdx ├── CACHING_STRATEGY.md └── patterns │ └── ai-workflows.mdx ├── renovate.json ├── codecov.yml ├── .pylintrc ├── .coveragerc ├── requirements-dev.txt ├── requirements.txt ├── .gitignore ├── .pre-commit-config.yaml ├── .github └── workflows │ ├── bumpversion.yml │ ├── issue-translator.yml │ ├── mr-test.yml │ ├── codecov.yml │ └── python-publish.yml ├── copy_schema.py ├── .gitattributes ├── .flake8 ├── LICENSE ├── Dockerfile ├── docker-compose.yml ├── .dockerignore ├── mypy.ini ├── fastmcp_entry.py ├── scripts └── copy_schema_files.py ├── noxfile.py ├── examples └── custom_app.py ├── pyproject.toml ├── API_COVERAGE_ANALYSIS.md └── README_zh.md /python: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /.python-version: -------------------------------------------------------------------------------- 1 | 3.12 2 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/py.typed: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /nox_actions/__init__.py: -------------------------------------------------------------------------------- 1 | """Nox actions for the project.""" 2 | -------------------------------------------------------------------------------- /tests/__init__.py: -------------------------------------------------------------------------------- 1 | """Test package for shotgrid_mcp_server.""" 2 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/data/__init__.py: -------------------------------------------------------------------------------- 1 | """Data package for shotgrid_mcp_server.""" 2 | -------------------------------------------------------------------------------- /images/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/loonghao/shotgrid-mcp-server/HEAD/images/logo.png -------------------------------------------------------------------------------- /images/sg-mcp.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/loonghao/shotgrid-mcp-server/HEAD/images/sg-mcp.gif -------------------------------------------------------------------------------- /tests/data/schema.bin: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/loonghao/shotgrid-mcp-server/HEAD/tests/data/schema.bin -------------------------------------------------------------------------------- /requirements-test.txt: -------------------------------------------------------------------------------- 1 | -r requirements-dev.txt 2 | PyYAML 3 | pytest 4 | pytest-asyncio 5 | pytest-cov 6 | pytest-mock -------------------------------------------------------------------------------- /tests/data/entity_schema.bin: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/loonghao/shotgrid-mcp-server/HEAD/tests/data/entity_schema.bin -------------------------------------------------------------------------------- /.hound.yml: -------------------------------------------------------------------------------- 1 | python: 2 | enabled: true 3 | 4 | flake8: 5 | enabled: true 6 | config_file: .flake8 7 | 8 | fail_on_violations: true 9 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/data/schema.bin: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/loonghao/shotgrid-mcp-server/HEAD/src/shotgrid_mcp_server/data/schema.bin -------------------------------------------------------------------------------- /docs/sphinx_source/modules.rst: -------------------------------------------------------------------------------- 1 | shotgrid_mcp_server 2 | =================== 3 | 4 | .. toctree:: 5 | :maxdepth: 4 6 | 7 | shotgrid_mcp_server 8 | -------------------------------------------------------------------------------- /renovate.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://docs.renovatebot.com/renovate-schema.json", 3 | "extends": [ 4 | "config:recommended" 5 | ] 6 | } 7 | -------------------------------------------------------------------------------- /codecov.yml: -------------------------------------------------------------------------------- 1 | coverage: 2 | status: 3 | project: off 4 | 5 | github_checks: 6 | annotations: false 7 | 8 | ignore: 9 | - "noxfile.py" 10 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/data/entity_schema.bin: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/loonghao/shotgrid-mcp-server/HEAD/src/shotgrid_mcp_server/data/entity_schema.bin -------------------------------------------------------------------------------- /nox_actions/utils.py: -------------------------------------------------------------------------------- 1 | # Import built-in modules 2 | import pathlib 3 | 4 | # Constants 5 | THIS_ROOT = pathlib.Path(__file__).parent.parent 6 | PACKAGE_NAME = "shotgrid_mcp_server" 7 | -------------------------------------------------------------------------------- /docs/api/index.md: -------------------------------------------------------------------------------- 1 | # ShotGrid MCP Server API Documentation 2 | 3 | This documentation provides details about the ShotGrid MCP Server API. 4 | 5 | ## Modules 6 | 7 | - [shotgrid_mcp_server](shotgrid_mcp_server.md) 8 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/__main__.py: -------------------------------------------------------------------------------- 1 | """Main entry point for the ShotGrid MCP server.""" 2 | 3 | # Import local modules 4 | from shotgrid_mcp_server.server import main 5 | 6 | if __name__ == "__main__": 7 | main() 8 | -------------------------------------------------------------------------------- /.pylintrc: -------------------------------------------------------------------------------- 1 | # Generated Pylint configuration file that disables default output tables. 2 | 3 | [MESSAGES CONTROL] 4 | disable=RP0001,RP0002,RP0003,RP0101,RP0401,RP0402,RP0701,RP0801,C0103,R0903 5 | 6 | [REPORTS] 7 | output-format=text 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.data.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.data package 2 | ================================== 3 | 4 | .. automodule:: shotgrid_mcp_server.data 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.utils.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.utils module 2 | ================================== 3 | 4 | .. automodule:: shotgrid_mcp_server.utils 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/api/shotgrid_mcp_server.tools.md: -------------------------------------------------------------------------------- 1 | # shotgrid_mcp_server.tools 2 | 3 | This module is part of the ShotGrid MCP Server package. 4 | 5 | ## Module Reference 6 | 7 | Please refer to the source code for detailed information about this module. 8 | -------------------------------------------------------------------------------- /docs/api/shotgrid_mcp_server.utils.md: -------------------------------------------------------------------------------- 1 | # shotgrid_mcp_server.utils 2 | 3 | This module is part of the ShotGrid MCP Server package. 4 | 5 | ## Module Reference 6 | 7 | Please refer to the source code for detailed information about this module. 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.logger.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.logger module 2 | =================================== 3 | 4 | .. automodule:: shotgrid_mcp_server.logger 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.models.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.models module 2 | =================================== 3 | 4 | .. automodule:: shotgrid_mcp_server.models 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.server.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.server module 2 | =================================== 3 | 4 | .. automodule:: shotgrid_mcp_server.server 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/api/shotgrid_mcp_server.filters.md: -------------------------------------------------------------------------------- 1 | # shotgrid_mcp_server.filters 2 | 3 | This module is part of the ShotGrid MCP Server package. 4 | 5 | ## Module Reference 6 | 7 | Please refer to the source code for detailed information about this module. 8 | -------------------------------------------------------------------------------- /docs/api/shotgrid_mcp_server.models.md: -------------------------------------------------------------------------------- 1 | # shotgrid_mcp_server.models 2 | 3 | This module is part of the ShotGrid MCP Server package. 4 | 5 | ## Module Reference 6 | 7 | Please refer to the source code for detailed information about this module. 8 | -------------------------------------------------------------------------------- /docs/api/shotgrid_mcp_server.server.md: -------------------------------------------------------------------------------- 1 | # shotgrid_mcp_server.server 2 | 3 | This module is part of the ShotGrid MCP Server package. 4 | 5 | ## Module Reference 6 | 7 | Please refer to the source code for detailed information about this module. 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.filters.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.filters module 2 | ==================================== 3 | 4 | .. automodule:: shotgrid_mcp_server.filters 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/api/shotgrid_mcp_server.constants.md: -------------------------------------------------------------------------------- 1 | # shotgrid_mcp_server.constants 2 | 3 | This module is part of the ShotGrid MCP Server package. 4 | 5 | ## Module Reference 6 | 7 | Please refer to the source code for detailed information about this module. 8 | -------------------------------------------------------------------------------- /docs/api/shotgrid_mcp_server.data_types.md: -------------------------------------------------------------------------------- 1 | # shotgrid_mcp_server.data_types 2 | 3 | This module is part of the ShotGrid MCP Server package. 4 | 5 | ## Module Reference 6 | 7 | Please refer to the source code for detailed information about this module. 8 | -------------------------------------------------------------------------------- /docs/api/shotgrid_mcp_server.tools.base.md: -------------------------------------------------------------------------------- 1 | # shotgrid_mcp_server.tools.base 2 | 3 | This module is part of the ShotGrid MCP Server package. 4 | 5 | ## Module Reference 6 | 7 | Please refer to the source code for detailed information about this module. 8 | -------------------------------------------------------------------------------- /docs/api/shotgrid_mcp_server.mockgun_ext.md: -------------------------------------------------------------------------------- 1 | # shotgrid_mcp_server.mockgun_ext 2 | 3 | This module is part of the ShotGrid MCP Server package. 4 | 5 | ## Module Reference 6 | 7 | Please refer to the source code for detailed information about this module. 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.constants.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.constants module 2 | ====================================== 3 | 4 | .. automodule:: shotgrid_mcp_server.constants 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.tools.base.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.tools.base module 2 | ======================================= 3 | 4 | .. automodule:: shotgrid_mcp_server.tools.base 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.data_types.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.data\_types module 2 | ======================================== 3 | 4 | .. automodule:: shotgrid_mcp_server.data_types 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.tools.types.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.tools.types module 2 | ======================================== 3 | 4 | .. automodule:: shotgrid_mcp_server.tools.types 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /.coveragerc: -------------------------------------------------------------------------------- 1 | [run] 2 | branch = True 3 | source = 4 | 5 | [report] 6 | exclude_lines = 7 | if self.debug: 8 | pragma: no cover 9 | raise NotImplementedError 10 | if __name__ == .__main__.: 11 | ignore_errors = True 12 | omit = 13 | tests/* 14 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.mockgun_ext.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.mockgun\_ext module 2 | ========================================= 3 | 4 | .. automodule:: shotgrid_mcp_server.mockgun_ext 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/api/shotgrid_mcp_server.tools.entity_tools.md: -------------------------------------------------------------------------------- 1 | # shotgrid_mcp_server.tools.entity_tools 2 | 3 | This module is part of the ShotGrid MCP Server package. 4 | 5 | ## Module Reference 6 | 7 | Please refer to the source code for detailed information about this module. 8 | -------------------------------------------------------------------------------- /docs/api/shotgrid_mcp_server.tools.schema_tools.md: -------------------------------------------------------------------------------- 1 | # shotgrid_mcp_server.tools.schema_tools 2 | 3 | This module is part of the ShotGrid MCP Server package. 4 | 5 | ## Module Reference 6 | 7 | Please refer to the source code for detailed information about this module. 8 | -------------------------------------------------------------------------------- /docs/api/shotgrid_mcp_server.tools.search_tools.md: -------------------------------------------------------------------------------- 1 | # shotgrid_mcp_server.tools.search_tools 2 | 3 | This module is part of the ShotGrid MCP Server package. 4 | 5 | ## Module Reference 6 | 7 | Please refer to the source code for detailed information about this module. 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.error_handler.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.error\_handler module 2 | =========================================== 3 | 4 | .. automodule:: shotgrid_mcp_server.error_handler 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.schema_loader.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.schema\_loader module 2 | =========================================== 3 | 4 | .. automodule:: shotgrid_mcp_server.schema_loader 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.connection_pool.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.connection\_pool module 2 | ============================================= 3 | 4 | .. automodule:: shotgrid_mcp_server.connection_pool 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.tools.read_tools.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.tools.read\_tools module 2 | ============================================== 3 | 4 | .. automodule:: shotgrid_mcp_server.tools.read_tools 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.tools.create_tools.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.tools.create\_tools module 2 | ================================================ 3 | 4 | .. automodule:: shotgrid_mcp_server.tools.create_tools 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.tools.delete_tools.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.tools.delete\_tools module 2 | ================================================ 3 | 4 | .. automodule:: shotgrid_mcp_server.tools.delete_tools 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.tools.helper_types.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.tools.helper\_types module 2 | ================================================ 3 | 4 | .. automodule:: shotgrid_mcp_server.tools.helper_types 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.tools.search_tools.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.tools.search\_tools module 2 | ================================================ 3 | 4 | .. automodule:: shotgrid_mcp_server.tools.search_tools 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.tools.update_tools.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.tools.update\_tools module 2 | ================================================ 3 | 4 | .. automodule:: shotgrid_mcp_server.tools.update_tools 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/mintlify.config.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | rootDir: ".", 3 | port: 3000, 4 | analytics: false, 5 | siteUrl: "https://docs.shotgrid-mcp-server.com", 6 | logo: { 7 | light: "/logo/light.svg", 8 | dark: "/logo/dark.svg" 9 | }, 10 | favicon: "/favicon.png" 11 | }; 12 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.tools.thumbnail_tools.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.tools.thumbnail\_tools module 2 | =================================================== 3 | 4 | .. automodule:: shotgrid_mcp_server.tools.thumbnail_tools 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /docs/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "shotgrid-mcp-server-docs", 3 | "version": "1.0.0", 4 | "description": "Documentation for ShotGrid MCP Server", 5 | "scripts": { 6 | "dev": "mintlify dev", 7 | "build": "mintlify build" 8 | }, 9 | "dependencies": { 10 | "mintlify": "^4.2.202" 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /docs/sphinx_source/index.rst: -------------------------------------------------------------------------------- 1 | ShotGrid MCP Server API Documentation 2 | =================================== 3 | 4 | .. toctree:: 5 | :maxdepth: 2 6 | :caption: Contents: 7 | 8 | modules 9 | 10 | Indices and tables 11 | ================== 12 | 13 | * :ref:`genindex` 14 | * :ref:`modindex` 15 | * :ref:`search` 16 | -------------------------------------------------------------------------------- /docs/sphinx_conf/index.rst: -------------------------------------------------------------------------------- 1 | ShotGrid MCP Server API Documentation 2 | =================================== 3 | 4 | .. toctree:: 5 | :maxdepth: 2 6 | :caption: Contents: 7 | 8 | shotgrid_mcp_server 9 | 10 | Indices and tables 11 | ================== 12 | 13 | * :ref:`genindex` 14 | * :ref:`modindex` 15 | * :ref:`search` 16 | -------------------------------------------------------------------------------- /requirements-dev.txt: -------------------------------------------------------------------------------- 1 | nox 2 | uv>=0.9.6 3 | fastmcp>=2.13.0 4 | mcp>=1.10.0 5 | uvicorn>=0.22.0 6 | pydantic[email]>=2.0.0 7 | python-dotenv>=1.0.0 8 | platformdirs>=4.1.0 9 | aiohttp>=3.12.14 10 | requests>=2.32.4 11 | shotgun-api3>=3.8.2 12 | shotgrid-query>=0.1.0 13 | python-slugify>=8.0.4,<9.0.0 14 | pendulum>=3.1.0,<4.0.0 15 | tenacity>=9.1.2,<10.0.0 16 | diskcache_rs>=0.4.4 17 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/tools/types.py: -------------------------------------------------------------------------------- 1 | """Type definitions for ShotGrid MCP server tools. 2 | 3 | This module contains type definitions used across the tools modules. 4 | """ 5 | 6 | from typing import Any, Dict, List 7 | 8 | from shotgrid_mcp_server.custom_types import EntityType, Filter 9 | 10 | # Define a type alias for FastMCP 11 | FastMCPType = Any 12 | 13 | # Define common type aliases 14 | FilterList = List[Filter] 15 | EntityDict = Dict[str, Any] 16 | EntityList = List[EntityType] 17 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | # Runtime dependencies for FastMCP Cloud deployment 2 | # This file mirrors pyproject.toml dependencies for cloud builds 3 | fastmcp>=2.13.0 4 | mcp>=1.10.0 5 | uvicorn[standard]>=0.35.0 6 | pydantic[email]>=2.0.0 7 | python-dotenv>=1.0.0 8 | platformdirs>=4.1.0 9 | aiohttp>=3.12.14 10 | requests>=2.32.4 11 | shotgun-api3>=3.8.2 12 | shotgrid-query>=0.1.0 13 | python-slugify>=8.0.4,<9.0.0 14 | pendulum>=3.1.0,<4.0.0 15 | tenacity>=9.1.2,<10.0.0 16 | click>=8.0.0 17 | websockets>=15.0.1 18 | diskcache_rs>=0.4.4 19 | 20 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/tools/utils_file.py: -------------------------------------------------------------------------------- 1 | """ 2 | File name utilities for ShotGrid MCP server. 3 | Provides safe file name conversion helpers. 4 | """ 5 | 6 | from slugify import slugify 7 | 8 | 9 | def safe_slug_filename(name: str, ext: str = "") -> str: 10 | """ 11 | Convert a string to a safe and beautiful file name using slugify. 12 | Optionally add extension (without dot). 13 | """ 14 | slug = slugify(name, lowercase=True, separator="_") 15 | if ext: 16 | return f"{slug}.{ext}" 17 | return slug 18 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled / optimized / DLL files 2 | *.py[cod] 3 | 4 | # PyCharm project files 5 | .idea/ 6 | 7 | # Vim / Notepad++ temp files 8 | *~ 9 | 10 | # Coverage output 11 | .coverage 12 | 13 | # Documentation build folders. 14 | docs/_* 15 | docs/src/* 16 | target/* 17 | /venv/ 18 | /run_pycharm.bat 19 | /.nox/ 20 | /build/ 21 | /coverage.xml 22 | /.zip/ 23 | /.env 24 | /.windsurfrules 25 | /dist/ 26 | /.venv/ 27 | /tests/data/convert_schema.py 28 | /tests/data/schema.bin 29 | /tests/data/entity_schema.bin 30 | __pycache__ 31 | node_modules 32 | .cache -------------------------------------------------------------------------------- /tests/test_imports.py: -------------------------------------------------------------------------------- 1 | """Import Test.""" 2 | 3 | # Import built-in modules 4 | import importlib 5 | import pkgutil 6 | 7 | # Import local modules 8 | import shotgrid_mcp_server 9 | 10 | 11 | def test_imports(): 12 | """Test import modules.""" 13 | prefix = f"{shotgrid_mcp_server.__name__}." 14 | iter_packages = pkgutil.walk_packages( 15 | shotgrid_mcp_server.__path__, # noqa: WPS609 16 | prefix, 17 | ) 18 | for _, name, _ in iter_packages: 19 | module_name = name if name.startswith(prefix) else prefix + name 20 | importlib.import_module(module_name) 21 | -------------------------------------------------------------------------------- /.pre-commit-config.yaml: -------------------------------------------------------------------------------- 1 | default_language_version: 2 | python: python3.10 3 | repos: 4 | - repo: https://github.com/pre-commit/pre-commit-hooks 5 | rev: v4.3.0 6 | hooks: 7 | - id: no-commit-to-branch # prevent direct commits to main branch 8 | - id: check-yaml 9 | args: ["--unsafe"] 10 | - id: check-toml 11 | - id: end-of-file-fixer 12 | - id: trailing-whitespace 13 | 14 | - repo: https://github.com/astral-sh/ruff-pre-commit 15 | rev: v0.8.6 16 | hooks: 17 | # Run the linter 18 | - id: ruff 19 | args: [--fix] 20 | # Run the formatter 21 | - id: ruff-format 22 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.tools.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server.tools package 2 | =================================== 3 | 4 | .. automodule:: shotgrid_mcp_server.tools 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | 9 | Submodules 10 | ---------- 11 | 12 | .. toctree:: 13 | :maxdepth: 4 14 | 15 | shotgrid_mcp_server.tools.base 16 | shotgrid_mcp_server.tools.create_tools 17 | shotgrid_mcp_server.tools.delete_tools 18 | shotgrid_mcp_server.tools.helper_types 19 | shotgrid_mcp_server.tools.read_tools 20 | shotgrid_mcp_server.tools.search_tools 21 | shotgrid_mcp_server.tools.thumbnail_tools 22 | shotgrid_mcp_server.tools.types 23 | shotgrid_mcp_server.tools.update_tools 24 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/tools/base.py: -------------------------------------------------------------------------------- 1 | """Base module for ShotGrid tools. 2 | 3 | This module contains common functions and utilities used by all tools. 4 | """ 5 | 6 | from shotgrid_mcp_server.error_handler import handle_tool_error 7 | 8 | # Re-export serialize_entity for backward compatibility 9 | from shotgrid_mcp_server.utils import serialize_entity # noqa: F401 10 | 11 | 12 | def handle_error(err: Exception, operation: str) -> None: 13 | """Handle errors from tool operations. 14 | 15 | Args: 16 | err: Exception to handle. 17 | operation: Name of the operation that failed. 18 | 19 | Raises: 20 | ToolError: Always raised with formatted error message. 21 | """ 22 | handle_tool_error(err, operation) 23 | -------------------------------------------------------------------------------- /.github/workflows/bumpversion.yml: -------------------------------------------------------------------------------- 1 | name: Bump version 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | 8 | jobs: 9 | bump-version: 10 | if: "!startsWith(github.event.head_commit.message, 'bump:')" 11 | runs-on: ubuntu-latest 12 | name: "Bump version and create changelog with commitizen" 13 | steps: 14 | - name: Check out 15 | uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6 16 | with: 17 | fetch-depth: 0 18 | token: '${{ secrets.PERSONAL_ACCESS_TOKEN }}' 19 | - name: Create bump and changelog 20 | uses: commitizen-tools/commitizen-action@master 21 | with: 22 | github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }} 23 | branch: main 24 | -------------------------------------------------------------------------------- /copy_schema.py: -------------------------------------------------------------------------------- 1 | import os 2 | import shutil 3 | from pathlib import Path 4 | 5 | # Get the current directory 6 | current_dir = Path.cwd() 7 | 8 | # Source and target paths 9 | source_schema = current_dir / "tests" / "data" / "schema.bin" 10 | target_dir = current_dir / "src" / "shotgrid_mcp_server" / "data" 11 | target_schema = target_dir / "schema.bin" 12 | 13 | # Ensure target directory exists 14 | os.makedirs(target_dir, exist_ok=True) 15 | 16 | # Copy the file 17 | print(f"Copying {source_schema} to {target_schema}") 18 | shutil.copy2(source_schema, target_schema) 19 | print(f"File copied successfully: {os.path.exists(target_schema)}") 20 | 21 | # List files in target directory 22 | print(f"Files in {target_dir}:") 23 | for file in os.listdir(target_dir): 24 | print(f" {file}") 25 | -------------------------------------------------------------------------------- /.github/workflows/issue-translator.yml: -------------------------------------------------------------------------------- 1 | name: 'issue-translator' 2 | on: 3 | issue_comment: 4 | types: [created] 5 | issues: 6 | types: [opened] 7 | 8 | jobs: 9 | build: 10 | runs-on: ubuntu-latest 11 | steps: 12 | - uses: usthe/issues-translate-action@v2.7 13 | with: 14 | IS_MODIFY_TITLE: false 15 | # not require, default false, . Decide whether to modify the issue title 16 | # if true, the robot account @Issues-translate-bot must have modification permissions, invite @Issues-translate-bot to your project or use your custom bot. 17 | CUSTOM_BOT_NOTE: Bot detected the issue body's language is not English, translate it automatically. 👯👭🏻🧑‍🤝‍🧑👫🧑🏿‍🤝‍🧑🏻👩🏾‍🤝‍👨🏿👬🏿 18 | # not require. Customize the translation robot prefix message. 19 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | # Set default behavior to automatically normalize line endings 2 | * text=auto 3 | 4 | # Force LF for all text files 5 | *.py text eol=lf 6 | *.md text eol=lf 7 | *.txt text eol=lf 8 | *.yml text eol=lf 9 | *.yaml text eol=lf 10 | *.json text eol=lf 11 | *.toml text eol=lf 12 | *.cfg text eol=lf 13 | *.ini text eol=lf 14 | *.sh text eol=lf 15 | 16 | # Denote all files that are truly binary and should not be modified 17 | *.png binary 18 | *.jpg binary 19 | *.jpeg binary 20 | *.gif binary 21 | *.ico binary 22 | *.mov binary 23 | *.mp4 binary 24 | *.mp3 binary 25 | *.flv binary 26 | *.fla binary 27 | *.swf binary 28 | *.gz binary 29 | *.zip binary 30 | *.7z binary 31 | *.ttf binary 32 | *.eot binary 33 | *.woff binary 34 | *.woff2 binary 35 | *.pyc binary 36 | *.pyd binary 37 | *.so binary 38 | *.dll binary 39 | *.exe binary 40 | 41 | -------------------------------------------------------------------------------- /docs/sphinx_source/shotgrid_mcp_server.rst: -------------------------------------------------------------------------------- 1 | shotgrid\_mcp\_server package 2 | ============================= 3 | 4 | .. automodule:: shotgrid_mcp_server 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | 9 | Subpackages 10 | ----------- 11 | 12 | .. toctree:: 13 | :maxdepth: 4 14 | 15 | shotgrid_mcp_server.data 16 | shotgrid_mcp_server.tools 17 | 18 | Submodules 19 | ---------- 20 | 21 | .. toctree:: 22 | :maxdepth: 4 23 | 24 | shotgrid_mcp_server.connection_pool 25 | shotgrid_mcp_server.constants 26 | shotgrid_mcp_server.data_types 27 | shotgrid_mcp_server.error_handler 28 | shotgrid_mcp_server.filters 29 | shotgrid_mcp_server.logger 30 | shotgrid_mcp_server.mockgun_ext 31 | shotgrid_mcp_server.models 32 | shotgrid_mcp_server.schema_loader 33 | shotgrid_mcp_server.server 34 | shotgrid_mcp_server.utils 35 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/tools/utils_date.py: -------------------------------------------------------------------------------- 1 | """ 2 | Date utilities for ShotGrid MCP server. 3 | Provides ISO8601 formatting and validation helpers. 4 | """ 5 | 6 | from typing import Union 7 | 8 | import pendulum 9 | 10 | 11 | def to_iso8601(dt: Union[str, pendulum.DateTime]) -> str: 12 | """ 13 | Convert date or datetime to ISO8601 string (with +08:00 timezone) using pendulum. 14 | Accepts 'YYYY-MM-DD', datetime, or pendulum.DateTime object. 15 | """ 16 | if isinstance(dt, str): 17 | try: 18 | dt_obj = pendulum.parse(dt, tz="Asia/Shanghai") 19 | except Exception as err: 20 | raise ValueError(f"Invalid date string: {dt}") from err 21 | elif isinstance(dt, pendulum.DateTime): 22 | dt_obj = dt.in_timezone("Asia/Shanghai") 23 | else: 24 | raise TypeError("dt must be str or pendulum.DateTime") 25 | return dt_obj.to_iso8601_string() 26 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/filters.py: -------------------------------------------------------------------------------- 1 | """ShotGrid filter utilities - Compatibility Layer. 2 | 3 | This module re-exports filter utilities from the shotgrid-query library for backward compatibility. 4 | 5 | Note: Core filter functionality has been migrated to the shotgrid-query library. 6 | Import FilterBuilder, TimeUnit, process_filters, etc. from shotgrid_query instead. 7 | 8 | This module is kept for backward compatibility only. 9 | """ 10 | 11 | # Import from shotgrid-query for backward compatibility 12 | from shotgrid_query import ( 13 | FilterBuilder, 14 | TimeUnit, 15 | build_date_filter, 16 | combine_filters, 17 | create_date_filter, 18 | process_filters, 19 | validate_filters, 20 | ) 21 | 22 | # Re-export for backward compatibility 23 | __all__ = [ 24 | "FilterBuilder", 25 | "TimeUnit", 26 | "build_date_filter", 27 | "combine_filters", 28 | "create_date_filter", 29 | "process_filters", 30 | "validate_filters", 31 | ] 32 | -------------------------------------------------------------------------------- /.flake8: -------------------------------------------------------------------------------- 1 | [flake8] 2 | ignore = BLK100 3 | 4 | # flake8-quotes: 5 | # Use double quotes as our default to comply with black, we like it and 6 | # don't want to use single quotes anymore. 7 | # We would love to configure this via our pyproject.toml but flake8-3.8 does 8 | # not support it yet. 9 | inline-quotes = double 10 | multiline-quotes = double 11 | docstring-quotes = double 12 | avoid-escape = True 13 | 14 | # flake8-docstrings 15 | # Use the Google Python Styleguide Docstring format. 16 | docstring-convention=google 17 | 18 | exclude = 19 | # No need to traverse our git directory 20 | .git, 21 | # There's no value in checking cache directories 22 | __pycache__, 23 | # The conf file is mostly autogenerated, ignore it 24 | docs/source/conf.py, 25 | # The old directory contains Flake8 2.0 26 | old, 27 | # This contains our built documentation 28 | build, 29 | # This contains builds of flake8 that we don't want to check 30 | dist, 31 | venv, 32 | docs 33 | 34 | max-line-length = 120 35 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2024 Hal 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/constants.py: -------------------------------------------------------------------------------- 1 | """Constants module for ShotGrid server. 2 | 3 | This module contains all constant values used throughout the ShotGrid server application. 4 | """ 5 | 6 | # No imports needed 7 | 8 | # HTTP Status Codes 9 | HTTP_200_OK = 200 10 | HTTP_201_CREATED = 201 11 | HTTP_400_BAD_REQUEST = 400 12 | HTTP_404_NOT_FOUND = 404 13 | HTTP_500_INTERNAL_SERVER_ERROR = 500 14 | 15 | 16 | # Common entity types - using a subset of EntityType 17 | DEFAULT_ENTITY_TYPES = [ 18 | "Version", 19 | "Shot", 20 | "Asset", 21 | "Task", 22 | "Sequence", 23 | "Project", 24 | "CustomEntity01", 25 | "CustomEntity02", 26 | "CustomEntity03", 27 | ] 28 | 29 | # Custom entity types can be added through environment variables 30 | ENV_CUSTOM_ENTITY_TYPES = "SHOTGRID_CUSTOM_ENTITY_TYPES" # Comma-separated list of custom entity types 31 | ENTITY_TYPES_ENV_VAR = "ENTITY_TYPES" # For backward compatibility 32 | 33 | # Batch operation limits 34 | MAX_BATCH_SIZE = 100 # Maximum number of operations per batch request 35 | MAX_FUZZY_RANGE = 1000 # Maximum range for fuzzy ID searches 36 | MAX_ID_RANGE = 10000 # Maximum range for ID-based searches 37 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | # Multi-stage build for ShotGrid MCP Server 2 | FROM python:3.12-slim AS builder 3 | 4 | WORKDIR /app 5 | 6 | # Install uv for dependency management 7 | RUN pip install --no-cache-dir uv 8 | 9 | # Copy dependency files 10 | COPY pyproject.toml uv.lock ./ 11 | 12 | # Install dependencies 13 | RUN uv pip install --system --no-cache . 14 | 15 | # Final stage 16 | FROM python:3.12-slim 17 | 18 | WORKDIR /app 19 | 20 | # Copy installed dependencies from builder 21 | COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages 22 | COPY --from=builder /usr/local/bin /usr/local/bin 23 | 24 | # Copy application source 25 | COPY src ./src 26 | COPY app.py ./ 27 | 28 | # Create non-root user 29 | RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app 30 | USER appuser 31 | 32 | # Expose port 33 | EXPOSE 8000 34 | 35 | # Health check 36 | HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \ 37 | CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health').read()" || exit 1 38 | 39 | # Run with uvicorn 40 | CMD ["uvicorn", "shotgrid_mcp_server.asgi:app", "--host", "0.0.0.0", "--port", "8000"] 41 | -------------------------------------------------------------------------------- /docker-compose.yml: -------------------------------------------------------------------------------- 1 | version: '3.8' 2 | 3 | services: 4 | shotgrid-mcp: 5 | build: 6 | context: . 7 | dockerfile: Dockerfile 8 | ports: 9 | - "8000:8000" 10 | environment: 11 | # Default ShotGrid credentials 12 | # These can be overridden via HTTP headers for multi-site support 13 | - SHOTGRID_URL=${SHOTGRID_URL:-https://your-site.shotgunstudio.com} 14 | - SHOTGRID_SCRIPT_NAME=${SHOTGRID_SCRIPT_NAME:-your_script_name} 15 | - SHOTGRID_SCRIPT_KEY=${SHOTGRID_SCRIPT_KEY:-your_api_key} 16 | restart: unless-stopped 17 | healthcheck: 18 | test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health').read()"] 19 | interval: 30s 20 | timeout: 10s 21 | retries: 3 22 | start_period: 5s 23 | 24 | # Optional: Nginx reverse proxy for SSL/TLS termination 25 | nginx: 26 | image: nginx:alpine 27 | ports: 28 | - "443:443" 29 | - "80:80" 30 | volumes: 31 | - ./nginx.conf:/etc/nginx/nginx.conf:ro 32 | - ./ssl:/etc/nginx/ssl:ro 33 | depends_on: 34 | - shotgrid-mcp 35 | restart: unless-stopped 36 | # Uncomment to enable nginx 37 | # profiles: 38 | # - with-nginx 39 | -------------------------------------------------------------------------------- /nox_actions/lint.py: -------------------------------------------------------------------------------- 1 | # Import built-in modules 2 | 3 | # Import third-party modules 4 | import nox 5 | 6 | # Ruff version should match .pre-commit-config.yaml 7 | RUFF_VERSION = "0.8.6" 8 | 9 | 10 | def get_default_commands() -> list[str]: 11 | """Get default linting commands.""" 12 | return ["ruff check .", "ruff format --check .", "mypy ."] 13 | 14 | 15 | def lint(session: nox.Session, commands: list[str] | None = None) -> None: 16 | """Run linters.""" 17 | # Install linting tools into the nox virtualenv using pip 18 | session.install(f"ruff=={RUFF_VERSION}", "black", "mypy") 19 | 20 | if commands is None: 21 | # Run default linting commands 22 | commands = get_default_commands() 23 | 24 | # Run commands 25 | for cmd in commands: 26 | parts = cmd.split() 27 | session.run(*parts) 28 | 29 | 30 | def lint_fix(session: nox.Session) -> None: 31 | """Run linters and fix issues.""" 32 | # Install linting tools into the nox virtualenv using pip 33 | session.install(f"ruff=={RUFF_VERSION}", "black", "mypy") 34 | 35 | # Run ruff format 36 | session.run("ruff", "format", "src") 37 | 38 | # Run ruff check with fix 39 | session.run("ruff", "check", "src", "--fix") 40 | -------------------------------------------------------------------------------- /.dockerignore: -------------------------------------------------------------------------------- 1 | # Python 2 | __pycache__/ 3 | *.py[cod] 4 | *$py.class 5 | *.so 6 | .Python 7 | build/ 8 | develop-eggs/ 9 | dist/ 10 | downloads/ 11 | eggs/ 12 | .eggs/ 13 | lib/ 14 | lib64/ 15 | parts/ 16 | sdist/ 17 | var/ 18 | wheels/ 19 | pip-wheel-metadata/ 20 | share/python-wheels/ 21 | *.egg-info/ 22 | .installed.cfg 23 | *.egg 24 | MANIFEST 25 | 26 | # Virtual environments 27 | venv/ 28 | ENV/ 29 | env/ 30 | .venv 31 | 32 | # IDEs 33 | .vscode/ 34 | .idea/ 35 | *.swp 36 | *.swo 37 | *~ 38 | .DS_Store 39 | 40 | # Testing 41 | .pytest_cache/ 42 | .coverage 43 | .coverage.* 44 | coverage.xml 45 | *.cover 46 | .hypothesis/ 47 | htmlcov/ 48 | 49 | # Documentation 50 | docs/_build/ 51 | docs/.doctrees/ 52 | 53 | # Git 54 | .git/ 55 | .gitignore 56 | .gitattributes 57 | 58 | # CI/CD 59 | .github/ 60 | .gitlab-ci.yml 61 | 62 | # Project specific 63 | *.log 64 | *.md 65 | LICENSE 66 | CHANGELOG.md 67 | README*.md 68 | .noxfile 69 | noxfile.py 70 | tests/ 71 | examples/ 72 | scripts/ 73 | images/ 74 | .dockerignore 75 | Dockerfile 76 | docker-compose.yml 77 | .env 78 | .env.* 79 | requirements-dev.txt 80 | requirements-test.txt 81 | mypy.ini 82 | codecov.yml 83 | renovate.json 84 | poetry.lock 85 | run_pycharm.bat 86 | copy_schema.py 87 | test_http_request.py 88 | nox_actions/ 89 | -------------------------------------------------------------------------------- /mypy.ini: -------------------------------------------------------------------------------- 1 | [mypy] 2 | python_version = 3.10 3 | warn_return_any = True 4 | warn_unused_configs = True 5 | disallow_untyped_defs = False 6 | disallow_incomplete_defs = False 7 | check_untyped_defs = True 8 | disallow_untyped_decorators = False 9 | no_implicit_optional = True 10 | strict_optional = True 11 | 12 | # Ignore specific error codes 13 | disable_error_code = arg-type, return-value, typeddict-item, literal-required 14 | 15 | [mypy-shotgrid_mcp_server.*] 16 | follow_imports = skip 17 | 18 | [mypy.plugins.pydantic.*] 19 | follow_imports = skip 20 | 21 | [mypy.plugins.fastapi.*] 22 | follow_imports = skip 23 | 24 | [mypy.plugins.shotgun_api3.*] 25 | follow_imports = skip 26 | ignore_missing_imports = True 27 | 28 | [mypy-shotgun_api3.*] 29 | ignore_missing_imports = True 30 | 31 | [mypy-shotgrid_mcp_server.mockgun_ext] 32 | disallow_untyped_defs = False 33 | check_untyped_defs = False 34 | disallow_any_generics = False 35 | disallow_subclassing_any = False 36 | disallow_any_explicit = False 37 | disallow_any_unimported = False 38 | disallow_any_expr = False 39 | disallow_any_decorated = False 40 | warn_return_any = False 41 | 42 | [mypy-shotgrid_mcp_server.tools.*] 43 | disallow_untyped_defs = False 44 | check_untyped_defs = False 45 | disallow_untyped_decorators = False 46 | -------------------------------------------------------------------------------- /docs/api/shotgrid_mcp_server.md: -------------------------------------------------------------------------------- 1 | # shotgrid_mcp_server 2 | 3 | ShotGrid MCP Server is a Model Context Protocol (MCP) server implementation for Autodesk ShotGrid. 4 | 5 | ## Core Modules 6 | 7 | - [shotgrid_mcp_server.server](shotgrid_mcp_server.server.md) - Server implementation 8 | - [shotgrid_mcp_server.models](shotgrid_mcp_server.models.md) - Data models 9 | - [shotgrid_mcp_server.filters](shotgrid_mcp_server.filters.md) - Filter utilities 10 | - [shotgrid_mcp_server.data_types](shotgrid_mcp_server.data_types.md) - Data type utilities 11 | - [shotgrid_mcp_server.constants](shotgrid_mcp_server.constants.md) - Constants 12 | - [shotgrid_mcp_server.utils](shotgrid_mcp_server.utils.md) - Utility functions 13 | - [shotgrid_mcp_server.mockgun_ext](shotgrid_mcp_server.mockgun_ext.md) - Mockgun extensions 14 | 15 | ## Tools 16 | 17 | - [shotgrid_mcp_server.tools](shotgrid_mcp_server.tools.md) - Tools package 18 | - [shotgrid_mcp_server.tools.base](shotgrid_mcp_server.tools.base.md) - Base tool functionality 19 | - [shotgrid_mcp_server.tools.search_tools](shotgrid_mcp_server.tools.search_tools.md) - Search tools 20 | - [shotgrid_mcp_server.tools.entity_tools](shotgrid_mcp_server.tools.entity_tools.md) - Entity tools 21 | - [shotgrid_mcp_server.tools.schema_tools](shotgrid_mcp_server.tools.schema_tools.md) - Schema tools 22 | -------------------------------------------------------------------------------- /.github/workflows/mr-test.yml: -------------------------------------------------------------------------------- 1 | name: MR Checks 2 | on: [ pull_request ] 3 | 4 | jobs: 5 | python-check: 6 | strategy: 7 | max-parallel: 3 8 | matrix: 9 | target: 10 | - os: 'ubuntu-latest' 11 | triple: 'x86_64-unknown-linux-gnu' 12 | - os: 'macos-latest' 13 | triple: 'x86_64-apple-darwin' 14 | - os: 'windows-latest' 15 | triple: 'x86_64-pc-windows-msvc' 16 | python-version: ["3.10", "3.11", "3.12"] 17 | fail-fast: false 18 | runs-on: ${{ matrix.target.os }} 19 | steps: 20 | - name: Checkout 21 | uses: actions/checkout@v6 22 | - name: Set up Python ${{ matrix.python-version }} 23 | uses: actions/setup-python@v6 24 | with: 25 | python-version: ${{ matrix.python-version }} 26 | - name: Install dependencies 27 | shell: bash 28 | run: | 29 | python -m pip install uv 30 | uv venv 31 | if [ "${{ matrix.target.os }}" = "windows-latest" ]; then 32 | source .venv/Scripts/activate 33 | else 34 | source .venv/bin/activate 35 | fi 36 | uv pip install -r requirements-dev.txt 37 | - name: lint 38 | shell: bash 39 | run: | 40 | if [ "${{ matrix.target.os }}" = "windows-latest" ]; then 41 | source .venv/Scripts/activate 42 | else 43 | source .venv/bin/activate 44 | fi 45 | nox -s lint 46 | -------------------------------------------------------------------------------- /docs/sphinx_conf/conf.py: -------------------------------------------------------------------------------- 1 | """Sphinx configuration for API documentation.""" 2 | 3 | import os 4 | import sys 5 | 6 | # Add the project root directory to the Python path 7 | sys.path.insert(0, os.path.abspath("../../src")) 8 | 9 | # Project information 10 | project = "ShotGrid MCP Server" 11 | copyright = "2025, Hal Long" 12 | author = "Hal Long" 13 | 14 | # General configuration 15 | extensions = [ 16 | "sphinx.ext.autodoc", 17 | "sphinx.ext.napoleon", 18 | "sphinx_autodoc_typehints", 19 | "sphinx_markdown_builder", 20 | ] 21 | 22 | # Napoleon settings 23 | napoleon_google_docstring = True 24 | napoleon_numpy_docstring = False 25 | napoleon_include_init_with_doc = True 26 | napoleon_include_private_with_doc = False 27 | napoleon_include_special_with_doc = True 28 | napoleon_use_admonition_for_examples = False 29 | napoleon_use_admonition_for_notes = False 30 | napoleon_use_admonition_for_references = False 31 | napoleon_use_ivar = False 32 | napoleon_use_param = True 33 | napoleon_use_rtype = True 34 | napoleon_preprocess_types = False 35 | napoleon_type_aliases = None 36 | napoleon_attr_annotations = True 37 | 38 | # Autodoc settings 39 | autodoc_typehints = "description" 40 | autodoc_member_order = "bysource" 41 | autodoc_default_options = { 42 | "members": True, 43 | "undoc-members": True, 44 | "show-inheritance": True, 45 | "special-members": "__init__", 46 | } 47 | 48 | # Source file settings 49 | source_suffix = { 50 | ".rst": "restructuredtext", 51 | ".md": "markdown", 52 | } 53 | -------------------------------------------------------------------------------- /.github/workflows/codecov.yml: -------------------------------------------------------------------------------- 1 | name: Codecov 2 | on: [push, pull_request] 3 | jobs: 4 | run: 5 | runs-on: ubuntu-latest 6 | steps: 7 | - name: Checkout 8 | uses: actions/checkout@v6 9 | with: 10 | fetch-depth: 0 11 | - name: Get repository name 12 | id: repo-name 13 | uses: MariachiBear/get-repo-name-action@v1.3.0 14 | with: 15 | with-owner: 'true' 16 | string-case: 'uppercase' 17 | - name: Set up Python 3.12 18 | uses: actions/setup-python@v6 19 | with: 20 | python-version: '3.12' 21 | - name: Install dependencies 22 | shell: bash 23 | run: | 24 | python -m pip install uv 25 | uv venv 26 | if [ "$RUNNER_OS" = "Windows" ]; then 27 | source .venv/Scripts/activate 28 | else 29 | source .venv/bin/activate 30 | fi 31 | uv pip install -r requirements-dev.txt 32 | - name: Run tests and collect coverage 33 | shell: bash 34 | run: | 35 | if [ "$RUNNER_OS" = "Windows" ]; then 36 | source .venv/Scripts/activate 37 | else 38 | source .venv/bin/activate 39 | fi 40 | nox -s tests 41 | - name: Upload coverage reports to Codecov 42 | uses: codecov/codecov-action@v5 43 | with: 44 | file: ./coverage.xml 45 | token: ${{ secrets.CODECOV_TOKEN }} 46 | slug: loonghao/shotgrid-mcp-server 47 | fail_ci_if_error: false 48 | verbose: true 49 | -------------------------------------------------------------------------------- /fastmcp_entry.py: -------------------------------------------------------------------------------- 1 | """FastMCP Cloud entry point. 2 | 3 | This module is specifically designed for FastMCP Cloud deployment. 4 | It handles the case where the package is not installed but the source 5 | code is available in the container. 6 | 7 | FastMCP Cloud Configuration: 8 | Entrypoint: fastmcp_entry.py 9 | Requirements File: requirements.txt 10 | 11 | HTTP Headers for Multi-Site Support: 12 | X-ShotGrid-URL: ShotGrid server URL for this request 13 | X-ShotGrid-Script-Name: Script name for this request 14 | X-ShotGrid-Script-Key: API key for this request 15 | 16 | Environment Variables (fallback): 17 | SHOTGRID_URL: Your ShotGrid server URL 18 | SHOTGRID_SCRIPT_NAME: Your ShotGrid script name 19 | SHOTGRID_SCRIPT_KEY: Your ShotGrid script key 20 | """ 21 | 22 | # Import built-in modules 23 | import os 24 | import sys 25 | 26 | # Add src directory to Python path for uninstalled package 27 | _current_dir = os.path.dirname(os.path.abspath(__file__)) 28 | _src_dir = os.path.join(_current_dir, "src") 29 | if _src_dir not in sys.path: 30 | sys.path.insert(0, _src_dir) 31 | 32 | # Now we can import the server module 33 | from shotgrid_mcp_server.server import create_server 34 | 35 | # Create MCP server with lazy connection for HTTP mode 36 | # Credentials will be provided via HTTP headers or environment variables 37 | mcp = create_server(lazy_connection=True, preload_schema=False) 38 | 39 | # Export the HTTP ASGI app for deployment 40 | # This enables multi-site support through HTTP headers 41 | app = mcp.http_app(path="/mcp") 42 | 43 | # Alternative name 44 | server = mcp 45 | 46 | -------------------------------------------------------------------------------- /docs/README.md: -------------------------------------------------------------------------------- 1 | # ShotGrid MCP Server Documentation 2 | 3 | This directory contains the documentation for ShotGrid MCP Server, a high-performance implementation of the Model Context Protocol (MCP) for Autodesk ShotGrid. 4 | 5 | ## Documentation Structure 6 | 7 | The documentation is organized into the following sections: 8 | 9 | - **Getting Started**: Basic information to get up and running 10 | - **Servers**: Details about the server components and configuration 11 | - **Clients**: Information about connecting to the server 12 | - **Patterns**: Best practices and patterns for common tasks 13 | 14 | ## Building the Documentation 15 | 16 | This documentation is designed to be built with [Mintlify](https://mintlify.com/), a modern documentation platform. 17 | 18 | ### Local Development 19 | 20 | To run the documentation locally: 21 | 22 | 1. Install Mintlify CLI: 23 | ```bash 24 | npm i -g mintlify 25 | ``` 26 | 27 | 2. Navigate to the docs directory: 28 | ```bash 29 | cd docs 30 | ``` 31 | 32 | 3. Start the development server: 33 | ```bash 34 | mintlify dev 35 | ``` 36 | 37 | 4. Open your browser to [http://localhost:3000](http://localhost:3000) 38 | 39 | ### Deployment 40 | 41 | To deploy the documentation to Mintlify: 42 | 43 | 1. Create an account on [Mintlify](https://mintlify.com/) 44 | 2. Connect your GitHub repository 45 | 3. Configure the deployment settings 46 | 47 | ## Contributing 48 | 49 | To contribute to the documentation: 50 | 51 | 1. Fork the repository 52 | 2. Make your changes 53 | 3. Submit a pull request 54 | 55 | Please ensure your changes follow the existing style and structure. 56 | 57 | ## License 58 | 59 | This documentation is licensed under the same license as the ShotGrid MCP Server project. 60 | -------------------------------------------------------------------------------- /nox_actions/release.py: -------------------------------------------------------------------------------- 1 | # Import built-in modules 2 | import os 3 | import platform 4 | 5 | # Import third-party modules 6 | import nox 7 | 8 | from nox_actions.utils import THIS_ROOT 9 | 10 | 11 | def build_exe(session: nox.Session) -> None: 12 | """Build executable using PyInstaller.""" 13 | # Install uv if not already installed 14 | session.run("python", "-m", "pip", "install", "uv", silent=True) 15 | 16 | # Install build dependencies using uv 17 | session.run("uv", "pip", "install", "pyinstaller", external=True) 18 | session.run("uv", "pip", "install", "-e", ".", external=True) 19 | 20 | # Get platform-specific settings 21 | is_windows = platform.system().lower() == "windows" 22 | exe_ext = ".exe" if is_windows else "" 23 | 24 | # Build executable 25 | session.run( 26 | "pyinstaller", 27 | "--clean", 28 | "--onefile", 29 | "--name", 30 | f"shotgrid_mcp_server{exe_ext}", 31 | os.path.join("src", "shotgrid_mcp_server", "__main__.py"), 32 | env={"PYTHONPATH": THIS_ROOT.as_posix()}, 33 | ) 34 | 35 | 36 | def build_wheel(session: nox.Session) -> None: 37 | """Build Python wheel package. 38 | 39 | Uses `python -m build` with the default isolated build environment. 40 | This avoids any interference from the current environment that could 41 | produce non-standard ZIP archives rejected by PyPI. 42 | """ 43 | # Install the build helper into the nox environment. `python -m build` 44 | # will then create an isolated PEP 517 environment based on 45 | # ``[build-system]`` in ``pyproject.toml``. 46 | session.install("build") 47 | 48 | # Build wheel using an isolated PEP 517 environment. 49 | session.run("python", "-m", "build", "--wheel") 50 | -------------------------------------------------------------------------------- /docs/docs.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://mintlify.com/docs.json", 3 | "background": { 4 | "color": { 5 | "dark": "#222831", 6 | "light": "#EEEEEE" 7 | }, 8 | "decoration": "windows" 9 | }, 10 | "colors": { 11 | "dark": "#f72585", 12 | "light": "#4cc9f0", 13 | "primary": "#2d00f7" 14 | }, 15 | "description": "A high-performance MCP server for ShotGrid integration.", 16 | "footer": { 17 | "socials": { 18 | "github": "https://github.com/loonghao/shotgrid-mcp-server" 19 | } 20 | }, 21 | "name": "ShotGrid MCP Server", 22 | "navbar": { 23 | "primary": { 24 | "href": "https://github.com/loonghao/shotgrid-mcp-server", 25 | "type": "github" 26 | } 27 | }, 28 | "navigation": { 29 | "groups": [ 30 | { 31 | "group": "Get Started", 32 | "pages": [ 33 | "getting-started/welcome", 34 | "getting-started/installation", 35 | "getting-started/quickstart", 36 | "configuration-examples" 37 | ] 38 | }, 39 | { 40 | "group": "Server", 41 | "pages": [ 42 | "servers/overview", 43 | "servers/tools", 44 | "servers/connection-pool", 45 | "servers/schema-loader", 46 | "servers/mockgun" 47 | ] 48 | }, 49 | { 50 | "group": "Clients", 51 | "pages": [ 52 | "clients/overview", 53 | "clients/python-client" 54 | ] 55 | }, 56 | { 57 | "group": "AI Integration", 58 | "pages": [ 59 | "guides/ai-prompts", 60 | "patterns/ai-workflows" 61 | ] 62 | }, 63 | { 64 | "group": "Patterns", 65 | "pages": [ 66 | "patterns/optimized-queries", 67 | "patterns/batch-operations", 68 | "patterns/error-handling" 69 | ] 70 | } 71 | ] 72 | }, 73 | "theme": "mint" 74 | } 75 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/tools/__init__.py: -------------------------------------------------------------------------------- 1 | """Tools for ShotGrid MCP server. 2 | 3 | This package contains all the tools that can be registered with the ShotGrid MCP server. 4 | Each module in this package contains a set of related tools. 5 | """ 6 | 7 | from typing import Any # noqa 8 | 9 | from shotgun_api3.lib.mockgun import Shotgun 10 | 11 | from shotgrid_mcp_server.schema_resources import register_schema_resources 12 | from shotgrid_mcp_server.tools.api_tools import register_api_tools 13 | from shotgrid_mcp_server.tools.create_tools import register_create_tools 14 | from shotgrid_mcp_server.tools.delete_tools import register_delete_tools 15 | from shotgrid_mcp_server.tools.note_tools import register_note_tools 16 | from shotgrid_mcp_server.tools.playlist_tools import register_playlist_tools 17 | from shotgrid_mcp_server.tools.read_tools import register_read_tools 18 | from shotgrid_mcp_server.tools.search_tools import register_search_tools 19 | from shotgrid_mcp_server.tools.thumbnail_tools import register_thumbnail_tools 20 | from shotgrid_mcp_server.tools.types import FastMCPType 21 | from shotgrid_mcp_server.tools.update_tools import register_update_tools 22 | from shotgrid_mcp_server.tools.vendor_tools import register_vendor_tools 23 | 24 | 25 | def register_all_tools(server: FastMCPType, sg: Shotgun) -> None: 26 | """Register all tools and resources with the server. 27 | 28 | Args: 29 | server: FastMCP server instance. 30 | sg: ShotGrid connection. 31 | """ 32 | # Register all tools 33 | register_create_tools(server, sg) 34 | register_read_tools(server, sg) 35 | register_update_tools(server, sg) 36 | register_delete_tools(server, sg) 37 | register_search_tools(server, sg) 38 | register_thumbnail_tools(server, sg) 39 | 40 | # Register entity-specific tools 41 | register_note_tools(server, sg) 42 | register_playlist_tools(server, sg) 43 | register_vendor_tools(server, sg) 44 | 45 | # Register direct API tools 46 | register_api_tools(server, sg) 47 | 48 | # Register schema-related MCP resources 49 | register_schema_resources(server, sg) 50 | -------------------------------------------------------------------------------- /docs/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: ShotGrid MCP Server 3 | description: A high-performance MCP server for ShotGrid integration 4 | --- 5 | 6 | ShotGrid MCP Server Logo 11 | ShotGrid MCP Server Logo 16 | 17 | # ShotGrid MCP Server 18 | 19 | ShotGrid MCP Server is a high-performance implementation of the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) for Autodesk ShotGrid. It provides a standardized way for LLMs to interact with your ShotGrid data and functionality. 20 | 21 | ## Getting Started 22 | 23 | 24 | 29 | Install and set up ShotGrid MCP Server 30 | 31 | 36 | Create your first ShotGrid MCP Server 37 | 38 | 39 | 40 | ## Explore Features 41 | 42 | 43 | 48 | Create tools to expose ShotGrid functionality 49 | 50 | 55 | Efficiently manage ShotGrid API connections 56 | 57 | 62 | Best practices for efficient ShotGrid queries 63 | 64 | 65 | 66 | ## AI Integration 67 | 68 | 69 | 74 | Effective prompts for using ShotGrid MCP with AI assistants 75 | 76 | 81 | Real-world AI workflow examples with ShotGrid 82 | 83 | 84 | -------------------------------------------------------------------------------- /scripts/copy_schema_files.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | """ 3 | Copy schema files to the package directory during installation. 4 | This script is meant to be run during the package installation process. 5 | """ 6 | 7 | import os 8 | import shutil 9 | from pathlib import Path 10 | 11 | from hatchling.builders.hooks.plugin.interface import BuildHookInterface 12 | 13 | 14 | class CopySchemaFilesBuildHook(BuildHookInterface): 15 | """Build hook to copy schema files to the package directory.""" 16 | 17 | def initialize(self, version, build_data): 18 | """Initialize the build hook. 19 | 20 | Args: 21 | version: The version of the package being built. 22 | build_data: The build data. 23 | """ 24 | # Get the source directory (project root) 25 | source_dir = Path(self.root) 26 | 27 | # Source schema files 28 | source_schema = source_dir / "tests" / "data" / "schema.bin" 29 | source_schema_entity = source_dir / "tests" / "data" / "entity_schema.bin" 30 | 31 | # Get the package directory 32 | package_dir = source_dir / "src" / "shotgrid_mcp_server" 33 | 34 | # Create target directory if it doesn't exist 35 | target_dir = package_dir / "data" 36 | os.makedirs(target_dir, exist_ok=True) 37 | 38 | # Target schema files 39 | target_schema = target_dir / "schema.bin" 40 | target_schema_entity = target_dir / "entity_schema.bin" 41 | 42 | # Copy files 43 | if source_schema.exists(): 44 | shutil.copy2(source_schema, target_schema) 45 | print(f"Copied schema file to {target_schema}") 46 | else: 47 | print(f"Warning: Source schema file {source_schema} not found") 48 | 49 | if source_schema_entity.exists(): 50 | shutil.copy2(source_schema_entity, target_schema_entity) 51 | print(f"Copied schema entity file to {target_schema_entity}") 52 | else: 53 | print(f"Warning: Source schema entity file {source_schema_entity} not found") 54 | 55 | 56 | # This is the hook that will be loaded by hatchling 57 | build_hook = CopySchemaFilesBuildHook 58 | -------------------------------------------------------------------------------- /docs/getting-started/installation.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Installation 3 | sidebarTitle: Installation 4 | description: How to install ShotGrid MCP Server 5 | icon: download 6 | --- 7 | 8 | # Installing ShotGrid MCP Server 9 | 10 | ShotGrid MCP Server can be installed using standard Python package managers. We recommend using `uv` for the best performance and dependency resolution. 11 | 12 | ## Requirements 13 | 14 | - Python 3.10 or higher 15 | - Access to a ShotGrid instance (or Mockgun for testing) 16 | 17 | ## Installation Options 18 | 19 | ### Using UV (Recommended) 20 | 21 | [UV](https://github.com/astral-sh/uv) is a fast, reliable Python package installer and resolver. 22 | 23 | ```bash 24 | # Install uv if you don't have it 25 | curl -sSf https://astral.sh/uv/install.sh | bash 26 | 27 | # Install shotgrid-mcp-server 28 | uv pip install shotgrid-mcp-server 29 | ``` 30 | 31 | ### Using pip 32 | 33 | ```bash 34 | pip install shotgrid-mcp-server 35 | ``` 36 | 37 | ## Installing from Source 38 | 39 | For the latest development version or to contribute: 40 | 41 | ```bash 42 | git clone https://github.com/loonghao/shotgrid-mcp-server.git 43 | cd shotgrid-mcp-server 44 | uv pip install -e . 45 | ``` 46 | 47 | ## Installing the ShotGrid Python API 48 | 49 | ShotGrid MCP Server depends on the ShotGrid Python API. The latest versions don't have published wheel files, so you'll need to install it directly from GitHub: 50 | 51 | ```bash 52 | # Using uv 53 | uv pip install git+https://github.com/shotgunsoftware/python-api.git@v3.4.0 54 | 55 | # Using pip 56 | pip install git+https://github.com/shotgunsoftware/python-api.git@v3.4.0 57 | ``` 58 | 59 | ## Verifying Installation 60 | 61 | You can verify that ShotGrid MCP Server is installed correctly by running: 62 | 63 | ```bash 64 | python -c "import shotgrid_mcp_server; print(shotgrid_mcp_server.__version__)" 65 | ``` 66 | 67 | This should print the version number of the installed package. 68 | 69 | ## Next Steps 70 | 71 | Once you have ShotGrid MCP Server installed, you can: 72 | 73 | - Follow the [Quickstart Guide](/getting-started/quickstart) to create your first server 74 | - Learn about [Server Configuration](/servers/overview) options 75 | - Explore the [Tools](/servers/tools) you can create 76 | -------------------------------------------------------------------------------- /docs/getting-started/welcome.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Welcome to ShotGrid MCP Server! 3 | sidebarTitle: Welcome! 4 | description: A high-performance MCP server for ShotGrid integration. 5 | icon: hand-wave 6 | --- 7 | 8 | # ShotGrid MCP Server 9 | 10 | ShotGrid MCP Server is a high-performance implementation of the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) for Autodesk ShotGrid. It provides a standardized way for LLMs to interact with your ShotGrid data and functionality, enabling AI assistants to help with production tracking, asset management, and more. 11 | 12 | ```python 13 | from shotgrid_mcp_server import ShotGridMCPServer 14 | 15 | server = ShotGridMCPServer( 16 | name="ShotGrid Assistant", 17 | shotgrid_url="https://your-site.shotgunstudio.com", 18 | script_name="your_script_name", 19 | api_key="your_api_key" 20 | ) 21 | 22 | @server.tool() 23 | def find_shots(project_name: str, status: str = None): 24 | """Find shots in a project with optional status filter.""" 25 | # The server handles ShotGrid connection management for you 26 | return server.find_shots(project_name, status) 27 | 28 | if __name__ == "__main__": 29 | server.run() 30 | ``` 31 | 32 | ## What is MCP? 33 | 34 | The Model Context Protocol lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. It is often described as "the USB-C port for AI", providing a uniform way to connect LLMs to resources they can use. 35 | 36 | MCP servers can: 37 | 38 | * Expose data through `Resources` (think of these as GET endpoints; they are used to load information into the LLM's context) 39 | * Provide functionality through `Tools` (like POST endpoints; they are used to execute code or produce side effects) 40 | * Define interaction patterns through `Prompts` (reusable templates for LLM interactions) 41 | 42 | ShotGrid MCP Server implements this protocol specifically for ShotGrid, making it easy to build AI assistants that can interact with your production data. 43 | 44 | ## Why ShotGrid MCP Server? 45 | 46 | ShotGrid MCP Server provides several key benefits: 47 | 48 | 🚀 **Optimized for ShotGrid**: Built specifically for ShotGrid's data model and API 49 | 50 | 🔄 **Connection Pooling**: Efficiently manages ShotGrid API connections 51 | 52 | 🧠 **Smart Queries**: Implements best practices for efficient ShotGrid queries 53 | 54 | 🛡️ **Robust Error Handling**: Gracefully handles ShotGrid API errors 55 | 56 | 🔌 **MCP Compatible**: Works with any MCP-compatible client, including Claude, ChatGPT, and more 57 | 58 | Whether you're building a production assistant, a data visualization tool, or integrating ShotGrid with your AI workflows, ShotGrid MCP Server provides the foundation you need. 59 | -------------------------------------------------------------------------------- /tests/test_asgi.py: -------------------------------------------------------------------------------- 1 | """Tests for ASGI application.""" 2 | 3 | # Import built-in modules 4 | import os 5 | from unittest.mock import patch 6 | 7 | # Import third-party modules 8 | import pytest 9 | from starlette.middleware import Middleware 10 | from starlette.middleware.cors import CORSMiddleware 11 | 12 | # Import local modules 13 | from shotgrid_mcp_server.asgi import create_asgi_app 14 | 15 | 16 | @pytest.fixture 17 | def mock_env_vars(): 18 | """Mock environment variables for testing.""" 19 | env_vars = { 20 | "SHOTGRID_URL": "https://test.shotgunstudio.com", 21 | "SHOTGRID_SCRIPT_NAME": "test_script", 22 | "SHOTGRID_SCRIPT_KEY": "test_key", 23 | } 24 | with patch.dict(os.environ, env_vars): 25 | yield env_vars 26 | 27 | 28 | def test_create_asgi_app_default(mock_env_vars): 29 | """Test creating ASGI app with default settings.""" 30 | app = create_asgi_app() 31 | assert app is not None 32 | 33 | 34 | def test_create_asgi_app_with_custom_path(mock_env_vars): 35 | """Test creating ASGI app with custom path.""" 36 | custom_path = "/api/shotgrid" 37 | app = create_asgi_app(path=custom_path) 38 | assert app is not None 39 | 40 | 41 | def test_create_asgi_app_with_middleware(mock_env_vars): 42 | """Test creating ASGI app with custom middleware.""" 43 | cors_middleware = Middleware( 44 | CORSMiddleware, 45 | allow_origins=["https://example.com"], 46 | allow_methods=["GET", "POST"], 47 | allow_headers=["*"], 48 | ) 49 | 50 | app = create_asgi_app(middleware=[cors_middleware]) 51 | assert app is not None 52 | 53 | 54 | def test_create_asgi_app_with_multiple_middleware(mock_env_vars): 55 | """Test creating ASGI app with multiple middleware.""" 56 | from starlette.middleware.gzip import GZipMiddleware 57 | 58 | middleware_list = [ 59 | Middleware( 60 | CORSMiddleware, 61 | allow_origins=["*"], 62 | allow_methods=["*"], 63 | allow_headers=["*"], 64 | ), 65 | Middleware(GZipMiddleware, minimum_size=1000), 66 | ] 67 | 68 | app = create_asgi_app(middleware=middleware_list) 69 | assert app is not None 70 | 71 | 72 | def test_create_asgi_app_lazy_initialization(mock_env_vars): 73 | """Test that the module-level app uses lazy initialization.""" 74 | # Import the module 75 | from shotgrid_mcp_server import asgi 76 | 77 | # The app should be a function (lazy init), not an instance 78 | assert callable(asgi.app) 79 | 80 | # Calling get_app() should create the instance 81 | app_instance = asgi.get_app() 82 | assert app_instance is not None 83 | 84 | # Calling again should return the same instance (singleton) 85 | app_instance2 = asgi.get_app() 86 | assert app_instance is app_instance2 87 | -------------------------------------------------------------------------------- /docs/guides/authentication.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Authentication' 3 | description: 'Learn how to authenticate with ShotGrid MCP Server' 4 | --- 5 | 6 | # Authentication 7 | 8 | ShotGrid MCP Server uses ShotGrid's script-based authentication to connect to your ShotGrid instance. 9 | 10 | ## Script-Based Authentication 11 | 12 | ShotGrid provides a script-based authentication method that uses a script name and API key. This is the recommended authentication method for server-to-server communication. 13 | 14 | ### Creating a Script User 15 | 16 | To create a script user in ShotGrid: 17 | 18 | 1. Log in to your ShotGrid instance as an admin 19 | 2. Go to **Admin > Scripts** 20 | 3. Click **+ New Script** 21 | 4. Enter a name for your script (e.g., "ShotGrid MCP Server") 22 | 5. Select the appropriate permission group 23 | 6. Click **Save** 24 | 7. ShotGrid will generate a script name and API key 25 | 26 | ### Permission Groups 27 | 28 | When creating a script user, you need to assign it to a permission group. The permission group determines what actions the script can perform in ShotGrid. 29 | 30 | For ShotGrid MCP Server, we recommend creating a dedicated permission group with the following permissions: 31 | 32 | - **Read access** to all entity types you want to query 33 | - **Write access** to entity types you want to modify 34 | - **Admin access** to schema (if you need to use schema-related tools) 35 | 36 | ### Configuration 37 | 38 | Once you have your script name and API key, you can configure ShotGrid MCP Server to use them: 39 | 40 | ```json 41 | { 42 | "shotgrid": { 43 | "server": "https://your-site.shotgunstudio.com", 44 | "script_name": "your_script_name", 45 | "api_key": "your_api_key" 46 | } 47 | } 48 | ``` 49 | 50 | Or using environment variables: 51 | 52 | ```bash 53 | export SHOTGRID_SERVER="https://your-site.shotgunstudio.com" 54 | export SHOTGRID_SCRIPT_NAME="your_script_name" 55 | export SHOTGRID_API_KEY="your_api_key" 56 | ``` 57 | 58 | ## Security Considerations 59 | 60 | - **API Key Security**: Treat your API key like a password. Do not commit it to version control or share it publicly. 61 | - **Least Privilege**: Give your script user only the permissions it needs. 62 | - **Firewall Rules**: Consider restricting access to your ShotGrid instance by IP address. 63 | - **Audit Logs**: Regularly review ShotGrid audit logs to monitor script user activity. 64 | 65 | ## Troubleshooting 66 | 67 | If you encounter authentication issues: 68 | 69 | 1. Verify that your script name and API key are correct 70 | 2. Check that your script user has the necessary permissions 71 | 3. Ensure your ShotGrid instance is accessible from the server running ShotGrid MCP Server 72 | 4. Check for any IP restrictions that might be blocking access 73 | 74 | ## Next Steps 75 | 76 | Once you have set up authentication, you can proceed to explore the [Tools](/guides/tools) available in ShotGrid MCP Server. 77 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/__init__.py: -------------------------------------------------------------------------------- 1 | """ShotGrid MCP Server Package. 2 | 3 | This package provides a Model Context Protocol (MCP) server for ShotGrid, 4 | allowing AI assistants to interact with ShotGrid data. 5 | """ 6 | 7 | __version__ = "0.1.0" 8 | 9 | # Define exported symbols 10 | __all__ = [ 11 | # ASGI 12 | "create_asgi_app", 13 | # Exceptions 14 | "ConnectionError", 15 | "EntityNotFoundError", 16 | "FilterError", 17 | "PermissionError", 18 | "SerializationError", 19 | "ShotGridMCPError", 20 | # Filter utilities 21 | "build_date_filter", 22 | "combine_filters", 23 | "create_date_filter", 24 | "process_filters", 25 | # Models 26 | "DateRangeFilter", 27 | "EntityDict", 28 | "EntitiesResponse", 29 | "Filter", 30 | "FilterList", 31 | "FilterOperator", 32 | "ProjectDict", 33 | "ProjectsResponse", 34 | "ShotGridDataType", 35 | "TimeFilter", 36 | "TimeUnit", 37 | "UserDict", 38 | "UsersResponse", 39 | "create_assigned_to_filter", 40 | "create_between_filter", 41 | "create_by_user_filter", 42 | "create_contains_filter", 43 | "create_in_last_filter", 44 | "create_in_next_filter", 45 | "create_in_project_filter", 46 | "create_is_filter", 47 | "create_today_filter", 48 | "create_tomorrow_filter", 49 | "create_yesterday_filter", 50 | # Server 51 | "create_server", 52 | "main", 53 | # Utilities 54 | "ShotGridJSONEncoder", 55 | "serialize_entity", 56 | ] 57 | 58 | # Import filter utilities from shotgrid-query 59 | from shotgrid_query import ( 60 | FilterBuilder, 61 | TimeFilter, 62 | build_date_filter, 63 | combine_filters, 64 | create_date_filter, 65 | process_filters, 66 | ) 67 | from shotgrid_query import ( 68 | FilterModel as Filter, 69 | ) 70 | from shotgrid_query import ( 71 | FilterOperatorEnum as FilterOperator, 72 | ) 73 | from shotgrid_query import ( 74 | TimeUnitEnum as TimeUnit, 75 | ) 76 | 77 | from shotgrid_mcp_server.asgi import create_asgi_app 78 | from shotgrid_mcp_server.exceptions import ( 79 | ConnectionError, 80 | EntityNotFoundError, 81 | FilterError, 82 | PermissionError, 83 | SerializationError, 84 | ShotGridMCPError, 85 | ) 86 | 87 | # Import MCP-specific models from local models module 88 | from shotgrid_mcp_server.models import ( 89 | DateRangeFilter, 90 | EntitiesResponse, 91 | EntityDict, 92 | FilterList, 93 | ProjectDict, 94 | ProjectsResponse, 95 | ShotGridDataType, 96 | UserDict, 97 | UsersResponse, 98 | create_assigned_to_filter, 99 | create_between_filter, 100 | create_by_user_filter, 101 | create_contains_filter, 102 | create_in_last_filter, 103 | create_in_next_filter, 104 | create_in_project_filter, 105 | create_is_filter, 106 | create_today_filter, 107 | create_tomorrow_filter, 108 | create_yesterday_filter, 109 | ) 110 | from shotgrid_mcp_server.server import create_server, main 111 | from shotgrid_mcp_server.utils import ShotGridJSONEncoder, serialize_entity 112 | -------------------------------------------------------------------------------- /tests/test_utils.py: -------------------------------------------------------------------------------- 1 | """Tests for utils module.""" 2 | 3 | import os 4 | import tempfile 5 | from pathlib import Path 6 | from unittest import mock 7 | 8 | from shotgrid_mcp_server.utils import ( 9 | generate_default_file_path, 10 | ) 11 | 12 | 13 | class TestGenerateDefaultFilePath: 14 | """Tests for generate_default_file_path function.""" 15 | 16 | def test_generate_default_file_path_default_params(self): 17 | """Test generate_default_file_path with default parameters.""" 18 | # Mock expanduser to return a temporary directory 19 | with mock.patch("os.path.expanduser") as mock_expanduser: 20 | with tempfile.TemporaryDirectory() as temp_dir: 21 | mock_expanduser.return_value = temp_dir 22 | 23 | # Call the function 24 | result = generate_default_file_path("Shot", 123) 25 | 26 | # Check the result 27 | expected_dir = Path(temp_dir) / ".shotgrid_mcp" / "thumbnails" 28 | expected_file = expected_dir / "Shot_123_image.jpg" 29 | assert result == str(expected_file) 30 | 31 | # Verify the directory was created 32 | assert expected_dir.exists() 33 | 34 | def test_generate_default_file_path_custom_params(self): 35 | """Test generate_default_file_path with custom parameters.""" 36 | # Mock expanduser to return a temporary directory 37 | with mock.patch("os.path.expanduser") as mock_expanduser: 38 | with tempfile.TemporaryDirectory() as temp_dir: 39 | mock_expanduser.return_value = temp_dir 40 | 41 | # Call the function with custom parameters 42 | result = generate_default_file_path( 43 | entity_type="Asset", 44 | entity_id=456, 45 | field_name="custom_image", 46 | image_format="png", 47 | ) 48 | 49 | # Check the result 50 | expected_dir = Path(temp_dir) / ".shotgrid_mcp" / "thumbnails" 51 | expected_file = expected_dir / "Asset_456_custom_image.png" 52 | assert result == str(expected_file) 53 | 54 | # Verify the directory was created 55 | assert expected_dir.exists() 56 | 57 | def test_generate_default_file_path_directory_creation(self): 58 | """Test that generate_default_file_path creates the directory if it doesn't exist.""" 59 | # Mock expanduser to return a temporary directory 60 | with mock.patch("os.path.expanduser") as mock_expanduser: 61 | with tempfile.TemporaryDirectory() as temp_dir: 62 | mock_expanduser.return_value = temp_dir 63 | 64 | # Ensure the directory doesn't exist 65 | expected_dir = Path(temp_dir) / ".shotgrid_mcp" / "thumbnails" 66 | if expected_dir.exists(): 67 | os.rmdir(expected_dir) 68 | 69 | # Call the function 70 | generate_default_file_path("Version", 789) 71 | 72 | # Verify the directory was created 73 | assert expected_dir.exists() 74 | -------------------------------------------------------------------------------- /tests/test_shotgun_args.py: -------------------------------------------------------------------------------- 1 | """Tests for ShotGrid arguments handling functions.""" 2 | 3 | import unittest 4 | 5 | from shotgrid_mcp_server.connection_pool import ( 6 | _get_value_from_shotgun_args, 7 | _ignore_shotgun_args, 8 | get_shotgun_connection_args, 9 | ) 10 | 11 | 12 | class TestShotgunArgs(unittest.TestCase): 13 | """Test ShotGrid arguments handling.""" 14 | 15 | def test_get_value_from_shotgun_args(self): 16 | """Test _get_value_from_shotgun_args function.""" 17 | # Test with empty args 18 | self.assertEqual(_get_value_from_shotgun_args({}, "key", "default"), "default") 19 | 20 | # Test with None args 21 | self.assertEqual(_get_value_from_shotgun_args(None, "key", "default"), "default") 22 | 23 | # Test with key not in args 24 | self.assertEqual(_get_value_from_shotgun_args({"other_key": "value"}, "key", "default"), "default") 25 | 26 | # Test with key in args but value is None 27 | self.assertEqual(_get_value_from_shotgun_args({"key": None}, "key", "default"), "default") 28 | 29 | # Test with key in args and value is not None 30 | self.assertEqual(_get_value_from_shotgun_args({"key": "value"}, "key", "default"), "value") 31 | 32 | def test_ignore_shotgun_args(self): 33 | """Test _ignore_shotgun_args function.""" 34 | # Test with empty args 35 | self.assertEqual(_ignore_shotgun_args({}), {}) 36 | 37 | # Test with None args 38 | self.assertEqual(_ignore_shotgun_args(None), {}) 39 | 40 | # Test with ShotGrid-specific args 41 | args = { 42 | "max_rpc_attempts": 10, 43 | "timeout_secs": 30, 44 | "rpc_attempt_interval": 10000, 45 | "other_key": "value", 46 | } 47 | expected = {"other_key": "value"} 48 | self.assertEqual(_ignore_shotgun_args(args), expected) 49 | 50 | # Test with no ShotGrid-specific args 51 | args = {"other_key": "value"} 52 | self.assertEqual(_ignore_shotgun_args(args), args) 53 | 54 | def test_get_shotgun_connection_args(self): 55 | """Test get_shotgun_connection_args function.""" 56 | # Test with empty args 57 | args = get_shotgun_connection_args({}) 58 | self.assertEqual(args["max_rpc_attempts"], 10) 59 | self.assertEqual(args["timeout_secs"], 30) 60 | self.assertEqual(args["rpc_attempt_interval"], 10000) 61 | 62 | # Test with custom args 63 | args = get_shotgun_connection_args( 64 | { 65 | "max_rpc_attempts": 20, 66 | "timeout_secs": 60, 67 | "rpc_attempt_interval": 20000, 68 | } 69 | ) 70 | self.assertEqual(args["max_rpc_attempts"], 20) 71 | self.assertEqual(args["timeout_secs"], 60) 72 | self.assertEqual(args["rpc_attempt_interval"], 20000) 73 | 74 | # Test with None args 75 | args = get_shotgun_connection_args(None) 76 | self.assertEqual(args["max_rpc_attempts"], 10) 77 | self.assertEqual(args["timeout_secs"], 30) 78 | self.assertEqual(args["rpc_attempt_interval"], 10000) 79 | 80 | 81 | if __name__ == "__main__": 82 | unittest.main() 83 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/logger.py: -------------------------------------------------------------------------------- 1 | """Logging configuration for the ShotGrid MCP server. 2 | 3 | This module provides a centralized logging configuration for the entire application. 4 | """ 5 | 6 | # Import built-in modules 7 | import logging 8 | import logging.handlers 9 | import sys 10 | from datetime import datetime 11 | from pathlib import Path 12 | from typing import Optional 13 | 14 | # Import third-party modules 15 | from platformdirs import PlatformDirs 16 | 17 | # Create platform dirs instance 18 | dirs = PlatformDirs("shotgrid-mcp-server") 19 | 20 | 21 | def get_logger(name: Optional[str] = None) -> logging.Logger: 22 | """Get a logger instance. 23 | 24 | Args: 25 | name: The name of the logger. If None, returns the root logger. 26 | 27 | Returns: 28 | logging.Logger: A logger instance. 29 | """ 30 | logger = logging.getLogger(name) 31 | if not logger.handlers: 32 | handler = logging.StreamHandler(sys.stdout) 33 | formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s") 34 | handler.setFormatter(formatter) 35 | logger.addHandler(handler) 36 | logger.setLevel(logging.INFO) 37 | return logger 38 | 39 | 40 | def setup_logging(log_dir: Optional[str] = None) -> None: 41 | """Set up logging configuration. 42 | 43 | Args: 44 | log_dir: Optional directory to store log files. If not provided, 45 | logs will be stored in the platform-specific user log directory. 46 | """ 47 | # Use platform-specific log directory if not specified 48 | if log_dir is None: 49 | log_dir = dirs.user_log_dir 50 | 51 | # Create logs directory if it doesn't exist 52 | log_path = Path(log_dir) 53 | log_path.mkdir(parents=True, exist_ok=True) 54 | 55 | # Generate log filename with timestamp 56 | timestamp = datetime.now().strftime("%Y%m%d") 57 | log_file = log_path / f"shotgrid_mcp_server_{timestamp}.log" 58 | 59 | # Create formatters 60 | file_formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(pathname)s:%(lineno)d - %(message)s") 61 | console_formatter = logging.Formatter("%(asctime)s - %(levelname)s - %(message)s") 62 | 63 | # Create file handler with rotation 64 | file_handler = logging.handlers.RotatingFileHandler( 65 | str(log_file), # Convert Path to str for compatibility 66 | maxBytes=10 * 1024 * 1024, # 10MB 67 | backupCount=5, 68 | encoding="utf-8", 69 | ) 70 | file_handler.setFormatter(file_formatter) 71 | file_handler.setLevel(logging.DEBUG) 72 | 73 | # Create console handler 74 | console_handler = logging.StreamHandler() 75 | console_handler.setFormatter(console_formatter) 76 | console_handler.setLevel(logging.INFO) 77 | 78 | # Configure root logger 79 | root_logger = logging.getLogger() 80 | root_logger.setLevel(logging.DEBUG) 81 | 82 | # Remove existing handlers to avoid duplicates 83 | root_logger.handlers.clear() 84 | 85 | # Add handlers 86 | root_logger.addHandler(file_handler) 87 | root_logger.addHandler(console_handler) 88 | 89 | # Create logger for this application 90 | logger = logging.getLogger("mcp_shotgrid_server") 91 | logger.info("Logging system initialized. Log file: %s", log_file) 92 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/exceptions.py: -------------------------------------------------------------------------------- 1 | """Custom exceptions for ShotGrid MCP server. 2 | 3 | This module defines custom exception types for the ShotGrid MCP server. 4 | """ 5 | 6 | from fastmcp.exceptions import ToolError 7 | 8 | 9 | class ShotGridMCPError(ToolError): 10 | """Base class for all ShotGrid MCP server errors.""" 11 | 12 | def __init__(self, message: str): 13 | """Initialize the error. 14 | 15 | Args: 16 | message: Error message. 17 | """ 18 | super().__init__(message) 19 | 20 | 21 | class FilterError(ShotGridMCPError): 22 | """Error raised when a filter is invalid.""" 23 | 24 | def __init__(self, message: str): 25 | """Initialize the error. 26 | 27 | Args: 28 | message: Error message. 29 | """ 30 | super().__init__(f"Filter error: {message}") 31 | 32 | 33 | class SerializationError(ShotGridMCPError): 34 | """Error raised when serialization fails.""" 35 | 36 | def __init__(self, message: str): 37 | """Initialize the error. 38 | 39 | Args: 40 | message: Error message. 41 | """ 42 | super().__init__(f"Serialization error: {message}") 43 | 44 | 45 | class EntityNotFoundError(ShotGridMCPError): 46 | """Error raised when an entity is not found.""" 47 | 48 | def __init__(self, entity_type: str = None, entity_id: int = None, message: str = None): 49 | """Initialize the error. 50 | 51 | Args: 52 | entity_type: Type of entity that was not found. 53 | entity_id: Optional ID of the entity. 54 | message: Optional custom message. 55 | """ 56 | self.entity_type = entity_type 57 | self.entity_id = entity_id 58 | 59 | if message: 60 | error_message = message 61 | elif entity_type and entity_id: 62 | error_message = f"{entity_type} with ID {entity_id} not found" 63 | elif entity_type: 64 | error_message = f"{entity_type} not found" 65 | else: 66 | error_message = "Entity not found" 67 | super().__init__(error_message) 68 | 69 | 70 | class PermissionError(ShotGridMCPError): 71 | """Error raised when a user does not have permission to perform an action.""" 72 | 73 | def __init__(self, message: str): 74 | """Initialize the error. 75 | 76 | Args: 77 | message: Error message. 78 | """ 79 | super().__init__(f"Permission denied: {message}") 80 | 81 | 82 | class ConnectionError(ShotGridMCPError): 83 | """Error raised when a connection to ShotGrid fails.""" 84 | 85 | def __init__(self, message: str): 86 | """Initialize the error. 87 | 88 | Args: 89 | message: Error message. 90 | """ 91 | super().__init__(f"Connection error: {message}") 92 | 93 | 94 | class ConfigurationError(ShotGridMCPError): 95 | """Error raised when there is a configuration error.""" 96 | 97 | def __init__(self, message: str): 98 | """Initialize the error. 99 | 100 | Args: 101 | message: Error message. 102 | """ 103 | super().__init__(f"Configuration error: {message}") 104 | 105 | 106 | class NoAvailableInstancesError(Exception): 107 | """Pool manager does not have any available instances to provide""" 108 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/shotgun_args.py: -------------------------------------------------------------------------------- 1 | """ShotGrid arguments handling module. 2 | 3 | This module provides utilities for handling ShotGrid arguments and configuration. 4 | """ 5 | 6 | import logging 7 | from typing import Any, Dict, Optional, TypeVar 8 | 9 | # Configure logging 10 | logger = logging.getLogger(__name__) 11 | 12 | # Type variables 13 | T = TypeVar("T") 14 | 15 | 16 | def _get_value_from_shotgun_args( 17 | shotgun_args: Dict[str, Any], 18 | key: str, 19 | default_value: T, 20 | ) -> T: 21 | """Get a value from ShotGrid arguments with a default fallback. 22 | 23 | Args: 24 | shotgun_args: Dictionary of ShotGrid arguments. 25 | key: Key to look up in the arguments. 26 | default_value: Default value to use if key is not found. 27 | 28 | Returns: 29 | Value from arguments or default value. 30 | """ 31 | if not shotgun_args or key not in shotgun_args: 32 | return default_value 33 | 34 | value = shotgun_args.get(key) 35 | if value is None: 36 | return default_value 37 | 38 | return value 39 | 40 | 41 | def _ignore_shotgun_args(shotgun_args: Dict[str, Any]) -> Dict[str, Any]: 42 | """Filter out ShotGrid-specific arguments. 43 | 44 | Args: 45 | shotgun_args: Dictionary of ShotGrid arguments. 46 | 47 | Returns: 48 | Dictionary with ShotGrid-specific arguments removed. 49 | """ 50 | if not shotgun_args: 51 | return {} 52 | 53 | # Create a copy of the arguments 54 | kwargs = shotgun_args.copy() 55 | 56 | # Remove ShotGrid-specific arguments 57 | for key in ["max_rpc_attempts", "timeout_secs", "rpc_attempt_interval"]: 58 | if key in kwargs: 59 | del kwargs[key] 60 | 61 | return kwargs 62 | 63 | 64 | def get_shotgun_connection_args( 65 | shotgun_args: Optional[Dict[str, Any]] = None, 66 | ) -> Dict[str, Any]: 67 | """Get ShotGrid connection arguments with default values. 68 | 69 | Args: 70 | shotgun_args: Optional dictionary of ShotGrid arguments. 71 | 72 | Returns: 73 | Dictionary of ShotGrid connection arguments with defaults applied. 74 | """ 75 | shotgun_args = shotgun_args or {} 76 | 77 | # Get connection parameters with defaults (increased for better reliability) 78 | max_rpc_attempts = _get_value_from_shotgun_args( 79 | shotgun_args, "max_rpc_attempts", default_value=10 80 | ) # Increased from 5 to 10 for better reliability with slow connections 81 | timeout_secs = _get_value_from_shotgun_args( 82 | shotgun_args, "timeout_secs", default_value=30 83 | ) # Increased from 10 to 30 seconds to handle larger responses 84 | rpc_attempt_interval = _get_value_from_shotgun_args( 85 | shotgun_args, "rpc_attempt_interval", default_value=10000 86 | ) # Increased from 5000 to 10000ms to reduce server load 87 | 88 | # Create connection arguments dictionary 89 | connection_args = { 90 | "max_rpc_attempts": max_rpc_attempts, 91 | "timeout_secs": timeout_secs, 92 | "rpc_attempt_interval": rpc_attempt_interval, 93 | } 94 | 95 | # Log connection parameters 96 | logger.debug( 97 | "ShotGrid connection parameters: max_rpc_attempts=%s, timeout_secs=%s, rpc_attempt_interval=%s", 98 | max_rpc_attempts, 99 | timeout_secs, 100 | rpc_attempt_interval, 101 | ) 102 | 103 | return connection_args 104 | -------------------------------------------------------------------------------- /noxfile.py: -------------------------------------------------------------------------------- 1 | # Import built-in modules 2 | import os 3 | import sys 4 | 5 | # Import third-party modules 6 | import nox 7 | 8 | 9 | ROOT = os.path.dirname(__file__) 10 | 11 | # Ensure shotgrid_mcp_server is importable 12 | if ROOT not in sys.path: 13 | sys.path.append(ROOT) 14 | 15 | # Import local modules 16 | from nox_actions import docs, lint, release 17 | from nox_actions.utils import PACKAGE_NAME, THIS_ROOT 18 | 19 | 20 | @nox.session(name="tests") 21 | def tests(session: nox.Session) -> None: 22 | """Run the test suite with pytest.""" 23 | 24 | # Install test + runtime dependencies into the nox virtualenv using pip 25 | # We deliberately avoid `uv pip` here to sidestep Windows permission issues 26 | # when uv tries to manage its own wheel cache. 27 | session.install("-r", "requirements-test.txt") 28 | 29 | # Run tests 30 | test_root = os.path.join(ROOT, "tests") 31 | 32 | # Get any additional arguments passed after -- 33 | pytest_args = session.posargs if session.posargs else [] 34 | 35 | # Default arguments 36 | default_args = [ 37 | f"--cov={PACKAGE_NAME}", 38 | "--cov-report=xml:coverage.xml", 39 | "--cov-report=term", 40 | f"--rootdir={test_root}", 41 | ] 42 | 43 | # Ensure src/ is on PYTHONPATH so we can import the package without installing it 44 | src_root = os.path.join(ROOT, "src") 45 | env = {"PYTHONPATH": os.pathsep.join([src_root, THIS_ROOT.as_posix()])} 46 | 47 | # Run pytest with all arguments 48 | session.run("pytest", *default_args, *pytest_args, env=env) 49 | 50 | 51 | @nox.session(name="lint") 52 | def lint_check(session: nox.Session) -> None: 53 | """Run the linter.""" 54 | # Run ruff and mypy via the shared lint helpers 55 | commands = ["ruff check src", "ruff format --check src"] 56 | lint.lint(session, commands) 57 | 58 | # Run mypy but ignore errors for now 59 | try: 60 | session.run("mypy", "src") 61 | except Exception: 62 | session.log("mypy found errors, but we're ignoring them for now") 63 | 64 | 65 | @nox.session(name="lint-fix") 66 | def lint_fix(session: nox.Session) -> None: 67 | """Run the linter and fix issues.""" 68 | # Run ruff format and ruff check --fix via the shared lint helpers 69 | lint.lint_fix(session) 70 | 71 | 72 | @nox.session(name="build-wheel") 73 | def build_wheel(session: nox.Session) -> None: 74 | """Build Python wheel package.""" 75 | # Delegate to the shared release helper, which uses ``python -m build`` 76 | # with an isolated PEP 517 environment. 77 | release.build_wheel(session) 78 | 79 | 80 | @nox.session(name="docs-api") 81 | def docs_api(session: nox.Session) -> None: 82 | """Generate API documentation using Sphinx.""" 83 | docs.generate_api_docs(session) 84 | 85 | 86 | @nox.session(name="docs-preview") 87 | def docs_preview(session: nox.Session) -> None: 88 | """Preview documentation locally using Mintlify.""" 89 | docs.preview_docs(session) 90 | 91 | 92 | @nox.session(name="docs-build") 93 | def docs_build(session: nox.Session) -> None: 94 | """Build documentation using Mintlify.""" 95 | docs.build_docs(session) 96 | 97 | 98 | @nox.session(name="docs-deploy") 99 | def docs_deploy(session: nox.Session) -> None: 100 | """Deploy documentation to Mintlify.""" 101 | docs.deploy_docs(session) 102 | 103 | 104 | @nox.session(name="docs-static") 105 | def docs_static(session: nox.Session) -> None: 106 | """Generate a static website from Mintlify documentation.""" 107 | docs.generate_static_site(session) 108 | -------------------------------------------------------------------------------- /tests/test_ssl_fix.py: -------------------------------------------------------------------------------- 1 | """Tests for SSL fix in thumbnail download.""" 2 | 3 | import os 4 | import ssl 5 | import tempfile 6 | from unittest.mock import MagicMock, patch 7 | 8 | import requests 9 | from shotgun_api3.shotgun import Shotgun 10 | 11 | from shotgrid_mcp_server.tools.thumbnail_tools import download_thumbnail 12 | from shotgrid_mcp_server.utils import create_ssl_context, download_file 13 | 14 | 15 | def test_create_ssl_context(): 16 | """Test creating SSL context with different TLS versions.""" 17 | # Test with default TLS version 18 | context = create_ssl_context() 19 | assert context.minimum_version == ssl.TLSVersion.TLSv1_2 20 | 21 | # Test with explicit TLS version 22 | context = create_ssl_context(ssl.TLSVersion.TLSv1_1) 23 | assert context.minimum_version == ssl.TLSVersion.TLSv1_1 24 | 25 | 26 | @patch("requests.Session") 27 | def test_download_file_with_ssl_error(mock_session_class): 28 | """Test download_file with SSL error fallback.""" 29 | # Setup mock session and responses 30 | mock_session = MagicMock() 31 | mock_session_class.return_value = mock_session 32 | 33 | # First response with SSL error 34 | mock_response1 = MagicMock() 35 | mock_response1.__enter__.return_value = mock_response1 36 | mock_response1.raise_for_status.side_effect = requests.exceptions.SSLError("SSL: WRONG_VERSION_NUMBER") 37 | 38 | # Second response succeeds 39 | mock_response2 = MagicMock() 40 | mock_response2.__enter__.return_value = mock_response2 41 | mock_response2.raise_for_status.return_value = None 42 | mock_response2.headers.get.return_value = "1000" 43 | mock_response2.iter_content.return_value = [b"test data"] 44 | 45 | # Configure mock session to return different responses 46 | mock_session.get.side_effect = [mock_response1, mock_response2] 47 | 48 | with tempfile.TemporaryDirectory() as temp_dir: 49 | file_path = os.path.join(temp_dir, "test.jpg") 50 | 51 | # Call the function with a URL 52 | download_file("https://example.com/test.jpg", file_path) 53 | 54 | # Verify the session was created and get was called 55 | # Note: We don't assert_called_once() because download_file creates multiple sessions 56 | # when the first attempt fails with SSL error 57 | assert mock_session_class.call_count >= 1 58 | assert mock_session.get.call_count >= 1 59 | 60 | # Verify file was created (mock doesn't actually create it, so we'll create it) 61 | with open(file_path, "wb") as f: 62 | f.write(b"test data") 63 | assert os.path.exists(file_path) 64 | 65 | 66 | def test_download_thumbnail_with_ssl_error(): 67 | """Test download_thumbnail with SSL error fallback. 68 | 69 | This test verifies that the download_thumbnail function can handle SSL errors 70 | by using a simplified approach that doesn't rely on mocking internal implementation details. 71 | """ 72 | # Create a mock ShotGrid instance 73 | mock_sg = MagicMock(spec=Shotgun) 74 | 75 | # Setup find_one to return an entity with attachment 76 | mock_entity = {"id": 123, "image": {"id": 456, "type": "Attachment"}} 77 | mock_sg.find_one.return_value = mock_entity 78 | 79 | # Setup download_attachment to succeed 80 | mock_sg.download_attachment.return_value = "/path/to/thumbnail.jpg" 81 | 82 | # Create a temporary file path 83 | with tempfile.TemporaryDirectory() as temp_dir: 84 | file_path = os.path.join(temp_dir, "thumbnail.jpg") 85 | 86 | # Call the function 87 | result = download_thumbnail(sg=mock_sg, entity_type="Shot", entity_id=123, file_path=file_path) 88 | 89 | # Verify the result 90 | assert result is not None 91 | assert result["entity_type"] == "Shot" 92 | assert result["entity_id"] == 123 93 | 94 | # Verify that find_one and download_attachment were called 95 | mock_sg.find_one.assert_called_once() 96 | mock_sg.download_attachment.assert_called_once() 97 | -------------------------------------------------------------------------------- /.github/workflows/python-publish.yml: -------------------------------------------------------------------------------- 1 | name: Upload Python Package 2 | 3 | permissions: 4 | contents: write # For creating releases 5 | id-token: write # For PyPI trusted publishing 6 | 7 | on: 8 | push: 9 | tags: 10 | - "v*" 11 | workflow_dispatch: 12 | inputs: 13 | python-version: 14 | description: 'Python version to use for testing' 15 | required: false 16 | default: '3.10' 17 | type: string 18 | 19 | jobs: 20 | deploy: 21 | runs-on: ubuntu-latest 22 | permissions: 23 | # IMPORTANT: this permission is mandatory for trusted publishing 24 | id-token: write 25 | contents: write 26 | 27 | steps: 28 | - uses: actions/checkout@v6 29 | with: 30 | token: "${{ secrets.GITHUB_TOKEN }}" 31 | fetch-depth: 0 32 | ref: main 33 | - uses: olegtarasov/get-tag@v2.1.4 34 | id: get_tag_name 35 | with: 36 | tagRegex: "v(?.*)" 37 | - name: Set up Python 38 | uses: actions/setup-python@v6 39 | with: 40 | python-version: '3.12' 41 | 42 | # Cache dependencies 43 | - name: Cache pip dependencies 44 | uses: actions/cache@v4 45 | with: 46 | path: ~/.cache/pip 47 | key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }} 48 | restore-keys: | 49 | ${{ runner.os }}-pip- 50 | 51 | # Cache nox environments 52 | - name: Cache nox environments 53 | uses: actions/cache@v4 54 | with: 55 | path: .nox 56 | key: ${{ runner.os }}-nox-${{ hashFiles('**/noxfile.py') }} 57 | restore-keys: | 58 | ${{ runner.os }}-nox- 59 | 60 | - name: Install dependencies 61 | shell: bash 62 | run: | 63 | python -m pip install --upgrade pip 64 | python -m pip install uv 65 | # Install the project in development mode using uvx 66 | uvx pip install -e ".[dev]" 67 | 68 | - name: Lint 69 | shell: bash 70 | run: | 71 | uvx nox -s lint 72 | 73 | - name: Test 74 | shell: bash 75 | run: | 76 | uvx nox -s tests 77 | 78 | - name: Build package 79 | shell: bash 80 | run: | 81 | # Install shotgun-api3 from GitHub 82 | uvx pip install git+https://github.com/shotgunsoftware/python-api.git@v3.8.2 83 | # Create a temporary pyproject.toml without direct references 84 | cp pyproject.toml pyproject.toml.bak 85 | sed -i 's|"shotgun-api3@git+https://github.com/shotgunsoftware/python-api.git@v3.8.2",|"shotgun-api3",|g' pyproject.toml 86 | # Build the package using nox 87 | uvx nox -s build-wheel 88 | # Restore original pyproject.toml 89 | mv pyproject.toml.bak pyproject.toml 90 | 91 | # Note that we don't need credentials. 92 | # We rely on https://docs.pypi.org/trusted-publishers/. 93 | - name: Upload to PyPI 94 | uses: pypa/gh-action-pypi-publish@release/v1 95 | with: 96 | packages-dir: dist 97 | verbose: true 98 | print-hash: true 99 | 100 | - name: Generate changelog 101 | id: changelog 102 | uses: jaywcjlove/changelog-generator@main 103 | with: 104 | token: ${{ secrets.GITHUB_TOKEN }} 105 | filter-author: (|dependabot|renovate\[bot\]|dependabot\[bot\]|Renovate Bot) 106 | filter: '[R|r]elease[d]\s+[v|V]\d(\.\d+){0,2}' 107 | template: | 108 | ## ShotGrid MCP Server ${{ steps.get_tag_name.outputs.version }} 109 | 110 | MCP Server for ShotGrid integration using shotgun-api3. 111 | 112 | ## Bugs 113 | {{fix}} 114 | ## Feature 115 | {{feat}} 116 | ## Improve 117 | {{refactor,perf,clean}} 118 | ## Misc 119 | {{chore,style,ci||🔶 Nothing change}} 120 | ## Unknown 121 | {{__unknown__}} 122 | 123 | - uses: ncipollo/release-action@v1 124 | with: 125 | artifacts: "dist/*" 126 | token: ${{ secrets.GITHUB_TOKEN }} 127 | body: | 128 | Comparing Changes: ${{ steps.changelog.outputs.compareurl }} 129 | 130 | ${{ steps.changelog.outputs.changelog }} 131 | -------------------------------------------------------------------------------- /tests/test_api_client.py: -------------------------------------------------------------------------------- 1 | """Tests for the ShotGridAPIClient wrapper and its parameter handling.""" 2 | 3 | from typing import Any, Dict, List, Optional 4 | 5 | from shotgrid_mcp_server.api_client import ShotGridAPIClient 6 | from shotgrid_mcp_server.api_models import FindOneRequest, FindRequest 7 | 8 | 9 | class _DummyConnection: 10 | """Minimal fake ShotGrid connection used to verify client kwargs. 11 | 12 | The class name is intentionally not ``MockgunExt`` so that the client 13 | exercises the "real ShotGrid" branch where all keyword arguments are 14 | passed through. 15 | """ 16 | 17 | def __init__(self) -> None: 18 | self.last_find_call: Optional[Dict[str, Any]] = None 19 | self.last_find_one_call: Optional[Dict[str, Any]] = None 20 | 21 | # The real ShotGrid API ``find`` signature is 22 | # find(entity_type, filters, **kwargs) 23 | def find(self, entity_type: str, filters: List[Any], **kwargs: Any) -> List[Dict[str, Any]]: # type: ignore[override] 24 | self.last_find_call = { 25 | "entity_type": entity_type, 26 | "filters": filters, 27 | "kwargs": kwargs, 28 | } 29 | # Return a simple payload so the client has a realistic result type 30 | return [{"id": 1, "type": entity_type, "code": "TEST"}] 31 | 32 | def find_one(self, entity_type: str, filters: List[Any], **kwargs: Any) -> Optional[Dict[str, Any]]: # type: ignore[override] 33 | self.last_find_one_call = { 34 | "entity_type": entity_type, 35 | "filters": filters, 36 | "kwargs": kwargs, 37 | } 38 | return {"id": 1, "type": entity_type, "code": "TEST_ONE"} 39 | 40 | 41 | def test_find_uses_full_kwargs_for_non_mockgun_connection() -> None: 42 | """ShotGridAPIClient.find should pass all supported kwargs for real connections.""" 43 | 44 | connection = _DummyConnection() 45 | client = ShotGridAPIClient(connection) 46 | 47 | request = FindRequest( 48 | entity_type="Shot", 49 | filters=[["code", "is", "TEST"]], 50 | fields=["code"], 51 | order=[{"field_name": "code", "direction": "asc"}], 52 | filter_operator="all", 53 | limit=10, 54 | retired_only=True, 55 | page=2, 56 | include_archived_projects=False, 57 | additional_filter_presets=[{"preset_name": "recent"}], 58 | ) 59 | 60 | result = client.find(request) 61 | 62 | # The dummy connection should have been called once with the expected kwargs 63 | assert connection.last_find_call is not None 64 | assert result == [{"id": 1, "type": "Shot", "code": "TEST"}] 65 | 66 | kwargs = connection.last_find_call["kwargs"] 67 | assert kwargs["fields"] == ["code"] 68 | assert kwargs["order"] == [{"field_name": "code", "direction": "asc"}] 69 | assert kwargs["filter_operator"] == "all" 70 | assert kwargs["retired_only"] is True 71 | assert kwargs["page"] == 2 72 | assert kwargs["include_archived_projects"] is False 73 | # These two were the main uncovered branches in the client 74 | assert kwargs["limit"] == 10 75 | assert kwargs["additional_filter_presets"] == [{"preset_name": "recent"}] 76 | 77 | 78 | def test_find_one_uses_full_kwargs_for_non_mockgun_connection() -> None: 79 | """ShotGridAPIClient.find_one should also pass retired_only and include_archived_projects.""" 80 | 81 | connection = _DummyConnection() 82 | client = ShotGridAPIClient(connection) 83 | 84 | request = FindOneRequest( 85 | entity_type="Shot", 86 | filters=[["code", "is", "TEST_ONE"]], 87 | fields=["code"], 88 | order=None, 89 | filter_operator="all", 90 | retired_only=True, 91 | include_archived_projects=False, 92 | ) 93 | 94 | result = client.find_one(request) 95 | 96 | assert connection.last_find_one_call is not None 97 | assert result == {"id": 1, "type": "Shot", "code": "TEST_ONE"} 98 | 99 | kwargs = connection.last_find_one_call["kwargs"] 100 | assert kwargs["fields"] == ["code"] 101 | assert kwargs["order"] is None 102 | assert kwargs["filter_operator"] == "all" 103 | assert kwargs["retired_only"] is True 104 | assert kwargs["include_archived_projects"] is False 105 | -------------------------------------------------------------------------------- /docs/guides/ai-prompts.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'AI Prompts for ShotGrid MCP' 3 | description: 'Effective prompts for using ShotGrid MCP with AI assistants' 4 | --- 5 | 6 | # AI Prompts for ShotGrid MCP 7 | 8 | This guide provides examples of effective prompts to use with AI assistants like Claude when working with the ShotGrid MCP server. These prompts demonstrate how to leverage AI to interact with your ShotGrid data in natural language. 9 | 10 | ## Basic Queries 11 | 12 | ### Finding Recent Updates 13 | 14 | ``` 15 | Help me find all ShotGrid entities updated in the last 3 months. 16 | ``` 17 | 18 | ``` 19 | Show me all shots that were updated last week for the "Awesome Project". 20 | ``` 21 | 22 | ``` 23 | What assets were modified yesterday? 24 | ``` 25 | 26 | ### Entity Information 27 | 28 | ``` 29 | Tell me about the shot "SHOT_010" in the "Main Project". 30 | ``` 31 | 32 | ``` 33 | What's the status of all shots in sequence "SEQ_001"? 34 | ``` 35 | 36 | ``` 37 | Show me all the notes attached to "SHOT_020". 38 | ``` 39 | 40 | ## Creating and Managing Playlists 41 | 42 | ### Creating Playlists 43 | 44 | ``` 45 | Create a playlist called "Daily Review - April 21" with all shots updated yesterday by the lighting department. 46 | ``` 47 | 48 | ``` 49 | Make a new playlist named "Client Review" containing shots SHOT_010, SHOT_020, and SHOT_030 from the "Main Project". 50 | ``` 51 | 52 | ``` 53 | Help me create a playlist of all approved shots in the "Forest Sequence". 54 | ``` 55 | 56 | ### Finding Playlists 57 | 58 | ``` 59 | Find all playlists created this week. 60 | ``` 61 | 62 | ``` 63 | Show me the contents of the playlist "Director's Review". 64 | ``` 65 | 66 | ## Notes and Feedback 67 | 68 | ### Creating Notes 69 | 70 | ``` 71 | Add a note to SHOT_010 saying "Please adjust the lighting in the background to be more dramatic". 72 | ``` 73 | 74 | ``` 75 | Create a note for all shots in sequence "SEQ_002" reminding the team about color consistency. 76 | ``` 77 | 78 | ### Finding Notes 79 | 80 | ``` 81 | Show me all notes created by John in the last week. 82 | ``` 83 | 84 | ``` 85 | Find all notes containing the word "revision" for the "Main Project". 86 | ``` 87 | 88 | ## Advanced Workflows 89 | 90 | ### Time Tracking and Reporting 91 | 92 | ``` 93 | Help me summarize the time logs for the "Animation" department this month. 94 | ``` 95 | 96 | ``` 97 | Generate a chart using echarts to visualize the hours spent on each department for "Project X" in the last quarter. 98 | ``` 99 | 100 | ``` 101 | Compare the time spent on "Project A" versus "Project B" in a visual format. 102 | ``` 103 | 104 | ### Status Updates and Statistics 105 | 106 | ``` 107 | What percentage of shots in "Project X" are currently in the "Approved" status? 108 | ``` 109 | 110 | ``` 111 | Generate a report of all assets and their current status for the "Sci-Fi Project". 112 | ``` 113 | 114 | ``` 115 | Show me the progress of the "Forest Sequence" over the last month with a visual chart. 116 | ``` 117 | 118 | ### Task Management 119 | 120 | ``` 121 | Assign the task "Final Lighting" for SHOT_050 to Jane with a due date of next Friday. 122 | ``` 123 | 124 | ``` 125 | Update the status of all compositing tasks in "SEQ_003" to "In Progress". 126 | ``` 127 | 128 | ``` 129 | Find all overdue tasks in the "Main Project" and help me prioritize them. 130 | ``` 131 | 132 | ## Combining Multiple Operations 133 | 134 | ``` 135 | Find all shots that were updated yesterday by the lighting team, create a playlist called "Lighting Review - April 21", and notify the director via a note. 136 | ``` 137 | 138 | ``` 139 | Analyze the feedback notes from the client review yesterday, summarize the common issues, and create tasks for the relevant departments. 140 | ``` 141 | 142 | ``` 143 | Help me prepare for tomorrow's review: find all shots due this week, check their status, create a playlist of the ones ready for review, and generate a summary report. 144 | ``` 145 | 146 | ## Tips for Effective Prompts 147 | 148 | 1. **Be specific about timeframes**: "in the last week", "yesterday", "this month" 149 | 2. **Include project names** when working with multiple projects 150 | 3. **Specify departments or users** when filtering by who created or modified entities 151 | 4. **Use natural language** - you don't need to know the exact API calls or field names 152 | 5. **Combine operations** for complex workflows 153 | 6. **Ask for visualizations** when dealing with numerical data 154 | 155 | Remember that the AI assistant will translate your natural language requests into the appropriate ShotGrid MCP tool calls, making it easy to interact with your production data without needing to remember specific API details. 156 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/cli.py: -------------------------------------------------------------------------------- 1 | """Command-line interface for ShotGrid MCP server.""" 2 | 3 | # Import built-in modules 4 | import logging 5 | import sys 6 | 7 | # Import third-party modules 8 | import click 9 | 10 | # Import local modules 11 | from shotgrid_mcp_server.server import create_server 12 | 13 | # Configure logger 14 | logger = logging.getLogger(__name__) 15 | 16 | 17 | @click.group( 18 | help=""" 19 | ShotGrid MCP Server - Connect LLMs to ShotGrid. 20 | 21 | This server provides Model Context Protocol (MCP) access to ShotGrid, 22 | allowing LLMs like Claude to interact with your production tracking data. 23 | 24 | \b 25 | Environment Variables: 26 | SHOTGRID_URL: Your ShotGrid server URL 27 | SHOTGRID_SCRIPT_NAME: Your ShotGrid script name 28 | SHOTGRID_SCRIPT_KEY: Your ShotGrid script key 29 | """, 30 | invoke_without_command=True, 31 | ) 32 | @click.pass_context 33 | def cli(ctx: click.Context) -> None: 34 | """ShotGrid MCP Server CLI.""" 35 | # If no subcommand is provided, default to stdio 36 | if ctx.invoked_subcommand is None: 37 | ctx.invoke(stdio) 38 | 39 | 40 | @cli.command() 41 | def stdio() -> None: 42 | """Run server with stdio transport (for local MCP clients like Claude Desktop). 43 | 44 | \b 45 | Example: 46 | shotgrid-mcp-server stdio 47 | shotgrid-mcp-server # stdio is the default 48 | """ 49 | try: 50 | logger.info("Starting ShotGrid MCP server with stdio transport") 51 | 52 | # For stdio, create connection immediately to validate credentials 53 | app = create_server(lazy_connection=False) 54 | app.run(transport="stdio") 55 | 56 | except ValueError as e: 57 | # Handle missing environment variables error 58 | if "Missing required environment variables for ShotGrid connection" in str(e): 59 | click.echo(f"\n{'=' * 80}", err=True) 60 | click.echo("ERROR: ShotGrid MCP Server Configuration Issue", err=True) 61 | click.echo(f"{'=' * 80}", err=True) 62 | click.echo(str(e), err=True) 63 | click.echo(f"{'=' * 80}\n", err=True) 64 | sys.exit(1) 65 | raise 66 | except KeyboardInterrupt: 67 | click.echo("\n\nShutting down server...") 68 | except Exception as e: 69 | logger.error("Failed to start server: %s", str(e), exc_info=True) 70 | click.echo(f"\n❌ Error: {e}", err=True) 71 | raise click.Abort() from e 72 | 73 | 74 | @cli.command() 75 | @click.option( 76 | "--host", 77 | type=str, 78 | default="127.0.0.1", 79 | show_default=True, 80 | help="Host to bind to", 81 | ) 82 | @click.option( 83 | "--port", 84 | type=int, 85 | default=8000, 86 | show_default=True, 87 | help="Port to bind to", 88 | ) 89 | @click.option( 90 | "--path", 91 | type=str, 92 | default="/mcp", 93 | show_default=True, 94 | help="API endpoint path", 95 | ) 96 | def http(host: str, port: int, path: str) -> None: 97 | """Run server with HTTP transport (for remote deployments). 98 | 99 | In HTTP mode, credentials can be provided via: 100 | - HTTP headers: X-ShotGrid-URL, X-ShotGrid-Script-Name, X-ShotGrid-Script-Key 101 | - Environment variables: SHOTGRID_URL, SHOTGRID_SCRIPT_NAME, SHOTGRID_SCRIPT_KEY 102 | 103 | \b 104 | Examples: 105 | shotgrid-mcp-server http 106 | shotgrid-mcp-server http --host 0.0.0.0 --port 8080 107 | shotgrid-mcp-server http --host 0.0.0.0 --port 8000 --path /api/mcp 108 | """ 109 | try: 110 | click.echo("\n💡 HTTP mode: ShotGrid connection will be created on-demand") 111 | click.echo(" You can provide credentials via HTTP headers or environment variables\n") 112 | 113 | # For HTTP, use lazy connection mode (credentials from headers) 114 | app = create_server(lazy_connection=True) 115 | 116 | logger.info( 117 | "Starting ShotGrid MCP server with HTTP transport on %s:%d%s", 118 | host, 119 | port, 120 | path, 121 | ) 122 | click.echo(f"\n{'=' * 80}") 123 | click.echo("ShotGrid MCP Server - HTTP Transport") 124 | click.echo(f"{'=' * 80}") 125 | click.echo(f"Server URL: http://{host}:{port}{path}") 126 | click.echo(f"{'=' * 80}\n") 127 | 128 | app.run(transport="http", host=host, port=port, path=path) 129 | 130 | except KeyboardInterrupt: 131 | click.echo("\n\nShutting down server...") 132 | except Exception as e: 133 | logger.error("Failed to start server: %s", str(e), exc_info=True) 134 | click.echo(f"\n❌ Error: {e}", err=True) 135 | raise click.Abort() from e 136 | 137 | 138 | def main() -> None: 139 | """Entry point for the ShotGrid MCP server.""" 140 | cli() 141 | 142 | 143 | if __name__ == "__main__": 144 | main() 145 | -------------------------------------------------------------------------------- /examples/custom_app.py: -------------------------------------------------------------------------------- 1 | """Example: Custom ASGI application with advanced middleware. 2 | 3 | This example demonstrates how to create a production-ready ASGI application 4 | with multiple middleware layers for security, performance, and monitoring. 5 | 6 | Deploy with: 7 | uvicorn examples.custom_app:app --host 0.0.0.0 --port 8000 --workers 4 8 | """ 9 | 10 | # Import built-in modules 11 | import logging 12 | import time 13 | from typing import Callable 14 | 15 | # Import third-party modules 16 | from starlette.middleware import Middleware 17 | from starlette.middleware.base import BaseHTTPMiddleware 18 | from starlette.middleware.cors import CORSMiddleware 19 | from starlette.middleware.gzip import GZipMiddleware 20 | from starlette.requests import Request 21 | from starlette.responses import Response 22 | 23 | # Import local modules 24 | from shotgrid_mcp_server.asgi import create_asgi_app 25 | 26 | # Configure logger 27 | logger = logging.getLogger(__name__) 28 | 29 | 30 | class RequestLoggingMiddleware(BaseHTTPMiddleware): 31 | """Middleware for logging HTTP requests and responses.""" 32 | 33 | async def dispatch(self, request: Request, call_next: Callable) -> Response: 34 | """Process request and log details. 35 | 36 | Args: 37 | request: Incoming HTTP request 38 | call_next: Next middleware in chain 39 | 40 | Returns: 41 | Response from next middleware 42 | """ 43 | start_time = time.time() 44 | 45 | # Log request 46 | logger.info( 47 | "Request: %s %s from %s", 48 | request.method, 49 | request.url.path, 50 | request.client.host if request.client else "unknown", 51 | ) 52 | 53 | # Process request 54 | response = await call_next(request) 55 | 56 | # Calculate processing time 57 | process_time = time.time() - start_time 58 | 59 | # Add custom headers 60 | response.headers["X-Process-Time"] = str(process_time) 61 | 62 | # Log response 63 | logger.info( 64 | "Response: %s %s - Status: %d - Time: %.3fs", 65 | request.method, 66 | request.url.path, 67 | response.status_code, 68 | process_time, 69 | ) 70 | 71 | return response 72 | 73 | 74 | class RateLimitMiddleware(BaseHTTPMiddleware): 75 | """Simple rate limiting middleware (example only, use proper rate limiter in production).""" 76 | 77 | def __init__(self, app, max_requests: int = 100): 78 | """Initialize rate limiter. 79 | 80 | Args: 81 | app: ASGI application 82 | max_requests: Maximum requests per client (simplified example) 83 | """ 84 | super().__init__(app) 85 | self.max_requests = max_requests 86 | self.requests = {} 87 | 88 | async def dispatch(self, request: Request, call_next: Callable) -> Response: 89 | """Check rate limits and process request. 90 | 91 | Args: 92 | request: Incoming HTTP request 93 | call_next: Next middleware in chain 94 | 95 | Returns: 96 | Response from next middleware or rate limit error 97 | """ 98 | client_ip = request.client.host if request.client else "unknown" 99 | 100 | # Simple counter (in production, use Redis or similar) 101 | if client_ip not in self.requests: 102 | self.requests[client_ip] = 0 103 | 104 | self.requests[client_ip] += 1 105 | 106 | if self.requests[client_ip] > self.max_requests: 107 | logger.warning("Rate limit exceeded for %s", client_ip) 108 | # In production, return proper rate limit response 109 | # For now, just log and continue 110 | 111 | response = await call_next(request) 112 | return response 113 | 114 | 115 | # Configure middleware stack 116 | middleware = [ 117 | # CORS middleware - configure for your domain 118 | Middleware( 119 | CORSMiddleware, 120 | allow_origins=[ 121 | "https://yourdomain.com", 122 | "https://app.yourdomain.com", 123 | ], 124 | allow_credentials=True, 125 | allow_methods=["GET", "POST"], 126 | allow_headers=["*"], 127 | expose_headers=["X-Process-Time"], 128 | ), 129 | # GZip compression for responses 130 | Middleware(GZipMiddleware, minimum_size=1000), 131 | # Request logging 132 | Middleware(RequestLoggingMiddleware), 133 | # Rate limiting (example only) 134 | Middleware(RateLimitMiddleware, max_requests=1000), 135 | ] 136 | 137 | # Create ASGI application with middleware 138 | app = create_asgi_app( 139 | middleware=middleware, 140 | path="/mcp", 141 | ) 142 | 143 | # Log startup 144 | logger.info("Custom ShotGrid MCP ASGI application initialized") 145 | logger.info("Middleware stack: CORS, GZip, Logging, RateLimit") 146 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/http_context.py: -------------------------------------------------------------------------------- 1 | """HTTP context utilities for extracting ShotGrid credentials from HTTP headers.""" 2 | 3 | import logging 4 | from typing import Dict, Optional, Tuple 5 | 6 | logger = logging.getLogger(__name__) 7 | 8 | # HTTP header names for ShotGrid credentials 9 | SHOTGRID_URL_HEADER = "X-ShotGrid-URL" 10 | SHOTGRID_SCRIPT_NAME_HEADER = "X-ShotGrid-Script-Name" 11 | SHOTGRID_SCRIPT_KEY_HEADER = "X-ShotGrid-Script-Key" 12 | 13 | 14 | def get_request_info() -> Dict[str, Optional[str]]: 15 | """Extract request information for debugging purposes. 16 | 17 | Returns: 18 | Dict with request information including: 19 | - client_host: Client IP address 20 | - user_agent: User-Agent header 21 | - referer: Referer header 22 | - request_id: X-Request-ID header if present 23 | """ 24 | try: 25 | from fastmcp.server.dependencies import get_http_headers 26 | 27 | headers = get_http_headers() 28 | if headers is None: 29 | return {} 30 | 31 | # Extract common debugging headers 32 | info = { 33 | "user_agent": headers.get("user-agent"), 34 | "referer": headers.get("referer"), 35 | "request_id": headers.get("x-request-id"), 36 | "forwarded_for": headers.get("x-forwarded-for"), 37 | } 38 | 39 | # Remove None values 40 | return {k: v for k, v in info.items() if v is not None} 41 | 42 | except Exception: 43 | return {} 44 | 45 | 46 | def get_shotgrid_credentials_from_headers() -> Tuple[Optional[str], Optional[str], Optional[str]]: 47 | """Extract ShotGrid credentials from HTTP request headers. 48 | 49 | This function attempts to get credentials from HTTP headers when using HTTP transport. 50 | If HTTP headers are not available (e.g., when using stdio transport), returns None values. 51 | 52 | Returns: 53 | Tuple[Optional[str], Optional[str], Optional[str]]: URL, script name, and API key from headers. 54 | Returns (None, None, None) if not in HTTP context or headers are missing. 55 | """ 56 | try: 57 | # Import here to avoid circular dependencies and to handle cases where fastmcp is not available 58 | from fastmcp.server.dependencies import get_http_headers 59 | 60 | # Get HTTP headers 61 | headers = get_http_headers() 62 | 63 | if headers is None: 64 | # Not in HTTP context (e.g., stdio transport) 65 | logger.debug("No HTTP headers available - likely using stdio transport") 66 | return None, None, None 67 | 68 | # DEBUG: Log all available headers to understand what's being passed 69 | logger.debug("Available HTTP headers: %s", dict(headers)) 70 | 71 | # Extract credentials from headers (case-insensitive) 72 | url = headers.get(SHOTGRID_URL_HEADER) or headers.get(SHOTGRID_URL_HEADER.lower()) 73 | script_name = headers.get(SHOTGRID_SCRIPT_NAME_HEADER) or headers.get(SHOTGRID_SCRIPT_NAME_HEADER.lower()) 74 | api_key = headers.get(SHOTGRID_SCRIPT_KEY_HEADER) or headers.get(SHOTGRID_SCRIPT_KEY_HEADER.lower()) 75 | 76 | # Get request info for debugging 77 | request_info = get_request_info() 78 | 79 | if url or script_name or api_key: 80 | # Build debug message with request source information 81 | debug_parts = [ 82 | f"ShotGrid URL: {url}" if url else None, 83 | f"Script Name: {script_name}" if script_name else None, 84 | f"Client: {request_info.get('forwarded_for', 'unknown')}" 85 | if request_info.get("forwarded_for") 86 | else None, 87 | f"User-Agent: {request_info.get('user_agent', 'unknown')}" if request_info.get("user_agent") else None, 88 | ] 89 | debug_msg = " | ".join(filter(None, debug_parts)) 90 | 91 | logger.info( 92 | "HTTP Request - %s", 93 | debug_msg, 94 | ) 95 | else: 96 | # No credentials in headers, log request info anyway 97 | if request_info: 98 | logger.debug( 99 | "HTTP Request without ShotGrid credentials - Client: %s, User-Agent: %s", 100 | request_info.get("forwarded_for", "unknown"), 101 | request_info.get("user_agent", "unknown"), 102 | ) 103 | 104 | return url, script_name, api_key 105 | 106 | except ImportError: 107 | # fastmcp.server.dependencies not available 108 | logger.debug("fastmcp.server.dependencies not available - cannot extract HTTP headers") 109 | return None, None, None 110 | except Exception as e: 111 | # Any other error (e.g., not in request context) 112 | logger.debug("Failed to extract credentials from HTTP headers: %s", str(e)) 113 | return None, None, None 114 | -------------------------------------------------------------------------------- /tests/test_search_tools_return_types.py: -------------------------------------------------------------------------------- 1 | """Test search tools return types.""" 2 | 3 | from unittest.mock import MagicMock, patch 4 | 5 | from shotgrid_mcp_server.models import EntitiesResponse, ProjectsResponse, UsersResponse 6 | 7 | 8 | class TestSearchToolsReturnTypes: 9 | """Test that search tools return correct types.""" 10 | 11 | @patch("shotgrid_mcp_server.tools.search_tools.Shotgun") 12 | def test_find_recently_active_projects_return_type(self, mock_sg_class): 13 | """Test find_recently_active_projects returns ProjectsResponse.""" 14 | from shotgrid_mcp_server.tools.search_tools import _find_recently_active_projects 15 | 16 | # Mock ShotGrid connection 17 | mock_sg = MagicMock() 18 | mock_sg.find.return_value = [{"id": 1, "type": "Project", "name": "Test Project", "updated_at": "2025-01-01"}] 19 | 20 | # Call function 21 | result = _find_recently_active_projects(mock_sg, days=90) 22 | 23 | # Verify return type 24 | assert isinstance(result, ProjectsResponse) 25 | assert hasattr(result, "projects") 26 | assert isinstance(result.projects, list) 27 | 28 | @patch("shotgrid_mcp_server.tools.search_tools.Shotgun") 29 | def test_find_active_users_return_type(self, mock_sg_class): 30 | """Test find_active_users returns UsersResponse.""" 31 | from shotgrid_mcp_server.tools.search_tools import _find_active_users 32 | 33 | # Mock ShotGrid connection 34 | mock_sg = MagicMock() 35 | mock_sg.find.return_value = [{"id": 1, "type": "HumanUser", "name": "Test User", "login": "testuser"}] 36 | 37 | # Call function 38 | result = _find_active_users(mock_sg, days=30) 39 | 40 | # Verify return type 41 | assert isinstance(result, UsersResponse) 42 | assert hasattr(result, "users") 43 | assert isinstance(result.users, list) 44 | 45 | @patch("shotgrid_mcp_server.tools.search_tools.Shotgun") 46 | def test_find_entities_by_date_range_return_type(self, mock_sg_class): 47 | """Test find_entities_by_date_range returns EntitiesResponse.""" 48 | from shotgrid_mcp_server.tools.search_tools import _find_entities_by_date_range 49 | 50 | # Mock ShotGrid connection 51 | mock_sg = MagicMock() 52 | mock_sg.find.return_value = [{"id": 1, "type": "Shot", "code": "SH001", "created_at": "2025-01-01"}] 53 | 54 | # Call function 55 | result = _find_entities_by_date_range( 56 | mock_sg, entity_type="Shot", date_field="created_at", start_date="2025-01-01", end_date="2025-01-31" 57 | ) 58 | 59 | # Verify return type 60 | assert isinstance(result, EntitiesResponse) 61 | assert hasattr(result, "entities") 62 | assert isinstance(result.entities, list) 63 | 64 | @patch("shotgrid_mcp_server.tools.search_tools.Shotgun") 65 | def test_find_recently_active_projects_empty_result(self, mock_sg_class): 66 | """Test find_recently_active_projects with empty result.""" 67 | from shotgrid_mcp_server.tools.search_tools import _find_recently_active_projects 68 | 69 | # Mock ShotGrid connection 70 | mock_sg = MagicMock() 71 | mock_sg.find.return_value = [] 72 | 73 | # Call function 74 | result = _find_recently_active_projects(mock_sg, days=90) 75 | 76 | # Verify return type and empty list 77 | assert isinstance(result, ProjectsResponse) 78 | assert result.projects == [] 79 | 80 | @patch("shotgrid_mcp_server.tools.search_tools.Shotgun") 81 | def test_find_active_users_empty_result(self, mock_sg_class): 82 | """Test find_active_users with empty result.""" 83 | from shotgrid_mcp_server.tools.search_tools import _find_active_users 84 | 85 | # Mock ShotGrid connection 86 | mock_sg = MagicMock() 87 | mock_sg.find.return_value = [] 88 | 89 | # Call function 90 | result = _find_active_users(mock_sg, days=30) 91 | 92 | # Verify return type and empty list 93 | assert isinstance(result, UsersResponse) 94 | assert result.users == [] 95 | 96 | @patch("shotgrid_mcp_server.tools.search_tools.Shotgun") 97 | def test_find_entities_by_date_range_empty_result(self, mock_sg_class): 98 | """Test find_entities_by_date_range with empty result.""" 99 | from shotgrid_mcp_server.tools.search_tools import _find_entities_by_date_range 100 | 101 | # Mock ShotGrid connection 102 | mock_sg = MagicMock() 103 | mock_sg.find.return_value = [] 104 | 105 | # Call function 106 | result = _find_entities_by_date_range( 107 | mock_sg, entity_type="Version", date_field="created_at", start_date="2025-01-01", end_date="2025-01-31" 108 | ) 109 | 110 | # Verify return type and empty list 111 | assert isinstance(result, EntitiesResponse) 112 | assert result.entities == [] 113 | -------------------------------------------------------------------------------- /docs/DEVELOPMENT.md: -------------------------------------------------------------------------------- 1 | # Development Guide 2 | 3 | ## Code Style and Linting 4 | 5 | This project uses [Ruff](https://docs.astral.sh/ruff/) for linting and formatting Python code. 6 | 7 | ### Running Ruff Manually 8 | 9 | ```bash 10 | # Check for linting issues 11 | uv run ruff check . 12 | 13 | # Fix auto-fixable issues 14 | uv run ruff check --fix . 15 | 16 | # Format code 17 | uv run ruff format . 18 | ``` 19 | 20 | ### Pre-commit Hooks (Optional) 21 | 22 | The project includes pre-commit configuration for automatic code quality checks. 23 | 24 | #### Installation 25 | 26 | 1. Install pre-commit (if not already installed): 27 | ```bash 28 | pip install pre-commit 29 | # or 30 | uv pip install pre-commit 31 | ``` 32 | 33 | 2. Install the git hooks: 34 | ```bash 35 | pre-commit install 36 | ``` 37 | 38 | #### Usage 39 | 40 | Once installed, pre-commit will automatically run on every commit: 41 | 42 | ```bash 43 | git commit -m "your message" 44 | # Pre-commit hooks will run automatically 45 | ``` 46 | 47 | To run pre-commit manually on all files: 48 | 49 | ```bash 50 | pre-commit run --all-files 51 | ``` 52 | 53 | #### Configured Hooks 54 | 55 | - **no-commit-to-branch**: Prevents direct commits to main branch 56 | - **check-yaml**: Validates YAML files 57 | - **check-toml**: Validates TOML files 58 | - **end-of-file-fixer**: Ensures files end with a newline 59 | - **trailing-whitespace**: Removes trailing whitespace 60 | - **ruff**: Lints and fixes Python code 61 | - **ruff-format**: Formats Python code 62 | 63 | ### Import Sorting 64 | 65 | Ruff automatically sorts imports according to the `isort` rules. The import order is: 66 | 67 | 1. Standard library imports 68 | 2. Third-party imports 69 | 3. Local application imports 70 | 71 | Example: 72 | ```python 73 | # Standard library 74 | import os 75 | from typing import Any, Dict 76 | 77 | # Third-party 78 | from fastmcp import FastMCP 79 | from shotgun_api3 import Shotgun 80 | 81 | # Local 82 | from shotgrid_mcp_server.models import EntityDict 83 | ``` 84 | 85 | ## Testing 86 | 87 | Run tests with pytest: 88 | 89 | ```bash 90 | # Run all tests 91 | uv run pytest 92 | 93 | # Run specific test file 94 | uv run pytest tests/test_filters.py 95 | 96 | # Run with coverage 97 | uv run pytest --cov=src/shotgrid_mcp_server 98 | ``` 99 | 100 | ## Keeping Local and CI in Sync 101 | 102 | To ensure your local development environment matches the CI environment: 103 | 104 | ### Ruff Version Consistency 105 | 106 | The project uses a specific version of Ruff defined in two places: 107 | - `.pre-commit-config.yaml` - for pre-commit hooks 108 | - `nox_actions/lint.py` - for CI linting 109 | 110 | **Important**: These versions must match to avoid inconsistent linting results. 111 | 112 | Current version: **0.8.6** 113 | 114 | ### Running the Same Checks as CI 115 | 116 | Before pushing, run the same checks that CI will run: 117 | 118 | ```bash 119 | # Run linting (same as CI) 120 | uv run nox -s lint 121 | 122 | # Run tests (same as CI) 123 | uv run nox -s tests 124 | 125 | # Or run both 126 | uv run nox -s lint tests 127 | ``` 128 | 129 | ### Line Ending Consistency 130 | 131 | The project uses LF (Unix-style) line endings for all text files, enforced by `.gitattributes`. 132 | 133 | If you're on Windows, configure Git: 134 | 135 | ```bash 136 | # Set Git to convert CRLF to LF on commit 137 | git config core.autocrlf input 138 | ``` 139 | 140 | This ensures that: 141 | - Files are committed with LF endings 142 | - `ruff format --check` passes on all platforms (Windows, macOS, Linux) 143 | 144 | ### Updating Ruff Version 145 | 146 | When updating Ruff, update both files: 147 | 148 | 1. `.pre-commit-config.yaml`: 149 | ```yaml 150 | - repo: https://github.com/astral-sh/ruff-pre-commit 151 | rev: v0.8.6 # Update this version 152 | ``` 153 | 154 | 2. `nox_actions/lint.py`: 155 | ```python 156 | RUFF_VERSION = "0.8.6" # Update this version 157 | ``` 158 | 159 | Then update pre-commit hooks: 160 | ```bash 161 | pre-commit autoupdate 162 | pre-commit install 163 | ``` 164 | 165 | ## Building Documentation 166 | 167 | ```bash 168 | # Build documentation 169 | uv run tox -e docs 170 | 171 | # Serve documentation locally 172 | uv run tox -e docs-server 173 | ``` 174 | 175 | ## Common Issues 176 | 177 | ### Import Sorting Errors 178 | 179 | If you see import sorting errors, run: 180 | 181 | ```bash 182 | uv run ruff check --select I --fix . 183 | ``` 184 | 185 | ### Whitespace Issues 186 | 187 | If you see trailing whitespace or blank line issues, run: 188 | 189 | ```bash 190 | uv run ruff format . 191 | ``` 192 | 193 | ### Pre-commit Fails 194 | 195 | If pre-commit fails, you can: 196 | 197 | 1. Fix the issues manually 198 | 2. Run `uv run ruff check --fix .` and `uv run ruff format .` 199 | 3. Stage the changes and commit again 200 | 201 | Or skip pre-commit (not recommended): 202 | 203 | ```bash 204 | git commit --no-verify -m "your message" 205 | ``` 206 | 207 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/tools/helper_types.py: -------------------------------------------------------------------------------- 1 | """Type definitions for ShotGrid MCP server helper functions. 2 | 3 | This module provides type definitions for helper functions in the ShotGrid MCP server. 4 | All types are now Pydantic models for better validation and type safety. 5 | """ 6 | 7 | from typing import Dict, List, Literal, Optional, Union 8 | 9 | from pydantic import BaseModel, Field 10 | 11 | from shotgrid_mcp_server.custom_types import Filter 12 | 13 | 14 | class ProjectDict(BaseModel): 15 | """ShotGrid project dictionary. 16 | 17 | Represents a ShotGrid project entity with common fields. 18 | """ 19 | 20 | id: int = Field(..., description="Project ID") 21 | type: str = Field(..., description="Entity type (always 'Project')") 22 | name: str = Field(..., description="Project name") 23 | sg_status: Optional[str] = Field(None, description="Project status") 24 | updated_at: Optional[str] = Field(None, description="Last update timestamp") 25 | updated_by: Optional[Dict[str, Union[int, str]]] = Field(None, description="User who last updated the project") 26 | 27 | class Config: 28 | """Pydantic configuration.""" 29 | 30 | extra = "allow" # Allow additional fields from ShotGrid 31 | 32 | 33 | class UserDict(BaseModel): 34 | """ShotGrid user dictionary. 35 | 36 | Represents a ShotGrid user entity with common fields. 37 | """ 38 | 39 | id: int = Field(..., description="User ID") 40 | type: str = Field(..., description="Entity type (always 'HumanUser')") 41 | name: str = Field(..., description="User's full name") 42 | login: str = Field(..., description="User's login name") 43 | email: Optional[str] = Field(None, description="User's email address") 44 | last_login: Optional[str] = Field(None, description="Last login timestamp") 45 | sg_status_list: str = Field(..., description="User status (act, dis, etc.)") 46 | 47 | class Config: 48 | """Pydantic configuration.""" 49 | 50 | extra = "allow" # Allow additional fields from ShotGrid 51 | 52 | 53 | class EntityDict(BaseModel): 54 | """ShotGrid entity dictionary. 55 | 56 | Represents a generic ShotGrid entity with common fields. 57 | """ 58 | 59 | id: int = Field(..., description="Entity ID") 60 | type: str = Field(..., description="Entity type") 61 | name: Optional[str] = Field(None, description="Entity name") 62 | code: Optional[str] = Field(None, description="Entity code") 63 | created_at: Optional[str] = Field(None, description="Creation timestamp") 64 | updated_at: Optional[str] = Field(None, description="Last update timestamp") 65 | sg_status_list: Optional[str] = Field(None, description="Entity status") 66 | 67 | class Config: 68 | """Pydantic configuration.""" 69 | 70 | extra = "allow" # Allow additional fields from ShotGrid 71 | 72 | 73 | # Define TimeUnit as a type alias 74 | TimeUnit = Literal["DAY", "WEEK", "MONTH", "YEAR"] 75 | """ShotGrid time unit for relative date filters.""" 76 | 77 | 78 | class TimeFilter(BaseModel): 79 | """ShotGrid time filter for relative date queries. 80 | 81 | Example: 82 | >>> filter = TimeFilter( 83 | ... field="created_at", 84 | ... operator="in_last", 85 | ... count=7, 86 | ... unit="DAY" 87 | ... ) 88 | """ 89 | 90 | field: str = Field(..., description="Field name to filter on") 91 | operator: Literal["in_last", "not_in_last", "in_next", "not_in_next"] = Field( 92 | ..., description="Time filter operator" 93 | ) 94 | count: int = Field(..., gt=0, description="Number of time units") 95 | unit: TimeUnit = Field(..., description="Time unit (DAY, WEEK, MONTH, YEAR)") 96 | 97 | 98 | class DateRangeFilter(BaseModel): 99 | """ShotGrid date range filter. 100 | 101 | Example: 102 | >>> filter = DateRangeFilter( 103 | ... field="created_at", 104 | ... start_date="2025-01-01", 105 | ... end_date="2025-01-31" 106 | ... ) 107 | """ 108 | 109 | field: str = Field(..., description="Field name to filter on") 110 | start_date: str = Field(..., description="Start date (YYYY-MM-DD)") 111 | end_date: str = Field(..., description="End date (YYYY-MM-DD)") 112 | additional_filters: Optional[List[Filter]] = Field(None, description="Additional filters to apply") 113 | 114 | 115 | class ProjectsResponse(BaseModel): 116 | """Response for find_recently_active_projects.""" 117 | 118 | projects: List[ProjectDict] = Field(..., description="List of projects") 119 | 120 | 121 | class UsersResponse(BaseModel): 122 | """Response for find_active_users.""" 123 | 124 | users: List[UserDict] = Field(..., description="List of users") 125 | 126 | 127 | class EntitiesResponse(BaseModel): 128 | """Response for find_entities_by_date_range.""" 129 | 130 | entities: List[EntityDict] = Field(..., description="List of entities") 131 | -------------------------------------------------------------------------------- /tests/test_factory.py: -------------------------------------------------------------------------------- 1 | """Tests for ShotGrid factory functions.""" 2 | 3 | import os 4 | import unittest 5 | from unittest.mock import MagicMock, patch 6 | 7 | from shotgrid_mcp_server.connection_pool import ( 8 | create_shotgun_connection, 9 | create_shotgun_connection_from_env, 10 | ) 11 | 12 | 13 | class TestFactory(unittest.TestCase): 14 | """Test ShotGrid factory functions.""" 15 | 16 | @patch("shotgrid_mcp_server.connection_pool.shotgun_api3.Shotgun") 17 | def test_create_shotgun_connection(self, mock_shotgun): 18 | """Test create_shotgun_connection function.""" 19 | # Create a mock Shotgun instance 20 | mock_instance = MagicMock() 21 | mock_instance.config = MagicMock() 22 | mock_shotgun.return_value = mock_instance 23 | 24 | # Test with default args 25 | sg = create_shotgun_connection("https://test.shotgunstudio.com", "script_name", "api_key") 26 | 27 | # Verify Shotgun was called with correct args 28 | mock_shotgun.assert_called_once_with( 29 | base_url="https://test.shotgunstudio.com", 30 | script_name="script_name", 31 | api_key="api_key", 32 | ) 33 | 34 | # Verify config was set correctly 35 | self.assertEqual(sg.config.max_rpc_attempts, 10) 36 | self.assertEqual(sg.config.timeout_secs, 30) 37 | self.assertEqual(sg.config.rpc_attempt_interval, 10000) 38 | 39 | # Reset mock 40 | mock_shotgun.reset_mock() 41 | 42 | # Test with custom args 43 | sg = create_shotgun_connection( 44 | "https://test.shotgunstudio.com", 45 | "script_name", 46 | "api_key", 47 | shotgun_args={ 48 | "max_rpc_attempts": 20, 49 | "timeout_secs": 60, 50 | "rpc_attempt_interval": 20000, 51 | "connect": False, 52 | }, 53 | ) 54 | 55 | # Verify Shotgun was called with correct args 56 | mock_shotgun.assert_called_once_with( 57 | base_url="https://test.shotgunstudio.com", 58 | script_name="script_name", 59 | api_key="api_key", 60 | connect=False, 61 | ) 62 | 63 | # Verify config was set correctly 64 | self.assertEqual(sg.config.max_rpc_attempts, 20) 65 | self.assertEqual(sg.config.timeout_secs, 60) 66 | self.assertEqual(sg.config.rpc_attempt_interval, 20000) 67 | 68 | @patch("shotgrid_mcp_server.connection_pool.create_shotgun_connection") 69 | @patch.dict( 70 | os.environ, 71 | { 72 | "SHOTGRID_URL": "https://test.shotgunstudio.com", 73 | "SHOTGRID_SCRIPT_NAME": "script_name", 74 | "SHOTGRID_SCRIPT_KEY": "api_key", 75 | }, 76 | ) 77 | def test_create_shotgun_connection_from_env(self, mock_create_shotgun): 78 | """Test create_shotgun_connection_from_env function.""" 79 | # Create a mock Shotgun instance 80 | mock_instance = MagicMock() 81 | mock_create_shotgun.return_value = mock_instance 82 | 83 | # Test with default args 84 | sg = create_shotgun_connection_from_env() 85 | 86 | # Verify create_shotgun_connection was called with correct args 87 | mock_create_shotgun.assert_called_once_with( 88 | url="https://test.shotgunstudio.com", 89 | script_name="script_name", 90 | api_key="api_key", 91 | shotgun_args=None, 92 | ) 93 | 94 | # Reset mock 95 | mock_create_shotgun.reset_mock() 96 | 97 | # Test with custom args 98 | sg = create_shotgun_connection_from_env( 99 | shotgun_args={ 100 | "max_rpc_attempts": 20, 101 | "timeout_secs": 60, 102 | "rpc_attempt_interval": 20000, 103 | }, 104 | ) 105 | 106 | # Verify create_shotgun_connection was called with correct args 107 | mock_create_shotgun.assert_called_once_with( 108 | url="https://test.shotgunstudio.com", 109 | script_name="script_name", 110 | api_key="api_key", 111 | shotgun_args={ 112 | "max_rpc_attempts": 20, 113 | "timeout_secs": 60, 114 | "rpc_attempt_interval": 20000, 115 | }, 116 | ) 117 | 118 | @patch.dict(os.environ, {}, clear=True) 119 | def test_create_shotgun_connection_from_env_missing_vars(self): 120 | """Test create_shotgun_connection_from_env function with missing environment variables.""" 121 | # Test with missing environment variables 122 | with self.assertRaises(ValueError) as context: 123 | create_shotgun_connection_from_env() 124 | 125 | # Verify error message 126 | self.assertIn("Missing required environment variables", str(context.exception)) 127 | 128 | 129 | if __name__ == "__main__": 130 | unittest.main() 131 | -------------------------------------------------------------------------------- /tests/test_filter_processing.py: -------------------------------------------------------------------------------- 1 | """Test end-to-end filter processing with shotgrid-query integration.""" 2 | 3 | from shotgrid_query import process_filters 4 | 5 | from shotgrid_mcp_server.api_models import SearchEntitiesRequest 6 | 7 | 8 | class TestFilterProcessingIntegration: 9 | """Test integration between SearchEntitiesRequest and shotgrid-query.""" 10 | 11 | def test_simple_filter_processing(self): 12 | """Test simple filter goes through validation and processing.""" 13 | # Step 1: Validate with SearchEntitiesRequest 14 | request = SearchEntitiesRequest(entity_type="Task", filters=[["sg_status_list", "is", "ip"]], fields=["id"]) 15 | 16 | # Step 2: Process with shotgrid-query 17 | processed = process_filters(request.filters) 18 | 19 | # Verify: Should be converted to tuple 20 | assert len(processed) == 1 21 | assert processed[0] == ("sg_status_list", "is", "ip") 22 | assert isinstance(processed[0], tuple) 23 | 24 | def test_multiple_filters_processing(self): 25 | """Test multiple filters processing.""" 26 | request = SearchEntitiesRequest( 27 | entity_type="Shot", 28 | filters=[["sg_status_list", "in", ["wtg", "rdy"]], ["project", "is", {"type": "Project", "id": 123}]], 29 | fields=["code"], 30 | ) 31 | 32 | processed = process_filters(request.filters) 33 | 34 | assert len(processed) == 2 35 | assert processed[0] == ("sg_status_list", "in", ["wtg", "rdy"]) 36 | assert processed[1] == ("project", "is", {"type": "Project", "id": 123}) 37 | 38 | def test_time_filter_processing(self): 39 | """Test time-based filter processing.""" 40 | request = SearchEntitiesRequest( 41 | entity_type="Version", filters=[["created_at", "in_last", [7, "DAY"]]], fields=["code"] 42 | ) 43 | 44 | processed = process_filters(request.filters) 45 | 46 | assert len(processed) == 1 47 | assert processed[0] == ("created_at", "in_last", [7, "DAY"]) 48 | 49 | def test_empty_filters_processing(self): 50 | """Test empty filters processing.""" 51 | request = SearchEntitiesRequest(entity_type="Asset", filters=[], fields=["code"]) 52 | 53 | processed = process_filters(request.filters) 54 | 55 | assert processed == [] 56 | 57 | def test_complex_filters_processing(self): 58 | """Test complex filters with various operators.""" 59 | request = SearchEntitiesRequest( 60 | entity_type="Task", 61 | filters=[ 62 | ["sg_status_list", "in", ["wtg", "rdy", "ip", "rev"]], 63 | ["task_assignees", "is", {"type": "HumanUser", "id": 42}], 64 | ["due_date", "greater_than", "2025-01-01"], 65 | ["content", "contains", "animation"], 66 | ], 67 | fields=["id", "content"], 68 | ) 69 | 70 | processed = process_filters(request.filters) 71 | 72 | assert len(processed) == 4 73 | # All should be tuples 74 | assert all(isinstance(f, tuple) for f in processed) 75 | # Verify values are preserved (dates are normalized to ISO 8601) 76 | assert processed[0][2] == ["wtg", "rdy", "ip", "rev"] 77 | assert processed[1][2] == {"type": "HumanUser", "id": 42} 78 | assert processed[2][2] == "2025-01-01T00:00:00Z" # Date normalized to ISO 8601 79 | assert processed[3][2] == "animation" 80 | 81 | def test_tuple_input_processing(self): 82 | """Test that tuple input is also accepted.""" 83 | request = SearchEntitiesRequest(entity_type="Task", filters=[("sg_status_list", "is", "ip")], fields=["id"]) 84 | 85 | processed = process_filters(request.filters) 86 | 87 | assert len(processed) == 1 88 | assert processed[0] == ("sg_status_list", "is", "ip") 89 | 90 | def test_filter_with_none_value(self): 91 | """Test filter with None value.""" 92 | request = SearchEntitiesRequest( 93 | entity_type="Task", filters=[["task_assignees", "is", None]], fields=["content"] 94 | ) 95 | 96 | processed = process_filters(request.filters) 97 | 98 | assert len(processed) == 1 99 | assert processed[0] == ("task_assignees", "is", None) 100 | 101 | def test_filter_with_boolean_value(self): 102 | """Test filter with boolean value.""" 103 | request = SearchEntitiesRequest(entity_type="Asset", filters=[["sg_is_published", "is", True]], fields=["code"]) 104 | 105 | processed = process_filters(request.filters) 106 | 107 | assert len(processed) == 1 108 | assert processed[0] == ("sg_is_published", "is", True) 109 | 110 | def test_filter_with_numeric_value(self): 111 | """Test filter with numeric value.""" 112 | request = SearchEntitiesRequest(entity_type="Shot", filters=[["id", "greater_than", 1000]], fields=["code"]) 113 | 114 | processed = process_filters(request.filters) 115 | 116 | assert len(processed) == 1 117 | assert processed[0] == ("id", "greater_than", 1000) 118 | -------------------------------------------------------------------------------- /tests/test_schema_resources.py: -------------------------------------------------------------------------------- 1 | """Tests for ShotGrid MCP schema resources. 2 | 3 | These tests focus on the helper functions that shape schema data into a 4 | stable JSON structure suitable for MCP resources. 5 | """ 6 | 7 | from __future__ import annotations 8 | 9 | from typing import Any, Dict 10 | 11 | import pytest 12 | from shotgun_api3.lib.mockgun import Shotgun 13 | 14 | from shotgrid_mcp_server import schema_resources as sr 15 | 16 | 17 | def test_extract_status_choices_full_payload() -> None: 18 | """_extract_status_choices handles full ShotGrid-style payload.""" 19 | 20 | field_schema: Dict[str, Any] = { 21 | "data_type": {"value": "status_list"}, 22 | "properties": { 23 | "valid_values": {"value": ["wtg", "ip", "fin"]}, 24 | "display_values": {"value": {"wtg": "Waiting", "ip": "In Progress", "fin": "Final"}}, 25 | "default_value": {"value": "wtg"}, 26 | }, 27 | } 28 | 29 | result = sr._extract_status_choices(field_schema) 30 | 31 | assert result["data_type"] == "status_list" 32 | assert result["valid_values"] == ["wtg", "ip", "fin"] 33 | assert result["display_values"]["ip"] == "In Progress" 34 | assert result["default_value"] == "wtg" 35 | 36 | 37 | def test_extract_status_choices_missing_optional_keys() -> None: 38 | """_extract_status_choices behaves when optional keys are absent.""" 39 | 40 | field_schema: Dict[str, Any] = { 41 | "data_type": {"value": "status_list"}, 42 | "properties": {}, 43 | } 44 | 45 | result = sr._extract_status_choices(field_schema) 46 | 47 | # We always at least expose the data_type 48 | assert result == {"data_type": "status_list"} 49 | 50 | 51 | def test_build_status_payload_for_entity_uses_schema(mock_sg: Shotgun) -> None: 52 | """_build_status_payload_for_entity picks up status_list fields. 53 | 54 | Our test schema defines an ``sg_status_list`` field with ``data_type`` 55 | ``"status_list"`` on the ``Asset`` entity, so that is the minimal 56 | contract we assert here. The real ShotGrid schema usually provides 57 | richer ``valid_values`` and ``display_values`` data, which will also 58 | be surfaced by the helpers but is not required for these tests. 59 | """ 60 | 61 | payload = sr._build_status_payload_for_entity(mock_sg, "Asset") 62 | 63 | assert "sg_status_list" in payload 64 | status_info = payload["sg_status_list"] 65 | assert status_info["data_type"] == "status_list" 66 | 67 | 68 | def test_build_all_status_payload_aggregates_entity_types(mock_sg: Shotgun, monkeypatch: pytest.MonkeyPatch) -> None: 69 | """_build_all_status_payload groups status fields by entity type. 70 | 71 | We stub ``get_entity_types_from_schema`` so that this test focuses on how 72 | the helper aggregates per-entity payloads rather than on the exact 73 | behaviour of the schema loader in different environments (Mockgun vs 74 | real ShotGrid). 75 | """ 76 | 77 | def fake_get_entity_types_from_schema(_sg: Shotgun) -> set[str]: 78 | return {"Asset"} 79 | 80 | monkeypatch.setattr(sr, "get_entity_types_from_schema", fake_get_entity_types_from_schema) 81 | 82 | payload = sr._build_all_status_payload(mock_sg) 83 | 84 | assert "Asset" in payload 85 | asset_status = payload["Asset"]["sg_status_list"] 86 | assert asset_status["data_type"] == "status_list" 87 | 88 | 89 | def test_register_schema_resources_registers_and_resolves(mock_sg: Shotgun, monkeypatch: pytest.MonkeyPatch) -> None: 90 | """register_schema_resources wires up resources that read from schema. 91 | 92 | We stub the schema loader to make the behaviour deterministic under 93 | Mockgun while still exercising the real helper functions. 94 | """ 95 | 96 | class DummyServer: 97 | def __init__(self) -> None: 98 | self.resources: Dict[str, Any] = {} 99 | 100 | def resource(self, uri: str): 101 | def decorator(func): 102 | self.resources[uri] = func 103 | return func 104 | 105 | return decorator 106 | 107 | def fake_get_entity_types_from_schema(_sg: Shotgun) -> set[str]: 108 | return {"Asset"} 109 | 110 | monkeypatch.setattr(sr, "get_entity_types_from_schema", fake_get_entity_types_from_schema) 111 | 112 | server = DummyServer() 113 | sr.register_schema_resources(server, mock_sg) 114 | 115 | # All expected resource URIs should be registered. 116 | assert "shotgrid://schema/entities" in server.resources 117 | assert "shotgrid://schema/statuses" in server.resources 118 | assert "shotgrid://schema/statuses/{entity_type}" in server.resources 119 | 120 | # Calling the resources should return sensible data. 121 | entities = server.resources["shotgrid://schema/entities"]() 122 | assert "Shot" in entities 123 | 124 | all_statuses = server.resources["shotgrid://schema/statuses"]() 125 | assert "Asset" in all_statuses 126 | 127 | per_entity = server.resources["shotgrid://schema/statuses/{entity_type}"](entity_type="Asset") 128 | assert "sg_status_list" in per_entity 129 | -------------------------------------------------------------------------------- /docs/servers/overview.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Server Overview 3 | sidebarTitle: Overview 4 | description: Understanding the ShotGrid MCP Server architecture 5 | icon: server 6 | --- 7 | 8 | # ShotGrid MCP Server Overview 9 | 10 | ShotGrid MCP Server is built on the Model Context Protocol (MCP) and provides a standardized way for LLMs to interact with ShotGrid data. This page provides an overview of the server architecture and key components. 11 | 12 | ## Architecture 13 | 14 | ShotGrid MCP Server consists of several key components: 15 | 16 | ```mermaid 17 | graph TD 18 | A[MCP Client] -->|MCP Protocol| B[ShotGrid MCP Server] 19 | B -->|API Calls| C[ShotGrid API] 20 | B --> D[Connection Pool] 21 | D -->|Manages| C 22 | B --> E[Schema Loader] 23 | E -->|Loads| F[Entity Schema] 24 | B --> G[Tool Manager] 25 | G -->|Registers| H[Tools] 26 | H -->|Use| D 27 | ``` 28 | 29 | ### Core Components 30 | 31 | 1. **Server**: The main `ShotGridMCPServer` class that implements the MCP protocol and manages all components. 32 | 33 | 2. **Connection Pool**: Manages connections to the ShotGrid API, providing efficient connection reuse and error handling. 34 | 35 | 3. **Schema Loader**: Loads and caches the ShotGrid schema, which defines entity types, fields, and relationships. 36 | 37 | 4. **Tool Manager**: Registers and manages tools that can be called by MCP clients. 38 | 39 | 5. **Mockgun Extension**: An enhanced version of ShotGrid's Mockgun for testing without a real ShotGrid instance. 40 | 41 | ## Server Configuration 42 | 43 | When creating a `ShotGridMCPServer` instance, you can configure various aspects of its behavior: 44 | 45 | ```python 46 | from shotgrid_mcp_server import ShotGridMCPServer 47 | 48 | server = ShotGridMCPServer( 49 | # Server identification 50 | name="Production Assistant", 51 | 52 | # ShotGrid connection (choose one approach) 53 | shotgrid_url="https://your-site.shotgunstudio.com", 54 | script_name="your_script_name", 55 | api_key="your_api_key", 56 | 57 | # OR use an existing Shotgun instance 58 | # shotgun=existing_shotgun_instance, 59 | 60 | # OR use Mockgun for testing 61 | # use_mockgun=True, 62 | 63 | # Connection pool settings 64 | max_connections=10, 65 | connection_timeout=30, 66 | 67 | # Schema settings 68 | schema_path="path/to/schema.bin", 69 | entity_schema_path="path/to/entity_schema.bin", 70 | 71 | # Behavior settings 72 | on_duplicate_tools="warn", # Options: "warn", "error", "replace", "ignore" 73 | ) 74 | ``` 75 | 76 | ### Configuration Options 77 | 78 | | Parameter | Type | Description | 79 | |-----------|------|-------------| 80 | | `name` | str | Name of the server, shown to clients | 81 | | `shotgrid_url` | str | URL of your ShotGrid instance | 82 | | `script_name` | str | Script name for API authentication | 83 | | `api_key` | str | API key for authentication | 84 | | `shotgun` | Shotgun | Existing Shotgun instance to use | 85 | | `use_mockgun` | bool | Whether to use Mockgun instead of real ShotGrid | 86 | | `max_connections` | int | Maximum number of connections in the pool | 87 | | `connection_timeout` | int | Timeout for ShotGrid API calls (seconds) | 88 | | `schema_path` | str | Path to a cached schema file | 89 | | `entity_schema_path` | str | Path to a cached entity schema file | 90 | | `on_duplicate_tools` | str | How to handle duplicate tool registrations | 91 | 92 | ## Lifecycle Hooks 93 | 94 | ShotGrid MCP Server provides hooks for running code at different points in the server lifecycle: 95 | 96 | ```python 97 | @server.on_startup 98 | async def startup_handler(): 99 | """Run when the server starts.""" 100 | print("Server is starting up!") 101 | # Initialize resources, load data, etc. 102 | 103 | @server.on_shutdown 104 | async def shutdown_handler(): 105 | """Run when the server is shutting down.""" 106 | print("Server is shutting down!") 107 | # Clean up resources, save state, etc. 108 | ``` 109 | 110 | ## Running the Server 111 | 112 | To start the server, call the `run` method: 113 | 114 | ```python 115 | if __name__ == "__main__": 116 | server.run( 117 | host="0.0.0.0", # Listen on all interfaces 118 | port=8000, # Port to listen on 119 | log_level="info" # Logging level 120 | ) 121 | ``` 122 | 123 | For more control over the server lifecycle, you can use the async API: 124 | 125 | ```python 126 | import asyncio 127 | 128 | async def main(): 129 | await server.start() 130 | try: 131 | # Keep the server running 132 | await asyncio.Future() 133 | finally: 134 | await server.stop() 135 | 136 | if __name__ == "__main__": 137 | asyncio.run(main()) 138 | ``` 139 | 140 | ## Next Steps 141 | 142 | Now that you understand the server architecture, you can: 143 | 144 | - Learn how to create [Tools](/servers/tools) for your server 145 | - Understand the [Connection Pool](/servers/connection-pool) for efficient API usage 146 | - Explore the [Schema Loader](/servers/schema-loader) for working with ShotGrid schemas 147 | - See how to use [Mockgun](/servers/mockgun) for testing 148 | -------------------------------------------------------------------------------- /tests/test_api_models_filters.py: -------------------------------------------------------------------------------- 1 | """Test API models filter validation.""" 2 | 3 | import pytest 4 | 5 | from shotgrid_mcp_server.api_models import SearchEntitiesRequest 6 | 7 | 8 | class TestSearchEntitiesRequestFilterValidation: 9 | """Test SearchEntitiesRequest filter validation.""" 10 | 11 | def test_valid_single_filter(self): 12 | """Test valid single filter.""" 13 | request = SearchEntitiesRequest( 14 | entity_type="Task", filters=[["sg_status_list", "is", "ip"]], fields=["id", "content"] 15 | ) 16 | assert request.filters == [["sg_status_list", "is", "ip"]] 17 | assert isinstance(request.filters[0], list) 18 | 19 | def test_valid_multiple_filters(self): 20 | """Test valid multiple filters.""" 21 | request = SearchEntitiesRequest( 22 | entity_type="Shot", 23 | filters=[["sg_status_list", "in", ["wtg", "rdy", "ip"]], ["project", "is", {"type": "Project", "id": 123}]], 24 | fields=["code"], 25 | ) 26 | assert len(request.filters) == 2 27 | assert request.filters[0] == ["sg_status_list", "in", ["wtg", "rdy", "ip"]] 28 | assert request.filters[1] == ["project", "is", {"type": "Project", "id": 123}] 29 | 30 | def test_valid_time_filter(self): 31 | """Test valid time-based filter. 32 | 33 | Note: 4-element time filters are automatically normalized to 3-element format. 34 | ["field", "operator", count, unit] -> ["field", "operator", [count, unit]] 35 | """ 36 | request = SearchEntitiesRequest( 37 | entity_type="Version", filters=[["created_at", "in_last", 7, "DAY"]], fields=["code"] 38 | ) 39 | # The 4-element format is normalized to 3-element format 40 | assert request.filters == [["created_at", "in_last", [7, "DAY"]]] 41 | 42 | def test_empty_filters(self): 43 | """Test empty filters list.""" 44 | request = SearchEntitiesRequest(entity_type="Asset", filters=[], fields=["code"]) 45 | assert request.filters == [] 46 | 47 | def test_none_filters(self): 48 | """Test None filters (should default to empty list).""" 49 | request = SearchEntitiesRequest(entity_type="Asset", fields=["code"]) 50 | assert request.filters == [] 51 | 52 | def test_invalid_filter_not_list(self): 53 | """Test invalid filter that is not a list/tuple.""" 54 | with pytest.raises(ValueError, match="Filter 0 must be a list/tuple"): 55 | SearchEntitiesRequest(entity_type="Task", filters=["invalid"], fields=["id"]) 56 | 57 | def test_invalid_filter_too_short(self): 58 | """Test invalid filter with less than 3 elements.""" 59 | with pytest.raises(ValueError, match="Filter 0 must have at least 3 elements"): 60 | SearchEntitiesRequest(entity_type="Task", filters=[["field", "operator"]], fields=["id"]) 61 | 62 | def test_invalid_filter_dict_format(self): 63 | """Test that dict format is no longer accepted.""" 64 | with pytest.raises(ValueError, match="Filter 0 must be a list/tuple"): 65 | SearchEntitiesRequest( 66 | entity_type="Task", 67 | filters=[{"field": "sg_status_list", "operator": "is", "value": "ip"}], 68 | fields=["id"], 69 | ) 70 | 71 | def test_tuple_format_accepted(self): 72 | """Test that tuple format is accepted and converted to list.""" 73 | request = SearchEntitiesRequest(entity_type="Task", filters=[("sg_status_list", "is", "ip")], fields=["id"]) 74 | # Tuples are converted to lists during validation 75 | assert request.filters == [["sg_status_list", "is", "ip"]] 76 | 77 | def test_filter_with_entity_reference(self): 78 | """Test filter with entity reference.""" 79 | request = SearchEntitiesRequest( 80 | entity_type="Task", filters=[["task_assignees", "is", {"type": "HumanUser", "id": 42}]], fields=["content"] 81 | ) 82 | assert request.filters[0][2] == {"type": "HumanUser", "id": 42} 83 | 84 | def test_filter_with_list_value(self): 85 | """Test filter with list value (in operator).""" 86 | request = SearchEntitiesRequest( 87 | entity_type="Shot", filters=[["sg_status_list", "in", ["wtg", "rdy", "ip", "rev"]]], fields=["code"] 88 | ) 89 | assert request.filters[0][2] == ["wtg", "rdy", "ip", "rev"] 90 | 91 | def test_complex_filters(self): 92 | """Test complex filters with multiple types.""" 93 | request = SearchEntitiesRequest( 94 | entity_type="Task", 95 | filters=[ 96 | ["sg_status_list", "in", ["wtg", "rdy", "ip"]], 97 | ["project", "is", {"type": "Project", "id": 123}], 98 | ["created_at", "in_last", 30, "DAY"], 99 | ["content", "contains", "animation"], 100 | ], 101 | fields=["id", "content", "sg_status_list"], 102 | ) 103 | assert len(request.filters) == 4 104 | # Verify filters are preserved as-is 105 | assert all(isinstance(f, list) for f in request.filters) 106 | -------------------------------------------------------------------------------- /docs/CACHING_STRATEGY.md: -------------------------------------------------------------------------------- 1 | # ShotGrid MCP Server 缓存策略调研与实施方案 2 | 3 | ## 调研结果 4 | 5 | ### 1. FastMCP 内置缓存支持 ✅ 6 | 7 | **FastMCP 2.13.0 (2025-10-25)** 已经内置了完整的缓存解决方案： 8 | 9 | #### Response Caching Middleware 10 | - 专为 MCP 设计的响应缓存中间件 11 | - 可以缓存 tool 和 resource 的响应 12 | - 支持 TTL（Time-To-Live）配置 13 | - 自动处理缓存失效 14 | 15 | #### Pluggable Storage Backends 16 | 基于 [py-key-value-aio](https://github.com/strawgate/py-key-value) 库，支持多种后端： 17 | - **Filesystem** (默认，带加密) 18 | - **In-Memory** 19 | - **Redis** 20 | - **DynamoDB** 21 | - **Elasticsearch** 22 | - 支持加密、TTL、缓存等包装器 23 | 24 | ### 2. MCP 协议层面的缓存 25 | 26 | MCP 协议本身没有定义缓存机制，但提供了一些相关特性： 27 | 28 | #### Resources 29 | - Resources 是只读的，天然适合缓存 30 | - 可以通过 URI 唯一标识 31 | - 支持模板化 URI (RFC 6570) 32 | 33 | #### Tools 34 | - Tools 可能有副作用，需要谨慎缓存 35 | - 可以基于参数哈希进行缓存 36 | 37 | ### 3. Schema 缓存策略 38 | 39 | ShotGrid schema 的特点： 40 | - **相对稳定**：schema 不会频繁变化 41 | - **体积较大**：完整 schema 包含大量字段定义 42 | - **访问频繁**：每次验证都可能需要 schema 43 | 44 | ## 推荐方案 45 | 46 | ### 方案 A：使用 FastMCP 内置缓存（推荐） 47 | 48 | **优势：** 49 | - ✅ 与 MCP 生态完美集成 50 | - ✅ 开箱即用，无需额外依赖 51 | - ✅ 支持多种存储后端 52 | - ✅ 自动处理序列化/反序列化 53 | - ✅ 支持加密存储 54 | 55 | **实施步骤：** 56 | 57 | ```python 58 | from fastmcp import FastMCP 59 | from fastmcp.middleware import CachingMiddleware 60 | 61 | # 创建服务器 62 | mcp = FastMCP("shotgrid-mcp-server") 63 | 64 | # 添加缓存中间件 65 | mcp.add_middleware( 66 | CachingMiddleware( 67 | # 缓存 schema 资源 24 小时 68 | resource_ttl=86400, # 24 hours 69 | # 缓存搜索结果 5 分钟 70 | tool_ttl=300, # 5 minutes 71 | # 使用文件系统存储（默认加密） 72 | backend="filesystem", 73 | # 或使用 Redis 74 | # backend="redis://localhost:6379/0" 75 | ) 76 | ) 77 | ``` 78 | 79 | ### 方案 B：使用 diskcache（备选） 80 | 81 | 如果需要更细粒度的控制，可以使用 diskcache： 82 | 83 | ```python 84 | from diskcache import Cache 85 | from functools import wraps 86 | 87 | # 创建缓存实例 88 | schema_cache = Cache("./cache/schema", size_limit=100 * 1024 * 1024) # 100MB 89 | 90 | def cached_schema(ttl=86400): 91 | """Schema 缓存装饰器""" 92 | def decorator(func): 93 | @wraps(func) 94 | def wrapper(*args, **kwargs): 95 | cache_key = f"{func.__name__}:{args}:{kwargs}" 96 | result = schema_cache.get(cache_key) 97 | if result is None: 98 | result = func(*args, **kwargs) 99 | schema_cache.set(cache_key, result, expire=ttl) 100 | return result 101 | return wrapper 102 | return decorator 103 | 104 | @cached_schema(ttl=86400) # 24 hours 105 | def get_entity_schema(entity_type: str): 106 | return sg.schema_field_read(entity_type) 107 | ``` 108 | 109 | ### 方案 C：混合方案（最佳实践） 110 | 111 | 结合两者优势： 112 | 113 | 1. **FastMCP 缓存中间件**：处理 MCP 层面的响应缓存 114 | 2. **diskcache**：处理应用层面的数据缓存（如 schema） 115 | 116 | ```python 117 | # 1. FastMCP 层缓存 118 | mcp.add_middleware(CachingMiddleware(resource_ttl=3600)) 119 | 120 | # 2. 应用层 Schema 缓存 121 | from diskcache import Cache 122 | schema_cache = Cache("./cache/schema") 123 | 124 | @schema_cache.memoize(expire=86400) 125 | def get_cached_schema(entity_type: str): 126 | return sg.schema_field_read(entity_type) 127 | ``` 128 | 129 | ## 缓存策略建议 130 | 131 | ### Schema 缓存 132 | - **TTL**: 24 小时 133 | - **失效策略**: 手动失效 + 定时刷新 134 | - **存储**: 文件系统（加密） 135 | 136 | ### 搜索结果缓存 137 | - **TTL**: 5-15 分钟 138 | - **失效策略**: 基于参数哈希 139 | - **存储**: 内存或 Redis 140 | 141 | ### 实体数据缓存 142 | - **TTL**: 1-5 分钟 143 | - **失效策略**: 写操作自动失效 144 | - **存储**: 内存 145 | 146 | ## 性能优化建议 147 | 148 | ### 1. Schema 预加载 149 | ```python 150 | async def preload_schemas(): 151 | """服务器启动时预加载常用 schema""" 152 | common_entities = ["Shot", "Asset", "Task", "Version", "Note"] 153 | for entity_type in common_entities: 154 | await get_cached_schema(entity_type) 155 | ``` 156 | 157 | ### 2. 批量缓存 158 | ```python 159 | def cache_multiple_schemas(entity_types: List[str]): 160 | """批量缓存多个 entity schema""" 161 | with schema_cache.transact(): 162 | for entity_type in entity_types: 163 | get_cached_schema(entity_type) 164 | ``` 165 | 166 | ### 3. 缓存预热 167 | ```python 168 | @mcp.lifespan() 169 | async def lifespan(): 170 | """服务器生命周期管理""" 171 | # 启动时预热缓存 172 | await preload_schemas() 173 | yield 174 | # 关闭时清理 175 | schema_cache.close() 176 | ``` 177 | 178 | ## 监控与调试 179 | 180 | ### 缓存命中率监控 181 | ```python 182 | from fastmcp.middleware import CachingMiddleware 183 | 184 | cache_middleware = CachingMiddleware( 185 | resource_ttl=86400, 186 | enable_metrics=True # 启用指标收集 187 | ) 188 | 189 | # 查看缓存统计 190 | print(f"Cache hits: {cache_middleware.hits}") 191 | print(f"Cache misses: {cache_middleware.misses}") 192 | print(f"Hit rate: {cache_middleware.hit_rate:.2%}") 193 | ``` 194 | 195 | ### 缓存调试 196 | ```python 197 | # 查看缓存内容 198 | for key in schema_cache: 199 | print(f"Key: {key}, Size: {len(schema_cache[key])}") 200 | 201 | # 清空特定缓存 202 | schema_cache.delete("schema:Shot") 203 | 204 | # 清空所有缓存 205 | schema_cache.clear() 206 | ``` 207 | 208 | ## 总结 209 | 210 | **推荐使用 FastMCP 2.13.0 内置的 Response Caching Middleware**，原因： 211 | 212 | 1. ✅ 原生支持，无需额外集成 213 | 2. ✅ 自动处理 MCP 协议细节 214 | 3. ✅ 支持多种存储后端 215 | 4. ✅ 内置加密和 TTL 支持 216 | 5. ✅ 与 FastMCP 生态完美集成 217 | 218 | 对于特殊需求（如 schema 验证缓存），可以在应用层使用 diskcache 作为补充。 219 | 220 | -------------------------------------------------------------------------------- /docs/getting-started/quickstart.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Quickstart Guide 3 | sidebarTitle: Quickstart 4 | description: Get started with ShotGrid MCP Server in minutes 5 | icon: bolt 6 | --- 7 | 8 | # Quickstart Guide 9 | 10 | This guide will help you set up a basic ShotGrid MCP Server and create your first tools. By the end, you'll have a working server that can interact with ShotGrid data through the MCP protocol. 11 | 12 | ## Basic Server Setup 13 | 14 | First, let's create a simple server that connects to ShotGrid: 15 | 16 | ```python 17 | from shotgrid_mcp_server import ShotGridMCPServer 18 | 19 | # Create a server with your ShotGrid credentials 20 | server = ShotGridMCPServer( 21 | name="ShotGrid Assistant", 22 | shotgrid_url="https://your-site.shotgunstudio.com", 23 | script_name="your_script_name", 24 | api_key="your_api_key" 25 | ) 26 | 27 | # Run the server 28 | if __name__ == "__main__": 29 | server.run(host="localhost", port=8000) 30 | ``` 31 | 32 | Save this as `server.py` and run it with `python server.py`. Your server will start on http://localhost:8000. 33 | 34 | ## Using Mockgun for Testing 35 | 36 | For development and testing, you can use Mockgun instead of connecting to a real ShotGrid instance: 37 | 38 | ```python 39 | from shotgrid_mcp_server import ShotGridMCPServer 40 | 41 | # Create a server with Mockgun 42 | server = ShotGridMCPServer( 43 | name="ShotGrid Test Server", 44 | use_mockgun=True, # This enables Mockgun 45 | schema_path="path/to/schema.bin" # Optional: path to a schema file 46 | ) 47 | 48 | if __name__ == "__main__": 49 | server.run(host="localhost", port=8000) 50 | ``` 51 | 52 | ## Creating Your First Tool 53 | 54 | Let's add a tool to search for projects: 55 | 56 | ```python 57 | from shotgrid_mcp_server import ShotGridMCPServer 58 | 59 | server = ShotGridMCPServer( 60 | name="ShotGrid Assistant", 61 | use_mockgun=True # For testing 62 | ) 63 | 64 | @server.tool() 65 | def find_projects(status: str = None): 66 | """ 67 | Find projects in ShotGrid, optionally filtered by status. 68 | 69 | Args: 70 | status: Filter projects by status (e.g., "Active", "Archived") 71 | 72 | Returns: 73 | A list of projects matching the criteria 74 | """ 75 | filters = [] 76 | if status: 77 | filters.append(["sg_status", "is", status]) 78 | 79 | return server.connection.find( 80 | "Project", 81 | filters, 82 | ["id", "name", "code", "sg_status"] 83 | ) 84 | 85 | if __name__ == "__main__": 86 | server.run(host="localhost", port=8000) 87 | ``` 88 | 89 | ## Adding Test Data to Mockgun 90 | 91 | If you're using Mockgun, you'll need to add some test data: 92 | 93 | ```python 94 | from shotgrid_mcp_server import ShotGridMCPServer 95 | 96 | server = ShotGridMCPServer( 97 | name="ShotGrid Test Server", 98 | use_mockgun=True 99 | ) 100 | 101 | # Add test data to Mockgun 102 | @server.on_startup 103 | def create_test_data(): 104 | # Create test projects 105 | server.connection.create("Project", { 106 | "name": "Awesome Film", 107 | "code": "AWSM", 108 | "sg_status": "Active" 109 | }) 110 | 111 | server.connection.create("Project", { 112 | "name": "Old Project", 113 | "code": "OLD", 114 | "sg_status": "Archived" 115 | }) 116 | 117 | @server.tool() 118 | def find_projects(status: str = None): 119 | """Find projects in ShotGrid, optionally filtered by status.""" 120 | filters = [] 121 | if status: 122 | filters.append(["sg_status", "is", status]) 123 | 124 | return server.connection.find( 125 | "Project", 126 | filters, 127 | ["id", "name", "code", "sg_status"] 128 | ) 129 | 130 | if __name__ == "__main__": 131 | server.run(host="localhost", port=8000) 132 | ``` 133 | 134 | ## Testing Your Server 135 | 136 | You can test your server using the built-in MCP client: 137 | 138 | ```python 139 | from mcp.client import Client 140 | 141 | async def test_server(): 142 | # Connect to your server 143 | client = Client("http://localhost:8000") 144 | 145 | # List available tools 146 | tools = await client.list_tools() 147 | print(f"Available tools: {[tool.name for tool in tools]}") 148 | 149 | # Call the find_projects tool 150 | result = await client.call_tool("find_projects", {"status": "Active"}) 151 | print(f"Active projects: {result}") 152 | 153 | if __name__ == "__main__": 154 | import asyncio 155 | asyncio.run(test_server()) 156 | ``` 157 | 158 | Save this as `test_client.py` and run it with `python test_client.py` while your server is running. 159 | 160 | ## Next Steps 161 | 162 | Now that you have a basic server running, you can: 163 | 164 | - Add more [tools](/servers/tools) for different ShotGrid entities 165 | - Learn about [optimized queries](/patterns/optimized-queries) for better performance 166 | - Explore [batch operations](/patterns/batch-operations) for efficient data manipulation 167 | - Set up [connection pooling](/servers/connection-pool) for production use 168 | 169 | Congratulations! You've created your first ShotGrid MCP Server. Continue exploring the documentation to learn more about the server's capabilities. 170 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/asgi.py: -------------------------------------------------------------------------------- 1 | """ASGI application for ShotGrid MCP server. 2 | 3 | This module provides a standalone ASGI application that can be deployed 4 | to any ASGI server (Uvicorn, Gunicorn, Hypercorn, etc.) or cloud platforms 5 | like FastMCP Cloud. 6 | 7 | Example: 8 | Deploy with Uvicorn: 9 | uvicorn shotgrid_mcp_server.asgi:app --host 0.0.0.0 --port 8000 10 | 11 | Deploy with Gunicorn: 12 | gunicorn shotgrid_mcp_server.asgi:app -k uvicorn.workers.UvicornWorker 13 | 14 | With custom middleware: 15 | from shotgrid_mcp_server.asgi import create_asgi_app 16 | from starlette.middleware import Middleware 17 | from starlette.middleware.cors import CORSMiddleware 18 | 19 | app = create_asgi_app(middleware=[ 20 | Middleware( 21 | CORSMiddleware, 22 | allow_origins=["*"], 23 | allow_methods=["*"], 24 | allow_headers=["*"], 25 | ) 26 | ]) 27 | """ 28 | 29 | # Import built-in modules 30 | import logging 31 | from typing import List, Optional 32 | 33 | # Import third-party modules 34 | from starlette.middleware import Middleware 35 | 36 | # Import local modules 37 | from shotgrid_mcp_server.logger import setup_logging 38 | from shotgrid_mcp_server.server import create_server 39 | 40 | # Configure logger 41 | logger = logging.getLogger(__name__) 42 | setup_logging() 43 | 44 | 45 | def create_asgi_app(middleware: Optional[List[Middleware]] = None, path: str = "/mcp"): 46 | """Create a standalone ASGI application. 47 | 48 | Args: 49 | middleware: Optional list of Starlette middleware to add to the app. 50 | path: API endpoint path (default: "/mcp"). 51 | 52 | Returns: 53 | Starlette application instance that can be deployed to any ASGI server. 54 | 55 | Example: 56 | Basic usage: 57 | app = create_asgi_app() 58 | 59 | With CORS middleware: 60 | from starlette.middleware import Middleware 61 | from starlette.middleware.cors import CORSMiddleware 62 | 63 | app = create_asgi_app(middleware=[ 64 | Middleware( 65 | CORSMiddleware, 66 | allow_origins=["*"], 67 | allow_methods=["*"], 68 | allow_headers=["*"], 69 | ) 70 | ]) 71 | 72 | With multiple middleware: 73 | from starlette.middleware.gzip import GZipMiddleware 74 | 75 | app = create_asgi_app(middleware=[ 76 | Middleware(CORSMiddleware, allow_origins=["*"]), 77 | Middleware(GZipMiddleware, minimum_size=1000), 78 | ]) 79 | """ 80 | try: 81 | logger.info("Creating ASGI application with lazy connection mode") 82 | 83 | # Create MCP server with lazy connection mode 84 | # Credentials will be provided via HTTP headers or environment variables 85 | mcp_server = create_server(lazy_connection=True) 86 | 87 | # Generate ASGI app from MCP server 88 | asgi_app = mcp_server.http_app(middleware=middleware, path=path) 89 | 90 | logger.info("ASGI application created successfully on path: %s", path) 91 | return asgi_app 92 | 93 | except Exception as err: 94 | logger.error("Failed to create ASGI application: %s", str(err), exc_info=True) 95 | raise 96 | 97 | 98 | # Lazy initialization of default ASGI application 99 | # The app is created on first access, not on module import 100 | # This prevents connection errors during Docker build or import time 101 | _app_instance = None 102 | 103 | 104 | def get_app(): 105 | """Get or create the default ASGI application instance. 106 | 107 | This function implements lazy initialization to avoid creating 108 | ShotGrid connections during module import or Docker build time. 109 | 110 | Returns: 111 | Starlette application instance. 112 | """ 113 | global _app_instance 114 | if _app_instance is None: 115 | logger.info("Initializing default ASGI application (lazy mode)") 116 | try: 117 | _app_instance = create_asgi_app() 118 | logger.info("ASGI application initialized successfully") 119 | logger.info("Deploy with: uvicorn shotgrid_mcp_server.asgi:app --host 0.0.0.0 --port 8000") 120 | except Exception as e: 121 | logger.error("Failed to initialize ASGI application: %s", str(e)) 122 | # Re-raise to let the ASGI server handle the error 123 | raise 124 | return _app_instance 125 | 126 | 127 | # For ASGI servers, we need a module-level callable 128 | # Import this as: uvicorn shotgrid_mcp_server.asgi:app 129 | def app(scope, receive, send): 130 | """ASGI application entry point with lazy initialization. 131 | 132 | This is a module-level callable that ASGI servers can import. 133 | The actual application is created on first request. 134 | 135 | Args: 136 | scope: ASGI scope dict 137 | receive: ASGI receive callable 138 | send: ASGI send callable 139 | 140 | Returns: 141 | Coroutine for the ASGI application 142 | """ 143 | application = get_app() 144 | return application(scope, receive, send) 145 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [project] 2 | name = "shotgrid-mcp-server" 3 | version = "0.14.0" 4 | description = "A Model Context Protocol (MCP) server implementation using fastmcp" 5 | readme = "README.md" 6 | requires-python = ">=3.10,<3.13" 7 | dependencies = [ 8 | "fastmcp>=2.13.0", 9 | "mcp>=1.10.0", # Fix CVE-2025-53365, CVE-2025-53366 10 | "uvicorn[standard]>=0.35.0", 11 | "pydantic[email]>=2.0.0", 12 | "python-dotenv>=1.0.0", 13 | "platformdirs>=4.1.0", 14 | "aiohttp>=3.12.14", # Fix CVE-2025-53643 15 | "requests>=2.32.4", # Fix CVE-2024-47081 16 | "shotgun-api3>=3.8.2", 17 | "shotgrid-query>=0.1.0", 18 | "python-slugify (>=8.0.4,<9.0.0)", 19 | "pendulum (>=3.1.0,<4.0.0)", 20 | "tenacity (>=9.1.2,<10.0.0)", 21 | "click>=8.0.0", 22 | "websockets>=15.0.1", 23 | "diskcache_rs>=0.4.4", 24 | ] 25 | authors = [ 26 | { name = "Hal Long", email = "hal.long@outlook.com" }, 27 | ] 28 | license = { text = "MIT" } 29 | keywords = ["shotgrid", "mcp", "server", "api", "Flow Production Tracking"] 30 | classifiers = [ 31 | "Development Status :: 4 - Beta", 32 | "Intended Audience :: Developers", 33 | "License :: OSI Approved :: MIT License", 34 | "Operating System :: OS Independent", 35 | "Programming Language :: Python :: 3", 36 | "Programming Language :: Python :: 3.10", 37 | "Programming Language :: Python :: 3.11", 38 | "Programming Language :: Python :: 3.12", 39 | "Topic :: Software Development :: Libraries :: Python Modules", 40 | ] 41 | 42 | [project.urls] 43 | Homepage = "https://github.com/loonghao/shotgrid-mcp-server" 44 | Repository = "https://github.com/loonghao/shotgrid-mcp-server.git" 45 | Issues = "https://github.com/loonghao/shotgrid-mcp-server/issues" 46 | Changelog = "https://github.com/loonghao/shotgrid-mcp-server/blob/main/CHANGELOG.md" 47 | 48 | [project.optional-dependencies] 49 | test = [ 50 | "pytest>=7.0.0", 51 | "pytest-asyncio>=0.21.0", 52 | "pytest-mock>=3.10.0", 53 | "pytest-cov>=4.0.0", 54 | "PyYAML", 55 | ] 56 | lint = [ 57 | "ruff", 58 | "black", 59 | "mypy", 60 | "types-requests", 61 | ] 62 | dev = [ 63 | "black>=23.12.1", 64 | "coverage>=7.4.0", 65 | "flake8>=7.0.0", 66 | "isort>=5.13.2", 67 | "mypy>=1.8.0", 68 | "nox>=2023.4.22", 69 | "pytest>=7.4.4", 70 | "pytest-cov>=4.1.0", 71 | "ruff>=0.1.11", 72 | "uv>=0.9.6", # Fix CVE-2025-62727, CVE-2025-54368, and other ZIP parsing vulnerabilities 73 | ] 74 | 75 | [project.scripts] 76 | shotgrid-mcp-server = "shotgrid_mcp_server.cli:main" 77 | 78 | [tool.commitizen] 79 | name = "cz_conventional_commits" 80 | version = "0.14.0" 81 | tag_format = "v$version" 82 | version_files = [ 83 | "pyproject.toml:version", 84 | ] 85 | 86 | [build-system] 87 | requires = ["hatchling"] 88 | build-backend = "hatchling.build" 89 | 90 | [tool.hatch.build.targets.wheel] 91 | packages = ["src/shotgrid_mcp_server"] 92 | 93 | [tool.hatch.metadata] 94 | allow-direct-references = true 95 | 96 | [tool.black] 97 | line-length = 120 98 | target-version = ['py310', 'py311', 'py312'] 99 | include = '\.pyi?$' 100 | exclude = ''' 101 | ( 102 | /( 103 | \.eggs # exclude a few common directories in the 104 | | \.git # root of the project 105 | | \.hg 106 | | \.mypy_cache 107 | | \.tox 108 | | \.nox 109 | | \.venv 110 | | _build 111 | | buck-out 112 | | build 113 | | dist 114 | )/ 115 | ) 116 | ''' 117 | 118 | [tool.isort] 119 | profile = "black" 120 | atomic = true 121 | include_trailing_comma = true 122 | lines_after_imports = 2 123 | lines_between_types = 1 124 | use_parentheses = true 125 | src_paths = ["shotgrid_mcp_server", "tests"] 126 | filter_files = true 127 | known_first_party = "shotgrid_mcp_server" 128 | 129 | # Enforce import section headers. 130 | import_heading_future = "Import future modules" 131 | import_heading_stdlib = "Import built-in modules" 132 | import_heading_thirdparty = "Import third-party modules" 133 | import_heading_firstparty = "Import local modules" 134 | 135 | force_sort_within_sections = true 136 | force_single_line = true 137 | 138 | # All project unrelated unknown imports belong to third-party. 139 | default_section = "THIRDPARTY" 140 | skip_glob = [] 141 | 142 | [tool.ruff] 143 | line-length = 120 144 | target-version = "py310" 145 | src = ["src", "tests"] 146 | 147 | [tool.ruff.lint] 148 | select = [ 149 | "E", # pycodestyle errors 150 | "W", # pycodestyle warnings 151 | "F", # pyflakes 152 | "I", # isort 153 | "C", # flake8-comprehensions 154 | "B", # flake8-bugbear 155 | ] 156 | ignore = ["E501", "PLR0913", "RUF001", "RUF002", "RUF003"] 157 | 158 | [tool.ruff.lint.per-file-ignores] 159 | "__init__.py" = ["F401"] 160 | "noxfile.py" = ["E402", "I001"] 161 | "tests/*" = ["S101"] 162 | 163 | [tool.coverage.run] 164 | source = ["shotgrid_mcp_server"] 165 | branch = true 166 | 167 | [tool.coverage.report] 168 | exclude_lines = [ 169 | "pragma: no cover", 170 | "def __repr__", 171 | "if __name__ == .__main__.:", 172 | "raise NotImplementedError", 173 | "if TYPE_CHECKING:", 174 | ] 175 | 176 | [tool.pytest.ini_options] 177 | asyncio_mode = "strict" 178 | testpaths = ["tests"] 179 | python_files = ["test_*.py"] 180 | addopts = "-v --cov=shotgrid_mcp_server --cov-report=term-missing" 181 | 182 | [tool.uvx.python] 183 | version = "3.10" 184 | 185 | [tool.uv] 186 | python-preference = "only-managed" 187 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/tools/read_tools.py: -------------------------------------------------------------------------------- 1 | """Read tools for ShotGrid MCP server. 2 | 3 | This module contains tools for reading entities from ShotGrid. 4 | """ 5 | 6 | from typing import Any, Dict 7 | 8 | from fastmcp.exceptions import ToolError 9 | from shotgun_api3.lib.mockgun import Shotgun 10 | 11 | from shotgrid_mcp_server.custom_types import EntityType 12 | from shotgrid_mcp_server.response_models import SchemaResult 13 | from shotgrid_mcp_server.tools.base import handle_error 14 | from shotgrid_mcp_server.tools.types import FastMCPType 15 | 16 | 17 | def register_read_tools(server: FastMCPType, sg: Shotgun) -> None: 18 | """Register read tools with the server. 19 | 20 | Args: 21 | server: FastMCP server instance. 22 | sg: ShotGrid connection. 23 | """ 24 | 25 | @server.tool("schema_get") 26 | def get_schema(entity_type: EntityType) -> Dict[str, Any]: 27 | """Get field schema information for an entity type in ShotGrid. 28 | 29 | **When to use this tool:** 30 | - You need to know what fields are available for an entity type 31 | - You need to check field data types (text, number, date, entity, etc.) 32 | - You need to validate field names before creating/updating entities 33 | - You need to see field properties (required, editable, default values) 34 | - You want to understand the structure of an entity type 35 | 36 | **When NOT to use this tool:** 37 | - To get entity data - Use `search_entities` or `find_one_entity` instead 38 | - To get all entity types - Use `sg_schema_entity_read` instead 39 | - To get a specific field's schema - Use `sg_schema_field_read` instead 40 | - For cached schema information - Check MCP resources first 41 | 42 | **Common use cases:** 43 | - Validate field names before creating a Shot 44 | - Check what fields are available for Task entity 45 | - Understand field data types for Version entity 46 | - See required fields for creating an Asset 47 | 48 | Args: 49 | entity_type: Type of entity to get schema for. 50 | Must be a valid ShotGrid entity type. 51 | 52 | Common types: 53 | - "Shot": Shots in sequences 54 | - "Asset": Assets (characters, props, environments) 55 | - "Task": Work assignments 56 | - "Version": Published versions 57 | - "PublishedFile": Published files 58 | - "Note": Notes and comments 59 | 60 | Example: "Shot" 61 | 62 | Returns: 63 | Dictionary containing: 64 | - entity_type: The entity type 65 | - fields: Dictionary of field schemas 66 | Each field schema includes: 67 | - data_type: Field data type (text, number, date, entity, etc.) 68 | - properties: Field properties (editable, required, default_value, etc.) 69 | 70 | Example: 71 | { 72 | "entity_type": "Shot", 73 | "fields": { 74 | "code": { 75 | "data_type": {"value": "text"}, 76 | "properties": { 77 | "editable": {"value": true}, 78 | "summary_default": {"value": "none"} 79 | } 80 | }, 81 | "sg_status_list": { 82 | "data_type": {"value": "status_list"}, 83 | "properties": { 84 | "valid_values": {"value": ["wtg", "ip", "rev", "fin", "omt"]} 85 | } 86 | }, 87 | ... 88 | } 89 | } 90 | 91 | Raises: 92 | ToolError: If the schema retrieval fails or entity_type is invalid. 93 | 94 | Examples: 95 | Get schema for Shot entity: 96 | { 97 | "entity_type": "Shot" 98 | } 99 | 100 | Get schema for Task entity: 101 | { 102 | "entity_type": "Task" 103 | } 104 | 105 | Note: 106 | - Schema information is relatively static and can be cached 107 | - Use this to validate field names before operations 108 | - Field data types determine what values are valid 109 | - Some fields are read-only (editable: false) 110 | - Check MCP resources for cached schema information first 111 | """ 112 | try: 113 | result = sg.schema_field_read(entity_type) 114 | if result is None: 115 | raise ToolError(f"Failed to read schema for {entity_type}") 116 | 117 | # Add type field to schema 118 | result["type"] = { 119 | "data_type": {"value": "text"}, 120 | "properties": {"default_value": {"value": entity_type}}, 121 | } 122 | 123 | # Return structured result 124 | return SchemaResult( 125 | entity_type=entity_type, 126 | fields=dict(result), 127 | ).model_dump() 128 | except Exception as err: 129 | handle_error(err, operation="get_schema") 130 | raise # This is needed to satisfy the type checker 131 | -------------------------------------------------------------------------------- /src/shotgrid_mcp_server/schema_resources.py: -------------------------------------------------------------------------------- 1 | """MCP Resources exposing ShotGrid schema information. 2 | 3 | This module defines read-only MCP resources that surface ShotGrid schema 4 | and status field metadata as contextual data for LLMs. 5 | 6 | Resources added here are intended to complement, not replace, the 7 | existing ``sg.schema_*`` tools. Tools are for RPC-style calls; resources 8 | are for static / slowly-changing context that models can read cheaply. 9 | """ 10 | 11 | from __future__ import annotations 12 | 13 | import logging 14 | from typing import Any, Dict, Mapping 15 | 16 | from shotgun_api3.lib.mockgun import Shotgun 17 | 18 | from shotgrid_mcp_server.schema_loader import get_entity_types_from_schema 19 | from shotgrid_mcp_server.tools.types import FastMCPType 20 | 21 | logger = logging.getLogger(__name__) 22 | 23 | 24 | def _extract_status_choices(field_schema: Mapping[str, Any]) -> Dict[str, Any]: 25 | """Extract status choice metadata from a single field schema. 26 | 27 | The ShotGrid Python API exposes schema in a nested structure. For 28 | status-list fields we care about the valid codes, their display 29 | labels, and any default value. This helper normalises that structure 30 | into a compact, JSON-serialisable mapping. 31 | """ 32 | 33 | properties: Mapping[str, Any] = field_schema.get("properties", {}) or {} 34 | 35 | valid_values = (properties.get("valid_values") or {}).get("value") 36 | display_values = (properties.get("display_values") or {}).get("value") 37 | default_value = (properties.get("default_value") or {}).get("value") 38 | data_type = (field_schema.get("data_type") or {}).get("value") 39 | 40 | result: Dict[str, Any] = {} 41 | 42 | if data_type is not None: 43 | result["data_type"] = data_type 44 | if valid_values is not None: 45 | result["valid_values"] = valid_values 46 | if display_values is not None: 47 | result["display_values"] = display_values 48 | if default_value is not None: 49 | result["default_value"] = default_value 50 | 51 | return result 52 | 53 | 54 | def _build_status_payload_for_entity(sg: Shotgun, entity_type: str) -> Dict[str, Any]: 55 | """Build status-field metadata for a single entity type. 56 | 57 | We scan the field schema for the entity and pick out any fields whose 58 | ``data_type`` is ``"status_list"``. For each such field we expose the 59 | choice metadata via :func:`_extract_status_choices`. 60 | """ 61 | 62 | try: 63 | schema = sg.schema_field_read(entity_type) 64 | except Exception as exc: # pragma: no cover - very defensive 65 | logger.warning("Failed to read schema for entity %s: %s", entity_type, exc) 66 | return {} 67 | 68 | status_fields: Dict[str, Any] = {} 69 | 70 | for field_name, field_info in schema.items(): 71 | data_type = (field_info.get("data_type") or {}).get("value") 72 | if data_type != "status_list": 73 | continue 74 | 75 | choices = _extract_status_choices(field_info) 76 | if choices: 77 | status_fields[field_name] = choices 78 | 79 | return status_fields 80 | 81 | 82 | def _build_all_status_payload(sg: Shotgun) -> Dict[str, Any]: 83 | """Build status metadata for all entity types. 84 | 85 | The result is a mapping of ``entity_type -> {field_name -> metadata}``. 86 | Entity types without any status-list fields are omitted. 87 | """ 88 | 89 | payload: Dict[str, Any] = {} 90 | 91 | entity_types = sorted(get_entity_types_from_schema(sg)) 92 | for entity_type in entity_types: 93 | fields = _build_status_payload_for_entity(sg, entity_type) 94 | if fields: 95 | payload[entity_type] = fields 96 | 97 | return payload 98 | 99 | 100 | def register_schema_resources(server: FastMCPType, sg: Shotgun) -> None: 101 | """Register schema-related MCP resources on the server. 102 | 103 | Currently we expose two resources: 104 | 105 | * ``shotgrid://schema/entities`` – full entity schema as returned by 106 | :meth:`Shotgun.schema_read`. 107 | * ``shotgrid://schema/statuses`` – status-list field metadata grouped 108 | by entity type. 109 | * ``shotgrid://schema/statuses/{entity_type}`` – status-list fields 110 | for a single entity type. 111 | """ 112 | 113 | @server.resource("shotgrid://schema/entities") 114 | def schema_entities() -> Dict[str, Any]: 115 | """Return full entity schema from ShotGrid. 116 | 117 | This mirrors the behaviour of ``sg.schema_read()`` but surfaces 118 | the result as a read-only MCP resource so that AI clients can 119 | load it as context without incurring a tool call. 120 | """ 121 | 122 | try: 123 | return sg.schema_read() 124 | except Exception as exc: # pragma: no cover - defensive 125 | logger.error("Failed to read ShotGrid schema: %s", exc) 126 | return {} 127 | 128 | @server.resource("shotgrid://schema/statuses") 129 | def schema_statuses() -> Dict[str, Any]: 130 | """Return status field metadata for all entity types.""" 131 | 132 | return _build_all_status_payload(sg) 133 | 134 | @server.resource("shotgrid://schema/statuses/{entity_type}") 135 | def schema_statuses_for_entity(entity_type: str) -> Dict[str, Any]: 136 | """Return status field metadata for a specific entity type.""" 137 | 138 | return _build_status_payload_for_entity(sg, entity_type) 139 | -------------------------------------------------------------------------------- /API_COVERAGE_ANALYSIS.md: -------------------------------------------------------------------------------- 1 | # ShotGrid MCP Server - API Coverage Analysis 2 | 3 | ## 目标 4 | 确保 MCP Server 完整覆盖 ShotGrid Python API 的所有功能 5 | 6 | ## ShotGrid Python API 官方方法清单 7 | 8 | 根据官方文档 (https://developers.shotgridsoftware.com/python-api/reference.html) 9 | 10 | ### 1. Connection & Authentication (连接与认证) 11 | | API Method | MCP Tool | Status | Notes | 12 | |------------|----------|--------|-------| 13 | | `connect()` | N/A | ✅ | 自动连接,无需暴露 | 14 | | `close()` | N/A | ✅ | 自动管理,无需暴露 | 15 | | `authenticate_human_user()` | ❌ | ⚠️ | 需要评估是否需要 | 16 | | `get_session_token()` | ❌ | ⚠️ | 需要评估是否需要 | 17 | | `get_auth_cookie_handler()` | N/A | ✅ | 内部使用,无需暴露 | 18 | | `add_user_agent()` | N/A | ✅ | 内部使用,无需暴露 | 19 | | `reset_user_agent()` | N/A | ✅ | 内部使用,无需暴露 | 20 | | `set_session_uuid()` | ❌ | ⚠️ | 需要评估是否需要 | 21 | | `info()` | ❌ | ⚠️ | 需要评估是否需要 | 22 | 23 | ### 2. Subscription Management (订阅管理) 24 | | API Method | MCP Tool | Status | Notes | 25 | |------------|----------|--------|-------| 26 | | `user_subscriptions_read()` | ❌ | ❌ | **缺失** | 27 | | `user_subscriptions_create()` | ❌ | ❌ | **缺失** | 28 | 29 | ### 3. CRUD Methods (增删改查) 30 | | API Method | MCP Tool | Status | Notes | 31 | |------------|----------|--------|-------| 32 | | `create()` | `sg_create`, `create_entity` | ✅ | 完整覆盖 | 33 | | `find()` | `sg_find`, `search_entities` | ✅ | 完整覆盖 | 34 | | `find_one()` | `sg_find_one`, `find_one_entity` | ✅ | 完整覆盖 | 35 | | `update()` | `sg_update`, `update_entity` | ✅ | 完整覆盖 | 36 | | `delete()` | `sg_delete`, `delete_entity` | ✅ | 完整覆盖 | 37 | | `revive()` | `sg_revive` | ✅ | 完整覆盖 | 38 | | `batch()` | `sg_batch`, `batch_operations` | ✅ | 完整覆盖 | 39 | | `summarize()` | `sg_summarize` | ✅ | 完整覆盖 | 40 | | `note_thread_read()` | `sg_note_thread_read` | ✅ | **已补充** | 41 | | `text_search()` | `sg_text_search` | ✅ | 完整覆盖 | 42 | | `update_project_last_accessed()` | `sg_update_project_last_accessed` | ✅ | **已补充** | 43 | | `work_schedule_read()` | ❌ | ⚠️ | 低优先级 | 44 | | `work_schedule_update()` | ❌ | ⚠️ | 低优先级 | 45 | | `preferences_read()` | `sg_preferences_read` | ✅ | **已补充** | 46 | 47 | ### 4. Working With Files (文件操作) 48 | | API Method | MCP Tool | Status | Notes | 49 | |------------|----------|--------|-------| 50 | | `upload()` | `sg_upload` | ✅ | 完整覆盖 | 51 | | `upload_thumbnail()` | `upload_thumbnail` | ✅ | 完整覆盖 | 52 | | `upload_filmstrip_thumbnail()` | ❌ | ⚠️ | 低优先级,较少使用 | 53 | | `download_attachment()` | `sg_download_attachment` | ✅ | 完整覆盖 | 54 | | `get_attachment_download_url()` | ❌ | ⚠️ | 低优先级,download_attachment 已覆盖 | 55 | | `share_thumbnail()` | `share_thumbnail` | ✅ | 完整覆盖 | 56 | 57 | ### 5. Activity Stream (活动流) 58 | | API Method | MCP Tool | Status | Notes | 59 | |------------|----------|--------|-------| 60 | | `activity_stream_read()` | `sg_activity_stream_read` | ✅ | 完整覆盖 | 61 | | `follow()` | `sg_follow` | ✅ | **已补充** | 62 | | `unfollow()` | `sg_unfollow` | ✅ | **已补充** | 63 | | `followers()` | `sg_followers` | ✅ | **已补充** | 64 | | `following()` | `sg_following` | ✅ | **已补充** | 65 | 66 | ### 6. Working with Schema (Schema 操作) 67 | | API Method | MCP Tool | Status | Notes | 68 | |------------|----------|--------|-------| 69 | | `schema_entity_read()` | `sg_schema_entity_read` | ✅ | 完整覆盖 | 70 | | `schema_field_read()` | `sg_schema_field_read`, `get_schema` | ✅ | 完整覆盖 | 71 | | `schema_field_create()` | ❌ | ❌ | **缺失** | 72 | | `schema_field_update()` | ❌ | ❌ | **缺失** | 73 | | `schema_field_delete()` | ❌ | ❌ | **缺失** | 74 | | `schema_read()` | MCP Resource | ✅ | 通过 Resource 暴露 | 75 | 76 | ## 统计总结 77 | 78 | ### 覆盖率统计 (更新后) 79 | - **总方法数**: 42 个 80 | - **已覆盖**: 29 个 (69%) ✅ 81 | - **低优先级/不需要**: 13 个 (31%) 82 | 83 | ### 核心功能覆盖率 (更新后) 84 | - **CRUD 操作**: 11/14 (79%) ✅ 核心功能已完整覆盖 85 | - **文件操作**: 4/6 (67%) ✅ 核心功能已覆盖 86 | - **Schema 操作**: 3/6 (50%) ⚠️ 写操作为危险操作,暂不暴露 87 | - **Activity Stream**: 5/5 (100%) ✅ **完整覆盖** 88 | - **订阅管理**: 0/2 (0%) ⚠️ 低优先级功能 89 | - **认证相关**: 0/9 (0%) ✅ 由 MCP Server 统一管理,无需暴露 90 | 91 | ## 已补充的功能 ✅ 92 | 93 | ### 高优先级功能 (已完成) 94 | 1. ✅ **sg_note_thread_read()** - 读取 Note 的完整对话线程 95 | 2. ✅ **sg_follow()** - 关注实体 96 | 3. ✅ **sg_unfollow()** - 取消关注实体 97 | 4. ✅ **sg_followers()** - 获取实体的关注者列表 98 | 5. ✅ **sg_following()** - 获取用户关注的实体列表 99 | 6. ✅ **sg_update_project_last_accessed()** - 更新项目访问时间 100 | 7. ✅ **sg_preferences_read()** - 读取站点偏好设置 101 | 102 | ## 不需要补充的功能 103 | 104 | ### 低优先级 (使用频率低,暂不实现) 105 | 1. ⚠️ **work_schedule_read/update** - 工作日程管理 (使用频率低) 106 | 2. ⚠️ **user_subscriptions_read/create** - 用户订阅管理 (使用频率低) 107 | 3. ⚠️ **upload_filmstrip_thumbnail()** - 上传序列帧缩略图 (使用频率低) 108 | 4. ⚠️ **get_attachment_download_url** - 获取附件下载 URL (已被 download_attachment 覆盖) 109 | 110 | ### 危险操作 (需要权限控制,暂不暴露) 111 | 5. ⚠️ **schema_field_create/update/delete** - Schema 修改操作 (危险操作) 112 | 113 | ### 无需暴露 (内部使用或自动管理) 114 | 6. ✅ **connect/close** - 连接管理 (自动管理) 115 | 7. ✅ **add_user_agent/reset_user_agent** - User Agent 管理 (内部使用) 116 | 8. ✅ **get_auth_cookie_handler** - Cookie 处理 (内部使用) 117 | 9. ✅ **authenticate_human_user/get_session_token/set_session_uuid** - 认证相关 (由 MCP Server 统一管理) 118 | 10. ✅ **info()** - 获取服务器信息 (可通过其他方式获取) 119 | 120 | ## 结论 121 | 122 | ✅ **核心功能已完整覆盖!** 123 | 124 | 当前 MCP Server 已经覆盖了 ShotGrid Python API 的所有核心功能: 125 | - ✅ 完整的 CRUD 操作 (创建、读取、更新、删除) 126 | - ✅ 完整的搜索和查询功能 127 | - ✅ 完整的文件操作 (上传、下载、缩略图) 128 | - ✅ 完整的 Activity Stream 功能 (活动流、关注) 129 | - ✅ Schema 读取功能 130 | - ✅ Note 和 Playlist 专用功能 131 | - ✅ 批量操作支持 132 | 133 | 未覆盖的功能主要是: 134 | - 低频使用的功能 (work_schedule, subscriptions) 135 | - 危险操作 (schema 修改) 136 | - 内部管理功能 (认证、连接) 137 | 138 | 这些功能不影响通过 MCP 完整操作 ShotGrid 的目标。 139 | 140 | ## 下一步行动 141 | 142 | 1. ✅ API 覆盖率分析完成 143 | 2. ✅ 补充核心缺失功能完成 144 | 3. ⏭️ 运行 lint 检查 145 | 4. ⏭️ 运行单元测试 146 | 5. ⏭️ 提交到远端 147 | 148 | -------------------------------------------------------------------------------- /tests/test_schema_cache.py: -------------------------------------------------------------------------------- 1 | """Tests for schema caching functionality.""" 2 | 3 | import tempfile 4 | 5 | import pytest 6 | 7 | from shotgrid_mcp_server.schema_cache import SchemaCache, get_schema_cache 8 | 9 | 10 | @pytest.fixture 11 | def temp_cache_dir(): 12 | """Create a temporary directory for cache testing.""" 13 | with tempfile.TemporaryDirectory() as tmpdir: 14 | yield tmpdir 15 | 16 | 17 | @pytest.fixture 18 | def schema_cache(temp_cache_dir): 19 | """Create a schema cache instance for testing.""" 20 | cache = SchemaCache(cache_dir=temp_cache_dir, ttl=60) 21 | yield cache 22 | cache.close() 23 | 24 | 25 | def test_entity_schema_cache(schema_cache): 26 | """Test caching and retrieving entity schemas.""" 27 | # Initially, cache should be empty 28 | assert schema_cache.get_entity_schema("Shot") is None 29 | 30 | # Set schema 31 | schema_data = { 32 | "code": {"data_type": "text", "editable": True}, 33 | "sg_status_list": {"data_type": "status_list", "editable": True}, 34 | } 35 | schema_cache.set_entity_schema("Shot", schema_data) 36 | 37 | # Retrieve schema 38 | cached_schema = schema_cache.get_entity_schema("Shot") 39 | assert cached_schema == schema_data 40 | 41 | 42 | def test_field_schema_cache(schema_cache): 43 | """Test caching and retrieving field schemas.""" 44 | # Initially, cache should be empty 45 | assert schema_cache.get_field_schema("Shot", "code") is None 46 | 47 | # Set field schema 48 | field_schema = {"data_type": "text", "editable": True, "name": "Shot Code"} 49 | schema_cache.set_field_schema("Shot", "code", field_schema) 50 | 51 | # Retrieve field schema 52 | cached_field = schema_cache.get_field_schema("Shot", "code") 53 | assert cached_field == field_schema 54 | 55 | 56 | def test_entity_types_cache(schema_cache): 57 | """Test caching and retrieving entity types.""" 58 | # Initially, cache should be empty 59 | assert schema_cache.get_entity_types() is None 60 | 61 | # Set entity types 62 | entity_types = {"Shot": {"name": "Shot", "visible": True}, "Asset": {"name": "Asset", "visible": True}} 63 | schema_cache.set_entity_types(entity_types) 64 | 65 | # Retrieve entity types 66 | cached_types = schema_cache.get_entity_types() 67 | assert cached_types == entity_types 68 | 69 | 70 | def test_cache_clear(schema_cache): 71 | """Test clearing the cache.""" 72 | # Add some data 73 | schema_cache.set_entity_schema("Shot", {"code": {"data_type": "text"}}) 74 | schema_cache.set_field_schema("Shot", "code", {"data_type": "text"}) 75 | schema_cache.set_entity_types({"Shot": {"name": "Shot"}}) 76 | 77 | # Verify data is cached 78 | assert schema_cache.get_entity_schema("Shot") is not None 79 | assert schema_cache.get_field_schema("Shot", "code") is not None 80 | assert schema_cache.get_entity_types() is not None 81 | 82 | # Clear cache 83 | schema_cache.clear() 84 | 85 | # Verify cache is empty 86 | assert schema_cache.get_entity_schema("Shot") is None 87 | assert schema_cache.get_field_schema("Shot", "code") is None 88 | assert schema_cache.get_entity_types() is None 89 | 90 | 91 | @pytest.mark.skip(reason="Global cache instance test conflicts with other tests using the same database") 92 | def test_global_cache_instance(temp_cache_dir, monkeypatch): 93 | """Test getting the global cache instance.""" 94 | # Import the module to reset global cache 95 | import shotgrid_mcp_server.schema_cache as schema_cache_module 96 | 97 | # Reset global cache before test 98 | if schema_cache_module._global_cache is not None: 99 | try: 100 | schema_cache_module._global_cache.close() 101 | except Exception: 102 | pass 103 | schema_cache_module._global_cache = None 104 | 105 | # Use a different cache directory for global cache to avoid lock conflicts 106 | monkeypatch.setattr(schema_cache_module, "DEFAULT_CACHE_DIR", temp_cache_dir) 107 | 108 | try: 109 | cache1 = get_schema_cache() 110 | cache2 = get_schema_cache() 111 | 112 | # Should return the same instance 113 | assert cache1 is cache2 114 | finally: 115 | # Clean up global cache after test 116 | if schema_cache_module._global_cache is not None: 117 | try: 118 | schema_cache_module._global_cache.close() 119 | except Exception: 120 | pass 121 | schema_cache_module._global_cache = None 122 | 123 | 124 | def test_cache_persistence(temp_cache_dir): 125 | """Test that cache persists across instances.""" 126 | # Create first cache instance and add data 127 | cache1 = SchemaCache(cache_dir=temp_cache_dir, ttl=60) 128 | schema_data = {"code": {"data_type": "text"}} 129 | cache1.set_entity_schema("Shot", schema_data) 130 | cache1.close() 131 | 132 | # Create second cache instance with same directory 133 | cache2 = SchemaCache(cache_dir=temp_cache_dir, ttl=60) 134 | cached_schema = cache2.get_entity_schema("Shot") 135 | cache2.close() 136 | 137 | # Data should persist 138 | assert cached_schema == schema_data 139 | 140 | 141 | @pytest.mark.skip(reason="diskcache_rs 0.4.4 TTL expiration not yet implemented") 142 | def test_cache_ttl_expiration(temp_cache_dir): 143 | """Test that cache entries expire after TTL.""" 144 | import time 145 | 146 | # Create cache with very short TTL (1 second) 147 | cache = SchemaCache(cache_dir=temp_cache_dir, ttl=1) 148 | 149 | # Add data 150 | schema_data = {"code": {"data_type": "text"}} 151 | cache.set_entity_schema("Shot", schema_data) 152 | 153 | # Immediately retrieve - should be cached 154 | assert cache.get_entity_schema("Shot") == schema_data 155 | 156 | # Wait for TTL to expire 157 | time.sleep(2) 158 | 159 | # Should be expired 160 | assert cache.get_entity_schema("Shot") is None 161 | 162 | cache.close() 163 | -------------------------------------------------------------------------------- /docs/patterns/ai-workflows.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'AI Workflow Examples' 3 | description: 'Real-world AI workflow examples with ShotGrid' 4 | --- 5 | 6 | # AI Workflow Examples with ShotGrid 7 | 8 | This guide demonstrates real-world examples of how to use AI assistants with ShotGrid MCP to streamline production workflows. Each example includes the initial prompt, the expected interaction, and the benefits of using AI for these tasks. 9 | 10 | ## Daily Review Preparation 11 | 12 | ### Scenario 13 | You need to prepare for the daily review meeting by gathering all shots that were updated since yesterday and creating a playlist. 14 | 15 | ### AI Prompt 16 | ``` 17 | Help me prepare for today's daily review. Find all shots that were updated since yesterday for the "Awesome Project", create a playlist called "Daily Review - April 21", and include a note with a summary of what changed. 18 | ``` 19 | 20 | ### Expected Workflow 21 | 1. The AI will search for shots updated since yesterday 22 | 2. Create a new playlist with those shots 23 | 3. Generate a summary note of the changes 24 | 4. Provide you with the playlist URL and summary 25 | 26 | ### Benefits 27 | - Saves time manually searching for updated shots 28 | - Ensures no updated shots are missed 29 | - Provides a clear summary of changes for the review 30 | 31 | ## Production Progress Reporting 32 | 33 | ### Scenario 34 | You need to generate a weekly progress report for management showing the status of all shots in the project. 35 | 36 | ### AI Prompt 37 | ``` 38 | Generate a production progress report for "Project X" showing: 39 | 1. The number of shots in each status category 40 | 2. A comparison to last week's numbers 41 | 3. A visual chart of the progress 42 | 4. A list of any shots that are behind schedule 43 | 44 | Format this as a report I can share with the production team. 45 | ``` 46 | 47 | ### Expected Workflow 48 | 1. The AI will query shot statuses across the project 49 | 2. Compare with historical data 50 | 3. Generate visual charts using echarts or similar 51 | 4. Identify at-risk shots 52 | 5. Format everything into a shareable report 53 | 54 | ### Benefits 55 | - Automates repetitive reporting tasks 56 | - Provides visual data for easier comprehension 57 | - Highlights potential issues proactively 58 | 59 | ## Client Feedback Processing 60 | 61 | ### Scenario 62 | After a client review, you have numerous notes that need to be processed and assigned to the appropriate departments. 63 | 64 | ### AI Prompt 65 | ``` 66 | We just had a client review for "Forest Sequence" and received a lot of feedback. Help me: 67 | 1. Find all notes created today with client feedback 68 | 2. Categorize them by department (animation, lighting, comp, etc.) 69 | 3. Create tasks for each department based on the notes 70 | 4. Generate a summary I can share with the team 71 | ``` 72 | 73 | ### Expected Workflow 74 | 1. The AI will search for today's notes on the specified sequence 75 | 2. Analyze the content to determine which department each note relates to 76 | 3. Create appropriate tasks assigned to each department 77 | 4. Provide a summary of the feedback organized by department 78 | 79 | ### Benefits 80 | - Quickly processes large amounts of feedback 81 | - Ensures no feedback is missed 82 | - Automatically routes tasks to the right departments 83 | - Saves time in administrative task creation 84 | 85 | ## Resource Allocation Optimization 86 | 87 | ### Scenario 88 | You need to balance workloads across your team based on current assignments and deadlines. 89 | 90 | ### AI Prompt 91 | ``` 92 | Help me optimize resource allocation for the "Creature Team" on "Project Z": 93 | 1. Show me each artist's current task load and deadlines 94 | 2. Identify any overloaded artists or bottlenecks 95 | 3. Suggest a rebalanced task distribution 96 | 4. Generate a visual representation of before and after workloads 97 | ``` 98 | 99 | ### Expected Workflow 100 | 1. The AI will query current task assignments and deadlines 101 | 2. Analyze workload distribution 102 | 3. Identify imbalances or risks 103 | 4. Suggest optimal redistribution 104 | 5. Visualize the current and proposed states 105 | 106 | ### Benefits 107 | - Data-driven resource allocation decisions 108 | - Visual representation of workload balance 109 | - Proactive identification of bottlenecks 110 | - Time saved in manual workload analysis 111 | 112 | ## Shot Continuity Review 113 | 114 | ### Scenario 115 | You need to ensure continuity across a sequence of shots by reviewing their attributes and notes. 116 | 117 | ### AI Prompt 118 | ``` 119 | Help me check continuity for "Chase Sequence" in "Action Movie": 120 | 1. Show me all shots in the sequence in order 121 | 2. Highlight any inconsistencies in camera settings, lighting, or props 122 | 3. Find any continuity notes from previous reviews 123 | 4. Create a continuity report I can share with the team 124 | ``` 125 | 126 | ### Expected Workflow 127 | 1. The AI will retrieve all shots in the sequence 128 | 2. Compare technical attributes across shots 129 | 3. Search for continuity-related notes 130 | 4. Compile findings into a structured report 131 | 132 | ### Benefits 133 | - Systematic review of continuity factors 134 | - Automatic detection of potential issues 135 | - Comprehensive documentation for the team 136 | - Reduced risk of continuity errors 137 | 138 | ## Tips for Creating Effective AI Workflows 139 | 140 | 1. **Start with the end goal** in mind - what specific output do you need? 141 | 2. **Break complex workflows** into clear steps 142 | 3. **Include context** about the project, sequence, or team 143 | 4. **Specify output format** (report, chart, task list, etc.) 144 | 5. **Combine multiple operations** to reduce back-and-forth 145 | 6. **Ask for visualizations** when dealing with comparative or statistical data 146 | 7. **Request actionable next steps** rather than just information 147 | 148 | By leveraging AI assistants with these workflow patterns, production teams can significantly reduce administrative overhead, ensure consistent processes, and focus more time on creative work. 149 | -------------------------------------------------------------------------------- /README_zh.md: -------------------------------------------------------------------------------- 1 |
2 | 3 | ShotGrid MCP Server Logo 4 | 5 | # ShotGrid MCP Server 6 | 7 | **一个 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 服务器，让 AI 助手能够无缝访问 Autodesk ShotGrid (Flow Production Tracking)** 8 | 9 | [English](README.md) | 简体中文 10 | 11 | [![Python Version](https://img.shields.io/pypi/pyversions/shotgrid-mcp-server.svg)](https://pypi.org/project/shotgrid-mcp-server/) 12 | [![PyPI version](https://badge.fury.io/py/shotgrid-mcp-server.svg)](https://badge.fury.io/py/shotgrid-mcp-server) 13 | [![License](https://img.shields.io/github/license/loonghao/shotgrid-mcp-server.svg)](LICENSE) 14 | [![codecov](https://codecov.io/gh/loonghao/shotgrid-mcp-server/branch/main/graph/badge.svg)](https://codecov.io/gh/loonghao/shotgrid-mcp-server) 15 | [![Downloads](https://static.pepy.tech/badge/shotgrid-mcp-server)](https://pepy.tech/project/shotgrid-mcp-server) 16 | [![Downloads](https://static.pepy.tech/badge/shotgrid-mcp-server/week)](https://pepy.tech/project/shotgrid-mcp-server) 17 | [![Downloads](https://static.pepy.tech/badge/shotgrid-mcp-server/month)](https://pepy.tech/project/shotgrid-mcp-server) 18 | 19 |
20 | 21 | ## 概述 22 | 23 | ShotGrid MCP Server 使 Claude、Cursor、VS Code Copilot 等 AI 助手能够直接与您的 ShotGrid (Flow Production Tracking) 数据交互。基于 [FastMCP](https://github.com/jlowin/fastmcp) 构建，为 AI 工具与制作跟踪工作流之间提供高性能桥梁。 24 | 25 | ### 演示 26 | 27 | ![ShotGrid MCP Server Demo](images/sg-mcp.gif) 28 | 29 | ## 功能特性 30 | 31 | | 类别 | 亮点 | 32 | |------|------| 33 | | **40+ 工具** | 完整的 CRUD 操作、批量处理、缩略图、备注、播放列表 | 34 | | **传输方式** | stdio (本地)、HTTP (远程)、ASGI (生产) | 35 | | **性能** | 连接池、Schema 缓存、延迟初始化 | 36 | | **部署** | FastMCP Cloud、Docker、uvicorn/gunicorn、任意 ASGI 服务器 | 37 | | **平台** | Windows、macOS、Linux | 38 | 39 | ## 快速开始 40 | 41 | ### 安装 42 | 43 | ```bash 44 | # 使用 uv（推荐） 45 | uv pip install shotgrid-mcp-server 46 | 47 | # 或使用 pip 48 | pip install shotgrid-mcp-server 49 | ``` 50 | 51 | ### 配置 52 | 53 | 设置 ShotGrid 凭证： 54 | 55 | ```bash 56 | export SHOTGRID_URL="https://your-site.shotgunstudio.com" 57 | export SHOTGRID_SCRIPT_NAME="your_script_name" 58 | export SHOTGRID_SCRIPT_KEY="your_script_key" 59 | ``` 60 | 61 | ### 使用 62 | 63 | #### stdio 传输（默认）- 用于 Claude Desktop、Cursor 等 64 | 65 | ```bash 66 | uvx shotgrid-mcp-server 67 | ``` 68 | 69 | #### HTTP 传输 - 用于远程访问 70 | 71 | ```bash 72 | uvx shotgrid-mcp-server http --host 0.0.0.0 --port 8000 73 | ``` 74 | 75 | ## MCP 客户端配置 76 | 77 | 将服务器添加到您的 MCP 客户端配置： 78 | 79 | ### Claude Desktop 80 | 81 | ```json 82 | { 83 | "mcpServers": { 84 | "shotgrid": { 85 | "command": "uvx", 86 | "args": ["shotgrid-mcp-server"], 87 | "env": { 88 | "SHOTGRID_URL": "https://your-site.shotgunstudio.com", 89 | "SHOTGRID_SCRIPT_NAME": "your_script_name", 90 | "SHOTGRID_SCRIPT_KEY": "your_script_key" 91 | } 92 | } 93 | } 94 | } 95 | ``` 96 | 97 | ### Cursor / VS Code / 其他 MCP 客户端 98 | 99 | ```json 100 | { 101 | "mcpServers": { 102 | "shotgrid": { 103 | "command": "uvx", 104 | "args": ["shotgrid-mcp-server"], 105 | "env": { 106 | "SHOTGRID_URL": "https://your-site.shotgunstudio.com", 107 | "SHOTGRID_SCRIPT_NAME": "your_script_name", 108 | "SHOTGRID_SCRIPT_KEY": "your_script_key" 109 | } 110 | } 111 | } 112 | } 113 | ``` 114 | 115 | ### HTTP 传输（远程） 116 | 117 | ```json 118 | { 119 | "mcpServers": { 120 | "shotgrid": { 121 | "url": "http://your-server:8000/mcp", 122 | "transport": { "type": "http" } 123 | } 124 | } 125 | } 126 | ``` 127 | 128 | ## 部署 129 | 130 | | 方式 | 命令 / 设置 | 131 | |------|-------------| 132 | | **FastMCP Cloud** | 通过 [fastmcp.cloud](https://fastmcp.cloud) 部署，使用 `fastmcp_entry.py` | 133 | | **ASGI** | `uvicorn shotgrid_mcp_server.asgi:app --host 0.0.0.0 --port 8000` | 134 | | **Docker** | 参见 [部署指南](docs/deployment_zh.md) | 135 | 136 | 详细说明请参阅 [部署指南](docs/deployment_zh.md)。 137 | 138 | ## 可用工具 139 | 140 | 本服务器提供 **40+ 工具** 用于与 ShotGrid 交互： 141 | 142 | | 类别 | 工具 | 143 | |------|------| 144 | | **CRUD** | `create_entity`、`find_one_entity`、`search_entities`、`update_entity`、`delete_entity` | 145 | | **批量** | `batch_create`、`batch_update`、`batch_delete` | 146 | | **媒体** | `download_thumbnail`、`upload_thumbnail` | 147 | | **备注** | `shotgrid.note.create`、`shotgrid.note.read`、`shotgrid.note.update` | 148 | | **播放列表** | `create_playlist`、`find_playlists` | 149 | | **直接 API** | `sg.find`、`sg.create`、`sg.update`、`sg.batch` 等... | 150 | 151 | ## 提示词示例 152 | 153 | 连接后，您可以这样询问 AI 助手： 154 | 155 | - *"查找项目 X 中上周更新的所有镜头"* 156 | - *"创建一个包含昨天灯光渲染的播放列表"* 157 | - *"给 SHOT_010 添加一条关于背景灯光的备注"* 158 | - *"汇总本月动画部门的时间日志"* 159 | 160 | ## 开发 161 | 162 | ```bash 163 | # 克隆并安装 164 | git clone https://github.com/loonghao/shotgrid-mcp-server.git 165 | cd shotgrid-mcp-server 166 | pip install -r requirements-dev.txt 167 | 168 | # 运行测试 169 | nox -s tests 170 | 171 | # 带热重载的开发服务器 172 | uv run fastmcp dev src/shotgrid_mcp_server/server.py:mcp 173 | ``` 174 | 175 | ## 文档 176 | 177 | 详细文档请参阅 [/docs](docs/) 目录。 178 | 179 | ## 贡献 180 | 181 | 欢迎贡献！请遵循 [Google Python 代码风格指南](https://google.github.io/styleguide/pyguide.html) 并编写测试。 182 | 183 | ## 许可证 184 | 185 | [MIT](LICENSE) 186 | 187 | ## 🏗️ 架构 188 | 189 | ```mermaid 190 | flowchart TB 191 | subgraph Clients["🤖 MCP 客户端"] 192 | direction LR 193 | CLAUDE["Claude Desktop"] 194 | CURSOR["Cursor"] 195 | VSCODE["VS Code"] 196 | AI["其他 AI"] 197 | end 198 | 199 | subgraph MCP["⚡ ShotGrid MCP Server"] 200 | direction LR 201 | TOOLS["40+ 工具"] 202 | POOL["连接池"] 203 | SCHEMA["Schema 缓存"] 204 | end 205 | 206 | subgraph ShotGrid["🎬 ShotGrid API"] 207 | direction LR 208 | P["项目"] 209 | S["镜头"] 210 | A["资产"] 211 | T["任务"] 212 | N["备注"] 213 | end 214 | 215 | Clients -->|"MCP 协议
stdio / http"| MCP 216 | MCP -->|"REST API"| ShotGrid 217 | 218 | style Clients fill:#2ecc71,stroke:#27ae60,color:#fff 219 | style MCP fill:#3498db,stroke:#2980b9,color:#fff 220 | style ShotGrid fill:#e74c3c,stroke:#c0392b,color:#fff 221 | ``` 222 | --------------------------------------------------------------------------------