# NannyFYI LLM Integration Reference

## Product Summary
NannyFYI is a bilingual (English + Chinese) childcare marketplace and profile platform for nannies, confinement nannies (月嫂 / yuesao), and doulas across North America, with public reviews, public job posts, skills assessments, and certificate verification.

## Domains
- Primary (Canonical): https://nanny.fyi

## Discovery URLs
- Sitemap: https://nanny.fyi/sitemap.xml
- Robots: https://nanny.fyi/robots.txt
- Agent setup (EN): https://nanny.fyi/en/agentic
- Agent setup (ZH): https://nanny.fyi/zh/agentic
- MCP Docs (EN): https://nanny.fyi/en/mcp
- MCP Docs (ZH): https://nanny.fyi/zh/mcp

## MCP Endpoint
- URL: `https://nanny.fyi/api/mcp`
- Transport: Streamable HTTP
- Protocol: JSON-RPC 2.0
- MCP protocol version: `2024-11-05`
- Server: `nanny-fyi-mcp` v1.0.0
- All tools are read-only.

## Supported RPC Methods
- `initialize`
- `notifications/initialized`
- `ping`
- `resources/list`
- `resources/read`
- `prompts/list`
- `prompts/get`
- `tools/list`
- `tools/call`

## Prompt Templates
Prebuilt prompts (via `prompts/list` / `prompts/get`) that map common intents to the tools:
- `find_local_nanny` (args: city, state, serviceCategory?, language?)
- `summarize_nanny_reviews` (args: serviceProviderId, locale?)
- `compare_nannies` (args: ids — comma-separated)
- `verify_nanny_certificate` (args: certificateId)
- `vet_a_nanny` (args: city, state, serviceCategory?)

## Tool Catalog

### `find_nannies`
Find nanny profiles near a location. For nearby requests, provide city + state (or lat/lon) and optionally distance in miles. Returns an interactive results widget where supported (ChatGPT apps / OpenAI Apps SDK).

Arguments:
- `top` (number, default 10, max 30)
- `country` (string, e.g. `US`, `CA`)
- `state` (string, recommended for nearby queries)
- `city` (string, recommended for nearby queries, e.g. `Sunnyvale`)
- `lat`/`lon` (number) — explicit coordinates
- `distance` (number, miles; defaults to 30 when a location is provided)
- `language` (string) — filter by spoken language
- `placeOfBirth` (string)
- `yob` (number) — year threshold for date-of-birth filtering
- `serviceCategory` (string) — group (`yuesao`, `nanny`, `doula`) or a flat category (`live-in-yuesao`, `live-out-yuesao`, `live-in-nanny`, `live-out-nanny`, `birth-doula`, `postpartum-doula`)

### `search_nannies`
Search public nanny profiles by partial name or pinyin/name keyword. Phone and WeChat fragment search are intentionally not supported.

Arguments:
- `query` (string, required) — partial name or pinyin keyword
- `top` (number, default 10, max 20)

### `get_nanny_profile`
Fetch a single public nanny profile by service provider ID, including profile metadata, contact details, and certifications.

Arguments:
- `id` (string, required) — service provider profile ID

### `get_nanny_reviews`
Get recent free public reviews for a nanny profile, plus a count/link for older locked reviews.

Arguments:
- `serviceProviderId` (string, required)
- `limit` (number, default 10, max 20)
- `locale` (string, `en` or `zh`) — locale for the returned review-section URL

### `list_job_posts`
List public active job posts and nanny looking-for-work posts. Posting and payments happen only on NannyFYI pages.

Arguments:
- `count` (number, default 20, max 50)

### `get_market_stats`
Aggregate, privacy-safe market statistics for caregivers in an area (no individual profile data). Returns total count, verified share, review volume and average caregiver rating, count of caregivers with a skills certificate, and breakdowns by service category and language. Omit location for nationwide stats. Provide city + state together (or lat + lon together) — partial pairs are rejected.

Arguments (all optional):
- `country` (string, e.g. `US`, `CA`)
- `state` (string), `city` (string) — provide together for a local radius
- `lat`/`lon` (number) — explicit coordinates; use instead of city/state, not together
- `distance` (number, miles; defaults to 30 when a location is provided)
- `serviceCategory` (string) — group or flat category (same values as find_nannies)
- `language` (string)

### `verify_certificate`
Verify a NannyFYI skills certificate by ID and return title, level, holder name, and expiration status.

Arguments:
- `certificateId` (string), or
- `id` (string alias)

## Example Requests

Initialize:
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05"
  }
}
```

List tools:
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}
```

Call `find_nannies`:
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "find_nannies",
    "arguments": {
      "top": 5,
      "country": "US",
      "state": "CA",
      "city": "Sunnyvale",
      "distance": 30,
      "language": "Mandarin"
    }
  }
}
```

Call `search_nannies`:
```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "search_nannies",
    "arguments": {
      "query": "Lily Chen",
      "top": 5
    }
  }
}
```

Call `get_nanny_profile`:
```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "get_nanny_profile",
    "arguments": {
      "id": "6366c7c954c9536d6c04bc35"
    }
  }
}
```

Call `get_nanny_reviews`:
```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "get_nanny_reviews",
    "arguments": {
      "serviceProviderId": "6366c7c954c9536d6c04bc35",
      "limit": 10,
      "locale": "en"
    }
  }
}
```

Call `list_job_posts`:
```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "list_job_posts",
    "arguments": {
      "count": 20
    }
  }
}
```

Call `get_market_stats`:
```json
{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "get_market_stats",
    "arguments": {
      "city": "Sunnyvale",
      "state": "CA",
      "serviceCategory": "yuesao",
      "distance": 30
    }
  }
}
```

Call `verify_certificate`:
```json
{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "verify_certificate",
    "arguments": {
      "certificateId": "ABCD1234"
    }
  }
}
```

## Public Content Focus
For web retrieval outside MCP, prefer:
- `/en/serviceProvider/*` and `/zh/serviceProvider/*` (profiles)
- `/en/serviceProvider/nanny`, `/en/serviceProvider/yuesao`, `/en/serviceProvider/doula` (category directories; same paths under `/zh`)
- `/en/skills` and `/zh/skills` (skills assessments + certificates)
- `/en/request/list` and `/zh/request/list` (public job posts)

## Safety and Scope
- All MCP tools are read-only; keep responses grounded in public profile / certificate / review / job-post data.
- Do not infer private contact details beyond publicly exposed fields.
- Do not initiate write actions (posting, payments, edits) — those happen only on NannyFYI pages and require the user to act there.
- Respect locale preference (`en` or `zh`) for final user-facing output.