belle-mcp-server

Эталонный Model Context Protocol (MCP) сервер, который предоставляет реальные данные управления недвижимостью Belle Realty — объекты, арендаторов, договоры аренды, заявки на обслуживание, арендную ведомость — в виде инструментов, которые Claude Desktop, Cursor или любой MCP-совместимый клиент может вызывать напрямую.

Шесть инструментов. Пять строго только на чтение. Один — это запись с подтверждением человека (HITL). Это соотношение намеренно, и в этом весь смысл репозитория.

Часть AI Fluency Program — Level 2.

Зачем это существует

Большинство демо «ИИ + ваши данные» дают модели неограниченный доступ к базе данных. Это способ выстрелить себе в ногу.

Model Context Protocol спроектирован так, чтобы открывать небольшую, тщательно подобранную поверхность с аутентификацией, лимитами частоты и аудитом для каждого инструмента — та же дисциплина, которую вы применили бы к публичному REST API. Этот репозиторий показывает, как это выглядит для реальной предметной области (торговый центр в Луизиане) с реальной схемой Postgres, рабочим сид-заполнением и единственным путём записи через HITL.

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

Что вы получаете

Каждый вызов ограничен по частоте (по умолчанию 60/мин) и заносится в аудит-лог mcp_audit_log.

Быстрый старт

# 1. Clone + install
git clone https://github.com/OrangeOnyx/belle-mcp-server.git
cd belle-mcp-server
npm install

# 2. Configure
cp .env.example .env
# Paste your Supabase URL + service-role key

# 3. Set up the schema (Supabase project)
#    Copy supabase/migrations/0001_init.sql into the SQL editor and run.

# 4. Seed demo data
npm run db:seed

# 5. Build + inspect
npm run build
npm run inspect

MCP Inspector открывает интерфейс, в котором можно просматривать инструменты, вызывать их и видеть необработанные ответы.

Подключение к Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или в аналог на Windows/Linux:

{
  "mcpServers": {
    "belle-realty": {
      "command": "node",
      "args": ["/absolute/path/to/belle-mcp-server/dist/index.js"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}

Перезапустите Claude Desktop. Теперь вы увидите набор инструментов belle-realty. Попробуйте:

«Какие помещения в On The Boulevard сейчас заняты и какую ежемесячную аренду они приносят?»

Claude вызовет get_cost_roll и ответит на основе возвращённых данных.

Паттерн записи HITL

Единственный инструмент записи (draft_maintenance_response) иллюстрирует общий шаблон, который стоит копировать для любого сервиса, ориентированного на ИИ:

1. ИИ предлагает изменение — в данном случае ответ на заявку арендатора.

2. Сервер сохраняет предложение как approved=false.

3. Ничего не доставляется, не отправляется и не применяется, пока человек не одобрит это вне системы (обычно в админ-интерфейсе управляющего недвижимостью).

4. Поверхность MCP намеренно не предоставляет инструмента подтверждения. Одобрение — операция только для человека.

Это значит, что слишком старательный или агент с промпт-инъекцией не может молча отправить текст арендатору. Он может предлагать, и может предлагать громко. Но он не может отправить.

Подробное описание см. в docs/hitl-pattern.md.

Персональное использование

Вы частный арендодатель с 3 сдаваемыми домами или одним небольшим коммерческим зданием.

1. Запустите миграцию в своём проекте Supabase.

2. Наполните базу своими данными (отредактируйте supabase/seed.ts или добавьте строки вручную).

3. Подключите Claude Desktop к серверу.

4. Задавайте вопросы: «у какого арендатора заканчивается договор в течение 90 дней?» или «составь черновой ответ на заявку из тикета о водонагревателе».

Вы построили ИИ-нативный уровень операций с арендаторами, который говорит на вашем языке ваших данных. Это стоило вам одного вечера.

Корпоративное использование

Вы управляете Belle Realty (или аналогичной управляющей компанией). Несколько сотрудников нуждаются в доступе Claude к данным портфеля без прямого доступа к сырому SQL и без какого-либо риска случайных изменений.

1. Разверните этот сервер как постоянный процесс (Railway, Fly или Docker-хост).

2. Задайте MCP_TRANSPORT=http и MCP_HTTP_TOKEN=<shared-secret>.

3. Каждый коллега настраивает Claude Desktop или Cursor, используя URL и токен.

4. Инструменты только для чтения дают каждому рычаг влияния. Единственный инструмент записи защищает отношения с арендаторами.

5. mcp_audit_log дает вам задним числом записи каждого действия ИИ.

Архитектура

graph LR
    A[Claude Desktop / Cursor] -->|MCP stdio or HTTP| B[belle-mcp-server]
    B --> C[RateLimiter]
    B --> D[Zod validation]
    B --> E[Supabase Postgres]
    B --> F[mcp_audit_log]
    E --> G[(properties, tenants, leases, tickets)]

Подробности в docs/architecture.md.

Расширение

Добавьте новый инструмент за 4 шага:

1. Добавьте Zod-схему для входа в src/schemas/domain.ts (если форма данных новая).

2. Создайте src/tools/<name>.ts со схемой входных данных, обработчиком и определением JSON-Schema.

3. Зарегистрируйте его в src/tools/index.ts.

4. Добавьте тесты в tests/.

Каждый инструмент записи должен следовать шаблону «предложение-запись» из draft_maintenance_response.

Развертывание

Railway (рекомендуется для HTTP-транспорта)

railway up

railway.json собирает сервер и запускает node dist/index.js. Установите переменные окружения в панели Railway.

Локально (только stdio)

Просто соберите проект и укажите своему MCP-клиенту на dist/index.js. Никакого хостинга не требуется.

Разработка

npm run dev       # tsx watch mode
npm run test      # vitest
npm run build     # tsc → dist/
npm run inspect   # MCP Inspector UI

Связанные репозитории

• lease-abstractor — извлечение структурированного представления из договора аренды PDF/DOCX

• support-triage-agent — радиус той же схемы HITL к сообщениям поддержки

• diligence-agent — комплексная проверка на основе RAG по папке с документами

• ai-fluency-program — родительская программа обучения

Лицензия

MIT — см. LICENSE.

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