feat: subscription historical filters + PDF supply-price extraction + local PDF save

[roughian]

Summary

Three related enhancements for the 청약 (subscription) tool group:

1. Historical / pending-occupancy filters on get_apt_subscription_info

   • rcrit_pblanc_de_from / rcrit_pblanc_de_to (YYYY-MM-DD) — server-side filter on 모집공고일 via odcloud cond[] syntax. Lets users pull past notices ("2021년 7월까지의 공고").
   • mvn_prearnge_ym_from (YYYYMM) + only_pending_occupancy flag — filter to 단지 with future MVN_PREARNGE_YM (i.e. 실거래가 미확정 입주예정).
   • Each item is enriched with is_pre_occupancy and expected_move_in_year_month derived fields.
   • applied_filters echo in the response for LLM traceability.

2. New tool get_apt_subscription_supply_prices

   • Accepts house_manage_no (looks up PBLANC_URL via odcloud) or pblanc_url directly.
   • Downloads the notice PDF (15 s timeout, 25 MB cap, magic-byte check) and extracts 평형별 분양가 via pdfplumber.
   • Extraction strategy: tables first (header keyword detection for 공급금액/공급가격/분양가 + 주택형/타입/모델/평형 + 전용면적), regex fallback on price-keyword pages.
   • KRW values are normalized to 만원 with a 1억 threshold heuristic; results are deduplicated by (unit_type, exclusive_area_sqm).

3. New tool download_subscription_pdf (added in follow-up commit)

   • Saves the notice PDF to a user-specified local directory (Claude Desktop stdio mode).
   • save_dir is required and ~-expanded; the directory is auto-created.
   • filename is sanitised (path separators, .., control chars removed; whitespace collapsed to _).
   • Default filename: {HOUSE_NM}_{HOUSE_MANAGE_NO}.pdf.
   • overwrite=False (default) appends a numeric suffix (_01, _02, ...) on collision; overwrite=True replaces the existing file.
   • Interactive flow: the tool's docstring and resources/custom-instructions-ko.md instruct the LLM to ask the user for save_dir before calling, rather than guessing a default. (Claude Desktop has no Skill/AskUserQuestion UI; this is the idiomatic equivalent.)

New utility module

• src/real_estate/common_utils/pdf_parser.py — extract_text() / extract_supply_prices() / SupplyPrice dataclass. Guards: 25 MB / 200 pages / OCR-required detection.

New helpers in _helpers.py

• _download_pdf — streaming GET with 15 s timeout, 25 MB cap, content-type / magic-byte check.
• _sanitize_filename_component, _resolve_save_dir, _next_available_path — used by download_subscription_pdf.
• _current_year_month, _validate_pblanc_date, _validate_year_month — used by the historical filter.

Dependencies

• pdfplumber==0.11.4 added (pure-Python, pdfminer.six + pypdfium2 transitively). No system packages required, friendly for Docker/HTTP-mode deployments.

Test plan

• uv run pytest tests/mcp_server/test_subscription.py tests/common_utils/test_pdf_parser.py — 54 tests pass
• uv run ruff check — clean on changed files
• uv run pyright on changed files — 0 errors
• Manual smoke test with a real 청약 공고 PDF (recommended before merging)
• Manual smoke test of download_subscription_pdf in Claude Desktop stdio mode

Notes / follow-ups

• _download_pdf accepts arbitrary URLs (via pblanc_url). A follow-up patch is recommended to add a host allowlist and private-IP blocklist for SSRF defence-in-depth before deploying in HTTP mode.
• The regex fallback \d{2,3}[A-Z]?T? can collide with non-평형 numbers when tables are absent. Recommend adding regression fixtures from real PDFs once available.
• The interactive save_dir prompt is policy-based (docstring + Project Instructions), not hard-enforced. If stricter UX becomes important, splitting into a two-step propose/confirm tool pair is an option.

🤖 Generated with Claude Code

[tae0y]

안녕하세요 기여 감사합니다.
먼저 이슈에서 방향을 의논하고 PR을 확인하고 싶어요.
준비되시면 해당하는 이슈에, 혹은 새로 이슈를 열어서
개괄적으로 설명 부탁드립니다.