# CLAUDE.md — mcp-synology-filestation

Development context for this project.

## Project

`mcp-synology-filestation` — MCP server exposing Synology FileStation as Claude tools.
Sibling project to `mcp-synology-container`.

## Infrastructure

- **NAS:** `https://dsm.gecheckt.de`
- **Config file:** `~/.config/mcp-synology-filestation/config.yaml`
- **Credentials:** OS keyring, service name `mcp-synology-filestation`
- **Gitea:** `https://gitea.gecheckt.de/marcus/mcp-synology-filestation`
- **Local code:** `D:\Dev\Projects\mcp-synology-filestation`
- **Runtime:** Python 3.12+, `uv`, MCP SDK, `httpx`, `keyring`, `click`, `rich`

## Deploy Workflow

1. Commit and push via Claude Code.
2. `uv tool install --reinstall git+https://gitea.gecheckt.de/marcus/mcp-synology-filestation.git`
3. Restart Claude Desktop.

## Toolchain

| Task | Command |
|------|---------|
| Format | `ruff format src/ tests/` |
| Lint | `ruff check src/ tests/` |
| Tests | `pytest` |
| Install dev | `uv sync --dev` |
| Run server | `uv run mcp-synology-filestation serve` |
| Setup | `uv run mcp-synology-filestation setup` |

## Code Standards

- **Type hints** on all public functions and methods.
- **Docstrings** (English) on all public modules, classes, and functions.
- **Async-first:** use `httpx.AsyncClient` throughout; never `requests`.
- **Formatter:** `ruff format` (line length 100).
- **Linter:** `ruff check` — fix all warnings before committing.

## Security Rules

- Never log or write credentials, session IDs, or passwords to disk or stderr.
- Never store passwords in the config YAML — OS keyring only.
- Mask sensitive query parameters (`_sid`, `passwd`) before logging request URLs.

## Destructive Operation Rules

- `delete`, `move` with `overwrite=True`, `copy` with `overwrite=True`, and `upload` with
  `overwrite=True` are considered destructive.
- The `delete` tool MUST require `confirmed=True` to proceed. Without it, return a preview
  message that describes exactly what would be deleted — never silently proceed.
- For overwrite scenarios in `move`/`copy`/`upload`, include a warning in the tool description
  and default `overwrite` to `False`.

## Error Handling Rules

- DSM error codes must be mapped to human-readable messages. See SPEC.md for the full map.
- Never surface raw Python stack traces in tool return values.
- Session expiry (codes 106, 107, 119): transparent single retry with re-login.
- Network errors: return "Cannot reach NAS at {host} — check connectivity."
- Auth failures (400–403): return message + "Run `mcp-synology-filestation setup` to
  reconfigure credentials."

## Tool Return Format

- All tools return `str`.
- Use `rich.table.Table` (rendered to string) for tabular data.
- Include item counts and pagination hints where relevant.
- Error messages are prefixed with `Error:` for easy recognition by Claude.

## Module Structure

```
src/mcp_synology_filestation/
├── __init__.py      # __version__
├── __main__.py      # entry point
├── server.py        # create_server(config, client) → FastMCP
├── client.py        # FileStationClient (async httpx wrapper)
├── auth.py          # AuthManager: keyring, env vars, 2FA, login/logout
├── config.py        # AppConfig, ConnectionConfig, load_config, save_config
├── cli.py           # click: setup / check / serve
└── tools/
    ├── __init__.py
    └── filestation.py  # register_filestation(mcp, config, client)
```

## Implemented Tools

| Tool | Description |
|------|-------------|
| `list_shares` | List all shared folders with volume usage |
| `list_dir` | List directory contents with pagination and sorting |
| `get_info` | Get detailed metadata for one or more paths |

See [SPEC.md](SPEC.md) for the full planned tool set.