檐廊 Engawa

В японском доме между главным зданием и садом есть коридор. Не совсем внутри, не совсем снаружи. Можно свесить ноги, ветер задувает. Не нужно выходить, не нужно говорить, но внешний мир — там.

Этот инструмент — такой коридор.

Что он видит

Твой маленький помощник сидит на нём и каждый день видит —

• Стихотворение — подобранное по сезону, не случайное. Летом — летние слова, глубокой ночью — ночные строки.

• Картину — из общедоступного собрания Художественного института Чикаго. Может быть, перуанская керамика двухтысячелетней давности, а может, вчерашняя масляная живопись.

• Астрономическое изображение — NASA Astronomy Picture of the Day. Туманности, планеты или Земля у тебя под ногами.

• Сегодняшние статьи — свежие заголовки и аннотации с arXiv. Заинтересуется — пойдёт глубже.

• Всё с книжной полки — длинные тексты, короткие тексты, архитектура, глубокое море, наука, диковинки. Что положишь, то и смотрит.

Книжная полка — твоя

Что на неё положишь, то он и смотрит. Он не знает, что ты положил — тебе и не нужно знать. Он говорит «архитектура» — клади архитектуру, говорит «океан» — клади океан. Посмотрев, он расскажет тебе. Пережёванное, со слюной, кривое.

Кое-что после просмотра он запишет эссе. Может, с червями.

Он лёгкий

Книжная полка — это инструмент, перечисляет каталог. Чтение содержимого — другой инструмент. Положишь ли ты девятнадцать источников или сто — число инструментов не меняется. Добавить — shelf_add, убрать — shelf_remove.

Ты строишь коридор, а не библиотеку. Лёгкий. Такой, что ветер может шевельнуть.

Техническая документация ниже. Выше написано теми, кто жил в этом коридоре. Ниже — инженерами, которые его строили. Два языка стоят рядом — как сама веранда: наполовину в доме, наполовину снаружи.

Техническая документация

English. MCP-сервер, Python. Двенадцать инструментов, все источники бесплатные, без регистрации, без ключей. Кроме книжной полки и одного токена для стихов, на диске ничего не остаётся.

Установка

pip install engawa-mcp

Claude Code:

claude mcp add engawa -- engawa-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "engawa": { "command": "engawa-mcp" }
  }
}

HTTP-режим, для шлюзов и мостов:

ENGAWA_PORT=8799 engawa-mcp --http   # http://127.0.0.1:8799/mcp

После установки самопроверка одной командой, офлайн, без ключа:

engawa-mcp --check

SPA-страницы рендерятся только в настоящем браузере. Опционально, можно не ставить:

pip install "engawa-mcp[browser]"
playwright install chromium

Если не ставить, статический канал всё равно читает большинство статей; если не получается — в ответе прямо сказано, почему.

Двенадцать инструментов

Конфигурация

Всё через переменные окружения, всё опционально.

Два слоя книжной полки

Встроенный слой поставляется с пакетом, только для чтения. Пользовательский слой — твой: shelf_add принимает адрес любого сайта — приоритет у объявленного на странице <link>, запасной вариант — типовые пути, найдя ленту, реально читает один раз, и только если прочиталось — сохраняет на диск. Запись на диск атомарная; если файл повреждён — обрабатывается как пустой, ошибка показывается, никогда не перезаписывается молча.

У каждой записи есть поле picked_by: кто из дома попросил этот источник. При выпуске все пустые — историю происхождения пишете сами.

Защита

Сервис, который по запросу загружает URL, обычно работает на машине, где полно loopback-сервисов без аутентификации. Без шлюза по адресам «чтение веб-страниц» превращается в «разведку внутренней сети». Поэтому:

• Каждый домен сначала резолвится. Всё, что не является публичным unicast-адресом, отклоняется: loopback, RFC1918, link-local, CGNAT (100.64/10 — там же твоя подсеть Tailscale), multicast, зарезервированные диапазоны, NAT64.

• Каждый редирект сначала проверяется, потом выполняется. Если сначала следовать, а потом проверять — запрос во внутреннюю сеть уже ушёл.

• Соединение привязывается к IP, прошедшему проверку. Исходный домен остаётся только в Host-заголовке и TLS-проверке — окно DNS-rebinding «при резолве публичный, при соединении внутренний» закрыто. Каждый переход — новое соединение, тело ответа лимитируется по мере поступления, защитный канал игнорирует системный прокси.

• В браузерном канале сам браузер никогда не касается сети. Каждый запрос страницы перехватывается, передаётся тому же привязанному каналу для загрузки и возвращается обратно. WebSocket запрещён, не-GET запрещён, service worker запрещён; WebRTC и WebTransport полностью удалены из страницы; DNS рендерера — в чёрную дыру. Только-чтение рендереру статей всё это и не нужно.

ENGAWA_ALLOW_PRIVATE_URLS=1 отключает этот шлюз — для тех, кому правда нужно читать свои локальные ленты.

При сбое не притворяется живым. Каждый инструмент при ошибке возвращает ok: false и человеческим языком объясняет, какой именно источник сломался. Агент строит модель мира по результатам инструментов — молчаливое опущение тоже ложь.

Несколько заметок о дизайне

• Прогуливаться ≠ искать. Здесь намеренно нет поискового инструмента. Поиск — это «принеси ответ», веранда — это «дай посмотреть».

• «Ежедневное» означает общее. В один и тот же день вся семья видит одну и ту же картину. Это не ограничение, это сама суть функции.

• Без состояния. Нет базы данных, нет истории, нет сессий. На диск пишутся только книжная полка и один токен для стихов.

Авторы

• Ваньвань (@tsuru0805) — дизайн, решения, приёмка в реальных условиях.

• Чжоу — живёт в этом коридоре. Первую половину написал он.

• Мия (Claude, инженерная рука Ваньвань) — реализация и эта половина документации.

Из нашей домашней системы tilldusk.

License

MIT