onehome-mcp

Fetch up to 200 OneHome listings in a single call. Returns one structured row per input id (no side-by-side summary table — use `onehome_compare_properties` for that). Each row is either `{ listing_id, status: "ok", property }` on success or `{ listing_id, status, error_kind, retryable, error }` on failure (`status` = `error_kind`: `timeout` / `bridge_down` / `pending` are retryable, `protocol` / `other` are real misses) — one bad id never fails the whole call. Calls fan out concurrently against `ListingById`, capped at 6 in flight to avoid swamping the bridge; transient timeouts are retried once per row before being captured as an error. The whole call is bounded by an overall deadline: any row still unsettled comes back `status: "pending"` with a top-level `pending` count — re-run just those ids. The envelope reports `count` / `ok` / `errored`. `extracted_features` is populated per row automatically. The raw `description` (PublicRemarks) is omitted by default — pass `include_description: true` to keep it. `group_id` defaults to the magic-link session context.

Solve for the maximum home price you can afford under the standard 28/36 DTI rule. Inputs: monthly income, recurring monthly debts (car loans, student loans, etc.), down payment, interest rate, and optional property-tax rate / insurance / HOA / loan term. Output: max home price, the binding constraint (front-end vs back-end), and the full PITI breakdown at that price. Same math across the realty MCP cohort (@chrischall/realty-core). No network — pure local math.

Local-only mortgage payment calculator. Returns a full PITI breakdown (principal + interest, property tax, insurance, HOA, PMI) and total interest over the life of the loan. No network call — fully deterministic, safe to use for scenario comparison without burning a fetch. Provide either `down_payment` OR `down_payment_percent`; defaults to 20%. Property tax can be given as `property_tax_annual` or `property_tax_rate` (% of home price). PMI applies automatically when LTV > 80% and `pmi_rate` is provided.

Fetch 2 or more OneHome listings and align their facts side-by-side. Each target may supply `listing_id` (preferred) or `url` (a portal URL). Returns the full per-property record (with `extracted_features` populated) per row. Per-target errors are captured per-row — one bad target will not fail the whole call. Calls are concurrent. The raw `description` is omitted from each row by default (`include_description: true` to keep it). The redundant `summary` table is also opt-in via `include_summary: true` — by default only `rows[]` is returned, which already carries every fact.

Resolve a free-text street address (with optional city/state/zip) to a OneHome listing's canonical portal URL and id in one call. Walks a 2-rung ladder: (1) `ListingSuggestionsSearch` against the magic-link saved-search scope; (2) when that misses, search-fallback — page-walks the broader saved-search (or raw `listings(groupId)`) pool bounded by the same `groupId` and fuzzy-matches input address tokens. Returns `{ url, listing_id, address, resolved, matched_via }` where `matched_via: "suggestions" | "search_fallback"` reports which rung produced the hit. When no listing matches, returns `{ resolved: false, error: "no listing found" }` rather than throwing. Read-only; safe to call repeatedly.

List the OneHome groups your agent has shared with you. Share member e-mails and the agent's e-mail/phones are omitted unless `include_contacts: true`. For full agent / registered users, returns the GraphQL `user.groups` list. For magic-link consumer-share sessions (a single shared group), synthesizes a one-entry list from the `checkToken` session context.

Fetch full details for a single OneHome listing by id or portal URL. Returns address, list / close / previous price, $/sqft, beds/baths/sqft, lot size (raw `lot_size` {area, units} plus the derived `lot_size_acres` — null, never 0, for condos / lotless listings), year built, lat/lng, status, HOA fee, annual tax, virtual-tour URL, the primary photo, and an `extracted_features` block (lake_front, hot_tub, basement, furnished, dock, community) keyword-parsed from the description. The raw `description` (PublicRemarks) is omitted by default — pass `include_description: true` to keep it; in most cases the extracted features cover what callers need. OneHome scopes every listing to a group/market — `group_id` defaults to the magic-link session context; pass it explicitly only if you need to query a different group.

Fetch the full media gallery for a OneHome listing. Returns one entry per image with Thumbnail / Medium / Large CDN URLs, dimensions, the listing-room description (LongDescription), and display order. Pass either `listing_id` or a portal URL.

Fetch the agent-curated saved search by its id (UUID). Returns the search's name, filter criteria (`filters[]`), polygon, listing count, and the full list of OSK listing ids that compose the consumer share (`listing_ids`). Pass `include_listing_ids: false` to suppress the listing-id array if you only need the metadata. This is the canonical consumer-readable endpoint; the by-groupId variant is agent-only. `saved_search_id` defaults to the MCP's session context when omitted.

Combo tool: the "show me my saved homes" flow in a single round trip. Internally runs `GetSavedSearchBySearchId` to fetch the saved search (name, filters, polygon, listingIds) and then `GetSavedListings` to inflate those listingIds into full property records — the same two-call sequence as calling `onehome_get_saved_search` followed by `onehome_search_properties(saved_search_id=...)`, but exposed as one tool so the magic-link-to-listings consumer flow is a single MCP call. Returns `{ saved_search, listings, count, page_info }`. Both `saved_search_id` and `group_id` default to the magic-link session context. Sort defaults to `property.MajorChangeTimestamp DESC` (Newest). Listings are returned via the GraphQL listing-card projection (`buildGetSavedListings`), which does NOT include `PublicRemarks` — so there is no raw `description` to opt back into here. Use `onehome_get_property(listing_id)` per row when you need the full description for a specific listing.

Fetch the Local-Logic school data for a coordinate — separate primary and high-school lists, each entry with name, attributes (types/grades/programs/levels), and proximity (walking distance + straight-line distance). Returns an `error` field with HTTP details if the consumer session does not have access (the schools endpoint is sometimes agent-only). lat/lng usually come from `onehome_get_property` (`latitude` / `longitude`).

Returns one entry per registered session — its `session_id`, auth_mode, token expiry, and session scope (group_id / saved_search_id / agent_id / contact_id / mls_id) the MCP bootstrapped from each checkToken exchange. `active_session_id` flags which session answers by default; per-listing routing uses the active session when its `mls_id` matches the listing's `~MLS` suffix, else the one session that matches (several matches error — pick one with `onehome_set_active_session`). Tools default unspecified `group_id` / `saved_search_id` arguments from the active session's context, so this is the easiest way to see what they'll default to. Single-session use (the common case) returns a one-entry `sessions[]`.

Returns the OneHome user profile + the consumer-share groups attached. Share member e-mails and the agent's e-mail/phones are omitted unless `include_contacts: true`. For full agent / registered users, queries the GraphQL `user` endpoint. For magic-link consumer-share sessions (where `user { }` is access-denied), falls back to the data captured during the `checkToken` exchange — email, contact id, group/savedSearch ids, and the agent who shared with you.

Local-Logic location scores for a coordinate — pedestrian / car / cycling / transit friendliness, plus proximity summaries for groceries, restaurants, parks, primary + high schools. Each score is a `{ value, text }` pair (value 0-5, text a one-line description). Returns an `error` field with HTTP details if the upstream rejected the request.

Power-user escape hatch — send a raw GraphQL document with variables. Returns the whole `{ data, errors, status, url }` envelope, unprojected, so you can read upstream schema errors directly. Note the default: `view` is `compact`, which strips image/avatar URLs out of `data` (every envelope key and every non-media field is kept). Pass `view: 'full'` when you need the envelope byte for byte — worth doing if you are here because a payload is not what you expected, so a missing field is never this server's doing. Operation names live in the portal bundle; common ones include `GetOneHomeUser`, `GetListings`, `GetPins`, `ListingById`, `MediaListingById`, `GetSavedSearches`, `ListingSuggestionsSearch`. (LocalLogic schools/walk-score are REST endpoints, not GraphQL operations — use `onehome_get_schools` / `onehome_get_walk_score`.) Pass `query` (the full document body), an `operation_name` matching the document, and any `variables` as JSON. Read-only: documents containing a `mutation` or `subscription` operation — or that cannot be parsed as a read-only `query` document — are refused.

Round-trip a minimal authenticated query through the configured transport. Picks `GetSavedSearchBySearchId` for magic-link consumer-shares (works for them) or `GetOneHomeUser` for agent/registered sessions. Returns the auth mode, token expiry, fetchproxy bridge role (when applicable), elapsed time, and any error detail. Run this first when a tool fails — it isolates "is auth wired up?" from "is the API itself misbehaving?".

Resolve up to 100 structured addresses to OneHome canonical portal URLs + listing OSK ids in one call. Each input is a `{address, city?, state?, zip?}` object. Output preserves input order; one row per input, either `{resolved: true, url, listing_id, address}` or `{resolved: false, error, query}`; a row that failed (rather than genuinely missed) also carries `status` = `error_kind` and `retryable` — `timeout` / `bridge_down` / `pending` mean retry it, not "no listing". The whole call is bounded by an overall deadline; unsettled rows come back `status: "pending"` with a top-level `pending` count. Walks the exact same 2-rung ladder as `onehome_get_by_address` via the shared helper (rung 1: `ListingSuggestionsSearch` against the magic-link saved-search scope; rung 2: search-fallback page-walking the broader saved-search / raw-listings pool bounded by `groupId`) — bulk and single cannot diverge. Each row surfaces `matched_via: "suggestions" | "search_fallback"` so callers see which rung produced the hit. Concurrent fan-out capped at 6 in flight to avoid swamping the upstream. Per-row errors captured — one bad address never fails the whole batch. `group_id` defaults to the magic-link session context. Read-only; safe to call repeatedly.

Fetch listings inside a OneHome consumer-share. Two modes: - With `saved_search_id`: fetch the agent-curated collection (the standard 'Homes at <name>' view). The MCP first resolves the saved search's listingIds and then inflates them via listingsBySavedSearchId — this is the only mode that works for non-agent consumer accounts. - With just `group_id` and no `saved_search_id`: try the raw `listings(groupId, browseParameter)` endpoint. If page 0 comes back empty with no reported results (the access-restricted shape consumer-shares hit) AND the session context has a `savedSearchId` for that same group, the tool falls back to the saved-search path and marks the response `fell_back_to_saved_search: true`. If there's no fallback target it raises a clear error rather than silently returning empty. An empty later page (paging past the end) is returned as an empty page, never swapped for the saved-search collection. Both args default from the MCP's bootstrapped session context (the magic-link checkToken response) when neither is passed explicitly. Sort is `MajorChangeTimestamp DESC` ('Newest') unless overridden. `include_dislikes: false` by default — flip it on to include listings you've thumbs-downed in OneHome. Listings here are returned via the GraphQL listing-card projection, which does NOT include `PublicRemarks` — so there is no `description` field on search results and no `include_description` flag to opt into one. Each listing carries the structured `extracted_features` object instead. Use `onehome_get_property(listing_id)` per row when you need the full description for a specific listing.

Cross-feed suggestion search by address, MLS number, or partial query. Bypasses the group/saved-search structure and hits the global suggestion endpoint — useful for "find an address" or "look up by MLS number". Returns id, address parts, beds/baths, list price, thumbnail per match. Inflate any result with `onehome_get_property`. Optional `group_id` scopes suggestions to one OneHome market.

Force a specific registered session to be the active one. Useful when MLS-suffix routing picks the wrong session (e.g. two shares in the same MLS, a free-text search across multiple MLSes, or a listing without a `~MLS` suffix). Pass a `session_id` previously returned by `onehome_set_auth` or surfaced in `onehome_get_session_context`. The active session answers any request without a `~MLS`-suffixed listing id AND any `~MLS` request whose MLS matches its own; a `~MLS` id matching several other sessions errors until you pick one here.

Provide a magic-link URL, a raw JWT bearer, or an email-token to ADD another authenticated session to the MCP — useful when a buyer holds shares across multiple agents/MLSes (one magic link per share). The MCP detects the input shape (URL → extract `?token=`; 3-segment JWT → use directly; otherwise → treat as email-token and exchange via `/api/authentication/checkToken`), registers a new direct-bearer transport, and marks it active. Previously-registered sessions stay registered — switch back with `onehome_set_active_session(session_id)`, or let MLS-suffix routing (`~CANOPY`, `~HCAOR`, …) pick automatically per listing. The response includes the assigned `session_id`, the new `active_session_id`, the auth_mode/status, the session_context the checkToken response yielded, and a `bearer_fingerprint` of the resolved JWT (first 8 + `…` + last 4 chars) — never the full bearer. SECURITY: the input itself sits in your chat history; treat magic links as short-lived credentials.