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.

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

Related MCP server: NDI-MCP-Server

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

Каждый вызов ограничен по частоте (по умолчанию 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.

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