Архитектура VMK Data MCP Server

Обзор системы

Сервер реализован как MCP (Model Context Protocol) Server на базе FastMCP (Python SDK v1.x) с транспортом Streamable HTTP. Он выступает безопасным посредником между AI-агентом и PostgreSQL-базой недвижимости, предоставляя агенту инструменты поиска без прямого доступа к БД.

Компоненты

┌─────────────────────────────────────────────────────────────────────────────┐
│                            AI Агент (Claude / GPT)                          │
│                              MCP Client                                     │
└───────────────────────────────┬─────────────────────────────────────────────┘
                                │ HTTP SSE + POST
                                ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         VMK Data MCP Server                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │   main.py   │  │   tools.py  │  │   models.py │  │      embedder.py    │ │
│  │ FastMCP app │  │ 4 tools     │  │  Pydantic   │  │  httpx → Ollama     │ │
│  │ HTTP transport│  │ SQL builders│  │ validation  │  │  /api/embed         │ │
│  └──────┬──────┘  └──────┬──────┘  └─────────────┘  └─────────────────────┘ │
│         │                │                                                    │
│         └────────────────┼────────────────────────────────────────────────────┘
│                          │
│  ┌───────────────────────┴───────────────────────┐
│  │                  db.py                        │
│  │  asyncpg pool + read-only safety            │
│  │  USER_COLUMNS whitelist                       │
│  └───────────────────────┬───────────────────────┘
│                          │ asyncpg
└──────────────────────────┼───────────────────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        PostgreSQL (vmk_data)                                │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────────┐ │
│  │  property_      │  │   embedding     │  │   search_vector             │ │
│  │  listings       │  │   vector(768)   │  │   tsvector (ukrainian)      │ │
│  │                 │  │   HNSW index    │  │   GIN index                 │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘

1. main.py — Entrypoint и FastMCP

• Создаёт экземпляр FastMCP(name=settings.mcp_server_name).
• Регистрирует 4 инструмента через декоратор @mcp.tool().
• Определяет lifespan — асинхронный контекстный менеджер для инициализации пула БД и закрытия ресурсов.
• Запускает mcp.run(transport="streamable-http", port=settings.mcp_port).

Streamable HTTP transport:

• GET /mcp — SSE-стрим для сервер→клиент сообщений.
• POST /mcp — приём сообщений клиент→сервер.

2. tools.py — SQL-конструкторы и бизнес-логика

Каждый инструмент — async-функция, которая:

1. Принимает Pydantic-модель (SearchSimilarInput, SearchMetadataInput …).
2. Строит SQL через _build_where_clause() (параметризованный).
3. Для векторного поиска — вызывает embedder.get_embedding(query).
4. Выполняет 2 запроса: COUNT(*) (для total) и SELECT … LIMIT/OFFSET.
5. Сериализует результат в SearchResult → JSON.

Ключевая функция _build_where_clause(filters):

• Проверяет, что значение фильтра не None.
• Использует strictly allowed columns — только известные имена колонок.
• Генерирует SQL-условия с нумерованными параметрами $N.

3. models.py — Pydantic v2

• Входные модели: валидация типов, границ, enum-значений.
• Выходные модели: ListingResult, SearchResult — сериализация asyncpg.Record.
• Все модели наследуют BaseModel с чёткими Field(description=…).

4. db.py — Безопасный доступ к БД

Пул asyncpg:

• create_pool(..., init=_init_conn) — каждое новое соединение получает SET default_transaction_read_only = on.
• Мин/макс размер пула и таймаут запросов из .env.

Read-only защита _is_safe_query(sql):

• Разрешённые префиксы: select, with, values, explain.
• Запрет ; внутри строки — блокировка multi-statement инъекций (DROP TABLE;).

USER_COLUMNS:

• Белый список колонок property_listings.
• build_select_columns() — динамически строит SELECT col1, col2 ….

5. embedder.py — Ollama клиент

• Singleton httpx.AsyncClient с base_url и таймаутом.
• get_embedding(text) → list[float] длины OLLAMA_EMBED_DIMENSIONS.
• Валидация размерности ответа.

6. config.py — Настройки

pydantic-settings загружает .env с extra="ignore". Все секреты и URL вынесены в переменные окружения.

Потоки данных

Векторный поиск (search_similar_listings)

┌─────────┐    украинский текст    ┌───────────┐
│  Agent  │ ───────────────────>  │ embedder  │
└─────────┘                       └─────┬─────┘
                                      │ HTTP POST /api/embed
                                      ▼
                               ┌──────────────┐
                               │   Ollama     │
                               │ 768d vector  │
                               └──────┬───────┘
                                      │
                                      ▼
┌─────────┐    SQL + $1..$N     ┌──────────┐    vector(768), max_distance
│  Agent  │ <─────────────────── │   db.py  │ <──────────────────────────────┐
└─────────┘    JSON result       └────┬─────┘                                  │
                                      │ asyncpg                               │
                                      ▼                                       │
                               ┌──────────────┐                               │
                               │  PostgreSQL  │                               │
                               │  HNSW scan   │                               │
                               │  embedding   │                               │
                               │  <=> vector  │                               │
                               └──────────────┘                               │
                                                                              │
                                        COSINE DISTANCE  [0, 2]               │
                                        max_distance = 2*(1 - similarity)   │

Полнотекстовый поиск (search_by_metadata)

┌─────────┐    украинский текст    ┌──────────┐
│  Agent  │ ───────────────────>  │  tools   │
└─────────┘                       └────┬─────┘
                                     │
                                     ▼
                              ┌──────────────┐
                              │  PostgreSQL  │
                              │  plainto_ts- │
                              │  query('uk..')│
                              │  @@ search_  │
                              │  vector      │
                              └──────────────┘

Индексы базы данных

Почему HNSW, а не IVFFlat?

• HNSW обеспечивает лучшую точность при высокой селективности фильтров.
• Не требует перестроения при добавлении данных (ef_construction, m настраиваются при создании).
• Рекомендуется для production-нагрузки с pgvector ≥ 0.5.0.

Почему vector_cosine_ops?

• Модель nomic-embed-text генерирует нормализованные векторы.
• Cosine distance (<=>) эквивалентен Euclidean distance для нормализованных векторов, но явно выражает семантическую близость.

Безопасность (Defense in Depth)

┌─────────────────────────────────────────────────────────────┐
│  Уровень 1: Сеть                                            │
│  — MCP Server доступен только внутри сети / через reverse   │
│    proxy с аутентификацией (не входит в скоуп проекта)      │
├─────────────────────────────────────────────────────────────┤
│  Уровень 2: PostgreSQL роли                               │
│  — Отдельный READ-ONLY пользователь БД (рекомендуется)      │
├─────────────────────────────────────────────────────────────┤
│  Уровень 3: default_transaction_read_only = on             │
│  — Каждая транзакция принудительно read-only                │
├─────────────────────────────────────────────────────────────┤
│  Уровень 4: Валидация SQL (_is_safe_query)                 │
│  — Только SELECT / WITH / VALUES / EXPLAIN                  │
│  — Блокировка `;` (multi-statement)                         │
├─────────────────────────────────────────────────────────────┤
│  Уровень 5: Параметризованные запросы                      │
│  — Никакого f-string / format в SQL                         │
├─────────────────────────────────────────────────────────────┤
│  Уровень 6: USER_COLUMNS whitelist                         │
│  — SELECT только разрешённые колонки                        │
└─────────────────────────────────────────────────────────────┘

Масштабирование и производительность

Потенциальные bottleneck'и

1. Ollama — если запросов много, стоит поднять Ollama на GPU или добавить кеширование эмбеддингов (Redis / in-memory LRU для популярных запросов).
2. PostgreSQL CPU — COUNT(*) с фильтрами на больших таблицах может требовать pg_stat_statements анализа и частичных индексов.
3. HNSW ef_search — при недостаточной точности можно увеличить SET hnsw.ef_search = 100 (по умолчанию обычно 40).

Логирование

Сервер использует стандартный logging из stdlib.

Пример:

WARNING  vmk_data_mcp.tools: Ollama error: ConnectError(...)