verychic-mcp: Instructions file for Claude Code

CLAUDE.md — verychic-mcp

Unofficial, read-only, anonymous MCP server for VeryChic hotel offers. 2 tools: verychic_search_offers, verychic_offer_details (details + availability/prices by date). Plain HTTP (curl_cffi), dual transport (stdio + streamable-http). Not affiliated with VeryChic — see the disclaimer in README.md.

The 4 principles to apply

1. Think Before Coding — make assumptions explicit; if several interpretations exist, present them (don't silently pick one); if something simpler exists, say so; if unclear, stop and ask.
2. Simplicity First — minimal code that solves the problem; nothing speculative; no abstraction for a single use; if it's 200 lines for 50, rewrite.
3. Surgical Changes — touch only what's needed; don't "improve" adjacent code; match the existing style; flag dead code, don't delete it; clean up only the orphans created by your own changes.
4. Goal-Driven Execution — turn the task into verifiable criteria ("fix the bug" → "write a test that reproduces it, then make it pass"); short multi-step plan with per-step verification.

Commands

pip install -e ".[dev]"               # install (deps: curl_cffi, mcp[cli])
pytest                                # offline tests (fixtures) — excludes @network
pytest -m network                     # real-network smoke test (hits the live API, low volume)
ruff check verychic_mcp tests         # lint
verychic-mcp --help                   # CLI (stdio / streamable-http transports)
verychic-mcp                          # runs in stdio (default)
python -m build                       # builds the wheel (publishing)

Offline tests: they run against real JSON fixtures in tests/fixtures/ (captured in Phase 0), with no network dependency. The @network smoke test is opt-in and excluded from CI by default (addopts = "-m 'not network'").

Architecture (one responsibility per module, independently testable)

config.py      → constants: routes, PRODUCT_PARAMS, rate-limit, channelVersion fallback
errors.py      → VeryChicError + CloudflareBlocked / NotFound / UpstreamError (actionable messages)
http_client.py → VeryChicClient: curl_cffi session (Chrome fingerprint), injectable rate-limit,
                 classify_block() maps HTTP responses to exceptions. get_json / get_text.
discovery.py   → get_channel_version(): reads channelVersion from the live site, hardcoded fallback
models.py      → Offer / Availability / OfferDetails dataclasses (+ offer_url, cheapest_price)
parsers.py     → raw JSON → models (tolerant to missing fields via .get)
api.py         → search_offers / offer_details: composes client + routes + parsers
server.py      → MCPServer (mcp 2.x): registers the 2 tools, resolve_transport(), main()