Home Services MCP Server

Открытый сервер Model Context Protocol с возможностью самостоятельного размещения для поиска домашних услуг, профилей и отзывов поставщиков, идентификации домовладельцев, запросов на бронирование и последующего сопровождения бронирований. Сервер предоставляет рабочий процесс и интерфейс MCP; каждый оператор предоставляет API, данные, учетные данные, брендинг и среду развертывания.

Этот репозиторий не содержит данных клиентов, данных поставщиков, ключей API или частных производственных конечных точек. Для удобства в него включен один документированный публичный размещенный резервный вариант MCP; операторы могут заменить его собственными конечной точкой и учетными данными для полностью самостоятельного развертывания.

Что включено

• Потоковый HTTP-транспорт MCP по адресу /mcp (корневая конечная точка также сопоставлена для клиентов, которым это требуется).

• Поток авторизации OAuth 2.0 с кодом авторизации и PKCE, если настроены учетные данные OAuth.

• Рабочие процессы поиска поставщиков, сведений о них, отзывов, профиля домовладельца, бронирования, предыдущих работ, статуса бронирования и повторного бронирования.

• Необязательные псевдонимы инструментов поиска/бронирования для конкретных категорий.

• Проверка входных данных, журналирование с учетом PII, разрешение исходящих хостов, ограничение частоты запросов и поведение автоматического выключателя.

• Локальная разработка ASGI, универсальный образ Docker и конфигурация развертывания AWS SAM/Lambda.

Публичный контракт MCP намеренно стабилен. Операторы могут заменять серверные части, не меняя видимые клиенту имена инструментов или семантику рабочих процессов.

Related MCP server: Home Assistant MCP Server

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

python3.10 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# The default setup uses the hosted MCP relay. For self-hosting, edit .env
# with your own upstream MCP endpoint, API URLs, and credentials.
uvicorn src.main:app --reload --port 8000

После этого сервер доступен по адресу http://localhost:8000/mcp.

Перед открытием релиза или проверки в маркетплейсе выполните проверки из docs/RELEASE_CHECKLIST.md, включая:

python3 scripts/audit_public_release.py

Для сборки контейнера:

docker build -t home-services-mcp .
docker run --env-file .env -p 8000:8080 home-services-mcp

Для AWS SAM укажите значения, специфичные для развертывания, через переопределения параметров или ваш менеджер секретов. Не размещайте секреты в template.yaml, файлах samconfig, слоях контейнера или в системе контроля версий.

Конфигурация

Начните с .env.example. Пустые необязательные переменные конечных точек отключают соответствующую возможность. Исключением является вышестоящий ретранслятор MCP: по умолчанию он использует документированный публичный размещенный сервис и может быть переопределен.

Основные конечные точки, принадлежащие оператору:

Необязательные интеграции включают конечные точки уведомлений, постоянное хранилище оператора, вебхуки мониторинга, OAuth и проверочный вызов приложения OpenAI. Все URL-адреса и секреты должны быть предоставлены оператором.

Вышестоящий ретранслятор MCP

По умолчанию сервер ретранслирует запросы с /upstream/mcp на https://mcp.hirenimbus.com/mcp. Установите UPSTREAM_MCP_URL, чтобы вместо этого использовать MCP-сервис, контролируемый оператором. Если выбранный вышестоящий сервис требует аутентификации, установите UPSTREAM_MCP_AUTH_TOKEN; токен не входит в комплект, и входящая авторизация клиента никогда не пересылается автоматически.

Перед отправкой пользовательских запросов ознакомьтесь с обработкой данных, хранением, условиями и политикой доступа выбранного вышестоящего сервиса. Для полностью самостоятельного развертывания замените вышестоящий сервис по умолчанию и настройте бизнес-API, принадлежащие оператору.

Безопасность и владение данными

Сервер — это программируемый интеграционный слой, а не обработчик данных со встроенным арендатором. Операторы несут ответственность за:

• авторизацию API, изоляцию арендаторов, хранение данных, резервное копирование и удаление;

• хранение секретов, их ротацию, области с минимальными привилегиями и политику производственной сети;

• уведомления о конфиденциальности, условия, контакты поддержки, региональные/юридические требования и любые раскрытия обработки третьими сторонами;

• подтверждение того, что настроенные API не возвращают больше личной информации, чем необходимо MCP-клиенту.

Конфигурация разработки по умолчанию оставляет внешние бизнес-API пустыми. Производственные развертывания должны закрываться при сбое, если требуемая возможность не настроена, использовать устойчивое общее состояние для OAuth и идемпотентности и держать мониторинг отключенным, если его конечная точка явно не настроена. Установите AUTH_STATE_TABLE_NAME на общую таблицу DynamoDB и REQUIRE_DURABLE_STATE=true для многоэкземплярных рабочих нагрузок OAuth или бронирования. Без этих настроек резервный вариант разработки является локальным для процесса и не обеспечивает защиту от повторного воспроизведения между экземплярами.

Подтвержденные вызовы бронирования принимают необязательный созданный клиентом idempotency_key. Клиенты должны повторно использовать этот ключ после тайм-аута. Настроенный API бронирования также должен учитывать то же поле; сервер никогда не повторяет неоднозначный запрос бронирования автоматически.

Тестирование

Установите зависимости для разработки и выполните:

pytest -q
ruff check .

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

Пакет для маркетплейса

Сервер и переносимые навыки рабочих процессов не зависят от какого-либо размещенного развертывания. Распространение от первого лица может добавить отдельный манифест маркетплейса, указывающий на собственный размещенный URL MCP и фирменное приложение, не помещая эти значения в этот репозиторий.

Переносимый рабочий процесс домашних услуг доступен по адресу skills/home-service-concierge/SKILL.md. Его передача в приложение использует значение APP_LINK, настроенное оператором.

Лицензия

Лицензировано в соответствии с Apache License 2.0. Названия продуктов, товарные знаки, частные сервисы и интеграции операторов не включены в этот код как значения по умолчанию. Документированный публичный размещенный резервный вариант MCP является намеренным исключением и не включает учетные данные или данные клиентов.