Home Services MCP 서버

홈서비스 발견, 제공업체 프로필 및 리뷰, 주택 소유자 신원, 예약 요청, 예약 후속 조치를 위한 오픈소스 자체 호스팅 가능 Model Context Protocol 서버입니다. 이 서버는 워크플로우와 MCP 인터페이스를 제공하며, 각 운영자가 API, 데이터, 자격 증명, 브랜딩, 배포 환경을 제공합니다.

이 저장소에는 고객 데이터, 제공업체 데이터, API 키 또는 비공개 프로덕션 엔드포인트가 포함되어 있지 않습니다. 편의를 위해 문서화된 공개 호스팅 MCP 폴백 하나가 포함되어 있으며, 운영자는 자체 엔드포인트와 자격 증명으로 교체하여 완전히 자체 호스팅된 배포를 구성할 수 있습니다.

포함 내용

• /mcp의 Streamable HTTP MCP 전송(루트 엔드포인트도 이를 요구하는 클라이언트를 위해 매핑됨).

• OAuth 자격 증명이 구성된 경우 PKCE를 사용한 OAuth 2.0 인증 코드 흐름.

• 제공업체 검색, 상세 정보, 리뷰, 주택 소유자 프로필, 예약, 이전 작업, 예약 상태, 재예약 워크플로우.

• 선택적 카테고리별 찾기/예약 도구 별칭.

• 입력 검증, 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로 릴레이합니다. 운영자가 제어하는 MCP 서비스를 대신 사용하려면 UPSTREAM_MCP_URL을 설정하세요. 선택한 업스트림에 인증이 필요한 경우 UPSTREAM_MCP_AUTH_TOKEN을 설정하세요. 토큰은 번들로 제공되지 않으며, 인바운드 클라이언트 권한 부여는 자동으로 전달되지 않습니다.

사용자 요청을 보내기 전에 선택한 업스트림의 데이터 처리, 보존, 약관 및 액세스 정책을 검토하세요. 완전히 자체 호스팅된 배포의 경우 기본 업스트림을 교체하고 운영자 소유 비즈니스 API를 구성하세요.

보안 및 데이터 소유권

이 서버는 프로그래밍 가능한 통합 계층이지, 내장 테넌트가 있는 데이터 프로세서가 아닙니다. 운영자는 다음에 대한 책임이 있습니다:

• API 권한 부여, 테넌트 격리, 데이터 보존, 백업 및 삭제;

• 비밀 저장, 순환, 최소 권한 범위 및 프로덕션 네트워크 정책;

• 개인정보 고지, 약관, 지원 연락처, 지역/법적 요구 사항 및 제3자 처리 공개;

• 구성된 API가 MCP 클라이언트가 필요로 하는 것보다 더 많은 개인 정보를 반환하지 않는지 확인.

기본 개발 구성은 외부 비즈니스 API를 비워 둡니다. 프로덕션 배포는 필수 기능이 구성되지 않은 경우 실패 시 닫히고(fail closed), OAuth 및 멱등성을 위해 영구 공유 상태를 사용하며, 엔드포인트가 명시적으로 구성되지 않은 한 모니터링을 비활성화 상태로 유지해야 합니다. 다중 인스턴스 OAuth 또는 예약 워크로드의 경우 AUTH_STATE_TABLE_NAME을 공유 DynamoDB 테이블로 설정하고 REQUIRE_DURABLE_STATE=true로 설정하세요. 이러한 설정이 없으면 개발 폴백은 프로세스 로컬이며 교차 인스턴스 재생 방지를 제공하지 않습니다.

확인된 예약 호출은 선택적 클라이언트 생성 멱등성_키(idempotency_key)를 허용합니다. 클라이언트는 시간 초과 후 해당 키를 재사용해야 합니다. 구성된 예약 API도 동일한 필드를 준수해야 합니다. 서버는 모호한 예약 요청을 자동으로 재시도하지 않습니다.

테스트

개발 종속성을 설치하고 실행하세요:

pytest -q
ruff check .

테스트는 외부 통합에 목(mock) 또는 로컬 픽스처를 사용해야 합니다. 라이브 운영자 엔드포인트를 호출해서는 안 됩니다.

마켓플레이스 패키지

서버와 이식 가능한 워크플로우 스킬은 호스팅된 배포와 독립적입니다. 퍼스트파티 배포는 자체 호스팅 MCP URL과 브랜드 앱을 가리키는 별도의 마켓플레이스 매니페스트를 추가할 수 있으며, 이러한 값을 이 저장소에 넣을 필요는 없습니다.

이식 가능한 홈서비스 워크플로우는 skills/home-service-concierge/SKILL.md에서 확인할 수 있습니다. 앱 핸드오프는 운영자가 구성한 APP_LINK 값을 사용합니다.

라이선스

Apache License 2.0에 따라 라이선스가 부여됩니다. 제품 이름, 상표, 비공개 서비스 및 운영자 통합은 이 코드베이스의 기본값으로 포함되지 않습니다. 문서화된 공개 호스팅 MCP 폴백은 의도적인 예외이며 자격 증명이나 고객 데이터를 포함하지 않습니다.