refactor: optimize tool signatures + server instructions + sort_by ...

1. config.py — moved _MIN_SIMILARITY into Settings as mcp_default_similarity
   (configurable via .env, default 0.7)

2. models.py — added sort_by to SearchMetadataInput:
   Literal["relevance", "price_asc", "price_desc", "date_desc", "area_desc"]
   Default "relevance". Full Field description with all options.

3. main.py — major refactor:
   - Tool signatures collapsed from 13 individual filter params into
     nested Pydantic models: filters: MetadataFilters, pagination: PaginationParams
     → AI agent now sees rich Field descriptions for every filter field
     through $defs/$ref in generated JSON schema
   - search_by_metadata_tool gains sort_by param
   - Removed manual dict construction (filters={"deal_type": deal_type, ...})
     → cleaner, less error-prone
   - Added SERVER_INSTRUCTIONS to FastMCP(instructions=...) —
     system-level guidance sent to every MCP client (Claude Desktop, etc.)
     covering: server purpose, language, tool selection strategy,
     filter best practices, sorting, fallback, pagination
   - search_guide prompt now reuses SERVER_INSTRUCTIONS (DRY)
   - describe_schema_tool docstring rewritten to be more compelling

4. tools.py — added _build_order_by_clause(sort_by) for metadata search:
   relevance → ts_rank_cd DESC
   price_asc/desc → price ASC/DESC NULLS LAST
   date_desc → publish_date DESC NULLS LAST
   area_desc → total_area DESC NULLS LAST
   Uses settings.mcp_default_similarity instead of hardcoded constant.
   describe_schema updated with sorting section.

5. test_models.py — 12 tests, covers:
   - sort_by defaults and validation
   - nested schema generation ($defs)
   - existing pagination, filter, serialization tests

12 tests pass, ruff clean.

Co-Authored-By: Claude <noreply@anthropic.com>

feat: enrich tool instructions, system prompts, and error hints ...

1. models.py — enriched Field descriptions with:
   - ✓/✗ query examples in descriptions
   - ILIKE semantics for city/district/metro
   - currency+price coupling warnings
   - rooms_count: 0=studio note
   - pagination strategy hints
   - Removed min_similarity from SearchSimilarInput (now hardcoded 0.7 in tools.py)

2. tools.py — added intelligent response layers:
   - _build_fallback_hint() — returns strategy tips on 0 results
     (switch tool, drop filters, simplify query, check language)
   - _build_invalid_query_hint() — detects stop-words & short queries,
     returns formatting tips with good/bad examples
   - describe_schema() enriched with:
     - usage_guidelines (when vector vs FTS)
     - query_examples (good/bad for both search types)
     - filter_combinations (recommended / avoid)
     - pagination_strategy

3. main.py — enriched tool docstrings with:
   - "When to use" vs other tools
   - Filter best practices
   - Fallback behavior description
   - Added @mcp.prompt() 'search_guide' — full agent guide
   - Added module docstring with server purpose, data scope, language

4. test_models.py — updated for removed min_similarity,
   added tests for description hints presence

10 tests pass, ruff clean.

Co-Authored-By: Claude <noreply@anthropic.com>

feat: implement MCP server for real estate database search ...

Add streamable-http MCP server with 4 tools:
- search_similar_listings: vector search via pgvector+HNSW (cosine)
- search_by_metadata: full-text search via FTS (ukrainian config)+GIN
- get_listing_by_id: fetch single listing by ID
- describe_schema: static schema documentation for AI agent

Features:
- asyncpg read-only pool with default_transaction_read_only
- parameterized queries + query safety check (multi-statement block)
- Pydantic models for input validation and JSON serialization
- Ollama nomic-embed-text client with dimension validation
- Error handling: Ollama/DB/validation exceptions wrapped in JSON
- Docker & docker-compose support
- ruff clean + 8 pytest tests passing

Co-Authored-By: Claude <noreply@anthropic.com>