Initial implementation

README.md

@@ -0,0 +1,185 @@
+# mcp-synology-container
+
+An MCP (Model Context Protocol) server for managing Docker projects on a Synology NAS via Container Manager. Enables Claude Desktop to list, start, stop, redeploy, and modify Docker Compose projects directly.
+
+## Features
+
+- **Project management**: list, start, stop, redeploy Container Manager projects
+- **Container inspection**: list containers, view status and resource usage, fetch logs
+- **Compose file editing**: read, modify image tags, update env vars, or replace compose files entirely
+- **Image update checks**: see which images have updates available
+- **2FA support**: device token flow for Synology accounts with OTP enabled
+- **OS keyring integration**: credentials stored securely, never in config files
+- **Confirmation required** for all destructive operations (stop, redeploy, exec, compose writes)
+
+## Requirements
+
+- Python 3.12+
+- Synology NAS with DSM 7.x and Container Manager installed
+- `pip` or `uv` for installation
+
+## Installation
+
+```bash
+pip install mcp-synology-container
+```
+
+Or with `uv`:
+
+```bash
+uv tool install mcp-synology-container
+```
+
+## Setup
+
+Run the interactive setup wizard:
+
+```bash
+mcp-synology-container setup
+```
+
+The wizard will:
+1. Ask for your NAS hostname/IP, port, and HTTPS settings
+2. Ask for your DSM username and password
+3. Handle 2FA if enabled (stores device token in OS keyring)
+4. Save the config to `~/.config/mcp-synology-container/config.yaml`
+5. Print the Claude Desktop configuration snippet
+
+### Claude Desktop configuration
+
+Add the snippet to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "synology-container": {
+      "command": "mcp-synology-container",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+## CLI Commands
+
+### `mcp-synology-container setup`
+
+Interactive setup: configure connection and store credentials.
+
+```bash
+mcp-synology-container setup
+mcp-synology-container setup --verbose
+```
+
+### `mcp-synology-container check`
+
+Test the connection and verify all required APIs are available.
+
+```bash
+mcp-synology-container check
+mcp-synology-container check --config /path/to/config.yaml
+```
+
+Exit code 0 = OK, 1 = error.
+
+### `mcp-synology-container serve`
+
+Start the MCP server (used by Claude Desktop).
+
+```bash
+mcp-synology-container serve
+mcp-synology-container serve --config /path/to/config.yaml
+```
+
+## Configuration
+
+Config file: `~/.config/mcp-synology-container/config.yaml`
+
+```yaml
+schema_version: 1
+alias: HomeNAS                        # Optional display name
+connection:
+  host: dsm.example.com
+  port: 443
+  https: true
+  verify_ssl: true
+compose_base_path: /volume1/docker   # Base path for compose projects on NAS
+```
+
+### Environment variable overrides
+
+| Variable | Description |
+|---|---|
+| `SYNOLOGY_HOST` | NAS hostname or IP |
+| `SYNOLOGY_PORT` | DSM port |
+| `SYNOLOGY_HTTPS` | Use HTTPS (true/false) |
+| `SYNOLOGY_VERIFY_SSL` | Verify SSL cert (true/false) |
+| `SYNOLOGY_USERNAME` | DSM username |
+| `SYNOLOGY_PASSWORD` | DSM password |
+
+Credentials from environment variables take priority over the keyring.
+
+## MCP Tools
+
+See [docs/tools.md](docs/tools.md) for the full tool reference.
+
+### Projects
+
+| Tool | Description | Confirmation |
+|---|---|---|
+| `list_projects` | List all Container Manager projects | — |
+| `get_project_status` | Detailed project status | — |
+| `start_project` | Start a project | — |
+| `stop_project` | Stop a project | required |
+| `redeploy_project` | Pull images + restart project | required |
+
+### Containers
+
+| Tool | Description | Confirmation |
+|---|---|---|
+| `list_containers` | List containers (optionally filtered by project) | — |
+| `get_container_status` | Status, uptime, resource limits | — |
+| `get_container_logs` | Fetch container log output | — |
+| `exec_in_container` | Execute command in container | required |
+
+### Compose Files
+
+| Tool | Description | Confirmation |
+|---|---|---|
+| `read_compose` | Read the compose file of a project | — |
+| `update_image_tag` | Update image tag for a service | required |
+| `update_env_var` | Add/update an environment variable | required |
+| `update_compose` | Replace entire compose file | required |
+
+### Images
+
+| Tool | Description | Confirmation |
+|---|---|---|
+| `check_image_updates` | Check for available image updates | — |
+
+## Development
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+python -m pytest tests/ -v
+
+# Lint
+ruff check src/ tests/
+
+# Format
+ruff format src/ tests/
+```
+
+## Security
+
+- Credentials are stored in the OS keyring only (never in config files)
+- All destructive operations require explicit confirmation (`confirmed=True`)
+- HTTPS with certificate verification is enabled by default
+- Session IDs and passwords are never written to stderr logs
+
+## License
+
+MIT