Skip to content

Finance Engine, Valuation, Integrations and More

Latest
Latest

Choose a tag to compare

View all tags
@genego-io genego-io released this 10 Oct 12:54
· 9 commits to main since this release
v2.0.0
ac075af
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

v2.0.0 - Major Build-out: Finance Engine, Valuation, Integrations and More

This is a major version release — a full build-out of the server from the v1.x property-search foundation into a comprehensive real estate workflow platform. All v1.x tool names and realestate:// resource URIs are preserved; existing integrations require no changes.

What's New

50+ Tools Across 11 Feature-Flagged Categories

v1 shipped roughly 7 tools across 4 categories. v2.0 adds 7 entirely new tool categories:

Mortgage

  • calculate_mortgage_payment
  • get_amortization_schedule
  • estimate_affordability_tool
  • compare_refinance

Valuation

  • estimate_property_value
  • comparable_market_analysis
  • analyze_investment
  • analyze_listing_investment

Document

  • ingest_listing_document (.txt / .docx)
  • compare_listing_documents
  • export_property_report (.docx)

Analysis Queue

  • queue_property_analysis
  • get_analysis_status
  • get_analysis_result
  • list_analysis_jobs

Deep Analysis

  • deep_analyze_property — MCP sampling with heuristic fallback

Integrations

  • integration_status
  • lookup_live_property
  • get_live_demographics

System (expanded)

  • get_server_info
  • refresh_data
  • get_data_summary

Deterministic Finance Engine

tools/finance_helpers.py is a new module of pure, side-effect-free finance math — fully unit-tested and importable independently:

  • Monthly P&I calculation (standard amortization formula)
  • Full amortization schedule generation
  • DTI-based affordability ceiling (28/36 rule)
  • Loan scenario comparison (rate and term matrix)
  • Refinance break-even analysis
  • Investment metrics: NOI, cap rate, GRM, cash flow, cash-on-cash return

Comparable-Based Valuation (CMA)

estimate_property_value multiplies a listing's square footage by the area's average price-per-sqft derived from recent sales — a lightweight but defensible CMA approach that works entirely offline.

Listing Document Ingestion and Report Export

ingest_listing_document reads real .txt and .docx files from disk and extracts structured property data (price, beds, baths, sqft, year built, type, address) via regex heuristics. Fields that cannot be confidently extracted return null rather than a guess.

export_property_report takes the structured JSON output and produces a formatted .docx report via python-docx.

Async Analysis Queue (SQLite-backed)

queue_property_analysis submits a listing file for analysis and returns a UUID job ID immediately. Results persist in a local SQLite database (real_estate_mcp_analysis.db) across server restarts. Use get_analysis_status, get_analysis_result, and list_analysis_jobs to retrieve results asynchronously. The database is gitignored and never committed to the repository.

MCP Sampling Support

deep_analyze_property issues a sampling/createMessage request to the connected MCP client's LLM for deeper strategic reasoning on top of the deterministic heuristic output. When the client does not advertise sampling capability (currently most clients), the tool falls back gracefully to the full heuristic analysis — no error is raised.

Opt-in Live Integrations (Off by Default)

Two network adapters are available in the new integrations/ package — both disabled by default and completely absent from the network during tests:

  • Census Bureau API — free demographic and economic context (CENSUS_ENABLED=true, optional CENSUS_API_KEY)
  • RentCast — rental market data and AVM estimates (RENTCAST_ENABLED=true, RENTCAST_API_KEY) — metered, use with care

Integration status is always reportable via integration_status and realestate://integrations/status without enabling anything. Credentials are never echoed back in any tool or resource response.

Feature Flags

Every tool category can be disabled before startup via a REALESTATE_MCP_ENABLE_* environment variable. Setting one to false (or 0, no, or off) skips registration of that category's tools and matching resources entirely. The current state is always inspectable via realestate://server-config and get_server_info.

2 New Prompt Templates

  • mortgage_planning_prompt — guides an end-to-end affordability and financing workflow
  • valuation_prompt — orchestrates CMA valuation plus investment read for a given property

New Resources

  • realestate://server-config — enabled categories, feature-flag env var names, and server version (always registered, ignores feature flags)
  • realestate://integrations/status — live integration on/off state and credential presence (no secret values exposed)

Architecture Changes

create_server() Factory

main.py now exposes both a module-level mcp object (for mcp dev main.py:mcp) and a create_server() factory used by tests. This decouples server construction from transport startup and makes the server trivially testable.

audit() and get_data_manager() Singleton (utils.py)

  • audit(tool, args, result) writes a provenance record for every tool call
  • get_data_manager() returns a process-wide singleton of RealEstateDataManager, eliminating redundant JSON loads
  • The module-level data_manager global is retained for backward compatibility

Multiple Transports

The server now supports three transports via --transport flag or MCP_TRANSPORT environment variable:

python main.py
python main.py --transport sse
python main.py --transport streamable-http

HOST, PORT, and LOG_LEVEL are also configurable via environment variables.

Docker

A docker-compose.yml and Dockerfile are included. docker compose up --build starts the server in SSE mode bound to 0.0.0.0:8000. Live integrations stay off unless environment variables are passed in.

Testing

The test suite expanded from a handful of smoke tests to 156 test functions across 37 test classes covering:

  • Finance engine (pure unit tests, no MCP dependency)
  • Feature flags (enable/disable each category, verify registration state)
  • Every new tool category (mortgage, valuation, document, analysis queue, deep analysis, integrations, system)
  • Live integration adapters via httpx.MockTransport — no real network calls
  • realestate://server-config and realestate://integrations/status resources
  • v1 backward compatibility (all original tool names and resource URIs)

Dependency and Build Changes

  • mcp[cli] >= 1.28 (was unpinned)
  • Added: python-docx, httpx, pydantic>=2.11, pytest-asyncio, pytest-cov, pytest-mock
  • pyproject.toml added (alongside requirements.txt)
  • .flake8, .env.example added
  • License changed from MIT to AGPL-3.0 with a commercial-license path via edwin@genego.io for organizations that need to keep modifications private

Documentation

  • README.md — fully rewritten with data flow diagram, per-integration variable tables, feature flags reference, and transport guide
  • WORKFLOW_EXAMPLES.md — 9 end-to-end workflows with full tool/resource/prompt call sequences and sample formatted output
  • AGENTS.md — guidance for AI agents and developers working in this repo
  • integrations/README.md — Census and RentCast setup guide
  • .agents/skills/ — vendor-agnostic agent skill for Claude, Cursor, and Codex

Upgrading from v1.2.0

No breaking changes. All existing tool names and resource URIs are preserved.

  1. Run pip install -r requirements.txt (new dependencies)
  2. Restart the server — no data or config migration required
  3. All v1 calls continue to work identically
  4. New tool categories are enabled by default — set REALESTATE_MCP_ENABLE_CATEGORY=false (e.g. REALESTATE_MCP_ENABLE_MORTGAGE=false) before startup to disable any category

Full Changelog: v1.2.0...main

Assets 2
Loading