Initial implementation

2026-04-13 14:22:37 +02:00
commit a0c1b6ed93
26 changed files with 4125 additions and 0 deletions
@@ -0,0 +1,274 @@
+# 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`.