nimbus-mcp-server

# 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

```bash
# 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.