Synphony MCP

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview Synphony MCP is a FastMCP server for managing video datasets with Hugging Face Hub integration. The server provides MCP tools for listing videos, validating setup, and uploading video files to Hugging Face datasets repositories. ## Core Architecture ### Single-File Server Pattern The entire MCP server is implemented in `server.py` using the FastMCP framework. All tools are defined as decorated functions within this file. ### Environment-Driven Configuration All configuration is handled through environment variables (loaded via `python-dotenv`): - `SYNPHONY_ROOT_DIR`: Base directory for all video file operations (security boundary) - `HF_TOKEN`: Hugging Face API token for authentication (optional) - `HF_DATASET_REPO_ID`: Target Hugging Face datasets repository (optional) ### Security Model: Path Validation The `_normalize_and_validate_path()` function (server.py:40-46) enforces security boundaries by: 1. Resolving all paths against `SYNPHONY_ROOT_DIR` 2. Preventing path traversal attacks outside ROOT_DIR 3. Normalizing symbolic links and relative paths All tools that accept file paths must use this validator. ## Development Commands ### Running the Server ```bash # Standard run python server.py # With environment variables SYNPHONY_ROOT_DIR=/path/to/videos python server.py ``` ### Testing the Server ```bash # Install dependencies first pip install -r requirements.txt # Test basic functionality python server.py ``` ### Claude Desktop Integration Update `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) with absolute paths and required environment variables as shown in `claude_desktop_config.json`. ## MCP Tools Structure All tools follow this pattern: 1. Decorated with `@mcp.tool` 2. Accept typed parameters with defaults 3. Return `Dict[str, Any]` with consistent structure 4. Handle errors gracefully, returning error info in response dict rather than raising ### Current Tools - `list_videos()`: Recursively lists video files in a directory (server.py:54-111) - `get_server_info()`: Returns server configuration status (server.py:114-132) - `validate_setup()`: Validates environment and dependencies (server.py:135-180) ### Planned Tool (Not Yet Implemented) The README describes an `upload_to_hf_datasets()` tool for uploading videos to Hugging Face, but this is not yet implemented in `server.py`. Implementation should follow the pattern in README.md:131-231. ## Video File Handling Supported extensions defined in `VIDEO_EXTS` (server.py:29-32): `.mp4`, `.mov`, `.mkv`, `.avi`, `.wmv`, `.flv`, `.webm`, `.m4v`, `.mpeg`, `.mpg`, `.3gp`, `.ts` The `_is_video_file()` helper (server.py:49-51) performs case-insensitive extension checking. ## Adding New Tools When adding new MCP tools: 1. Use the `@mcp.tool` decorator 2. Validate file paths with `_normalize_and_validate_path()` 3. Return structured dictionaries with error information 4. Check for required environment variables (HF_TOKEN, etc.) at tool runtime 5. Use `MAX_UPLOAD_BATCH = 50` limit for batch operations 6. Follow existing error handling patterns (no exceptions raised to client) ## Environment Setup Required environment variables must be set before running: ```bash cp .env.example .env # Edit .env with actual values ``` The server will run with partial functionality if optional HF variables are missing (see `validate_setup()` for warnings).