mcp-synology-container/docs/tools.md

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.