275 lines
6.6 KiB
Markdown
275 lines
6.6 KiB
Markdown
# 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`.
|