홈 서비스 검색, 제공업체 프로필 및 리뷰, 주택 소유자 신원, 예약 요청, 예약 후속 조치를 위한 오픈소스 자체 호스팅 가능 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: @qasperai/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-mcpAWS SAM의 경우 매개변수 재정의 또는 시크릿 관리자를 통해 배포별 값을 제공하세요. template.yaml, samconfig 파일, 컨테이너 레이어 또는 소스 제어에 시크릿을 넣지 마세요.
.env.example에서 시작하세요. 빈 선택적 엔드포인트 변수는 관련 기능을 비활성화합니다. 업스트림 MCP 릴레이가 예외입니다. 문서화된 공개 호스팅 서비스를 기본값으로 사용하며 재정의할 수 있습니다.
핵심 운영자 소유 엔드포인트:
변수 | 용도 |
| 제공업체 검색 엔드포인트 |
| 텍스트/좌표 위치 확인자 |
| 우편번호 위치 확인자 |
| 선택적 주소 보강 통합 |
| 제공업체 프로필 및 리뷰 엔드포인트 |
| 예약/요청 생성 엔드포인트 |
| 예약 내역/상태 엔드포인트 |
| 알림 메타데이터용 선택적 엔드포인트 |
| 선택적 전화/프로필 조회 엔드포인트 |
| 선택적 OTP 전송/확인 엔드포인트 |
| 선택적 토큰 기반 프로필 엔드포인트 |
| 선택적 인증 및 소유권 확인 기반 취소 엔드포인트 |
선택적 통합에는 알림 엔드포인트, 운영자 영속성, 모니터링 웹훅, OAuth, OpenAI 앱 검증 챌린지가 포함됩니다. 모든 URL과 시크릿은 운영자가 제공해야 합니다.
OAuth가 활성화되면 액세스 토큰과 리프레시 토큰은 별도의 ES256 서명 키를 사용합니다. 액세스 토큰 공개 검증 키는 메타데이터 jwks_uri를 통해 노출됩니다. OAUTH_ALLOWED_REDIRECT_URIS를 클라이언트가 사용하는 정확한 호스팅 또는 클레임된 스킴 콜백으로 설정하세요. 네이티브 클라이언트는 localhost, 127.0.0.1 또는 [::1]에서 임의의 명시적 포트로 HTTP 루프백 콜백을 등록할 수 있습니다. 네이티브 앱은 일반적으로 임시 포트에 바인딩하므로 이러한 콜백을 열거할 필요가 없습니다. 다른 사용자 정의 스킴(임의의 cursor:// 또는 vscode:// 콜백 포함)은 전체 URI가 명시적으로 구성되지 않는 한 거부됩니다. 동적 등록만으로는 비공개 스킴의 소유권을 증명할 수 없기 때문입니다. OAUTH_DYNAMIC_CLIENT_REGISTRATION_ENABLED를 활성화하면 공개 PKCE 클라이언트가 /oauth/register에서 고유한 영속 클라이언트 ID를 얻을 수 있습니다. 레거시 구성 클라이언트 ID와 미등록 PKCE 클라이언트는 계속 지원됩니다.
OAUTH_CLIENT_SECRET에는 최소 32바이트의 암호학적 난수를 사용하세요. 서버는 해당 시크릿에서 도메인 분리된 ES256 키를 파생하므로 무상태 인스턴스가 리프레시 토큰 서명에 재사용하지 않고 동일한 액세스 토큰 키를 게시하고 검증할 수 있습니다. OAuth 토큰은 불투명한 주택 소유자 세션 ID를 전달하며, 프로필 PII와 업스트림 베어러 자격 증명은 서버 측 상태 저장소에 유지됩니다.
기본적으로 서버는 /upstream/mcp의 요청을 https://mcp.hirenimbus.com/mcp로 릴레이합니다. UPSTREAM_MCP_URL을 설정하여 운영자가 제어하는 MCP 서비스를 대신 사용하세요. 선택한 업스트림이 인증을 요구하는 경우 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 폴백은 의도적인 예외이며 자격 증명이나 고객 데이터를 포함하지 않습니다.
This server cannot be deployed
Book local tradespeople — plumber, electrician, HVAC, and 7 more — via your AI agent. All US.
Verified local businesses, bookable by AI agents: services, prices, availability and appointments.
Agent-first booking of home-service contractors in Canada and the US: quotes, availability, booking.
Search & install 13,000+ AI agent skills from skills-hub.ai inside any MCP tool.
