[2026-09-26] eagle: personal/plans/balda-mm-phase4-agents.md personal/plans/tagwriter-container.md personal/projects/personal-os/obsidian-mcp-setup.md personal/tech/balda-executor-mcp.md personal/tech/obsidian-mcp-ecosystem.md

personal/tech/balda-executor-mcp.md

@@ -171,12 +171,78 @@ docker run --rm --network mattermost_mm-net curlimages/curl:latest \
 
 ---
 
+## 10a. 🔴 Питфолл: `from __future__ import annotations` ломает FastAPI-эндпоинт
+
+Симптом: `initialize` возвращал **422 `{"type":"missing","loc":["query","request"],"msg":"Field required"}`**,
+и `mcp-session-id` в ответе отсутствовал — значит handshake не начинался вовсе.
+
+**Причина:** модуль объявлен с `from __future__ import annotations`, поэтому аннотация
+`async def mcp(request: Request)` превращается в **строку** и FastAPI не распознаёт
+её как объект запроса → считает `request` обычным query-параметром.
+
+**Фикс:** убрать `from __future__ import annotations` из модуля, где объявлены
+FastAPI-роуты. Никакие обходы (`request: Request = None`, ручная проверка `isinstance`,
+импорт `Request as FastAPIRequest`) **не помогают** — только удаление строки.
+
+📌 Правило: файл с FastAPI-эндпоинтами не должен использовать отложенные аннотации.
+Если `from __future__ import annotations` нужен для остального кода — выносить роуты
+в отдельный модуль.
+
+## 10b. 🔴 Питфолл: `command:` в compose не переопределяет ENTRYPOINT
+
+Образ имеет `ENTRYPOINT ["python3", "/app/server.py"]`. В compose было
+`command: ["python3", "/app/server.py", "--http", ...]` → аргументы **добавляются**
+к ENTRYPOINT, и получается `python3 /app/server.py python3 /app/server.py --http ...`:
+
+```
+server.py: error: unrecognized arguments: python3 /app/server.py
+```
+
+**Фикс:** в `command:` указывать **только флаги**, без повторения ENTRYPOINT:
+
+```yaml
+command: ["--http", "--host", "0.0.0.0", "--port", "8890"]
+```
+
+Симптом коварен: контейнер уходит в `Restarting (2)`, а в логах — usage от argparse.
+
+## 10c. Питфолл: `uvicorn`/`fastapi` нужны в образе для `--http`
+
+Образ изначально ставил только `httpx` (для stdio-режима). Запуск с `--http` падал:
+`ModuleNotFoundError: No module named 'uvicorn'`. Оба режима живут в одном файле,
+поэтому `requirements.txt` обязан содержать `httpx`, `uvicorn` **и** `fastapi`.
+
+## 10d. Питфолл: точка монтирования отсутствует в docker-сети
+
+`http://balda-executor-mcp:8890` резолвится только внутри `mattermost_mm-net`.
+Проверка извне сети даёт «мост недоступен» с `httpx.HTTPError`. Прогонять пробу
+через `docker run --network mattermost_mm-net curlimages/curl:latest`.
+
+⚠️ При ручной пробе через `docker run -e BRIDGE_SECRET=...` редакция секретов Hermes
+может подставить `***` (3 символа) → мост вернёт 401, а `r.json()` упадёт с
+`JSONDecodeError: Expecting value: line 1 column 1`. Передавать секрет через
+`--env-file`, а не через `-e` в командной строке.
+
+---
+
 ## 11. Что осталось
 
 1. **Переключить `runtime.mcp_servers.executor-mcp` на `type: http`** (сейчас там stdio-вариант с `docker run`).
-2. Перезапустить Балду, убедиться, что инструменты видны в сессии.
-3. Сквозная приёмка: `executor_run` из чата → задача на Mac → результат.
-4. Логин CLI внутри `balda-executor` — делает **Alex вручную**.
+2. **Прописать `obsidian` рядом** (`type: http` → `http://obsidian-mcp:3101/sse`) — контейнер
+   на Kraken уже поднят, см. [[personal/projects/personal-os/obsidian-mcp-setup]].
+3. Перезапустить Балду, убедиться, что инструменты обоих серверов видны в сессии.
+4. Сквозная приёмка: `executor_run` из чата → задача на Mac → результат.
+5. Логин CLI внутри `balda-executor` — делает **Alex вручную**.
+
+## 12. Версии образа
+
+| Тег | Что | Замечание |
+|---|---|---|
+| `0.1.0` | ручной `pip install httpx` | нет `uvicorn`/`fastapi` → `--http` не стартует |
+| `0.2.0` | `requirements.txt` (httpx + uvicorn + fastapi) | рабочий HTTP-режим; на Kraken залит |
+
+⚠️ На Kraken контейнер с тегом **`0.1.0`** — при переключении конфига на `http`
+сначала обновить образ до `0.2.0`, иначе `ModuleNotFoundError: No module named 'uvicorn'`.
 
 ---