@nomadamas/k-skill 0.1.0

package/skills/mfds-food-safety/instruction.md

@@ -0,0 +1,126 @@
+# 식품 안전 체크
+
+## What this skill does
+
+식약처/식품안전나라 공개 표면을 **`k-skill-proxy` 경유**로 조회해 식품 안전 정보를 확인한다.
+
+조회 가능한 공식 데이터:
+- **건강기능식품 기능성 원료 인정현황** (I-0040) — 원료가 공식 인정됐는지, 1일 섭취량, 섭취시 주의사항
+- **건강기능식품 개별인정형 정보** (I-0050) — 개별 인정 원료의 기능성, 섭취량 상·하한, 주의사항
+- **건강기능식품 품목제조 신고사항** (I0030) — 신고된 제품의 원재료, 기능성, 섭취 주의사항, 기준규격 (고시형 원료 포함)
+- **검사부적합 현황(국내)** (I2620) — 국내 유통 식품 부적합 판정 이력
+- **부적합 식품 목록** — 공공데이터포털 경유
+- **회수·판매중지 공개 목록** (I0490) — 식품안전나라 경유
+
+하지만 사용자가 복통, 설사, 발진 같은 증상을 말하면 **바로 단정하지 말고 먼저 되묻는다.**
+
+- 누가 먹었는지 (본인/아이/임산부/고령자)
+- 무엇을 언제 얼마나 먹었는지
+- 같이 먹은 음식/술/약
+- 현재 증상과 시작 시점
+- 기저질환, 임신, 알레르기
+- red flag (`혈변`, `탈수`, `호흡곤란`, `의식저하`, `심한 복통/고열`)
+
+red flag 가 있으면 식품 조회보다 **즉시 응급실·119·의료진 안내**가 우선이다.
+
+## When to use
+
+- "이 음식 먹어도 괜찮니?" → 건강기능식품 원료 인정현황 + 검사부적합 조회
+- "차전자피를 먹어도 되나?" → 기능성 원료 인정현황에서 1일 섭취량·주의사항 확인
+- "이 김밥 먹고 배가 아픈데 회수 이력 있나?" → 회수·부적합 목록 조회
+- "식약처 공식 부적합 식품 목록에서 제품명 확인해줘"
+- "식품안전나라 공개 회수 목록에서 업체명으로 찾아줘"
+
+## Prerequisites
+
+- 인터넷 연결
+- `python3`
+- 설치된 skill payload 안에 `scripts/mfds_food_safety.py` helper 포함
+- `k-skill-proxy`의 food-safety route들이 있는 hosted/self-host 프록시에 접근 가능할 것
+
+## Credential requirements
+
+- 사용자 측 **필수** 시크릿 없음.
+- `KSKILL_PROXY_BASE_URL` — self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted `https://k-skill-proxy.nomadamas.org` 를 사용한다.
+- `DATA_GO_KR_API_KEY` 는 **프록시 운영 서버** 환경에서 부적합 식품 live 조회용으로만 둔다.
+- `FOODSAFETYKOREA_API_KEY` 는 **프록시 운영 서버** 환경에서 식품안전나라 live 조회용으로만 둔다. 없으면 public sample feed로 fallback 할 수 있다.
+- FOODSAFETYKOREA_API_KEY 발급: `https://www.foodsafetykorea.go.kr` 에서 회원가입 후 OpenAPI 이용신청. 하나의 키로 I-0040, I-0050, I0490, I2620 등 모든 서비스 호출 가능.
+
+## Mandatory interview first
+
+증상/섭취상황이 언급되면 결론을 말하기 전에 먼저 되묻는다.
+
+권장 첫 질문 예시:
+
+- `누가 무엇을 언제 얼마나 먹었는지, 지금 복통/구토/설사/발진 같은 증상이 있는지 먼저 알려주세요.`
+- `호흡곤란, 혈변, 심한 탈수, 의식저하, 심한 복통/고열이 있으면 즉시 응급실이나 119가 우선입니다.`
+
+## Official surfaces
+
+- 공공데이터포털 문서: `https://www.data.go.kr/data/15056516/openapi.do`
+- 부적합 식품 endpoint: `https://apis.data.go.kr/1471000/PrsecImproptFoodInfoService03/getPrsecImproptFoodList01`
+- 식품안전나라 회수·판매중지 (I0490): `https://www.foodsafetykorea.go.kr/api/openApiInfo.do?menu_grp=MENU_GRP31&menu_no=661&show_cnt=10&start_idx=1&svc_no=I0490&svc_type_cd=API_TYPE06`
+- 식품안전나라 회수 sample: `https://openapi.foodsafetykorea.go.kr/api/sample/I0490/json/1/5`
+- 건강기능식품 기능성 원료 인정현황 (I-0040): `https://www.foodsafetykorea.go.kr/api/openApiInfo.do?menu_grp=MENU_GRP31&menu_no=661&show_cnt=10&start_idx=1&svc_no=I-0040&svc_type_cd=API_TYPE06`
+- 건강기능식품 기능성 원료 sample: `https://openapi.foodsafetykorea.go.kr/api/sample/I-0040/json/1/5`
+- 건강기능식품 개별인정형 정보 (I-0050): `https://www.foodsafetykorea.go.kr/api/openApiInfo.do?menu_grp=MENU_GRP31&menu_no=661&show_cnt=10&start_idx=1&svc_no=I-0050&svc_type_cd=API_TYPE06`
+- 건강기능식품 개별인정형 sample: `https://openapi.foodsafetykorea.go.kr/api/sample/I-0050/json/1/5`
+- 검사부적합(국내) (I2620): `https://www.foodsafetykorea.go.kr/api/openApiInfo.do?menu_grp=MENU_GRP31&menu_no=661&show_cnt=10&start_idx=1&svc_no=I2620&svc_type_cd=API_TYPE06`
+- 검사부적합(국내) sample: `https://openapi.foodsafetykorea.go.kr/api/sample/I2620/json/1/5`
+- 건강기능식품 품목제조 신고사항 (I0030): `https://www.foodsafetykorea.go.kr/api/openApiInfo.do?menu_grp=MENU_GRP31&menu_no=661&show_cnt=10&start_idx=1&svc_no=I0030&svc_type_cd=API_TYPE06`
+- 건강기능식품 품목제조 신고 sample: `https://openapi.foodsafetykorea.go.kr/api/sample/I0030/json/1/5`
+- 프록시 route: `GET /v1/mfds/food-safety/search`
+- 프록시 route: `GET /v1/mfds/food-safety/health-food-ingredient`
+- 프록시 route: `GET /v1/mfds/food-safety/product-report`
+- 프록시 route: `GET /v1/mfds/food-safety/inspection-fail`
+
+## Workflow
+
+1. 증상/섭취상황이 있으면 인터뷰를 먼저 진행한다.
+2. red flag 가 있으면 즉시 응급 안내로 전환한다.
+3. "이거 먹어도 되나?" 류 질문:
+   - `/v1/mfds/food-safety/product-report` 로 건강기능식품 품목제조 신고사항을 조회한다 (원재료, 기능성, 섭취 주의사항, 기준규격). 고시형 원료(차전자피 등)는 여기서 확인.
+   - `/v1/mfds/food-safety/health-food-ingredient` 로 건강기능식품 기능성 원료 인정현황을 조회한다 (개별인정형 원료의 1일 섭취량, 주의사항).
+   - `/v1/mfds/food-safety/inspection-fail` 로 국내 검사부적합 이력을 확인한다.
+   - `/v1/mfds/food-safety/search` 로 회수·부적합 공개 목록도 함께 조회한다.
+4. 제품명, 업체명, 기능성, 섭취량, 주의사항, 부적합 사유를 짧게 정리하고, 먹어도 되는지 단정하지 않는다.
+5. 프록시가 `FOODSAFETYKOREA_API_KEY` 없이 동작 중이면 결과가 sample feed 기반일 수 있음을 warnings 로 확인한다.
+
+## CLI examples
+
+```bash
+python3 scripts/mfds_food_safety.py interview \
+  --question "이 김밥 먹어도 되나요?" \
+  --symptoms "복통과 설사"
+```
+
+```bash
+python3 scripts/mfds_food_safety.py search --query "김밥" --limit 5
+```
+
+```bash
+python3 scripts/mfds_food_safety.py product-report --query "차전자피" --limit 5
+```
+
+```bash
+python3 scripts/mfds_food_safety.py health-food-ingredient --query "스타놀" --limit 5
+```
+
+```bash
+python3 scripts/mfds_food_safety.py inspection-fail --query "쪽갓" --limit 5
+```
+
+## Response policy
+
+- 이 스킬은 **직접 진단**을 하지 않는다.
+- 이 스킬은 **식중독 진단**이나 **섭취 허가/금지의 최종 판정**을 하지 않는다.
+- 공식 공개 목록에 있는 사실만 전달한다.
+- 증상이 있는 질문은 인터뷰 없이 바로 답하지 않는다.
+- red flag 또는 고위험군이면 의료진 상담을 우선 권고한다.
+
+## Done when
+
+- 증상 또는 섭취상황을 먼저 되물었다.
+- red flag 여부를 확인했다.
+- 프록시 route를 통해 공식 공개 목록에서 제품명 또는 업체명 기준 결과를 최소 1건 이상 찾았거나, 없다고 분명히 알렸다.
+- 제품명, 업체명, 공개사유/부적합 사유, 공개일자를 포함한 요약을 제공했다.

package/skills/mfds-food-safety/scripts/mfds_food_safety.py

@@ -0,0 +1,281 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from html import unescape
+from typing import Any
+
+PROXY_BASE_URL_ENV_VAR = "KSKILL_PROXY_BASE_URL"
+DEFAULT_PROXY_BASE_URL = "https://k-skill-proxy.nomadamas.org"
+PROXY_DOWN_MSG = "설정된 k-skill-proxy 서버가 응답하지 않습니다. 잠시 후 재시도하거나 운영자에게 문의하세요."
+PROXY_KEY_NOT_CONFIGURED_MSG = "k-skill-proxy에 필요한 API 키가 설정되어 있지 않습니다. 운영자에게 문의하세요."
+
+
+class ApiError(RuntimeError):
+    def __init__(self, message: str, *, status_code: int | None = None, url: str | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.url = url
+
+
+def summarize_text(value: Any) -> str:
+    if value is None:
+        return ""
+    text = unescape(str(value))
+    text = re.sub(r"<[^>]+>", " ", text)
+    text = re.sub(r"\s+", " ", text).strip()
+    return text
+
+
+def resolve_proxy_base_url(explicit_base_url: str | None = None, env: dict[str, str] | None = None) -> str:
+    env = env or os.environ
+    candidate = summarize_text(explicit_base_url or env.get(PROXY_BASE_URL_ENV_VAR))
+    if candidate.casefold() in {"off", "false", "0", "disable", "disabled", "none"}:
+        raise ValueError("KSKILL_PROXY_BASE_URL 가 비활성화되어 있습니다.")
+    if candidate and candidate != "replace-me":
+        return candidate.rstrip("/")
+    return DEFAULT_PROXY_BASE_URL
+
+
+def build_food_interview(question: str | None = None, symptoms: str | None = None) -> dict[str, Any]:
+    return {
+        "domain": "food",
+        "question": summarize_text(question),
+        "symptoms": summarize_text(symptoms),
+        "must_ask": [
+            "누가 먹었거나 먹으려는지 알려주세요. (본인/아이/임산부/고령자)",
+            "무엇을 언제 먹었는지, 얼마나 먹었는지 알려주세요.",
+            "같이 먹은 음식이나 술, 복용 중인 약이 있는지 알려주세요.",
+            "복통·구토·설사·발진 같은 증상이 언제부터 시작됐는지 알려주세요.",
+            "기저질환, 임신 여부, 알레르기 여부를 알려주세요.",
+        ],
+        "red_flags": [
+            "호흡곤란, 입술·혀 붓기 같은 급성 알레르기 반응",
+            "혈변 또는 검은변",
+            "심한 탈수, 소변 감소, 계속되는 구토",
+            "의식저하, 고열, 심한 복통",
+        ],
+        "urgent_action": "red flag 가 있으면 식품 조회보다 즉시 응급실·119·의료진 연결을 우선하세요.",
+        "policy": "이 helper 는 공식 식품 안전정보 조회 전에 반드시 되묻기 흐름을 제공하며, 먹어도 되는지 단정하지 않습니다.",
+    }
+
+
+def normalize_food_recall_row(row: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "source": "foodsafetykorea_recall",
+        "product_name": summarize_text(row.get("product_name") or row.get("PRDLST_NM") or row.get("PRDTNM")),
+        "company_name": summarize_text(row.get("company_name") or row.get("BSSH_NM") or row.get("BSSHNM")),
+        "reason": summarize_text(row.get("reason") or row.get("RTRVLPRVNS")),
+        "created_at": summarize_text(row.get("created_at") or row.get("CRET_DTM")),
+        "distribution_deadline": summarize_text(row.get("distribution_deadline") or row.get("DISTBTMLMT")),
+        "category": summarize_text(row.get("category") or row.get("PRDLST_TYPE") or row.get("PRDLST_CD_NM")),
+    }
+
+
+def normalize_improper_food_item(item: dict[str, Any]) -> dict[str, Any]:
+    reason_parts = [
+        summarize_text(item.get("reason") or item.get("IMPROPT_ITM")),
+        summarize_text(item.get("INSPCT_RESULT")),
+    ]
+    return {
+        "source": "mfds_improper_food",
+        "product_name": summarize_text(item.get("product_name") or item.get("PRDUCT")),
+        "company_name": summarize_text(item.get("company_name") or item.get("ENTRPS")),
+        "reason": "; ".join(part for part in reason_parts if part),
+        "created_at": summarize_text(item.get("created_at") or item.get("REGIST_DT")),
+        "category": summarize_text(item.get("category") or item.get("FOOD_TY")),
+    }
+
+
+def filter_food_items(items: list[dict[str, Any]], query: str) -> list[dict[str, Any]]:
+    needle = summarize_text(query).casefold()
+    if not needle:
+        return items
+
+    product_matches = [item for item in items if needle in summarize_text(item.get("product_name")).casefold()]
+    if product_matches:
+        return product_matches
+
+    company_matches = [item for item in items if needle in summarize_text(item.get("company_name")).casefold()]
+    if company_matches:
+        return company_matches
+
+    return [item for item in items if needle in summarize_text(item.get("reason")).casefold()]
+
+
+def read_json_response(request: urllib.request.Request | str) -> dict[str, Any]:
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as error:
+        body = error.read().decode("utf-8", errors="replace")
+        try:
+            payload = json.loads(body)
+        except json.JSONDecodeError:
+            payload = None
+        if error.code == 503 and isinstance(payload, dict) and payload.get("error") == "upstream_not_configured":
+            raise ApiError(PROXY_KEY_NOT_CONFIGURED_MSG, status_code=error.code, url=getattr(error, "url", None)) from error
+
+        if isinstance(payload, dict) and payload.get("message"):
+            raise ApiError(str(payload["message"]), status_code=error.code, url=getattr(error, "url", None)) from error
+        raise ApiError(
+            f"MFDS food proxy request failed with HTTP {error.code}",
+            status_code=error.code,
+            url=getattr(error, "url", None),
+        ) from error
+    except urllib.error.URLError as error:
+        raise ApiError(f"{PROXY_DOWN_MSG} (상세: {error.reason})") from error
+
+
+def search_food_safety(
+    query: str,
+    *,
+    limit: int = 10,
+    base_url: str | None = None,
+    request_json: Any = read_json_response,
+) -> dict[str, Any]:
+    resolved_base_url = resolve_proxy_base_url(base_url)
+    url = f"{resolved_base_url}/v1/mfds/food-safety/search"
+    params = urllib.parse.urlencode({"query": query, "limit": str(limit)})
+    request = urllib.request.Request(
+        f"{url}?{params}",
+        headers={"Accept": "application/json", "User-Agent": "k-skill-mfds/1.0"},
+    )
+    return request_json(request)
+
+
+def search_health_food_ingredient(
+    query: str,
+    *,
+    limit: int = 10,
+    base_url: str | None = None,
+    request_json: Any = read_json_response,
+) -> dict[str, Any]:
+    resolved_base_url = resolve_proxy_base_url(base_url)
+    url = f"{resolved_base_url}/v1/mfds/food-safety/health-food-ingredient"
+    params = urllib.parse.urlencode({"query": query, "limit": str(limit)})
+    request = urllib.request.Request(
+        f"{url}?{params}",
+        headers={"Accept": "application/json", "User-Agent": "k-skill-mfds/1.0"},
+    )
+    return request_json(request)
+
+
+def search_product_report(
+    query: str,
+    *,
+    limit: int = 10,
+    base_url: str | None = None,
+    request_json: Any = read_json_response,
+) -> dict[str, Any]:
+    resolved_base_url = resolve_proxy_base_url(base_url)
+    url = f"{resolved_base_url}/v1/mfds/food-safety/product-report"
+    params = urllib.parse.urlencode({"query": query, "limit": str(limit)})
+    request = urllib.request.Request(
+        f"{url}?{params}",
+        headers={"Accept": "application/json", "User-Agent": "k-skill-mfds/1.0"},
+    )
+    return request_json(request)
+
+
+def search_inspection_fail(
+    query: str,
+    *,
+    limit: int = 10,
+    base_url: str | None = None,
+    request_json: Any = read_json_response,
+) -> dict[str, Any]:
+    resolved_base_url = resolve_proxy_base_url(base_url)
+    url = f"{resolved_base_url}/v1/mfds/food-safety/inspection-fail"
+    params = urllib.parse.urlencode({"query": query, "limit": str(limit)})
+    request = urllib.request.Request(
+        f"{url}?{params}",
+        headers={"Accept": "application/json", "User-Agent": "k-skill-mfds/1.0"},
+    )
+    return request_json(request)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="MFDS food-safety helper")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    interview = subparsers.add_parser("interview", help="print the mandatory symptom follow-up interview")
+    interview.add_argument("--question", default="")
+    interview.add_argument("--symptoms", default="")
+
+    search = subparsers.add_parser("search", help="search official food-safety records through k-skill-proxy")
+    search.add_argument("--query", required=True)
+    search.add_argument("--limit", type=int, default=10)
+    search.add_argument("--proxy-base-url")
+
+    product_report = subparsers.add_parser("product-report", help="search health food product manufacturing reports")
+    product_report.add_argument("--query", required=True)
+    product_report.add_argument("--limit", type=int, default=10)
+    product_report.add_argument("--proxy-base-url")
+
+    ingredient = subparsers.add_parser("health-food-ingredient", help="search health food ingredient recognition status")
+    ingredient.add_argument("--query", required=True)
+    ingredient.add_argument("--limit", type=int, default=10)
+    ingredient.add_argument("--proxy-base-url")
+
+    inspection = subparsers.add_parser("inspection-fail", help="search domestic inspection failure records")
+    inspection.add_argument("--query", required=True)
+    inspection.add_argument("--limit", type=int, default=10)
+    inspection.add_argument("--proxy-base-url")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.command == "interview":
+        print(json.dumps(build_food_interview(question=args.question, symptoms=args.symptoms), ensure_ascii=False, indent=2))
+        return 0
+
+    if args.command == "search":
+        try:
+            payload = search_food_safety(args.query, limit=args.limit, base_url=args.proxy_base_url)
+            print(json.dumps(payload, ensure_ascii=False, indent=2))
+            return 0
+        except (ValueError, ApiError) as error:
+            print(json.dumps({"error": str(error)}, ensure_ascii=False, indent=2), file=sys.stderr)
+            return 1
+
+    if args.command == "product-report":
+        try:
+            payload = search_product_report(args.query, limit=args.limit, base_url=args.proxy_base_url)
+            print(json.dumps(payload, ensure_ascii=False, indent=2))
+            return 0
+        except (ValueError, ApiError) as error:
+            print(json.dumps({"error": str(error)}, ensure_ascii=False, indent=2), file=sys.stderr)
+            return 1
+
+    if args.command == "health-food-ingredient":
+        try:
+            payload = search_health_food_ingredient(args.query, limit=args.limit, base_url=args.proxy_base_url)
+            print(json.dumps(payload, ensure_ascii=False, indent=2))
+            return 0
+        except (ValueError, ApiError) as error:
+            print(json.dumps({"error": str(error)}, ensure_ascii=False, indent=2), file=sys.stderr)
+            return 1
+
+    if args.command == "inspection-fail":
+        try:
+            payload = search_inspection_fail(args.query, limit=args.limit, base_url=args.proxy_base_url)
+            print(json.dumps(payload, ensure_ascii=False, indent=2))
+            return 0
+        except (ValueError, ApiError) as error:
+            print(json.dumps({"error": str(error)}, ensure_ascii=False, indent=2), file=sys.stderr)
+            return 1
+
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/mfds-food-safety/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "mfds-food-safety",
+  "description": "식약처/식품안전나라 공개 표면을 k-skill-proxy 경유로 조회하기 전에 증상·섭취상황을 반드시 되묻는 인터뷰형 식품 안전 체크 스킬.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "lookup"
+  ],
+  "frontmatter": "name: mfds-food-safety\ndescription: 식약처/식품안전나라 공개 표면을 k-skill-proxy 경유로 조회하기 전에 증상·섭취상황을 반드시 되묻는 인터뷰형 식품 안전 체크 스킬.\nlicense: MIT\nmetadata:\n  category: public-health\n  locale: ko-KR\n  phase: v1"
+}

package/skills/myrealtrip-search/instruction.md

@@ -0,0 +1,239 @@
+# 마이리얼트립 검색
+
+## 이 스킬이 하는 일
+
+마이리얼트립 공식 개발자센터의 MCP 문서에 공개된 엔드포인트를 사용해 여행 검색을 수행한다.
+
+- MCP 엔드포인트: `https://mcp-servers.myrealtrip.com/mcp`
+- 문서: <https://docs.myrealtrip.com/#/api/mcp/overview>
+- 연결 가이드: <https://docs.myrealtrip.com/#/api/mcp/setup>
+- 인증: 문서 기준 별도 인증 없음
+
+지원 범위:
+
+- 국내선/국제선 항공권 검색
+- 항공권 날짜별 최저가 캘린더와 프로모션 항공사 조회
+- 숙소 검색 및 상세/객실/리뷰/편의시설 조회
+- 투어·티켓·액티비티 검색, 상세, 날짜별 옵션/가격/예약 가능 여부 조회
+- 현재 한국 시간(KST) 조회
+
+## 동작 방식
+
+```
+Claude Code / Codex / Hermes Agent
+  → myrealtrip-search/scripts/myrealtrip_mcp.py
+    → https://mcp-servers.myrealtrip.com/mcp (Streamable HTTP MCP)
+      ├─ searchDomesticFlights / searchInternationalFlights
+      ├─ flightsFareCalendar / getPromotionAirlines
+      ├─ searchStays / getStayDetail
+      ├─ getCategoryList / searchTnas / getTnaDetail / getTnaOptions
+      └─ getCurrentTime
+```
+
+이 스킬은 화면 scraping이 아니라 마이리얼트립이 공개한 MCP 서버를 직접 호출한다. 따라서 DOM 선택자나 브라우저 자동화에 의존하지 않는다.
+
+## 사용할 때
+
+- "마이리얼트립에서 제주 항공권 찾아줘"
+- "다음 주 오사카 가는 최저가 항공권 봐줘"
+- "부산 해운대 호텔 2박 검색해줘"
+- "이 호텔 객실 타입이랑 취소정책 자세히 봐줘"
+- "오사카 유니버설 스튜디오 티켓 가격 확인해줘"
+- "도쿄 디즈니랜드 날짜별 옵션 확인해줘"
+- "항공권 특가 항공사 있어?"
+
+## 사용하지 않을 때
+
+- 실제 예약/결제/로그인이 필요한 경우
+- 마이리얼트립 계정의 예약 내역이나 개인화 데이터가 필요한 경우
+- 항공권·숙소·투어 외의 파트너 API 수익/예약 내역 조회가 목적일 때
+- 가격·재고를 법적/회계적 증빙 수준으로 확정해야 할 때
+
+## 준비 사항
+
+Python MCP SDK가 필요하다. 없으면 설치한다.
+
+```bash
+python3 -m pip install mcp
+```
+
+기본 엔드포인트는 공식 문서의 URL이다. 필요할 때만 환경변수로 바꾼다.
+
+```bash
+export MYREALTRIP_MCP_ENDPOINT="https://mcp-servers.myrealtrip.com/mcp"
+```
+
+Hermes Agent에 MCP 서버로 직접 등록하려면 다음 설정을 쓸 수 있다.
+
+```yaml
+mcp_servers:
+  myrealtrip:
+    url: "https://mcp-servers.myrealtrip.com/mcp"
+```
+
+CLI별 공식 연결 명령은 문서 기준 다음과 같다.
+
+```bash
+claude mcp add --transport http myrealtrip https://mcp-servers.myrealtrip.com/mcp
+codex mcp add myrealtrip --url https://mcp-servers.myrealtrip.com/mcp
+gemini mcp add -t http -s user myrealtrip https://mcp-servers.myrealtrip.com/mcp
+```
+
+## 사용 흐름
+
+### 1. 요청 유형을 분류한다
+
+- 국내 항공: 출발지와 도착지가 모두 한국 도시/공항이면 `searchDomesticFlights`
+- 국제 항공: 목적지가 해외면 `searchInternationalFlights`
+- 날짜 유연 항공 최저가: `flightsFareCalendar` 후 실제 검색 도구로 재확인
+- 숙소 목록: `searchStays`
+- 특정 숙소 상세/객실/리뷰/편의시설: `searchStays`로 `gid` 확보 후 `getStayDetail`
+- 투어·티켓·액티비티 목록: `searchTnas`
+- 도시별 카테고리 필터가 필요하면 `getCategoryList` 후 `searchTnas`
+- 특정 투어 상세: `searchTnas` 결과의 `gid`, `url`로 `getTnaDetail`
+- 날짜별 실제 옵션/가격/가능 여부: `getTnaOptions`
+
+### 2. 도구 목록과 입력 스키마를 확인한다
+
+```bash
+python3 myrealtrip-search/scripts/myrealtrip_mcp.py tools
+```
+
+### 3. 항공권 검색
+
+국내선은 두 공항이 모두 한국일 때만 사용한다.
+
+```bash
+python3 myrealtrip-search/scripts/myrealtrip_mcp.py call searchDomesticFlights \
+  --arg origin=GMP \
+  --arg destination=CJU \
+  --arg departDate=2026-05-20 \
+  --arg maxResults=10
+```
+
+국제선은 해외 목적지일 때 사용한다. 사용자가 출발 공항을 말하지 않으면 인천(`ICN`)을 기본값으로 둔다.
+
+```bash
+python3 myrealtrip-search/scripts/myrealtrip_mcp.py call searchInternationalFlights \
+  --json '{"tripType":"ROUND_TRIP","origin":"ICN","destination":"KIX","departDate":"2026-06-10","returnDate":"2026-06-14","passengers":{"adults":1,"children":0,"infants":0},"maxResults":5}'
+```
+
+날짜가 유동적인 최저가 요청은 캘린더를 먼저 본다. 캘린더 가격은 캐시/추정값이므로, 최종 답변 전에 실제 검색 도구로 후보 날짜를 다시 확인한다.
+
+```bash
+python3 myrealtrip-search/scripts/myrealtrip_mcp.py call flightsFareCalendar \
+  --arg from=ICN \
+  --arg to=NRT \
+  --arg departureDate=2026-06-01 \
+  --arg period=4 \
+  --arg maxResults=30
+```
+
+특가/할인 항공사 요청은 프로모션 항공사를 먼저 확인한다.
+
+```bash
+python3 myrealtrip-search/scripts/myrealtrip_mcp.py call getPromotionAirlines
+```
+
+### 4. 숙소 검색과 상세 조회
+
+```bash
+python3 myrealtrip-search/scripts/myrealtrip_mcp.py call searchStays \
+  --json '{"keyword":"부산 해운대","checkIn":"2026-06-10","checkOut":"2026-06-12","adultCount":2,"childCount":0,"isDomestic":true,"order":"recommended","minReviewRating":4.0}'
+```
+
+사용자가 특정 숙소의 객실, 가격, 편의시설, 리뷰, 취소정책을 묻거나 "자세히"를 요청하면 `searchStays` 결과의 `gid`로 상세를 이어서 호출한다.
+
+```bash
+python3 myrealtrip-search/scripts/myrealtrip_mcp.py call getStayDetail \
+  --json '{"gid":123456,"checkIn":"2026-06-10","checkOut":"2026-06-12","adultCount":2,"childCount":0}'
+```
+
+### 5. 투어/티켓/액티비티 검색과 옵션 확인
+
+도시별 카테고리 필터를 쓰려면 카테고리 값을 추측하지 말고 먼저 조회한다.
+
+```bash
+python3 myrealtrip-search/scripts/myrealtrip_mcp.py call getCategoryList --arg city=Osaka
+```
+
+검색어는 한국어가 가장 잘 맞는다.
+
+```bash
+python3 myrealtrip-search/scripts/myrealtrip_mcp.py call searchTnas \
+  --arg query="오사카 유니버설 스튜디오" \
+  --arg perPage=5
+```
+
+상세는 검색 결과의 `gid`와 `url`을 같이 넘긴다.
+
+```bash
+python3 myrealtrip-search/scripts/myrealtrip_mcp.py call getTnaDetail \
+  --json '{"gid":"123456","url":"https://www.myrealtrip.com/offers/123456"}'
+```
+
+날짜별 예약 가능 여부와 실제 가격은 `getTnaOptions`로 확인한다.
+
+```bash
+python3 myrealtrip-search/scripts/myrealtrip_mcp.py call getTnaOptions \
+  --json '{"gid":"123456","url":"https://www.myrealtrip.com/offers/123456","selectedDate":"2026-06-10"}'
+```
+
+## 사용 가능한 도구
+
+| 도구명 | 용도 | 주요 입력 |
+|--------|------|-----------|
+| `getCurrentTime` | 현재 KST 조회 | 없음 |
+| `searchDomesticFlights` | 국내선 항공권 검색 | `origin`, `destination`, `departDate`, `returnDate`, `passengers`, `cabinClass`, `maxResults` |
+| `searchInternationalFlights` | 국제선 항공권 검색 | `origin`, `destination`, `departDate`, `returnDate`, `passengers`, `cabinClass`, `directFlightOnly`, `preferredAirline` |
+| `flightsFareCalendar` | 날짜별 최저가 캘린더 | `from`, `to`, `departureDate`, `period`, `international`, `transfer` |
+| `getPromotionAirlines` | 프로모션 항공사 조회 | 없음 |
+| `searchStays` | 숙소 목록 검색 | `keyword`, `checkIn`, `checkOut`, `adultCount`, `childCount`, `isDomestic`, 가격/평점/시설 필터 |
+| `getStayDetail` | 숙소 상세/객실/리뷰/편의시설 | `gid`, `checkIn`, `checkOut`, `adultCount`, `childCount` |
+| `getCategoryList` | 도시별 TNA 카테고리 조회 | `city` |
+| `searchTnas` | 투어/티켓/액티비티 검색 | `query`, `page`, `perPage`, `category`, `sort` |
+| `getTnaDetail` | TNA 상품 상세 | `gid`, `url` |
+| `getTnaOptions` | 날짜별 예약 가능 여부와 실제 가격 | `gid`, `url`, `selectedDate` |
+
+## 응답 형식
+
+래퍼는 MCP `CallToolResult`를 JSON으로 출력한다. 보통 `content[].text`에 사람이 읽을 수 있는 검색 결과가 들어온다.
+
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "검색 결과 ..."
+    }
+  ],
+  "isError": false
+}
+```
+
+답변할 때는 원문을 그대로 길게 붙이지 말고 다음 기준으로 정리한다.
+
+- 항공: 항공사, 출발/도착 시각, 총 소요시간, 직항/경유, 가격, 예약 URL
+- 숙소: 숙소명, 지역, 1박/총액 가격, 평점, 핵심 장점, 상세 확인 필요 여부
+- 투어/TNA: 상품명, 시작가, 평점/리뷰, 포함사항 핵심, 날짜별 옵션 확인 결과, URL
+- 후보가 많으면 상위 3~5개만 비교
+- 가격·좌석·재고·예약 가능 여부는 실시간 변동 가능하다고 명시
+
+## 실패 상황과 대응
+
+- `Python package 'mcp' is required`: `python3 -m pip install mcp` 후 재시도한다.
+- MCP 엔드포인트 연결 실패: `MYREALTRIP_MCP_ENDPOINT` 오타, 네트워크, upstream 장애를 확인한다.
+- 빈 결과: 날짜/지역/인원/공항코드를 바꿔 재검색한다.
+- 항공 검색 실패: 국내/국제 도구 선택이 맞는지 확인한다. 해외 목적지는 반드시 `searchInternationalFlights`다.
+- 숙소 상세 실패: `searchStays` 결과의 `gid`가 최신인지 확인하고 같은 날짜로 다시 검색한다.
+- TNA 옵션 실패: `getTnaOptions`에는 `searchTnas` 결과의 `gid`와 `url`, `YYYY-MM-DD` 날짜가 모두 필요하다.
+- 캘린더 가격 불일치: `flightsFareCalendar`는 캐시/추정값이므로 실제 검색 결과를 우선한다.
+- 예약/결제 요청: 자동화하지 말고 예약 URL을 제공해 사용자가 직접 진행하게 한다.
+
+## 완료 기준
+
+- 요청 유형에 맞는 MCP 도구를 선택했다.
+- 필요한 날짜, 인원, 공항/도시, `gid`/`url` 등 필수 입력을 확보했다.
+- 실제 MCP 호출 결과를 바탕으로 상위 후보를 요약했다.
+- 가격·재고·예약 가능 여부의 변동 가능성을 안내했다.
+- 예약/결제는 자동화하지 않고 마이리얼트립 URL을 제공했다.