Skip to main content
Glama
README.md
# 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

A3.9/5.0

Scored across 4 tools

Disambiguation5/5

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.

Naming Consistency4/5

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.

Tool Count4/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessOutdated data