archviz_mcp
# archviz_mcp
**Живые архитектурные референсы, пробный кадр и проверяемая серия визуализаций по BIM.**
Находит проекты онлайн, читает описание и авторство, показывает выбранные фотографии. Не создаёт локальную базу проектов, архив изображений или поисковый индекс. Подключены **OfficeNext, ArchDaily, FRAME, Architizer и WAF** — с разными возможностями поиска и чтения, указанными ниже. API-ключи не нужны.
English: a read-only stdio MCP server for live architectural references and stateless visualization review, with a Russian-language skill. Adapters cover OfficeNext, ArchDaily public projects, FRAME public projects, Architizer Journal/A+Awards and WAF winner panels. Search capabilities vary; discovery-only fallbacks are explicit. No renderer, automatic image-quality scorer, persistent project database or image archive.
## Что внутри
| Инструмент | Результат |
|---|---|
| `reference_sources()` | Поддерживаемые источники, ограничения поиска и хранения |
| `search_references(query, source="all", page=1, limit=10, year=2025)` | Поиск по доступным источникам и явные подсказки для веб-поиска там, где нет серверного поиска |
| `browse_reference_catalog(source, year=2025, query="", limit=10, offset=0)` | Фильтрация одного годового каталога Architizer или WAF; ID конкретных конкурсных карточек |
| `read_reference(url, focus="", entry_id=None)` | Авторство, сведения источника, выдержки и ссылки на галерею |
| `view_reference_image(project_url, image_index=0, entry_id=None)` | Одна фотография в ответе MCP, без создания файла |
| `visualization_workflow()` | Контракт серии: роли источников, камеры, пробный кадр, раздельные проверки и JSON Schema паспорта |
| `check_visualization_series(series)` | Проверка записей о принятии пилота, версиях входов, визуальных разборах и финальном отборе |
Скилл [architectural-visualization](skills/architectural-visualization/SKILL.md) связывает референсы, паспорт камеры, пробный кадр и проверку серии. Сам сервер не меняет BIM и не генерирует рендеры — для этого нужны инструменты хоста.
## Источники: версия 0.3
| Источник | Что работает в MCP | Границы |
|---|---|---|
| **OfficeNext** | Нативный поиск, карточки, авторство, галерея и просмотр фото | Короткие русские запросы; выдача не охватывает весь архив |
| **ArchDaily** | Публичные карточки проектов, спецификации, галерея и просмотр изображений | Поиск через веб-инструмент хоста; статьи за подпиской не извлекаются |
| **FRAME** | Публичные проекты: описание, бюро, фото, планы и подписи | Поиск через хост; только данные выбранного проекта, без профилей и соседних подборок |
| **Architizer** | Поиск Journal, чтение статей; годовые каталоги A+Awards, отдельные конкурсные карточки и изображения | Journal — редакционные статьи, не карточки зданий. Полные `/projects/` могут блокироваться |
| **WAF / Interiors** | Каталог победителей 2025, авторство, категории и изображения конкурсных карточек | Картинка может быть конкурсным планшетом. World Buildings Directory не подключён |
| **Office Snapshots, Dezeen** | Адреса источников и запросы для веб-поиска хоста | Прямой доступ заблокирован в проверке; серверных адаптеров нет |
Для Architizer можно запросить отдельный выпуск **2013–2026**. Проверены 2013, 2018, 2020, 2024, 2025 и 2026; остальные годы не объявляются проверенными. Для WAF сейчас настроен только 2025. Год выпуска премии не равен году реализации.
`source="all"` возвращает результаты доступных поисков вперемешку и отдельный `source_reports` с ограничениями и ошибками. Подсказки `host_search_required` — **ещё не выполненный поиск**. Для совместимости значение `source` по умолчанию остаётся `officenext`; широкий поиск нужно запросить явно. Английские ключевые слова нужны для международных источников, автоматического перевода нет.
```python
search_references(query="office ceiling", source="all", limit=8)
browse_reference_catalog(source="architizer", year=2024, query="office", limit=5)
# Из результата каталога переносим ОБА поля — url и entry_id:
read_reference(url=entry["url"], entry_id=entry["entry_id"], focus="ceiling")
view_reference_image(project_url=entry["url"], entry_id=entry["entry_id"], image_index=0)
```
Это примеры аргументов инструментов, не отдельный Python-клиент. Выборки каталога используют `offset`/`next_offset`; Journal поддерживает только первую страницу. Текстовый фильтр каталога ищет все слова запроса в описании, названии, авторстве и категории. Это не семантическая оценка сходства интерьеров.
## Серия визуализаций: версия 0.2
Фотографическая убедительность и соответствие проекту проверяются отдельно. Принятая палитра или успешный вызов генератора не означают принятый кадр. Для новой фотографической серии скилл сначала делает один пробный кадр и получает явную пользовательскую оценку конкретной версии; пользователь может явно отменить паузу, сохранив проверки качества.
1. Вызвать `visualization_workflow`, зафиксировать паспорт проекта и роли источников.
2. Получить пробный кадр инструментом хоста. Открыть картинку и источники, записать наблюдения по геометрии и подаче.
3. Добавить точную пользовательскую оценку с областью действия и SHA-256 изображения. Решения агента хранятся отдельно.
4. Проверить готовность через `check_visualization_series`, расширить серию и проверить каждый отобранный ракурс, включая сравнение между видами.
5. Сохранить в проекте финальный отбор и историю отклонений. Заменённые изображения/входы и изменённый целевой свет/материалы требуют свежей проверки.
При строгой геометрии контракт требует рендер общей сцены с зафиксированными версиями света, материалов и камер. Генеративный путь остаётся концептуальным. Наличие подходящего рендера агент проверяет отдельно; эта версия MCP его не добавляет.
Паспорт передаётся в вызов как JSON и сохраняется хостом **в проекте пользователя**, не в этом репозитории. Сервер не читает файлы и не сохраняет паспорт. Он проверяет предоставленные записи и хеши, но не видит пиксели, не вычисляет оценку фотореализма и не удостоверяет авторство цитат. Зелёная проверка не заменяет просмотр и решение пользователя. Подробности: [контракт серии](skills/architectural-visualization/references/series-contract.md).
При доработке изучены [внешние скиллы](skills/architectural-visualization/references/workflow-sources.md): управление камерой, проверка исходных экспортов, воспроизводимая сцена и сравнение ракурсов. Их код не устанавливался и не включён в пакет.
## Быстрый запуск
Требуются Python 3.11+ и [uv](https://docs.astral.sh/uv/). Вариант из исходников даёт воспроизводимые зависимости из `uv.lock`:
```sh
git clone https://github.com/proovcme/archviz_mcp.git
cd archviz_mcp
uv sync --locked
uv run --locked archviz-mcp
```
Сервер ждёт MCP-сообщения в stdin/stdout, это не сайт и не интерактивная консоль. Завершение вручную — Ctrl+C. Диагностика идёт в stderr.
Для разового запуска без клонирования:
```sh
uvx --from git+https://github.com/proovcme/archviz_mcp.git archviz-mcp
```
Этот вариант устанавливает код и зависимости в кэш uv. Требование «без базы» относится к контенту референсов, а не к установленным программам. Для фиксированной версии к Git URL можно добавить `@<commit-sha>`.
## Подключение к Codex
После клонирования замените `/absolute/path/archviz_mcp` на свой абсолютный путь:
```sh
codex mcp add architectural_references --env PYTHONUTF8=1 -- uv --directory /absolute/path/archviz_mcp run --locked archviz-mcp
```
На Windows путь с пробелами заключите в кавычки. Если `uv` не находится в окружении приложения, укажите полный путь к нему.
Для других MCP-клиентов используйте эквивалентную конфигурацию (имя верхнего поля зависит от клиента):
```json
{
"mcpServers": {
"architectural_references": {
"command": "uv",
"args": ["--directory", "/absolute/path/archviz_mcp", "run", "--locked", "archviz-mcp"],
"env": {"PYTHONUTF8": "1"}
}
}
}
```
Скопируйте папку `skills/architectural-visualization` в каталог навыков вашего агента. Для Codex это обычно `~/.codex/skills/` (либо каталог `skills` внутри настроенного `CODEX_HOME`). Не перезаписывайте свою изменённую версию без сравнения. Затем откройте новый чат и проверьте наличие семи инструментов. Уже работающий MCP-процесс после обновления нужно переподключить средствами хоста. [Документация Codex MCP](https://learn.chatgpt.com/docs/extend/mcp).
## Как использовать
Пример задания агенту:
> Используй $architectural-visualization. Найди примеры акустических потолков для высокого вестибюля. Нужны подвесные скруглённые острова, спокойный характер и выразительный свет. Посмотри фотографии, объясни, что применимо к нашей геометрии. Сохрани только выбранные ссылки и выводы.
Типичная последовательность:
1. Проверить `reference_sources`.
2. Выполнить короткие русские запросы в OfficeNext и английские с `source="all"`: `acoustic`, `ceiling`, `lobby`. Обработать подсказки веб-поиска хостом; выбрать подходящие годы и категории премий.
3. Прочитать подходящие карточки; для `focus` полезны корни «акуст», «потол», «освещ».
4. Открыть релевантные фотографии через `view_reference_image`.
5. Разделить сведения автора, видимое на фото и предложенный перенос в новый проект.
Поисковая выдача не является готовой рекомендацией. Совпадение по слову «акустика» не доказывает наличие нужных потолочных панелей. Бюджет, высота, класс акустики и узлы крепления остаются неизвестными, если источник их не подтверждает.
## Хранение, источники и ограничения
- Никаких фоновых обходов каталога и массового скачивания. Сетевые запросы выполняются по вызову инструмента.
- HTML-кэш только в оперативной памяти: до 16 страниц, срок повторного использования 180 секунд. Изображения не кэшируются сервером на диск, выбранное фото передаётся в память клиента с размером до 1600 px.
- MCP-хост может сохранять ответы и изображения в истории чата. Сервер не управляет политикой хранения хоста.
- Поиск и охват различаются по источникам: нативная выдача, фильтр одного каталога или явная передача поиска хосту. Ни один режим не обещает полный архив.
- Веб-страницы могут менять разметку, выдачу и доступность. Ошибки возвращаются явно; при проблемах используйте браузер или поиск по домену источника.
- Разрешены только конкретные HTTPS-домены, маршруты и CDN источников. Перенаправления между источниками отклоняются; размеры ответов ограничены, запросы разделены паузой. Произвольные URL и локальные адреса не поддерживаются.
- Тексты источников считаются данными, а не инструкциями для агента.
- Независимый проект, не официальный продукт перечисленных площадок. Фотографии и тексты принадлежат правообладателям; лицензия кода не даёт прав на их перепубликацию. Сохраняйте ссылки и авторство, учитывайте условия источника.
## Проверка
```sh
uv run --locked python -m unittest -v test_server test_visualization test_sources
uv run --locked python test_server.py --live
uv run --locked python live_sources.py
uv build
```
Обычные тесты не обращаются к сети: проверяют парсинг, границы URL, этап принятия пользователем, раздельные проверки, устаревшие ревизии, отбор и согласованность сцены. Они также запускают реальный stdio MCP и проверяют контракт/приёмку на синтетическом паспорте. Live smoke test отдельно ищет три темы, читает карточки и проверяет передачу фото в памяти. Тесты не оценивают художественное качество. Межисточниковый тест `live_sources.py` проверяет чтение и декодирование изображения через настоящий stdio MCP для пяти площадок, включая Journal и конкурсные карточки. Live-тесты зависят от доступности сайтов и запускаются вручную; CI выполняет автономные тесты на Windows/Linux и Python 3.11/3.13.
## Развитие
[Проверка дополнительных источников](docs/source-audit.md): ArchDaily, Office Snapshots, WAF, FRAME, Architizer и Dezeen. В отчёте указаны проверенные страницы, выпуски, работающие операции и ограничения.
Новые источники добавляются отдельными проверенными адаптерами. Для каждого нужны понятная семантика поиска, ссылки и авторство, тесты изменения разметки и явные ограничения. Не добавляйте в репозиторий клиентские модели, изображения проектов, персональные оценки или ключи доступа.
Код и скилл: [MIT](LICENSE). Сторонние материалы в репозиторий не включены.
TDQS
Scored across 4 tools
Each tool has a distinct role: reporting sources, searching candidates, reading project details, and viewing a single gallery image. The search/read/view split is clear, and descriptions explicitly state boundaries such as search returning candidates versus read returning verified project content.
Three tools follow a clear verb_noun pattern: search_references, read_reference, view_reference_image. reference_sources is a noun phrase rather than an action, but it is still readable and semantically appropriate as a metadata/reporting tool.
Four tools are well scoped for a focused workflow around searching, reading, and visually inspecting OfficeNext references. It is slightly thin but each tool earns its place without unnecessary overlap.
The surface covers source discovery, keyword search, project reading, and image viewing, which is a coherent lifecycle for the stated reference-inspection purpose. Minor gaps include no browse/list operation independent of search and no batch image viewing, but these are workable limitations.