HireNimbus MCP Server

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.

Variable	Purpose
PROVIDERS_API	Provider search endpoint
REVIEWS_API	Provider profile & reviews base URL
BOOKING_API	Job creation endpoint
COORDS_RESOLVE_API	City/text to coordinates resolution
ZIP_RESOLVE_API	ZIP to city resolution
SEND_BOOK_NOTIFICATION_API	SMS notification to homeowner
SEND_JOB_TO_SLACK_API	Slack job alerts
MCP_MONITOR_ENABLED	Post MCP auth/tool events to Slack (default: true)
MCP_MONITOR_SLACK_CHANNEL	Slack channel for MCP monitor events (default: mcp-monitor)
MCP_MONITOR_SLACK_API	Slack webhook for monitor events (defaults to SEND_JOB_TO_SLACK_API)
OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET	Enable OAuth2 (both must be set)
OAUTH_TOKEN_TTL	Access token lifetime in seconds (default: 3600)
RATE_LIMIT_RPM	Requests per minute per IP (default: 60, 0 = off)
PUBLIC_BASE_URL	Canonical public URL for OAuth issuer/audience

---

MCP Tools

Implemented

search_providers

Search for home service professionals near a location.

Parameter	Type	Required	Description
query	string	Yes	Service keyword — "plumber", "HVAC repair", "house cleaning"
location	object	Yes	One of: {"text": "Alexandria, VA"}, {"zip": "22314"}, or {"lat": 38.8, "lng": -77.0}
page	int	No	Pagination page (default: 1)
limit	int	No	Results count (default: 6)

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.

Parameter	Type	Required	Description
slug	string	Yes	Provider slug from search_providers results

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.

Parameter	Type	Required	Description
slug	string	Yes	Provider slug from search_providers results
page	int	No	Pagination page (default: 1)
page_size	int	No	Reviews per page, 1–10 (default: 5)

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.

Parameter	Type	Required	Description
serviceProviderSlug	string	Yes	Provider slug
name	string	Yes	Homeowner full name
phone	string	Yes	Homeowner phone
job_description	string	Yes	Detailed description of work needed
address	object	Yes	Must include address1, city, region, postalCode
source	string	No	AI assistant name (default: "AI Assistant")
location	object	No	Optional geocoding hint (same format as search_providers)

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.

Parameter	Type	Required	Description
job_id	string	Yes	Job identifier from create_booking
amount	number	Yes	Payment amount in USD
payment_method	string	Yes	One of: card_on_file, new_card, bank_transfer
card_token	string	No	Required when payment_method is new_card

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.

Parameter	Type	Required	Description
invoice_id	string	Yes	Invoice identifier
action	string	Yes	One of: approve, reject, request_revision
notes	string	No	Homeowner comments or reason for rejection

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.

Parameter	Type	Required	Description
serviceProviderSlug	string	Yes	Provider slug
job_id	string	No	Existing job ID (if scheduling for an already-booked job)
preferred_date	string	Yes	ISO 8601 date (2025-03-28)
preferred_time_slot	string	Yes	One of: morning, afternoon, evening, or specific time like 14:00
notes	string	No	Special instructions (access codes, pet info, etc.)

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.