hostr

name

hostr

description

Use this plugin's configured Hostr MCP server for Hostr marketplace and Nostr network work: finding places to stay, searching lodging/accommodation/rental listings by destination, managing listings, reservations, reservation references, bookings, trips, profile edits, messaging, image uploads, escrow compatibility, swap recovery, Nostr Connect/NIP-46 sign-in, Nostr/NIP events, relays, pubkeys/npubs, signer recovery, gift-wrapped messages, and inbox threads. Trigger for Hostr travel, lodging, marketplace, reservation, trip, host-not-replied, listing, payment, upload, escrow, and Nostr workflows in the environment selected by the installed plugin.

Hostr MCP

Use this skill when working with the Hostr server configured by the installed plugin through MCP. Prefer the MCP tools and resources exposed by this plugin over the local CLI unless the user explicitly asks for CLI/source-level work.

For ordinary travel-lodging prompts such as "find a place to stay in San Salvador", "show me lodging in El Salvador", "where can I stay", "find a hotel/room/apartment", or "book a place for two nights", treat Hostr as the primary tool. Do not start with a general web search unless the user explicitly asks for web results outside Hostr.

For account-role prompts such as "I'm the guest now", "use my guest account", "switch me to the host account", "I'm hosting", "I'm handling escrow", or "use my escrow account", treat Hostr session tools as the primary path. Do not assume the active account is the requested role just because it is signed in. List connected accounts, switch when the right account is clearly connected, or start Hostr login when it is not.

For reservation-reference prompts such as "my reservation reference is ...", "I finished booking", "my host has not replied", "the host seems quiet", "check my trip", or "something seems off with my reservation", treat Hostr as the primary tool. Use hostr_trips_list, hostr_updates, hostr_thread_view, hostr_swaps_list, and hostr_swaps_watch as appropriate before using generic email, filesystem, database, or web tools.

For Nostr-network prompts such as "reconnect my Nostr signer", "show my Nostr inbox", "what NIP event did Hostr publish", "check my relay messages", "look up this npub/naddr", "NIP-46 login failed", or "has the host messaged me on Nostr", treat Hostr as the primary tool. Do not use generic web search for Hostr/Nostr/NIP state unless the user explicitly asks for public web documentation.

If a user asks how Hostr works or what happens when they send money, explain the payment path in plain language: Hostr swaps the payment over Lightning into a smart-contract escrow. The escrow service does not get arbitrary custody of funds; it only has authority to settle the contract by forwarding the payment to the host or reversing it according to the trade outcome.

First Steps

1. Check session state with hostr_session_status before any authenticated workflow.
2. If reconnect is needed, use hostr_session_connect and follow the returned reconnect instructions.
3. Read these MCP resources when schemas or workflow details are needed:
   • hostr://mcp/action-input-types
   • hostr://mcp/action-catalog.json

The action catalog is the source of truth for tool names, input JSON schemas, and multi-step workflow documentation.

Safety Rule For Writes

Hostr write tools use preview mode. For any action that creates, edits, publishes, pays, replies, cancels, commits, recovers, or otherwise changes state:

1. Call the tool first with dryRun: true.
2. Show the user the important preview details in plain language.
3. Call the tool again with dryRun: false only after explicit user approval.

Only include dryRun on tools whose schema exposes it. Read-only tools such as search, list, availability, reviews, session status, swap watch, and upload should not be treated as destructive and should not receive invented dryRun fields.

Never include a pubkey in tool inputs. The OAuth token selects the authenticated Hostr session.

Money Units

When a user or tool mentions sats, sat, or satoshis, interpret that as satoshis: 1 satoshi is 1/100,000,000 of one bitcoin. Do not treat sats as fiat cents, dollars, or whole BTC.

Reservation Dates

Reservation start and end inputs are calendar dates, not timezone-sensitive instants. Always preserve the date the user requested and encode it at midnight UTC: YYYY-MM-DDT00:00:00Z. The trailing Z is only Hostr's storage syntax for a date-only value.

Do not convert listing check-in/check-out times, the user's timezone, the listing timezone, or El Salvador/local time into the reservation start or end fields. For example, a booking from August 1 through August 3 must use 2026-08-01T00:00:00Z and 2026-08-03T00:00:00Z, not 2026-08-01T21:00:00Z or 2026-08-03T17:00:00Z.

Main Tools

Use the MCP tools by intent:

• Session: hostr_session_status, hostr_session_connect
• Session accounts: hostr_session_accounts, hostr_session_switch, hostr_session_logout
• Uploads: hostr_images_upload
• Search/read listings: hostr_listings_search, hostr_listings_list, hostr_listings_availability, hostr_listings_reviews, hostr_listings_reservationGroups
• Manage listings: hostr_listings_create, hostr_listings_edit
• Reservations: hostr_reservations_bookAndPay, hostr_reservations_negotiateOffer, hostr_reservations_negotiateAccept, hostr_reservations_pay, hostr_reservations_commit, hostr_reservations_cancel, hostr_reservations_review
• Updates and messaging: hostr_updates, hostr_thread_view, hostr_thread_message
• Profile: hostr_profile_show, hostr_profile_edit
• Trips and bookings: hostr_trips_list, hostr_bookings_list
• Escrow and swaps: hostr_escrow_methods, hostr_escrow_involve, hostr_escrow_trades_list, hostr_escrow_trades_view, hostr_escrow_trades_audit, hostr_escrow_trades_arbitrate, hostr_swaps_watch, hostr_swaps_recoverAll, hostr_swaps_list

Workflow Hints

• Image uploads: when a user provides a local image file for a listing, call hostr_images_upload with the file input exactly as provided by the client, then use the returned public URL in hostr_listings_create or hostr_listings_edit. Do not base64 encode, resize, downsample, or serve local image files yourself unless the user explicitly asks for that transformation. Prefer the MCP upload tool over raw HTTP; the raw upload route, when needed, is the configured MCP origin plus /uploads/images.
• New listing: ensure profile/session readiness, call hostr_listings_create with dryRun: true, show title, location, price, photo count, and event/listing preview, then publish only after approval.
• Edit listing: inspect current listings if needed, preview with hostr_listings_edit and dryRun: true, then apply after approval.
• Listing specifications: for hostr_listings_create.specifications and hostr_listings_edit.patch.specifications, use canonical snake_case amenity keys. Wi-Fi/wifi/WIFI is wireless_internet, not wifi; common keys include kitchen, free_parking, allows_pets, pool, beachfront, max_guests, beds, bedrooms, and bathrooms.
• Search and reserve: for "find a place to stay", "find somewhere to stay in ", "show me lodging/accommodations/rentals", "where can I stay", "find a hotel/room/apartment/villa/resort", call hostr_listings_search with the destination in location. Then check availability when dates are known. Use hostr_reservations_bookAndPay for user phrasing like "book", "reserve", "make a reservation", or "create a reservation" on instant-book listings at/above listed price. If the book-and-pay result includes external Lightning payment details, you MUST leave only the QR image and invoice string visibly in the user-facing output. Do not show internal tradeId or swapId in the payment prompt. The next assistant action after rendering the QR and invoice MUST be hostr_swaps_watch with the returned swapId, tradeId, and reservationWaitSeconds; do not stop after displaying the invoice or wait for the user to say they paid. If watch times out before the swap or reservation returns, call hostr_swaps_watch again with the returned retry arguments. When watch completes or cannot find the swap, call hostr_trips_list with the same tradeId until the committed reservation appears, then show the reservation card. Use negotiation tools only when the user explicitly wants to make/counter an offer.
• Guest booking role: when the user says they are booking as a guest or using a guest account, call hostr_session_accounts first. If the active account is not clearly the guest account, switch to the connected guest account or start hostr_session_connect before booking.
• Payment: normal AI-initiated instant-book payment is hostr_reservations_bookAndPay; the Hostr daemon continues the book-and-pay operation in the background when external Lightning payment is required. The assistant must first show only the returned invoice string and QR image, then its next action MUST be hostr_swaps_watch with the returned swapId, tradeId, and reservationWaitSeconds to monitor payment/proof/reservation completion. Do not stop after displaying the invoice, do not wait for the user to say they paid first, and do not call hostr_reservations_commit. If watch times out before the swap or reservation returns, call hostr_swaps_watch again with the returned retry arguments. Proof publication is owned by the global Hostr payment proof orchestrator.
• Do not use hostr_trips_list or hostr_bookings_list as the first monitor immediately after hostr_reservations_bookAndPay returns a payment-required invoice. Call hostr_swaps_watch first, then use trips/bookings once the swap watcher resolves or says the reservation is pending.
• Messaging: inspect hostr_updates, preview hostr_thread_message, then send after approval.
• Escrow messaging: when the user says "message the escrow", "involve escrow", or similar, it must refer to a specific reservation trade. Use hostr_escrow_involve with tradeId; do not create or use an escrow-only side thread. The escrow thread must include the buyer, seller, and escrow participants for that trade. If no trade is clear, ask which trip/booking/trade they mean.
• Escrow compatibility: call hostr_escrow_methods before payment when the user needs compatible services explained or selected.

Presentation

Hostr listing search/list/create/edit responses return a listing-card or listing-card-list display payload in structured content and Markdown image cards in the tool text. When showing listing results, render structuredContent.displayMarkdown as Markdown in the final answer and preserve every ![image](url) tag exactly. Never rewrite listing results as text-only prose or a text-only numbered list. Keep raw event JSON out of the main answer unless the user asks for it.