Metadata-Version: 2.4
Name: orange-shotgrid-mcp-server
Version: 0.2.5
Summary: A Model Context Protocol (MCP) server implementation using fastmcp
Project-URL: Homepage, https://github.com/loonghao/shotgrid-mcp-server
Project-URL: Repository, https://github.com/loonghao/shotgrid-mcp-server.git
Project-URL: Issues, https://github.com/loonghao/shotgrid-mcp-server/issues
Project-URL: Changelog, https://github.com/loonghao/shotgrid-mcp-server/blob/main/CHANGELOG.md
Author-email: Hal Long <hal.long@outlook.com>
License: MIT
License-File: LICENSE
Keywords: Flow Production Tracking,api,mcp,server,shotgrid
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.11,>=3.10
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: fastmcp>=0.4.1
Requires-Dist: mcp>=1.2.0
Requires-Dist: platformdirs>=4.1.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: shotgun-api3>=3.5
Requires-Dist: uvicorn>=0.22.0
Provides-Extra: dev
Requires-Dist: black>=23.12.1; extra == 'dev'
Requires-Dist: coverage>=7.4.0; extra == 'dev'
Requires-Dist: flake8>=7.0.0; extra == 'dev'
Requires-Dist: isort>=5.13.2; extra == 'dev'
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: nox>=2023.4.22; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.4; extra == 'dev'
Requires-Dist: ruff>=0.1.11; extra == 'dev'
Requires-Dist: uv>=0.1.12; extra == 'dev'
Provides-Extra: lint
Requires-Dist: black; extra == 'lint'
Requires-Dist: mypy; extra == 'lint'
Requires-Dist: ruff; extra == 'lint'
Requires-Dist: types-requests; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Requires-Dist: pyyaml; extra == 'test'
Description-Content-Type: text/markdown

# ShotGrid MCP Server

English | [简体中文](README_zh.md)

<div align="center">

A high-performance ShotGrid Model Context Protocol (MCP) server implementation based on fastmcp

[![Python Version](https://img.shields.io/pypi/pyversions/shotgrid-mcp-server.svg)](https://pypi.org/project/shotgrid-mcp-server/)
[![License](https://img.shields.io/github/license/loonghao/shotgrid-mcp-server.svg)](LICENSE)
[![PyPI version](https://badge.fury.io/py/shotgrid-mcp-server.svg)](https://badge.fury.io/py/shotgrid-mcp-server)
[![Downloads](https://pepy.tech/badge/shotgrid-mcp-server)](https://pepy.tech/project/shotgrid-mcp-server)

</div>

## ✨ Features

- 🚀 High-performance implementation based on fastmcp
- 🛠 Complete CRUD operation toolset
- 🖼 Dedicated thumbnail download/upload tools
- 🔄 Efficient connection pool management
- ✅ Comprehensive test coverage with pytest
- 📦 Dependency management with UV
- 🌐 Cross-platform support (Windows, macOS, Linux)

## 🚀 Quick Start

### Installation

Install using UV:
```bash
uv pip install shotgrid-mcp-server
```

### Development Setup

1. Clone the repository:
```bash
git clone https://github.com/loonghao/shotgrid-mcp-server.git
cd shotgrid-mcp-server
```

2. Install development dependencies:
```bash
pip install -r requirements-dev.txt
```

3. Development Commands
All development commands are managed through nox. Check `noxfile.py` for available commands:
```bash
# Run tests
nox -s tests

# Run linting
nox -s lint

# Run type checking
nox -s type_check

# And more...
```

## Quick Demo

Here's a simple example of querying entities using the ShotGrid MCP server:

![ShotGrid MCP Server Demo](images/sg-mcp.gif)

## Development

#### Environment Setup

1. Set up environment variables:
```powershell
$env:SHOTGRID_URL='your_shotgrid_url'
$env:SHOTGRID_SCRIPT_NAME='your_script_name'
$env:SHOTGRID_SCRIPT_KEY='your_script_key'
```

2. Run the development server:
```bash
uv run fastmcp dev src\shotgrid_mcp_server\server.py:app
```
The server will start in development mode with hot reloading enabled.

## ⚙️ Configuration

### Environment Variables

Create a `.env` file with the following variables:
```bash
SHOTGRID_URL=your_shotgrid_url
SHOTGRID_SCRIPT_NAME=your_script_name
SHOTGRID_SCRIPT_KEY=your_script_key
```

## 🔧 Available Tools

- `create`: Create ShotGrid entities
- `read`: Read entity information
- `update`: Update entity data
- `delete`: Delete entities
- `download_thumbnail`: Download entity thumbnails
- `upload_thumbnail`: Upload entity thumbnails

## 📚 API Documentation

For detailed API documentation, please refer to the documentation files in the `/docs` directory.

## 🤝 Contributing

Contributions are welcome! Please ensure:

1. Follow Google Python Style Guide
2. Write tests using pytest
3. Update documentation
4. Use absolute imports
5. Follow the project's coding standards

## 📝 Version History

See [CHANGELOG.md](CHANGELOG.md) for detailed version history.

## 📄 License

MIT License - see the [LICENSE](LICENSE) file for details.

## 🔌 MCP Client Configuration

To use the ShotGrid MCP server in your MCP client, add the following configuration to your client's settings:

```json
{
  "mcpServers": {
    "shotgrid-server": {
      "command": "uvx",
      "args": [
        "shotgrid-mcp-server"
      ],
      "env": {
        "SHOTGRID_SCRIPT_NAME": "XXX",
        "SHOTGRID_SCRIPT_KEY": "XX",
        "SHOTGRID_URL": "XXXX"
      },
      "disabled": false,
      "alwaysAllow": [
        "search_entities",
        "create_entity",
        "batch_create",
        "find_entity",
        "get_entity_types",
        "update_entity",
        "download_thumbnail",
        "batch_update",
        "delete_entity",
        "batch_delete"
      ]
    }
  }
}
```

### 🔑 Credentials Setup

Replace the following values with your ShotGrid credentials:
- `SHOTGRID_SCRIPT_NAME`: Your ShotGrid script name
- `SHOTGRID_SCRIPT_KEY`: Your ShotGrid script key
- `SHOTGRID_URL`: Your ShotGrid server URL

### 🛡️ Tool Permissions

The `alwaysAllow` section lists the tools that can be executed without requiring user confirmation. These tools are carefully selected for safe operations.