[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

2026-09-26 21:37:37 +06:00
1 parent 9e7a888f94
commit 270c4b7c52
@@ -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'`.

 ---

@@ -15,12 +15,37 @@
 ### 1. @bitbonsai/mcpvault (наш текущий) — filesystem

 - **npm:** `@bitbonsai/mcpvault` (бывший `obsidian-mcp`, переименован март 2026 из-за trademark)
- **Версия:** 0.12.1 (июнь 2026)
+- **Версия:** 0.12.1 (июнь 2026); на Kraken стоит **0.11.0**
 - **Язык:** TypeScript
- **Транспорт:** stdio только
+- **Транспорт:** **stdio только** — HTTP-режима нет (проверено: `mcpvault --help`
+  принимает единственный аргумент `[vault-path]`, флагов порта/хоста не существует)
 - **Инструменты:** 14: read_note, write_note, patch_note, list_directory, delete_note, search_notes, move_note, move_file, read_multiple_notes, update_frontmatter, get_notes_info, get_frontmatter, manage_tags, get_vault_stats, list_all_tags
 - **Проблема:** exact string match в patch_note (`fullContent.split(oldString).length - 1`), без fuzzy, без trim, без нормализации whitespace

+#### Как отдать mcpvault по сети (проверено на Mac и Kraken)
+
+Поскольку HTTP-режима нет, для сетевого доступа нужна обёртка **`mcp-proxy`**
+(пакет `mcp-proxy@6.4.4`), которая поднимает SSE поверх stdio-сервера:
+
+```yaml
+# docker-compose.yml — рабочая пара
+services:
+  obsidian-mcp:
+    image: obsidian-mcp-image:0.1.0   # node:24-bookworm + оба пакета
+    command: ["--port", "3101", "--", "mcpvault", "/vault"]
+```
+
+| Питфолл | Симптом | Фикс |
+|---|---|---|
+| У `mcp-proxy` **нет** флага `--host` | контейнер падает на разборе аргументов | только `--port N -- <cmd> <args>`; слушает `0.0.0.0` по умолчанию |
+| Точка монтирования должна существовать в образе | mcpvault стартует не в том каталоге | `RUN mkdir -p /vault` + `WORKDIR /vault` в Dockerfile |
+
+Проверка живости: `curl -o /dev/null -w "%{http_code}" http://<host>:3101/sse` → **200**.
+Endpoint для MCP-клиента — `/sse` (не `/mcp`; `/mcp` отдаёт 400).
+
+📌 Для Балды на Kraken волт монтируется **`:ro`** — агент читает документацию,
+но не правит её. Запись в волт через агента — отдельное решение.
+
 ### 2. cyanheads/obsidian-mcp-server — REST API, самый популярный по загрузкам

 - **npm:** `obsidian-mcp-server`