From 8321db6adfb555b4fc43144832c874e7f32a3ad4 Mon Sep 17 00:00:00 2001 From: host Date: Fri, 28 Aug 2026 17:47:13 +0300 Subject: [PATCH] Add deploy instructions (TrueNAS SCALE + Dockge build-context caveat) --- README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c01976e --- /dev/null +++ b/README.md @@ -0,0 +1,55 @@ +## truenas-mcp + +MCP-сервер для управления TrueNAS через AI-ассистентов, завёрнутый через mcpo +в OpenAPI-совместимый HTTP-сервис. Внутри используется пакет truenas-mcp-server (PyPI). + +Официальный Go-бинарник truenas/truenas-mcp в Docker на TrueNAS SCALE не запустился +(ошибка exec format error / ENOEXEC) - поэтому используется этот вариант на Python. + +### Важно: особенность сборки на TrueNAS SCALE + Dockge + +Docker-сервис на TrueNAS SCALE не всегда видит файлы, положенные в папку стека +после её создания в Dockge. Если положить Dockerfile заранее не в ту папку - +получишь ошибку "unable to prepare context: path ... not found", даже если путь +физически существует. + +Правильный порядок: + +1. В Dockge: "+ Compose" -> вставить compose.yaml из этого репозитория -> Save + (пока НЕ Deploy). +2. Найти физическую папку стека на диске - обычно + /mnt/pool/apps/dockge/stacks/имя_стека/ +3. Скопировать в эту папку Dockerfile и config.json из этого репозитория. +4. Создать в этой же папке .env (см. .env.example) со своим реальным API-ключом + TrueNAS. +5. Только теперь нажать Deploy в Dockge. + +### Файлы + +- compose.yaml - конфигурация сервиса (порт 8814:8000) +- Dockerfile - собирает образ на python:3.11-slim, ставит mcpo и truenas-mcp-server +- config.json - регистрирует truenas-mcp-server как stdio MCP-сервер для mcpo +- .env.example - шаблон; реальный .env с ключом никогда не коммитить + +### Переменные окружения + +TRUENAS_API_KEY (в .env) - API-ключ TrueNAS +TRUENAS_URL - URL TrueNAS, например http://192.168.31.100 +TRUENAS_VERIFY_SSL - false для самоподписанного сертификата +TRUENAS_ENABLE_DESTRUCTIVE_OPS - false блокирует разрушительные операции +TRUENAS_LOG_LEVEL - уровень логирования, например INFO + +### Проверка после деплоя + +docker logs truenas-mcp --tail 15 + +Должно быть: Successfully connected to: truenas / Uvicorn running on http://0.0.0.0:8000 + +### Подключение клиентов + +- OpenAPI-схема: http://truenas-ip:8814/openapi.json +- Документация в браузере: http://truenas-ip:8814/docs +- Open WebUI: Admin Panel -> Settings -> External Tools -> Type: OpenAPI -> URL выше. +- Claude Desktop: сервис отдаёт OpenAPI, а не MCP Streamable HTTP - Custom Connectors + не примет его напрямую. Для Claude Desktop используется локальный запуск того же + truenas-mcp-server через uvx в claude_desktop_config.json.