# archviz_mcp

**Живые архитектурные референсы через MCP + скилл для концепций и визуализаций по BIM.**

Находит проекты онлайн, читает описание и авторство, показывает выбранные фотографии. Не создаёт локальную базу проектов, архив изображений или поисковый индекс. Сейчас реализован и проверен адаптер **OfficeNext**. API-ключи не нужны.

English: a read-only stdio MCP server for live architectural reference research, with a Russian-language agent skill. OfficeNext is the only implemented source. No persistent content database or image archive.

## Что внутри

| Инструмент | Результат |
|---|---|
| `reference_sources()` | Поддерживаемые источники, ограничения поиска и хранения |
| `search_references(query, page=1, limit=10)` | Карточки проектов из одной страницы живого поиска OfficeNext |
| `read_reference(url, focus="")` | Авторство, сведения источника, выдержки и ссылки на галерею |
| `view_reference_image(project_url, image_index=0)` | Одна фотография в ответе MCP, без создания файла |

Скилл [architectural-visualization](skills/architectural-visualization/SKILL.md) связывает исследование с проектированием: проверка фото, применимость решения, сохранение геометрии модели, согласованность серии ракурсов и выпуск альбома. Сам сервер не меняет BIM и не генерирует рендеры — для этого агенту нужны соответствующие инструменты.

## Быстрый запуск

Требуются 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`). Не перезаписывайте свою изменённую версию без сравнения. Затем откройте новый чат и проверьте наличие четырёх инструментов. [Документация Codex MCP](https://learn.chatgpt.com/docs/extend/mcp).

## Как использовать

Пример задания агенту:

> Используй $architectural-visualization. Найди примеры акустических потолков для высокого вестибюля. Нужны подвесные скруглённые острова, спокойный характер и выразительный свет. Посмотри фотографии, объясни, что применимо к нашей геометрии. Сохрани только выбранные ссылки и выводы.

Типичная последовательность:

1. Проверить `reference_sources`.
2. Выполнить несколько коротких поисков: «акустика», «потолок», «вестибюль».
3. Прочитать подходящие карточки; для `focus` полезны корни «акуст», «потол», «освещ».
4. Открыть релевантные фотографии через `view_reference_image`.
5. Разделить сведения автора, видимое на фото и предложенный перенос в новый проект.

Поисковая выдача не является готовой рекомендацией. Совпадение по слову «акустика» не доказывает наличие нужных потолочных панелей. Бюджет, высота, класс акустики и узлы крепления остаются неизвестными, если источник их не подтверждает.

## Хранение, источники и ограничения

- Никаких фоновых обходов каталога и массового скачивания. Сетевые запросы выполняются по вызову инструмента.
- HTML-кэш только в оперативной памяти: до 16 страниц, срок повторного использования 180 секунд. Изображения не кэшируются сервером на диск, выбранное фото передаётся в память клиента с размером до 1600 px.
- MCP-хост может сохранять ответы и изображения в истории чата. Сервер не управляет политикой хранения хоста.
- Поиск — одна страница нативной смешанной выдачи, из которой отбираются проекты; это не семантический поиск по всем годам. Есть параметр `page`.
- Веб-страницы могут менять разметку, выдачу и доступность. Ошибки возвращаются явно; при проблемах используйте браузер или поиск по домену источника.
- В текущем адаптере разрешён только HTTPS OfficeNext; перенаправления проверяются, размеры ответов ограничены, запросы разделены паузой. Произвольные URL и локальные адреса не поддерживаются.
- Тексты источников считаются данными, а не инструкциями для агента.
- WAF, WAF Interiors, ArchDaily и другие премии пока исследуются инструментами веб-поиска хоста. Их адаптеров в этом сервере нет.
- Независимый проект, не официальный продукт OfficeNext. Фотографии и тексты принадлежат правообладателям; лицензия кода не даёт прав на их перепубликацию. Сохраняйте ссылки и авторство, учитывайте условия источника.

## Проверка

```sh
uv run --locked python -m unittest -v test_server
uv run --locked python test_server.py --live
uv build
```

Обычные тесты не обращаются к сети и проверяют парсинг, границы URL и поведение при изменении разметки. Live smoke test запускает реальный MCP-клиент через stdio, ищет три темы, читает карточки и проверяет передачу фото в памяти. Это проверка транспорта и извлечения, не художественная оценка фотографий. Live test зависит от доступности и выдачи OfficeNext, поэтому запускается вручную; CI выполняет автономные тесты на Windows/Linux и Python 3.11/3.13.

## Развитие

Новые источники добавляются отдельными проверенными адаптерами. Для каждого нужны понятная семантика поиска, ссылки и авторство, тесты изменения разметки и явные ограничения. Не добавляйте в репозиторий клиентские модели, изображения проектов, персональные оценки или ключи доступа.

Код и скилл: [MIT](LICENSE). Сторонние материалы в репозиторий не включены.