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>
Eugene Sukhodolskiy
committed
1 day ago
