# Tool Reference This document describes all MCP tools provided by mcp-synology-container. Tools marked **confirmation required** will return a description of the action and ask you to call the tool again with `confirmed=True` before executing. This prevents accidental destructive operations. --- ## Project Tools ### `list_projects` List all Container Manager projects with their current status. **Parameters:** none **Returns:** Formatted table with project name, status, path, and container count. **Example output:** ``` Projects: myapp Status: RUNNING Path: /volume1/docker/myapp Containers: 2 database Status: STOPPED Path: /volume1/docker/database Containers: 0 ``` --- ### `get_project_status` Get detailed status of a specific project. **Parameters:** - `project_name` (string, required): Name of the project **Returns:** Detailed status including ID, path, timestamps, container IDs, and services. --- ### `start_project` Start a stopped Container Manager project. **Parameters:** - `project_name` (string, required): Name of the project to start **Returns:** Success or error message. --- ### `stop_project` Stop a running Container Manager project. Stops all containers in the project. **Confirmation required.** **Parameters:** - `project_name` (string, required): Name of the project to stop - `confirmed` (boolean, default `false`): Set to `true` to confirm **Returns:** Confirmation prompt or success message. --- ### `redeploy_project` Redeploy a project by pulling latest images, stopping, and restarting. **Confirmation required.** **Parameters:** - `project_name` (string, required): Name of the project to redeploy - `confirmed` (boolean, default `false`): Set to `true` to confirm **Steps performed:** 1. Pull latest images (`SYNO.Docker.Project` build) 2. Stop all containers 3. Start all containers **Returns:** Confirmation prompt or step-by-step progress output. --- ## Container Tools ### `list_containers` List containers, optionally filtered by project. **Parameters:** - `project_name` (string, optional): Filter by project name. Lists all containers if omitted. **Returns:** Formatted list with container name, status, and image. --- ### `get_container_status` Get detailed status and resource information for a container. **Parameters:** - `container_name` (string, required): Name of the container **Returns:** Status, running state, image, start/stop times, memory limits, and environment variable count. --- ### `get_container_logs` Fetch log output from a container. **Parameters:** - `container_name` (string, required): Name of the container - `tail` (integer, default `100`): Number of recent log lines to return - `keyword` (string, optional): Filter logs to lines containing this keyword **Returns:** Log lines with timestamps and stream tags (stdout/stderr). **Example:** ``` Logs for myapp_web (showing 50 of 312): 2025-01-01T10:00:00Z [stdout] Server started on port 8080 2025-01-01T10:00:01Z [stderr] Warning: deprecated config option ``` --- ### `exec_in_container` Execute a shell command in a running container. **Confirmation required.** **Parameters:** - `container_name` (string, required): Name of the container - `command` (string, required): Shell command to execute - `confirmed` (boolean, default `false`): Set to `true` to confirm **Returns:** Confirmation prompt, or exit code and command output. --- ## Compose File Tools Compose files are accessed via the Synology FileStation API. The server looks for the following filenames under `{compose_base_path}/{project_name}/`: - `docker-compose.yml` - `docker-compose.yaml` - `compose.yml` - `compose.yaml` ### `read_compose` Read the compose file of a project. **Parameters:** - `project_name` (string, required): Name of the project **Returns:** File path and full YAML content. --- ### `update_image_tag` Update the image tag for a service in the compose file. **Confirmation required.** **Parameters:** - `project_name` (string, required): Name of the project - `service_name` (string, required): Name of the service in the compose file - `new_tag` (string, required): New image tag (e.g. `"latest"`, `"1.2.3"`) - `confirmed` (boolean, default `false`): Set to `true` to confirm **Returns:** Confirmation prompt showing before/after, or success message with redeploy suggestion. **Example confirmation prompt:** ``` About to update service 'web' in project 'myapp': Before: nginx:1.24 After: nginx:1.25 Call this tool again with confirmed=True to apply the change. ``` After applying: suggests running `redeploy_project`. --- ### `update_env_var` Add or update an environment variable for a service. **Confirmation required.** **Parameters:** - `project_name` (string, required): Name of the project - `service_name` (string, required): Name of the service - `var_name` (string, required): Environment variable name - `var_value` (string, required): New value - `confirmed` (boolean, default `false`): Set to `true` to confirm Supports both list format (`- KEY=VALUE`) and dict format (`KEY: VALUE`) in the compose file. After applying: suggests running `redeploy_project`. --- ### `update_compose` Replace the entire compose file with new content. **Confirmation required.** **Parameters:** - `project_name` (string, required): Name of the project - `new_content` (string, required): Complete new YAML content (must contain a `services` key) - `confirmed` (boolean, default `false`): Set to `true` to confirm Validates that the content is valid YAML with a `services` key before writing. After applying: suggests running `redeploy_project`. --- ## Image Tools ### `check_image_updates` Check which images have updates available. **Parameters:** - `project_name` (string, optional): Filter to images used by this project. Checks all images if omitted. **Returns:** List of images with update status. Images with the `upgradable` flag from the NAS are highlighted. **Example output:** ``` Image update status for project 'myapp': Updates available (1): nginx:1.24 (50 MiB) ← UPDATE AVAILABLE Up to date (1): postgres:15 (80 MiB) ``` --- ## Confirmation Pattern Tools that modify state require confirmation to prevent accidents. The pattern is: 1. Call the tool without `confirmed`: ``` stop_project(project_name="myapp") ``` Returns a description of what will happen. 2. Call again with `confirmed=True`: ``` stop_project(project_name="myapp", confirmed=True) ``` Executes the operation. This applies to: `stop_project`, `redeploy_project`, `exec_in_container`, `update_image_tag`, `update_env_var`, `update_compose`.