{"title":"Johnson Bros. Plumbing MCP Integration Guide","version":"1.0.0","description":"AI-accessible plumbing service discovery, availability, estimate, booking, and callback system for Johnson Bros. Plumbing & Drain Cleaning.","endpoint":"https://thejohnsonbros.com/mcp","transport":"streamable-http","authentication":{"type":"mixed","description":"Public business, service-area, service/pricing, quote, availability, and emergency-guidance tools require no authentication. Callback and pending-booking requests require explicit user consent and a valid customer phone number. Final booking confirmation requires the SMS code sent to that phone. Customer-specific data requires a separate verified customer session. Internal tools are hidden from the public tool surface and require separate bearer authorization.","public_tools":{"method":"none","includes":["business information","service-area checks","services and pricing","quotes","availability","emergency guidance"]},"pending_booking":{"method":"explicit_user_consent_and_valid_customer_phone"},"booking_confirmation":{"method":"sms_verification_code"},"customer_data":{"method":"verified_customer_session"},"internal_tools":{"method":"bearer","publicly_exposed":false}},"getting_started":{"agents_page":"https://thejohnsonbros.com/agents","discovery":"https://thejohnsonbros.com/.well-known/mcp.json","manifest":"https://thejohnsonbros.com/api/mcp/manifest","llms_txt":"https://thejohnsonbros.com/llms.txt","support":"https://thejohnsonbros.com/mcp-support","rate_limits":"20 public requests per minute per IP; stricter limits apply to verification and write tools."},"tools":[{"name":"get_quote","description":"Use this when the user wants a non-binding estimate for a specific plumbing issue. Do not present the range as a guaranteed final repair price.","parameters":{"type":"object","properties":{"service_type":{"type":"string"},"issue_description":{"type":"string"},"property_type":{"type":"string","enum":["residential","commercial"]},"urgency":{"type":"string","enum":["routine","soon","urgent","emergency"]}},"required":["service_type","issue_description"]},"access_class":"public_low_risk","requires_phone_verification":false,"requires_explicit_confirmation":false,"risk_level":"medium"},{"name":"emergency_help","description":"Use this immediately for urgent plumbing safety or damage situations. This provides bounded guidance and a phone handoff; it is not monitored emergency dispatch.","parameters":{"type":"object","properties":{"emergency_type":{"type":"string"},"additional_details":{"type":"string"}},"required":["emergency_type"]},"access_class":"public_read","requires_phone_verification":false,"requires_explicit_confirmation":false,"risk_level":"low"},{"name":"get_availability","description":"Use this when the user wants live Johnson Bros. appointment availability. Returns arrival windows and capacity only; it does not create an appointment.","parameters":{"type":"object","properties":{"days":{"type":"number","minimum":1,"maximum":14,"description":"How many days ahead to search (default 7)"},"start_date":{"type":"string","format":"date"},"time_preference":{"type":"string","enum":["any","morning","afternoon","evening"]}}},"access_class":"public_read","requires_phone_verification":false,"requires_explicit_confirmation":false,"risk_level":"low"},{"name":"check_service_area","description":"Use this when the user gives a Massachusetts ZIP code or town and wants to know whether Johnson Bros. serves it. Do not use this as proof of availability.","parameters":{"type":"object","properties":{"zip":{"type":"string","description":"5-digit ZIP code"},"town":{"type":"string","description":"Town/city name, e.g. 'Quincy'"}}},"access_class":"public_read","requires_phone_verification":false,"requires_explicit_confirmation":false,"risk_level":"low"},{"name":"get_services_pricing","description":"Use this to browse Johnson Bros. services or general non-binding price ranges. For an issue-specific estimate, use get_quote.","parameters":{"type":"object","properties":{"category":{"type":"string","enum":["emergency","maintenance","repair","installation","specialty"]},"search":{"type":"string"}}},"access_class":"public_read","requires_phone_verification":false,"requires_explicit_confirmation":false,"risk_level":"low"},{"name":"business_info","description":"Use this for Johnson Bros. contact details, credentials, hours, payment methods, service area, or booking process. Do not use it for live availability or customer records.","parameters":{"type":"object","properties":{}},"access_class":"public_read","requires_phone_verification":false,"requires_explicit_confirmation":false,"risk_level":"low"},{"name":"request_booking","description":"Use this only after the user explicitly approves starting a booking with their own details. It sends an SMS code and does not schedule a visit.","parameters":{"type":"object","properties":{"service":{"type":"string","description":"Requested service, e.g. 'water heater replacement'"},"preferred_windows":{"type":"array","maxItems":5,"items":{"type":"object","properties":{"start_time":{"type":"string","description":"ISO start from get_availability"},"end_time":{"type":"string","description":"ISO end from get_availability"}},"required":["start_time","end_time"]}},"time_preference":{"type":"string","enum":["any","morning","afternoon","evening"]},"name":{"type":"string","description":"Customer full name"},"phone":{"type":"string","description":"Customer mobile number — receives the 6-digit code"},"address":{"type":"object","properties":{"street":{"type":"string"},"unit":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"}},"required":["street","city","zip"]},"email":{"type":"string","format":"email"},"notes":{"type":"string"},"confirmed":{"type":"boolean","const":true,"description":"True only after the user explicitly approves starting the booking and sending the SMS code"}},"required":["service","name","phone","address","confirmed"]},"access_class":"public_low_risk","requires_phone_verification":false,"requires_explicit_confirmation":true,"risk_level":"medium"},{"name":"confirm_booking","description":"Use this after the customer supplies the six-digit SMS code. Only status:confirmed with booked:true means the appointment is scheduled; callback_pending is not an appointment.","parameters":{"type":"object","properties":{"booking_id":{"type":"string","description":"booking_id returned by request_booking"},"code":{"type":"string","description":"6-digit SMS code"}},"required":["booking_id","code"]},"access_class":"public_low_risk","requires_phone_verification":false,"requires_explicit_confirmation":true,"risk_level":"medium"},{"name":"request_callback","description":"Use this when the user explicitly wants Johnson Bros. to call them about a plumbing need but is not ready to schedule. Do not use it for emergency dispatch or without the user's consent.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"Customer full name, for example Jane Smith"},"phone":{"type":"string","description":"Customer phone number for the callback, for example 617-555-0123"},"issue_description":{"type":"string","description":"Short description of the plumbing issue"},"preferred_callback_time":{"type":"string","description":"Optional customer preference, for example weekday morning"},"confirmed":{"type":"boolean","const":true,"description":"True only after the user explicitly asks Johnson Bros. to contact them"}},"required":["name","phone","issue_description","confirmed"]},"access_class":"public_low_risk","requires_phone_verification":false,"requires_explicit_confirmation":true,"risk_level":"medium"}],"resources":[{"name":"service_pricing","description":"Customer-facing pricing ranges for common plumbing services","mimeType":"application/json"},{"name":"service_areas","description":"Service area coverage for Quincy, Abington, and South Shore communities","mimeType":"application/json"},{"name":"business_hours","description":"Office hours and emergency availability","mimeType":"application/json"},{"name":"booking_confirmation_card","description":"Branded booking confirmation UI for a verified appointment","uri":"ui://widget/v2/booking-confirmation.html","mimeType":"text/html;profile=mcp-app"},{"name":"availability_card","description":"Branded live appointment availability UI","uri":"ui://widget/v2/availability.html","mimeType":"text/html;profile=mcp-app"},{"name":"services_card","description":"Branded service and pricing UI","uri":"ui://widget/v2/services.html","mimeType":"text/html;profile=mcp-app"},{"name":"quote_card","description":"Branded non-binding estimate UI","uri":"ui://widget/v2/quote.html","mimeType":"text/html;profile=mcp-app"},{"name":"emergency_guidance_card","description":"Branded emergency safety guidance and phone handoff UI","uri":"ui://widget/v2/emergency.html","mimeType":"text/html;profile=mcp-app"},{"name":"date_picker_card","description":"Date selection UI used by compatible booking hosts","uri":"ui://widget/v2/date-picker.html","mimeType":"text/html;profile=mcp-app"},{"name":"time_picker_card","description":"Arrival-window selection UI used by compatible booking hosts","uri":"ui://widget/v2/time-picker.html","mimeType":"text/html;profile=mcp-app"},{"name":"lead_capture_card","description":"Consent-aware callback request UI","uri":"ui://widget/v2/lead-capture.html","mimeType":"text/html;profile=mcp-app"},{"name":"service_fee_card","description":"Current service-fee explanation UI","uri":"ui://widget/v2/service-fee.html","mimeType":"text/html;profile=mcp-app"}],"booking_flow":["Use check_service_area when the customer supplies a ZIP code or town.","Use get_availability to retrieve open arrival windows; this does not reserve an appointment.","After explicit customer approval, request_booking sends a six-digit SMS code and creates only a pending request.","confirm_booking verifies the customer-supplied code. Only status:confirmed with booked:true means an appointment exists."],"safety":{"emergency":"For urgent plumbing problems, call (617) 479-9911; MCP is not monitored emergency dispatch.","pricing":"Quotes and ranges are non-binding. Final scope and pricing are confirmed before work.","customer_data":"Customer-account data and internal operations are not exposed in the public version-one tool surface.","consent":"Never guess an SMS code or submit a phone number the customer does not control."},"business":{"name":"Johnson Bros. Plumbing & Drain Cleaning","phone":"(617) 479-9911","email":"sales@thejohnsonbros.com","license":"Massachusetts Master Plumber License PL #17034-M","hours":"Monday-Friday, 7 AM-6 PM ET","service_areas":["Quincy, MA","Abington, MA","Braintree, MA","Weymouth, MA","Milton, MA","Hingham, MA","Plymouth, MA","Marshfield, MA","Rockland, MA","Hanover, MA","Scituate, MA","Cohasset, MA","Hull, MA","Whitman, MA","Hanson, MA","Halifax, MA","Kingston, MA","South Shore, MA"]},"metadata":{"last_updated":"2026-08-21","api_version":"1.0.0","documentation_url":"https://thejohnsonbros.com/api/mcp/docs"}}