synology-chat-hermes-mcp

English · 繁體中文

Ограниченный HTTP-сервер FastMCP, который предоставляет агентам ИИ фиксированную SMB-папку Synology NAS как инструменты для чтения/записи файлов — со строгой изоляцией путей, ограничениями размера и блокировкой активного контента.

Изначально создан как файловый канал для семейного развёртывания Hermes (управляющий агент → MCP → SMB3 → NAS). Работает с любым MCP-клиентом (Hermes, Claude и т.д.).

Зачем это нужно

Агенты ИИ с доступом к файлам безопасны только в том случае, если доступ ограничен. Этот сервер:

• Изолирует каждый путь до одной фиксированной папки (NAS_SHARE). Обход пути (.., абсолютные пути, symlink/reparse-point escape) отклоняется до любого SMB-вызова.

• Отклоняет публичные WAN-серверы — NAS_SERVER должен быть частным, link-local или Tailscale (100.64.0.0/10) литеральным IP. DNS-имена и публичные IP-адреса не принимаются.

• Никогда не хранит учётные данные — пароль SMB читается из docker secret-файла при запуске (NAS_PASSWORD_FILE), никогда из переменных окружения или кода.

• Блокирует активный контент — генераторы DOCX/XLSX/PDF создают только очищенные документы; бинарные загрузки проверяются на макросы, внешние связи и скрипты; несоответствия расширения и медиатипа отклоняются.

• Ограничивает всё — размер файла, размер бинарного файла, количество символов в документе, ячеек в таблице, пикселей изображения, результаты поиска — всё имеет жёсткие лимиты.

• Аудирует операции — каждое изменение добавляется в JSONL-журнал аудита.

Related MCP server: MCP File System Server

Архитектура

Hermes (or any MCP client)
  → HTTP :8000/mcp (FastMCP, streamable HTTP)
    → NasService (validation, limits, audit)
      → SMBBackend (smbprotocol, SMB3, encryption+signing required)
        → Synology NAS share

Инструменты

Известное ограничение: create_directory проверяет родительский каталог до вызова makedirs, поэтому многоуровневый путь, первый сегмент которого не существует, возвращает not_found даже с parents=True. Создавайте по одному уровню за раз.

Быстрый старт

cp .env.example .env   # set NAS_SERVER (Tailscale/private IP), NAS_USERNAME
# provide the SMB password as a docker secret:
printf '%s' 'YOUR_SMB_PASSWORD' > ./synology_password
chmod 600 ./synology_password

docker build -t nas-mcp .
docker run -d --name nas-mcp \
  --env-file .env \
  -v "$PWD/synology_password:/run/secrets/synology_password:ro" \
  -v nas-mcp-audit:/var/log/nas-mcp \
  -p 8000:8000 \
  nas-mcp

Проверка работоспособности:

curl -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"health","arguments":{}}}'

Конфигурация Hermes MCP

mcp_servers:
  nas-mcp:
    type: http
    url: http://nas-mcp:8000/mcp

Запуск тестов

python -m nas_mcp.smoke   # exercises the full tool chain against the live share

Справочник переменных окружения

Замечания по безопасности

• Пароль SMB — единственный секрет в системе, и он находится только в файле docker secret. Ничего не зашито жёстко, ничего не хранится в .env в открытом виде, кроме несекретных настроечных значений (а .env игнорируется git).

• В продакшене привязывайтесь к частному интерфейсу; не открывайте :8000 публично.

• Имя общего ресурса и пользователь SMB являются конфигурационными (NAS_SHARE, NAS_USERNAME) — задавайте их для каждого развёртывания; в коде не предполагается конкретное значение.

Лицензия

MIT