Differences

This shows you the differences between two versions of the page.

--- tech:server:toolmesh [2026/07/28 09:59] – created vas_admin
+++ tech:server:toolmesh [2026/07/28 11:38] (current) – removed vas_admin
@@ Line 1: / Line 1: @@
-====== ToolMesh (MCP-сервер) ======
-Даёт Claude инструменты для работы с вики через Model Context Protocol.
-Проксирует JSON-RPC API DokuWiki, описанный декларативно в DADL-файле.
-Планируется инструмент для доступа к QoE.
-Публичный адрес: ''https://mcp.ve-playground.ai.zevgen.com/mcp''
-(через [[tech:server:nginx|nginx]], внутри — ''127.0.0.1:8123'')
-===== Версия =====
-Готовых образов проект **не публикует** под тем именем, что предполагалось изначально
-(''ghcr.io/dunkelcloud/toolmesh''), и тегов/релизов в репозитории нет — только ветка
-''main''. Поэтому образ собирается локально из исходников, а версия фиксируется
-commit SHA.
-^ Параметр ^ Значение ^
-| Источник | https://github.com/DunkelCloud/ToolMesh |
-| Зафиксированный commit | ''fb965bc69ef850a3e939751c72e5e554c485f6e1'' |
-| Путь на сервере | ''/opt/ve-playground/ToolMesh'' |
-| Контейнер | ''toolmesh-toolmesh-1'' |
-Обновление — осознанно, не ''git pull'':
-После обновления обязательно проверить лог загрузки бэкендов.
-===== Конфигурация =====
-^ Файл ^ Содержимое ^
-| ''.env'' | секреты, порт, issuer, CORS, лимиты |
-| ''config/backends.yaml'' | подключённые бэкенды |
-| ''dadl/dokuwiki.dadl'' | описание инструментов DokuWiki |
-| ''docker-compose.yml'' | сборка, сеть, volume'ы |
-==== Ключевые параметры .env ====
-^ Параметр ^ Значение ^ Комментарий ^
-| ''TOOLMESH_PORT'' | 8123 | хостовый порт; внутри контейнера — 8080 |
-| ''TOOLMESH_ISSUER'' | ''https://mcp.ve-playground.ai.zevgen.com/'' |
-| ''TOOLMESH_AUTH_PASSWORD'' | секрет | OAuth (Simple mode) |
-| ''TOOLMESH_API_KEY'' | секрет | Bearer — основной способ подключения |
-| ''TOOLMESH_CORS_ORIGINS'' | ''https://claude.ai'' | без явного значения политика открытая |
-| ''REDIS_URL'' | ''redis://keydb:6379/0'' | база 0; у бота — база 1 |
-| ''OPENFGA_MODE'' | ''bypass'' | fine-grained authz не включён, см. [[tech:risks]] |
-| ''AUDIT_STORE'' | ''log'' | пишет в stdout; ''sqlite'' даёт запросы по журналу |
-| ''DO_NOT_SEND_ANONYMOUS_STATISTICS'' | ''yes'' | телеметрия отключена |
-| ''LOG_LEVEL'' | ''info'' | ''debug'' логирует полные запросы, включая чувствительные данные — только для разбора инцидентов |
-===== Бэкенд DokuWiki =====
-<code yaml>
-- name: dokuwiki
-  transport: rest
-  dadl: dokuwiki.dadl
-  url: "https://entrypoint.ve-playground.ai.zevgen.com/lib/exe/jsonrpc.php"
-  credentials:
-    dokuwiki_username: "${CREDENTIAL_DOKUWIKI_USERNAME}"
-    dokuwiki_password: "${CREDENTIAL_DOKUWIKI_PASSWORD}"
-</code>
-Учётные данные — пользователь ''claude'', его права описаны в
-[[tech:server:dokuwiki]]. Авторизация — HTTP Basic.
-Путь ''dadl:'' относительный, ищется в ''TOOLMESH_DADL_DIR'' (по умолчанию
-''/app/dadl'' внутри контейнера, смонтирован из ''./dadl'').
-===== DADL и инструменты =====
-^ Параметр ^ Значение ^
-| Файл | ''dadl/dokuwiki.dadl'' |
-| Источник | @zevgen |
-| sha256 | ''bfc7dd4ef447e390b732b7c9e606f8409eb42d8eca9ebd2add4d7e21c1be81e7'' |
-| Инструментов | 30 базовых + 3 композита = 33 |
-| Покрытие API | 31 из 33 методов JSON-RPC |
-Хэш фиксируется по той же причине, что и commit SHA: файл получен извне, содержимое
-должно быть воспроизводимым. ToolMesh печатает ''content_hash'' в логе при загрузке.
-==== Базовые инструменты (30) ====
-Страницы: ''get_page'', ''get_page_html'', ''get_page_info'', ''get_page_history'',
-''get_page_links'', ''get_page_backlinks'', ''list_pages'', ''search_pages'',
-''save_page'', ''append_page'', ''lock_pages'', ''unlock_pages'',
-''get_recent_page_changes''
-Медиа: ''list_media'', ''get_media'', ''get_media_info'', ''save_media'',
-''delete_media'', ''get_recent_media_changes''
-Метаданные и права: ''who_am_i'', ''acl_check'', ''get_api_version'',
-''get_wiki_version'', ''get_wiki_title'', ''get_wiki_time''
-Администрирование: ''list_acls'', ''add_acl'', ''delete_acl'', ''create_user'',
-''delete_user''
-==== Композиты ====
-Выполняются на стороне ToolMesh: полный текст страницы не покидает сервер, наружу
-уходит только небольшой результат.
-^ Композит ^ Что делает ^
-| ''page_search_and_replace'' | замена подстроки (литерал, не regex) с сохранением |
-| ''page_append_section'' | вставка в конец секции перед следующим заголовком того же или высшего уровня — то, что ''append_page'' не умеет (он пишет только в конец страницы) |
-| ''chunked_save_page'' | посекционная сборка большой страницы в буфере с записью одной ревизией; промежуточные операции помечаются minor, чтобы не засорять Recent Changes |
-==== Служебные ====
-''echo_echo'', ''echo_add'', ''echo_time'' — встроенные, удобны для проверки
-живости связки без обращения к вики.
-===== Code Mode =====
-Помимо прямых вызовов инструментов всегда доступны ''discover_tools'' и
-''execute_code'': модель пишет JavaScript, который вызывает инструменты через
-''api.<tool>()''. Результат ''execute_code'' ограничен примерно 55 000 символов.
-===== Подключение =====
-Способы и пошаговая инструкция — [[tech:connect]].
-Механика аутентификации и известный дефект OAuth — [[tech:server:toolmesh:auth]].
-===== Диагностика =====
-<code>
-curl -s http://127.0.0.1:8123/health                 # {"status":"ok"}
-docker logs toolmesh-toolmesh-1 --tail 50
-</code>
-**''/health'' недостаточно.** Он отвечает ''ok'' даже если DADL не распарсился и
-бэкенд молча не загрузился. Признак успешной загрузки — строка в логе:
-<code>
-"msg":"REST proxy backend loaded","name":"dokuwiki","tools":30,"content_hash":"bfc7dd..."
-</code>
-Нормальные предупреждения при старте, не требующие действий:
-  * ''SSRF base_url validation skipped (allow_private_url)'' — наш backend URL
-    публичный HTTPS-домен, а не приватный адрес
-  * ''authorization is BYPASSED'' — следствие ''OPENFGA_MODE=bypass''
-Аудит вызовов инструментов виден в том же логе:
-<code>
-docker logs toolmesh-toolmesh-1 --since 24h | grep '"msg":"audit"'
-</code>
-Каждая запись содержит инструмент, пользователя, длительность, статус и
-''tool_access'' (''read''/''write''). Это единственный способ узнать, что именно
-модель делала с вики — журнал изменений DokuWiki покажет только результат.
-----
-[[tech:server|← Сервер]]