FreeSpirits Real Estate WebMCP

An agent-native real estate discovery experience where humans and AI search, compare, save, and prepare enquiries together.

Comment

Inspiration

Property search is repetitive. Users repeatedly apply filters, open listings, compare details, remember tradeoffs, save candidates, and fill enquiry forms. Generic browser agents face the same problem from another angle: they must infer what buttons, filters, cards, and forms mean from changing page layouts.

FreeSpirits Real Estate WebMCP explores a better model: the website exposes explicit, structured tools that AI agents can use directly while the human remains in control of consequential actions.

What it does

The application exposes five agent-facing WebMCP tools that form a complete real-estate discovery workflow:

  • search_properties — find properties using structured criteria such as location, transaction type, price, bedrooms, property type, renovation status, features, and bounded result limits.
  • get_property_details — retrieve normalized public property facts from a stable property ID.
  • compare_properties — deterministically compare 2–5 properties using transparent priorities such as price, space, renovation status, metro access, university access, and outdoor space.
  • save_favorite — save a selected property to the current challenge session.
  • prepare_enquiry — prepare a contact enquiry for human review without silently sending it.

The headline demo request is:

Find renovated 2–3 bedroom apartments in Thessaloniki under €760/month, compare the best three, save my favorite, and prepare an enquiry for me to review.

When an agent calls the tools, the page visibly updates so the user can see the search results, ranking, favorites, enquiry draft, and agent activity.

How we built it

The project is a focused public challenge edition of the larger FreeSpirits Real Estate marketplace. It was created during the hackathon period as a standalone React + TypeScript application with sanitized Thessaloniki property data so judges can reproduce the complete workflow without production credentials.

The WebMCP layer uses document.modelContext.registerTool(...) to expose structured actions to compatible AI agents. Tool inputs are narrow, validated, and bounded.

The comparison engine is intentionally deterministic rather than asking an LLM to invent a ranking score. It returns strengths, tradeoffs, and missing-data warnings grounded in available property facts.

The enquiry workflow deliberately returns requiresHumanConfirmation: true. The agent may prepare the next step, but the human controls whether consequential contact occurs.

The repository includes automated tests, production builds, CI, documentation, and automatic GitHub Pages deployment from the main branch.

AI / Agent role

The product is designed specifically for AI-agent collaboration. Instead of scraping or visually interpreting the UI, a compatible agent can discover and invoke structured WebMCP tools exposed by the website. This makes the agent workflow more reliable, auditable, and safer while keeping the human informed through visible UI updates.

Challenges we ran into

The main design challenge was deciding what should be automated and what should remain human-controlled. Property discovery and comparison are excellent candidates for delegation, while contacting an advertiser is consequential. We therefore created an explicit human confirmation boundary.

Another challenge was creating useful comparison logic without hiding decisions inside an opaque model. We solved this with transparent deterministic scoring and preference-aware priorities.

Accomplishments we're proud of

  • Five meaningful WebMCP tools form an end-to-end workflow rather than a one-tool proof of concept.
  • The application visibly shows agent activity and results.
  • Property comparison is deterministic and explainable.
  • The project uses sanitized public demo data with no production secrets.
  • Consequential contact is never performed automatically.
  • Automated tests and GitHub Actions verify every deployment.
  • A public HTTPS demo is available for immediate testing.

Presentation Deck

The full 10-slide AI Builders Hackathon presentation is publicly available here:

https://github.com/infogatel2/freespirits-realestate-webmcp/blob/main/docs/AI_BUILDERS_PRESENTATION.md

It covers the problem statement, solution overview, target users, product features, technical architecture, AI technologies, human + AI safety, impact/value, live demo, and roadmap.

Demo Video

https://youtu.be/VMTohINDioM

Live Demo

https://infogatel2.github.io/freespirits-realestate-webmcp/

Source Code

https://github.com/infogatel2/freespirits-realestate-webmcp

What we learned

The project reinforced that agent-native UX is not just about adding a chatbot. A better approach is to expose well-defined capabilities that both the website and an AI agent understand, while giving the user a clear view of what the agent is doing.

It also showed how powerful a human-plus-agent workflow can be when automation is deliberately bounded rather than unrestricted.

What's next

The next phase is to connect the WebMCP layer to a challenge-safe live property API while retaining bundled data as a fallback, expand multilingual agent interactions, add more preference dimensions, and bring the same structured agent interface into the production FreeSpirits Real Estate marketplace.

The broader vision is an agent-native marketplace where users can delegate repetitive discovery, comparison, shortlisting, and preparation work while staying in control of decisions and communication.

Built With

Share this project:

Updates

Submission history