75 lines
4.3 KiB
Markdown
75 lines
4.3 KiB
Markdown
## truenas-mcp
|
||
|
||
MCP-сервер для управления TrueNAS SCALE через AI-ассистентов, завёрнутый через mcpo
|
||
в OpenAPI-совместимый HTTP-сервис.
|
||
|
||
Используется пакет spranab/truenas-mcp (npm) - 278 действий в 18 категориях
|
||
(system, storage, sharing, network, account, disk, vm, app, update, certificate,
|
||
alert, data_protection, filesystem, reporting, directory, service_config, audit, api)
|
||
через один хешированный эндпоинт /truenas.
|
||
|
||
### История выбора пакета
|
||
|
||
1. Официальный Go-бинарник truenas/truenas-mcp в Docker на TrueNAS SCALE не запустился
|
||
(ошибка exec format error / ENOEXEC).
|
||
2. Python-пакет truenas-mcp-server (vespo92/TrueNasCoreMCP) завёлся, но оказался
|
||
ограничен: только 4 универсальные категории (users, storage, sharing, snapshots),
|
||
без system info и без SCALE-специфичных функций (apps, VM) - автоопределение
|
||
Core/SCALE ошибочно посчитало систему TrueNAS Core.
|
||
3. Итоговый выбор: spranab/truenas-mcp (npm) - полное покрытие 278 действий,
|
||
без проблем автоопределения.
|
||
|
||
### Важно: особенность сборки на TrueNAS SCALE + Dockge
|
||
|
||
Docker-сервис на TrueNAS SCALE может по-разному видеть пути build.context в
|
||
зависимости от того, относительный он или абсолютный (Dockge и docker-демон
|
||
видят файловую систему по-разному). Относительный context: "." иногда не находит
|
||
Dockerfile ("unable to prepare context: path ... not found") - используй абсолютный
|
||
путь на хосте.
|
||
|
||
### Важно: конфликт версий mcp/mcpo
|
||
|
||
mcpo требует mcp>=1.28 (с streamablehttp_client). Если ставить mcpo без явной
|
||
фиксации версии mcp, pip может подтянуть более старую несовместимую версию -
|
||
контейнер падает в рестарт-луп с ImportError. Решение - ставить mcp отдельным
|
||
шагом ДО mcpo (см. Dockerfile).
|
||
|
||
### Файлы
|
||
|
||
- compose.yaml - конфигурация сервиса (порт 8814:8000)
|
||
- Dockerfile - образ на node:20-slim + python3/pip для mcpo, npx для truenas-mcp
|
||
- config.json - регистрирует truenas-mcp (через npx) как 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 40
|
||
|
||
Должно быть: Successfully connected to: truenas / Uvicorn running on http://0.0.0.0:8000
|
||
|
||
### Использование
|
||
|
||
Один эндпоинт POST /truenas принимает {"category": "...", "action": "...", "params": {...}}.
|
||
|
||
Примеры:
|
||
- {"category": "help"} - список всех категорий
|
||
- {"category": "system"} - список действий в категории system
|
||
- {"category": "system", "action": "system_info"} - версия TrueNAS, hostname, uptime и т.д.
|
||
|
||
### Подключение клиентов
|
||
|
||
- OpenAPI-схема: http://truenas-ip:8814/truenas/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 через npx в claude_desktop_config.json.
|