HireNimbus home services MCP

Model Context Protocol server that connects AI assistants (Claude, ChatGPT, Gemini) to the HireNimbus home-services marketplace. Enables provider search, review aggregation, homeowner profile retrieval, and job booking — all through natural conversation.

Architecture

• Runtime: Python 3.10, FastAPI, FastMCP (mcp 1.26.0)
• Transport: Streamable HTTP at /mcp (rewritten from / for root-level MCP clients)
• Deploy: AWS Lambda (arm64) via SAM + Docker container image; Mangum ASGI adapter
• Auth: Optional OAuth2 with JWT Bearer tokens; rate limiting per IP

Quick Start

# 1. Local secrets (gitignored — never commit)
cp local.config.example.json local.config.json
# Edit local.config.json with your values (or use .env — see .env.example)

# 2. SAM deploy overrides (ECR image URI — gitignored)
cp samconfig.local.toml.example samconfig.local.toml
# Edit samconfig.local.toml with your AWS ECR repository

# Build & deploy to AWS (local)
sam build && sam deploy --config-file samconfig.toml --config-file samconfig.local.toml

# Local development
pip install -r requirements.txt
uvicorn src.main:app --reload

GitHub Actions auto-deploy on main uses repository secrets (see internal deploy docs).

Configuration

Sensitive values live in local.config.json (gitignored) or environment variables. Copy local.config.example.json → local.config.json and fill in your values. Env vars always take precedence.

Public defaults remain in code for shared HireNimbus API endpoints (service.hirenimbus.com). URLs, tokens, and credentials must be set explicitly.

MCP Tools

Implemented

search_providers

Search for home service professionals near a location.

Returns: providers list (name, slug, profile_url, rating, reviews_count, highlights) + resolved_location.

get_provider_details

Full profile for a single provider — bio, services, areas, hours, FAQ, photos.

Returns: name, about, profile_url, profile_image_url, primary_service, services_offered, operational_areas, rating, reviews_count, hours_of_operation, faq, media_count, booking_supported.

get_provider_reviews

Aggregated reviews from Google, Yelp, Thumbtack, HomeAdvisor, and Nimbus.

Returns: reviews list (reviewer_name, date, rating, comment, source), stats (avg_rating, total_reviews), pagination, profile_url.

get_homeowner_profile

Returns the OAuth-linked homeowner's saved name, phone, and address. No parameters — identity comes from the JWT session.

Returns: connected, name, phone, address, source, tool_sourced_only.

create_booking

Submit a job request to a provider. Triggers instant SMS + Slack notification.

Returns: status, job_id, message, details (notification delivery status).

Planned Tools

process_payment

Process a payment for a completed or quoted job through the Nimbus platform.

Expected returns: status (success/pending/failed), transaction_id, receipt_url, message.

Typical flow: After a provider sends an estimate through Nimbus, the homeowner confirms the amount and the assistant processes payment via this tool. Supports saved payment methods and one-time card tokens.

approve_invoice

Review and approve (or reject) an invoice submitted by a service provider.

Expected returns: status, invoice_id, updated_amount, provider_notified, message.

Typical flow: The assistant retrieves pending invoices for the homeowner, presents line items and totals, and lets the homeowner approve, reject, or request changes — all conversationally.

schedule_appointment

Book a specific date and time slot with a provider for an existing or new job.

Expected returns: status (confirmed/pending_provider), appointment_id, confirmed_datetime, provider_notified, message.

Typical flow: After booking a job, the homeowner asks "Can I get this done Friday morning?" — the assistant checks provider availability and locks in a time slot, notifying both parties.

Typical Conversation Flow

User: "I need a plumber in Alexandria, VA"
  -> search_providers(query="plumber", location={"text": "Alexandria, VA"})

User: "Tell me more about the first one"
  -> get_provider_details(slug="...")

User: "What do people say about them?"
  -> get_provider_reviews(slug="...")

User: "Book them for a leaking faucet"
  -> get_homeowner_profile()          # load saved name/phone/address
  -> [confirm with user]
  -> create_booking(...)              # submit job + notify provider

User: "Schedule it for Friday morning"
  -> schedule_appointment(...)        # (planned)

User: "They sent an invoice — looks good, approve it"
  -> approve_invoice(...)             # (planned)

User: "Pay with my card on file"
  -> process_payment(...)             # (planned)

License

This repository is source-available under the HireNimbus Demo Software License. It is provided for demo, reference, and evaluation purposes only. It is not open source and is not licensed for commercial, production, hosted, or competitive use.