# 빵빵카 공개 MCP 계약 v1.0.0

**이 계약면은 삭제·변경하지 않고 버전으로만 추가한다.**

- 엔드포인트: `https://mcp.rentcar00.com/mcp` (Streamable HTTP, 무상태, 인증 없음)
- 상태 확인: `GET https://mcp.rentcar00.com/health` → `{"status":"ok"}`
- 조회 전용입니다. 예약·결제·고객정보 쓰기 기능은 없습니다. **예약은 항상 홈페이지(rentcar00.com)에서 진행합니다.**
- 가용 여부·가격·정책 판정은 홈페이지 검색(`rentcar00.com/api/search-cars`)이 합니다. 결과는 홈페이지 검색과 같아야 합니다.

## Tool: `search_available_vehicles`

### 입력

| 이름 | 형식 | 필수 | 설명 |
| --- | --- | --- | --- |
| `pickup_at` | string, ISO 8601 | 예 | 배차 일시. 예 `2026-11-10T10:00:00+09:00`. offset이 없으면 한국 시간. 날짜만(`2026-11-10`)이면 오전 9시 |
| `return_at` | string, ISO 8601 | 예 | 반납 일시. 이용기간만 들었으면 배차 일시에 더해 계산. 날짜만이면 오전 9시 |
| `region` | string | 아니오 | 배송받을 위치 시·구·동. 예 `서울 강남구 역삼동` |

그 외 입력은 없습니다. 고정 조건: 운전자 만 26세 이상, 탁송(딜리버리), 홈페이지 기본 정렬(가격 낮은 순).

### 흐름

1. 배차·반납 일시만으로 호출 → 가능한 차량과 대여료(`rental_price`). `price_stage: "rental_only"`
2. 같은 일시 + `region`으로 다시 호출 → 탁송비 포함 결제 예정 총액(`total_price`)과 예약 링크(`reserve_url`). `price_stage: "total_with_delivery"`

위치가 모호하거나(`ambiguous`) 배송지역 밖이면(`out_of_area`) **서울 강남고속버스터미널(서울특별시 서초구 반포동)** 기준으로 계산하고 `location.default_applied: true`, `location.reason`으로 알립니다.

### 시각 조정

영업시간은 09:00~21:00 정시입니다. 날짜만 있거나 영업시간·정시에 맞지 않는 시각은 거절하지 않고, 요청 시간을 포함하도록 넓혀 조회합니다.

- 배차: 요청 시각 이전의 가장 늦은 영업 시각 (예 07:00 → 전날 21:00, 22:00 → 21:00, 10:30 → 10:00)
- 반납: 요청 시각 이후의 가장 이른 영업 시각 (예 22:30 → 다음날 09:00, 10:30 → 11:00)
- 앞당긴 배차가 홈페이지의 "현재부터 3시간 이후" 규칙에 걸리면 요청 시각 이후 첫 영업 시각으로 배차
- 조정 내역은 `adjustments`에 담고 `next`와 `display`로도 알립니다.

```json
"adjustments": [
  { "field": "pickup_at", "requested": "2026-11-10", "applied": "2026-11-10T09:00:00+09:00", "reason": "time_not_given" },
  { "field": "return_at", "requested": "2026-11-12T22:30:00+09:00", "applied": "2026-11-13T09:00:00+09:00", "reason": "outside_business_hours" }
]
```

`reason`: `time_not_given` · `outside_business_hours` · `not_on_the_hour` · `pickup_too_soon`. 조정이 없으면 빈 배열입니다.

### 응답 A — 입력 필요 (정상 응답, 오류 아님)

배차·반납 일시가 없거나, 해석할 수 없거나, 시각 조정 후에도 홈페이지 예약 규칙(3시간 이후, 기간 1~30일, 30일 이내 반납 등)에 맞지 않을 때.

```json
{
  "status": "need_input",
  "message": "배차 일시와 반납 일시가 있어야 조회할 수 있습니다.",
  "required": ["pickup_at", "return_at"],
  "format": "ISO 8601, 예: 2026-11-10T10:00:00+09:00",
  "business_hours": "09:00~21:00 정시(한국 시간)",
  "rules": ["배차는 현재부터 3시간 이후", "배차·반납 모두 09:00~21:00 정시", "대여 기간 1~30일", "반납은 오늘부터 30일 이내"],
  "note": "1일과 3일 이상은 요금 구조가 달라 기간이 필요합니다.",
  "display": "빵빵카 가용 차량 조회\n…"
}
```

### 응답 B — 조회 결과

```json
{
  "status": "ok",
  "pickup_at": "2026-11-09T10:00:00+09:00",
  "return_at": "2026-11-11T10:00:00+09:00",
  "hours": 48,
  "days": 2,
  "as_of": "2026-11-06T00:37:00+09:00",
  "conditions": { "driver_age": "만 26세 이상", "pickup_method": "탁송(딜리버리)" },
  "price_stage": "total_with_delivery",
  "location": {
    "input": "서초구 잠원동",
    "applied": "서울특별시 서초구 잠원동",
    "default_applied": false,
    "round_trip_delivery_fee": 20000
  },
  "adjustments": [],
  "note": "가용 여부는 조회 시점 기준이며 결제 시 확정됩니다.",
  "next": "…다음 안내 문장…",
  "count": 12,
  "truncated": false,
  "display": "빵빵카 가용 차량\n…",
  "vehicles": [
    {
      "id": "224219",
      "name": "더 뉴 셀토스 2025년 가솔린",
      "seats": 5,
      "rental_price": 144000,
      "delivery_fee": 20000,
      "total_price": 164000,
      "currency": "KRW",
      "reserve_url": "https://rentcar00.com/cars/224219?..."
    }
  ]
}
```

- `vehicles`는 **최대 30대**. 넘으면 `truncated: true`와 `message`("…30대만 보여 줍니다. 더 있습니다.").
- `region`이 없으면 `location`, `delivery_fee`, `total_price`, `reserve_url`은 `null`.
- 위치를 기본값으로 계산하면 `location`에 `landmark`, `default_applied: true`, `reason`(`ambiguous` | `out_of_area`)이 붙습니다.
- 차급·차종 분류 필드는 없습니다. 홈페이지 단기 검색 API가 분류를 내주지 않기 때문입니다. 분류가 생기면 새 버전에서 필드를 추가합니다.
- `reserve_url`은 홈페이지 차량 상세·예약 화면이며 발급 후 약 15분 유효합니다. 만료되면 같은 조건으로 다시 조회합니다.
- 홈페이지 조회 자체가 실패하면 MCP 표준 오류(`isError: true`)를 돌려줍니다.

### `display` — 서버가 완성한 고정폭 표

`need_input`과 `ok` 모두 `display` 문자열을 줍니다. 에이전트는 이것을 ` ```text ` 코드블록에 **그대로** 넣고, 아래에 한두 문장만 덧붙입니다. 표를 다시 그리거나 요약하지 않습니다.

- 한 줄 최대 44칸(표시 폭). 한글·한자·전각 2칸, 그 외 1칸(Unicode East Asian Width, Ambiguous는 1칸). 공백으로 정렬, 탭 없음
- 열: 번호 3칸 · 차량 20칸 · 인승 4칸 · 금액 10칸, 사이 2칸
- 차량명은 20칸에서 자르고 잘리면 끝에 `…`
- 금액은 천 단위 콤마, 단위는 머리글에 `(원)`. 대여료 단계는 `대여료(원)`, 위치 단계는 `총액(원)`
- 번호는 1부터, `vehicles` 배열 순서와 같습니다. 사용자가 번호로 고르면 그 항목의 `reserve_url`을 안내합니다. 표에는 링크를 넣지 않습니다
- 기본값 위치면 `(기본값: 강남고속버스터미널 기준)`, 시각 조정이 있으면 `※ 요청 시각 조정: …`, 30대를 넘으면 `총 N대 중 30대 표시`

```text
빵빵카 가용 차량
11/09(월) 10:00 → 11/11(수) 10:00 · 2일
만 26세 이상 · 탁송
배송지: 서울 서초구 잠원동 (왕복 20,000)
───────────────────────────────────────────
  #  차량                  인승    총액(원)
  1  더 뉴 셀토스 2025년…     5     164,000
  2  2026 쏘나타 디 엣지…     5     168,000
───────────────────────────────────────────
12대 전체 · 가격 낮은 순 · 조회 11/06 00:37
총액 = 대여료 + 왕복 탁송비. 결제 시 확정.
예약은 번호를 말씀하시면 링크를 드립니다.
```

## 운영 원칙

- 호출 제한: IP당 분당 30회(초과 시 HTTP 429).
- 로그: 호출 시각·입력(일시·위치 문구)·결과 상태·건수만. 개인정보는 받지 않습니다.