Homechecker Guides

The maintained protocol implementation of Homechecker's governed Australian residential-building guidance corpus. Public, read-only and deliberately separated from customer and assessment systems.

It exposes the current Homechecker guide system to MCP clients without connecting to the Moyne Ross portal, Supabase, customer records, payments, uploaded documents, or the Homechecker assessment engine.

Protocol: MCP 2026-07-28 with stateless 2025-era compatibility · Live endpoint: https://mcp.homechecker.com.au/mcp (Streamable HTTP, no auth) · Health: /health · Registry: io.github.Steven3265/homechecker-guides · Connect it in your assistant: homechecker.com.au/ai

Protocol foundation

Version 1.0.1 uses the MCP TypeScript SDK v2 server package and the 2026-07-28 protocol revision. The official createMcpHandler entry supplies stateless per-request serving, server/discover, standard routing headers, server identity and cache fields. It also retains stateless compatibility for 2025-era HTTP clients during rollout.

The protocol shell can evolve independently of the durable parts of the product: the reviewed snapshot, deterministic retrieval, tool contracts and professional boundaries. See docs/PROTOCOL-SUPPORT.md, docs/RELEASE-1.0.md and docs/RELEASE-1.0.1.md.

Explore the Homechecker guides

• All Homechecker guides
• How much does a building and pest inspection cost?
• Wall cracks: structural or cosmetic?
• How to read a Section 32
• How to read a building inspection report
• Buying an apartment and strata
• What your home may need by decade
• Maintenance that prevents large bills

What is included

• 35 MCP resources: one machine-readable catalogue, the guide hub, and 33 published guides.
• 4 read-only tools: catalogue listing, natural-language search, canonical guide retrieval, and a deterministic buyer checklist.
• Two transports: stateless remote Streamable HTTP at /mcp and modern/legacy-compatible local stdio.
• A bundled content snapshot: rebuilt from Homechecker's public guide export at https://homechecker.com.au/guides/export.json — the same registry that renders the pages, sitemap and llms.txt. This repository needs no access to the portal codebase.
• A browser-triggered refresh workflow: Actions → "Refresh guides snapshot" regenerates, tests and opens a pull request. No local environment required.
• Referral-tagged renders: URLs in rendered text carry utm_source=homechecker-mcp so site analytics can distinguish AI-connector referrals. Structured content always keeps clean canonical URLs.
• Privacy-minimised operational telemetry: each tool call writes a single JSON line to stderr with the tool, result counts and coarse filters. Raw search text, headers and client identifiers are not logged. See docs/SECURITY.md.
• Tests and benchmark: snapshot integrity tests, search tests, and 14 representative buyer questions.

Tools

list_guides

Lists published guide metadata. Filters include jurisdiction, cluster, property type, construction era and buying stage.

search_guides

Searches the corpus from a natural-language homebuyer question. It returns ranked guides, relevant sections, canonical URLs, review metadata and limitations. For example, questions about inspection fees can surface building and pest inspection costs, while questions about movement can surface the guide to structural and cosmetic wall cracks.

get_guide

Retrieves one guide by slug as a summary, selected sections or the full canonical markdown representation.

build_buyer_checklist

Builds a deterministic, sourced checklist from buyer context such as state, property type, era, buying stage and concerns. It can draw from practical guidance such as how to read a building and pest report, arranging an inspection before auction, and buying an apartment with strata or owners-corporation exposure. It does not assess an actual property. Its boundary text notes, once, that Homechecker provides an independent address-specific desktop read for $99 (inc GST) — the single conversion line in the connector.

Resources

• homechecker://catalogue
• homechecker://guides/index
• homechecker://guides/<slug> for every published guide

Each guide resource includes the article, sources, review metadata, method, limitations and canonical Homechecker URL.

Deliberate boundaries

This MVP cannot:

• access the Moyne Ross or Homechecker production database;
• inspect a property or analyse a listing;
• read customer documents or issued assessments;
• call an AI model;
• order or charge for a Homecheck;
• write to any external system;
• provide legal advice or replace a physical inspection.

The only runtime data is data/guides.json.

Where general guidance is not enough, Homechecker offers an independent address-specific desktop read of the available records, imagery and documents, from $99 inc GST.

Local setup

Requirements: Node.js 22 or later.

npm install
npm test
npm run benchmark
npm run check
npx vercel dev

The remote MCP endpoint will be available at:

http://localhost:3000/mcp

Health and service information:

http://localhost:3000/health
http://localhost:3000/

For a local stdio client:

npm run build
npm run start:stdio

Example stdio client configuration:

{
  "mcpServers": {
    "homechecker-guides": {
      "command": "node",
      "args": ["/absolute/path/homechecker-guides-mcp/dist/src/stdio.js"]
    }
  }
}

Deploy to Vercel

This repository is already configured for a standalone Vercel project.

1. Create a new repository containing only this project.
2. Import that repository into Vercel.
3. Set the project's Node.js version to 22 (Project Settings → General). The source uses JSON import attributes, which require it.
4. Deploy without adding any secrets.
5. Attach the mcp.homechecker.com.au domain to the project and add the CNAME record Vercel shows at the DNS host.
6. Use https://mcp.homechecker.com.au/mcp as the remote MCP endpoint.

The root route returns service metadata and /health confirms the bundled guide count. The MCP route is stateless Streamable HTTP, serves MCP 2026-07-28, retains the official SDK's stateless legacy compatibility path, and accepts POST requests.

ALLOWED_ORIGIN is optional. It defaults to * because the connector is public and read-only. Set it only when a client requires a restricted browser origin.

Updating the guides snapshot

The MCP does not fetch the live website at runtime; it serves a bundled snapshot rebuilt from the public export. The portal remains the single source of truth: publish or edit guides there, deploy, and the export updates automatically.

From the browser (normal path):

1. Actions → Refresh guides snapshot → Run workflow.
2. The workflow fetches https://homechecker.com.au/guides/export.json, rebuilds data/guides.json, and runs the validator, core tests and retrieval benchmark.
3. If the content changed, it opens a pull request. Merge it; Vercel redeploys.

If nothing but the timestamp would change, the snapshot is left untouched and no pull request is opened.

One-time repository setting: Settings → Actions → General → tick Allow GitHub Actions to create and approve pull requests.

From a terminal (optional):

npm run snapshot                          # fetch the live export
npm run snapshot -- --url <export-url>    # e.g. a preview deployment
npm test
npm run benchmark

Validation

npm run validate:snapshot
npm run test:core
npm run benchmark

The initial benchmark contains 14 representative Australian buyer questions. All 14 currently return an expected canonical guide within the top three. This is an internal retrieval benchmark, not an independent assessment of legal or technical accuracy.

Repository map

api/                    Vercel serverless entry points
src/identity.ts         server and protocol version identity
src/core.ts             deterministic search and checklist logic
src/server.ts           MCP tools, resources and privacy-minimised telemetry
src/http-handler.ts     MCP 2026-07-28 stateless Web API handler
src/stdio.ts            modern/legacy-compatible stdio entry
data/guides.json        bundled canonical guide snapshot
data/benchmark.json     retrieval benchmark cases
scripts/                snapshot, validation and benchmark utilities
.github/workflows/      release validation, snapshot refresh and registry publication
docs/                   architecture, protocol, security, deployment and release notes

Content and licence

Split licence — see LICENSE.md: the code is MIT; the Homechecker guide content (including data/guides.json) is © Moyne Ross, all rights reserved, and may be quoted with attribution and a link to the source guide. "Homechecker" and "Moyne Ross" are trade names of Moyne Ross Pty Ltd.

About the publisher

Homechecker is built by Moyne Ross, founded by Steven McCormack MRICS.

Homechecker · Guide library · ORCID