rigshare_create_booking

Instructions

Implementation Reference

• src/index.ts:245-295 (schema)

  Tool definition and input schema for rigshare_create_booking, registered in the ListToolsRequestSchema handler. Describes required fields (equipment_id, start_date, end_date, duration_type) and optional fields (pickup_type, idempotency_key).

  {
    name: "rigshare_create_booking",
    description:
      "REQUIRES API KEY (bookings:write scope). Creates a new RIGShare booking for the authenticated user. Server computes all prices from the equipment's canonical rates — client-side price hints are ignored. Enforces identity verification, security deposit hold, and a daily/monthly budget cap configured on the API key. Returns confirmation code + booking ID on success. Use rigshare_list_my_bookings to check status afterwards.",
    inputSchema: {
      type: "object",
      required: ["equipment_id", "start_date", "end_date", "duration_type"],
      properties: {
        equipment_id: {
          type: "string",
          format: "uuid",
          description:
            "From rigshare_search_equipment or rigshare_get_equipment.",
        },
        start_date: {
          type: "string",
          format: "date-time",
          description: "ISO-8601 start datetime.",
        },
        end_date: {
          type: "string",
          format: "date-time",
          description: "ISO-8601 end datetime. Must be after start_date.",
        },
        duration_type: {
          type: "string",
          enum: ["HOURLY", "FOUR_HOURS", "DAILY", "WEEKLY", "MONTHLY"],
          description:
            "Determines which rate is used. Must match a rate the equipment actually offers (e.g., use HOURLY only when equipment has a rateHourly).",
        },
        pickup_type: {
          type: "string",
          enum: [
            "SELF_PICKUP",
            "OWNER_DELIVERY",
            "PLATFORM_DELIVERY",
            "REMOTE_ACCESS",
          ],
          default: "REMOTE_ACCESS",
          description:
            "Default REMOTE_ACCESS for robotics/AI equipment. Use SELF_PICKUP or OWNER_DELIVERY for construction equipment.",
        },
        idempotency_key: {
          type: "string",
          maxLength: 100,
          description:
            "Optional. If provided, repeated calls with the same key within 5 minutes return the same booking instead of creating duplicates.",
        },
      },
    },
  },

• src/index.ts:301-325 (registration)

  Tool dispatch — maps the tool name 'rigshare_create_booking' to the createBooking handler function.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
    try {
      switch (name) {
        case "rigshare_search_equipment":
          return await searchEquipment(args || {});
        case "rigshare_get_equipment":
          return await getEquipment(args || {});
        case "rigshare_list_categories":
          return await listCategories();
        case "rigshare_get_owner_onboarding":
          return getOwnerOnboarding(args || {});
        case "rigshare_list_my_bookings":
          return await listMyBookings(args || {});
        case "rigshare_list_my_sessions":
          return await listMySessions(args || {});
        case "rigshare_create_booking":
          return await createBooking(args || {});
        default:
          return toolError(`Unknown tool: ${name}`);
      }
    } catch (err: any) {
      return toolError(err?.message || "Unknown error");
    }
  });

• src/index.ts:709-760 (handler)

  Core handler function for rigshare_create_booking: validates required args, builds a POST body, calls the authenticated RIGShare Agent API /bookings endpoint, and formats the response with confirmation code, booking ID, status, total, and security deposit.

  async function createBooking(args: Record<string, unknown>) {
    if (!RIGSHARE_API_KEY) return toolError(API_KEY_ERROR_MSG);
  
    // Minimum-viable validation client-side before hitting the server
    if (!args.equipment_id || typeof args.equipment_id !== "string") {
      return toolError("equipment_id is required (uuid)");
    }
    if (!args.start_date || typeof args.start_date !== "string") {
      return toolError("start_date is required (ISO-8601)");
    }
    if (!args.end_date || typeof args.end_date !== "string") {
      return toolError("end_date is required (ISO-8601)");
    }
    if (!args.duration_type) {
      return toolError(
        "duration_type is required (HOURLY | FOUR_HOURS | DAILY | WEEKLY | MONTHLY)",
      );
    }
  
    const body: Record<string, unknown> = {
      equipment_id: args.equipment_id,
      start_date: args.start_date,
      end_date: args.end_date,
      duration_type: args.duration_type,
      pickup_type: args.pickup_type || "REMOTE_ACCESS",
    };
    if (args.idempotency_key) body.idempotency_key = args.idempotency_key;
  
    const res = await fetchAuthJson(RIGSHARE_API_KEY, `${RIGSHARE_AGENT_API}/bookings`, {
      method: "POST",
      body: JSON.stringify(body),
    });
    if (res.error) return toolError(res.error);
  
    const d = res.data as any;
    const idempotent = d?.idempotent ? " (idempotent — matched existing booking)" : "";
    return toolText(
      [
        `Booking created${idempotent}:`,
        ``,
        `Confirmation code: ${d?.confirmation_code || d?.booking?.confirmationCode || "—"}`,
        `Booking ID: ${d?.booking_id || d?.booking?.id || "—"}`,
        `Status: ${d?.booking?.status || "PENDING"}`,
        `Total: $${((d?.booking?.totalAmount || 0) / 100).toFixed(2)}`,
        `Security deposit hold: $${((d?.booking?.securityDeposit || 0) / 100).toFixed(2)}`,
        ``,
        `View at: https://www.rigshare.app/booking/${d?.booking_id || d?.booking?.id}`,
        ``,
        `Next steps: the owner will approve or decline. Use rigshare_list_my_bookings to check status.`,
      ].join("\n"),
    );
  }

• src/index.ts:617-646 (helper)

  Authenticated HTTP helper used by createBooking — sends requests with Bearer token auth, returns parsed JSON data or error.

  async function fetchAuthJson(
    apiKey: string,
    url: string,
    init: RequestInit = {},
  ): Promise<{ data?: any; status?: number; error?: string }> {
    try {
      const res = await fetch(url, {
        ...init,
        headers: {
          ...(init.headers || {}),
          Accept: "application/json",
          "Content-Type": "application/json",
          "User-Agent": USER_AGENT,
          Authorization: `Bearer ${apiKey}`,
        },
      });
      const data = await res.json().catch(() => ({}));
      if (!res.ok) {
        return {
          status: res.status,
          error:
            (data as any)?.error ||
            `RIGShare Agent API returned HTTP ${res.status}`,
        };
      }
      return { data, status: res.status };
    } catch (err: any) {
      return { error: err?.message || "Network error contacting RIGShare Agent API" };
    }
  }

• src/index.ts:785-796 (helper)

  Response formatting helpers — toolError returns an MCP error response, toolText returns a success text response. Both used by createBooking.

  function toolText(text: string) {
    return {
      content: [{ type: "text" as const, text }],
    };
  }
  
  function toolError(message: string) {
    return {
      content: [{ type: "text" as const, text: `Error: ${message}` }],
      isError: true,
    };
  }